diff options
| -rw-r--r-- | Makefile-man.am | 2 | ||||
| -rw-r--r-- | man/systemd-networkd.service.xml | 2 | ||||
| -rw-r--r-- | man/systemd.link.xml | 383 | ||||
| -rw-r--r-- | man/udev.xml | 288 |
4 files changed, 394 insertions, 281 deletions
diff --git a/Makefile-man.am b/Makefile-man.am index aad3f444da..cb6ed94edd 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -100,6 +100,7 @@ MANPAGES += \ man/systemd.time.7 \ man/systemd.timer.5 \ man/systemd.unit.5 \ + man/systemd.link.5 \ man/telinit.8 \ man/tmpfiles.d.5 \ man/udev.7 \ @@ -1467,6 +1468,7 @@ EXTRA_DIST += \ man/systemd.time.xml \ man/systemd.timer.xml \ man/systemd.unit.xml \ + man/systemd.link.xml \ man/systemd.xml \ man/telinit.xml \ man/timedatectl.xml \ diff --git a/man/systemd-networkd.service.xml b/man/systemd-networkd.service.xml index df5ca36406..7585832230 100644 --- a/man/systemd-networkd.service.xml +++ b/man/systemd-networkd.service.xml @@ -63,7 +63,7 @@ <para>To configure low-level link settings independently of networks, see - <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry> .</para> <para>Network configurations applied before networkd is started diff --git a/man/systemd.link.xml b/man/systemd.link.xml new file mode 100644 index 0000000000..c1176ba176 --- /dev/null +++ b/man/systemd.link.xml @@ -0,0 +1,383 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Tom Gundersen + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.link"> + <refentryinfo> + <title>systemd.link</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.link</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.link</refname> + <refpurpose>Network device configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>link</replaceable>.link</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>Network link configuration is performed by the <literal>net_setup_link</literal> + udev builtin.</para> + + <para>The link files are read from the files located in the + system network directory <filename>/usr/lib/systemd/network</filename>, + the volatile runtime network directory <filename>/run/systemd/network</filename> + and the local administration network directory <filename>/etc/systemd/network</filename>. + Link files must have the extension <filename>.link</filename>; other extensions are ignored. + All link files are collectively sorted and processed in lexical order, + regardless of the directories in which they live. However, files with + identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence + over files with the same name in <filename>/usr/lib</filename>. This can be + used to override a system-supplied link file with a local file if needed; + a symlink in <filename>/etc</filename> with the same name as a link file in + <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, + disables the link file entirely.</para> + + <para>The link file contains a <literal>[Match]</literal> section, which + determines if a given link file may be applied to a given device; and a + <literal>[Link]</literal> section specifying how the device should be + configured. The first (in lexical order) of the link files that matches + a given device is applied.</para> + + <para>A link file is said to match a device if each of the entries in the + <literal>[Match]</literal> section matches, or if the section is empty. + The following keys are accepted:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The hardware address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Path=</varname></term> + <listitem> + <para>The persistent path, as exposed by the + udev property <literal>ID_PATH</literal>. May + contain shell style globs.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Driver=</varname></term> + <listitem> + <para>The driver currently bound to the device, + as exposed by the udev property <literal>DRIVER</literal> + of its parent device, or if that is not set the + driver as exposed by <literal>ethtool -i</literal> + of the device itself.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Type=</varname></term> + <listitem> + <para>The device type, as exposed by the udev + property <literal>DEVTYPE</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Host=</varname></term> + <listitem> + <para>Matches against the hostname or machine + ID of the host. See <literal>ConditionHost=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Virtualization=</varname></term> + <listitem> + <para>Checks whether the system is executed in + a virtualized environment and optionally test + whether it is a specific implementation. See + <literal>ConditionVirtualization=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>KernelCommandLine=</varname></term> + <listitem> + <para>Checks whether a specific kernel command + line option is set (or if prefixed with the + exclamation mark unset). See + <literal>ConditionKernelCommandLine=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Architecture=</varname></term> + <listitem> + <para>Checks whether the system is running on a + specific architecture. See + <literal>ConditionArchitecture=</literal> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The <literal>[Link]</literal> section accepts the following + keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>Description=</varname></term> + <listitem> + <para>A description of the device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Alias=</varname></term> + <listitem> + <para>The <literal>ifalias</literal> is set to + this value.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddressPolicy=</varname></term> + <listitem> + <para>The policy by which the MAC address + should be set. The available policies are: + </para> + + <variablelist> + <varlistentry> + <term><literal>persistent</literal></term> + <listitem> + <para>If the hardware has a persistent + MAC address, as most hardware should, + and this is used by the kernel, nothing + is done. Otherwise, a new MAC address + is generated which is guaranteed to be + the same on every boot for the given + machine and the given device, but which + is otherwise random.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>random</literal></term> + <listitem> + <para>If the kernel is using a random MAC + address, nothing is done. Otherwise, a new + address is randomly generated each time the + device appears, typically at boot.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>The MAC address to use, if no + <literal>MACAddressPolicy=</literal> + is specified.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>NamePolicy=</varname></term> + <listitem> + <para>An ordered, space-separated list of + policies by which the interface name should + be set. <literal>NamePolicy</literal> may be + disabled by specifying + <literal>net.ifnames=0</literal> on the kernel + commandline. Each of the policies may fail, and + the first successful one is used. The name is + not set directly, but is exported to udev as + the property <literal>ID_NET_NAME</literal>, + which is, by default, used by a udev rule to set + <literal>NAME</literal>. The available policies + are:</para> + + <variablelist> + <varlistentry> + <term><literal>database</literal></term> + <listitem> + <para>The name is set based on entries in + the udev's Hardware Database with the key + <literal>ID_NET_NAME_FROM_DATABASE</literal> + .</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>onboard</literal></term> + <listitem> + <para>The name is set based on information given by + the firmware for on-board devices, as exported by + the udev property <literal>ID_NET_NAME_ONBOARD</literal> + .</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>slot</literal></term> + <listitem> + <para>The name is set based on information given by + the firmware for hot-plug devices, as exported by + the udev property <literal>ID_NET_NAME_SLOT</literal> + .</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>path</literal></term> + <listitem> + <para>The name is set based on the device's physical + location, as exported by the udev property + <literal>ID_NET_NAME_PATH</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>mac</literal></term> + <listitem> + <para>The name is set based on the device's + persistent MAC address, as exported by the udev + property <literal>ID_NET_NAME_MAC</literal>.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Name=</varname></term> + <listitem> + <para>The interface name to use in case all the + policies specified in + <varname>NamePolicy=</varname> fail, or in case + <varname>NamePolicy=</varname> is missing or + disabled.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MTUBytes=</varname></term> + <listitem> + <para>The maximum transmission unit in bytes to + set for the device. The usual suffixes K, M, G, + are supported and are understood to the base of + 1024.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>BitsPerSecond=</varname></term> + <listitem> + <para>The speed to set for the device, the + value is rounded down to the nearest Mbps. + The usual suffixes K, M, G, are supported and + are understood to the base of 1000.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Duplex=</varname></term> + <listitem> + <para>The duplex mode to set for the device. + The accepted values are <literal>half</literal> + and <literal>full</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>WakeOnLan=</varname></term> + <listitem> + <para>The Wake-on-LAN policy to set for the + device. The supported values are:</para> + + <variablelist> + <varlistentry> + <term><literal>phy</literal></term> + <listitem> + <para>Wake on PHY activity.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>magic</literal></term> + <listitem> + <para>Wake on receipt of a magic packet + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>off</literal></term> + <listitem> + <para>Never wake.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Example</title> + <example> + <title>/etc/systemd/network/wireless.link</title> + + <programlisting>[Match] +MACAddress=12:34:56:78:9a:bc +Driver=brcmsmac +Path=pci-0000:02:00.0-* +Type=wlan +Virtualization=no +Host=my-laptop +Architecture=x86-64 + +[Link] +Name=wireless0 +MTUBytes=1450 +BitsPerSecond=10M +WakeOnLan=magic +MACAddress=cb:a9:87:65:43:21</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry> + <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> + </citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/udev.xml b/man/udev.xml index 95b37fd0cf..4e5f8f00aa 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -307,8 +307,11 @@ <varlistentry> <term><varname>NAME</varname></term> <listitem> - <para>The name to use for a network interface. The name of a device node - cannot be changed by udev, only additional symlinks can be created.</para> + <para>The name to use for a network interface. See + <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a higher-level mechanism for setting the interface name. + The name of a device node cannot be changed by udev, only additional + symlinks can be created.</para> </listitem> </varlistentry> @@ -759,284 +762,6 @@ During runtime only the binary database is used.</para> </refsect1> - <refsect1><title>Network Link Configuration</title> - <para>Network link configuration is performed by the <literal>net_setup_link</literal> - udev builtin.</para> - - <para>The link files are read from the files located in the - system network directory <filename>/usr/lib/systemd/network</filename>, - the volatile runtime network directory <filename>/run/systemd/network</filename> - and the local administration network directory <filename>/etc/systemd/network</filename>. - Link files must have the extension <filename>.link</filename>; other extensions are ignored. - All link files are collectively sorted and processed in lexical order, - regardless of the directories in which they live. However, files with - identical filenames replace each other. Files in <filename>/etc</filename> - have the highest priority, files in <filename>/run</filename> take precedence - over files with the same name in <filename>/usr/lib</filename>. This can be - used to override a system-supplied link file with a local file if needed; - a symlink in <filename>/etc</filename> with the same name as a link file in - <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>, - disables the link file entirely.</para> - - <para>The link file contains a <literal>[Match]</literal> section, which - determines if a given link file may be applied to a given device; and a - <literal>[Link]</literal> section specifying how the device should be - configured. The first (in lexical order) of the link files that matches - a given device is applied.</para> - - <para>A link file is said to match a device if each of the entries in the - <literal>[Match]</literal> section matches, or if the section is empty. - The following keys are accepted:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The hardware address. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Path=</varname></term> - <listitem> - <para>The persistent path, as exposed by the udev property <literal>ID_PATH</literal>. - May contain shell style globs.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Driver=</varname></term> - <listitem> - <para>The driver currently bound to the device, as exposed by the - udev property <literal>DRIVER</literal> of its parent device, or if - that is not set the driver as exposed by <literal>ethtool -i</literal> - of the device itself.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Type=</varname></term> - <listitem> - <para>The device type, as exposed by the udev property <literal>DEVTYPE</literal>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Host=</varname></term> - <listitem> - <para>Matches against the hostname or machine ID of the - host. See <literal>ConditionHost=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Virtualization=</varname></term> - <listitem> - <para>Checks whether the system is executed in a virtualized - environment and optionally test whether it is a specific - implementation. See <literal>ConditionVirtualization=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>KernelCommandLine=</varname></term> - <listitem> - <para>Checks whether a specific kernel command line option is - set (or if prefixed with the exclamation mark unset). See - <literal>ConditionKernelCommandLine=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Architecture=</varname></term> - <listitem> - <para>Checks whether the system is running on a specific - architecture. See <literal>ConditionArchitecture=</literal> in - <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>The <literal>[Link]</literal> section accepts the following keys:</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>Description=</varname></term> - <listitem> - <para>A description of the device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Alias=</varname></term> - <listitem> - <para>The <literal>ifalias</literal> is set to this value.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddressPolicy=</varname></term> - <listitem> - <para>The policy by which the MAC address should be set. The - available policies are: - </para> - <variablelist> - <varlistentry> - <term><literal>persistent</literal></term> - <listitem> - <para>If the hardware has a persistent MAC address, as most - hardware should, and this is used by the kernel, nothing is - done. Otherwise, a new MAC address is generated which is - guaranteed to be the same on every boot for the given - machine and the given device, but which is otherwise random. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>random</literal></term> - <listitem> - <para>If the kernel is using a random MAC address, nothing is - done. Otherwise, a new address is randomly generated each - time the device appears, typically at boot. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>The MAC address to use, if no <literal>MACAddressPolicy=</literal> - is specified. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>NamePolicy=</varname></term> - <listitem> - <para>An ordered, space-separated list of policies by which the - interface name should be set. <literal>NamePolicy</literal> may - be disabled by specifying <literal>net.ifnames=0</literal> on the - kernel commandline. Each of the policies may fail, and the first - successful one is used. The name is not set directly, but - is exported to udev as the property <literal>ID_NET_NAME</literal>, - which is, by default, used by a udev rule to set - <literal>NAME</literal>. The available policies are: - </para> - <variablelist> - <varlistentry> - <term><literal>database</literal></term> - <listitem> - <para>The name is set based on entries in the Hardware - Database with the key - <literal>ID_NET_NAME_FROM_DATABASE</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>onboard</literal></term> - <listitem> - <para>The name is set based on information given by the - firmware for on-board devices, as exported by the udev - property <literal>ID_NET_NAME_ONBOARD</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>slot</literal></term> - <listitem> - <para>The name is set based on information given by the - firmware for hot-plug devices, as exported by the udev - property <literal>ID_NET_NAME_SLOT</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>path</literal></term> - <listitem> - <para>The name is set based on the device's physical location, - as exported by the udev property - <literal>ID_NET_NAME_PATH</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>mac</literal></term> - <listitem> - <para>The name is set based on the device's persistent MAC - address, as exported by the udev property - <literal>ID_NET_NAME_MAC</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Name=</varname></term> - <listitem> - <para>The interface name to use in case all the policies specified - in <varname>NamePolicy=</varname> fail, or in case - <varname>NamePolicy=</varname> is missing or disabled. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MTUBytes=</varname></term> - <listitem> - <para>The maximum transmission unit in bytes to set for - the device. The usual suffixes K, M, G, are supported and - are understood to the base of 1024.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>BitsPerSecond=</varname></term> - <listitem> - <para>The speed to set for the device, the value is - rounded down to the nearest Mbps. The usual suffixes K, M, - G, are supported and are understood to the base of - 1000.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Duplex=</varname></term> - <listitem> - <para>The duplex mode to set for the device. The accepted values - are <literal>half</literal> and <literal>full</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>WakeOnLan=</varname></term> - <listitem> - <para>The Wake-on-LAN policy to set for the device. The supported - values are: - </para> - <variablelist> - <varlistentry> - <term><literal>phy</literal></term> - <listitem> - <para>Wake on PHY activity.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>magic</literal></term> - <listitem> - <para>Wake on receipt of a magic packet.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>off</literal></term> - <listitem> - <para>Never wake.</para> - </listitem> - </varlistentry> - </variablelist> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - <refsect1> <title>See Also</title> <para> @@ -1046,6 +771,9 @@ <citerefentry> <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum> </citerefentry> + <citerefentry> + <refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> </para> </refsect1> </refentry> |