<citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a
general description of the syntax.</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
+ <para>The <filename>.link</filename> files are read from the files located in the system network
+ directory <filename>/usr/lib/systemd/network</filename> and
+ <filename>/usr/local/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
+ <filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
+ processed in alphanumeric order, regardless of the directories in which they live. However, files
+ with identical filenames replace each other. It is recommended that each filename is prefixed with
+ a number (e.g. <filename>10-eth0.link</filename>). Otherwise, the default
+ <filename>.link</filename> files or those generated by
+ <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ may take precedence over user configured files. 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. As a special case, an empty file (file size 0) or symlink with the same name
pointing to <filename>/dev/null</filename> disables the configuration file entirely (it is
"masked").</para>
<refsect1>
<title>[Match] Section Options</title>
- <para>A link file is said to match a device if all matches specified by the
- [Match] section are satisfied. When a link file does not contain valid settings
- in [Match] section, then the file will match all devices and
- <command>systemd-udevd</command> warns about that. Hint: to avoid the warning and to make it clear
- that all interfaces shall be matched, add the following:
+ <para>A link file is said to match an interface if all matches specified by the [Match] section are
+ satisfied. When a link file does not contain valid settings in [Match] section, then the file will
+ match all interfaces and <command>systemd-udevd</command> warns about that. Hint: to avoid the
+ warning and to make it clear that all interfaces shall be matched, add the following:
<programlisting>OriginalName=*</programlisting>
- The following keys are accepted:</para>
+ The first (in alphanumeric order) of the link files that matches a given interface is applied, all
+ later files are ignored, even if they match as well. The following keys are accepted:</para>
<variablelist class='network-directives'>
<!-- This list is reused in systemd.network(3), hence maintain a specific order:
</listitem>
</varlistentry>
+ <varlistentry id='kind'>
+ <term><varname>Kind=</varname></term>
+ <listitem>
+ <para>A whitespace-separated list of shell-style globs matching the device kind, as exposed by
+ <command>networkctl status <replaceable>INTERFACE</replaceable></command> or
+ <command>ip -d link show <replaceable>INTERFACE</replaceable></command>. If the list is
+ prefixed with a "!", the test is inverted. Some valid values are <literal>bond</literal>,
+ <literal>bridge</literal>, <literal>gre</literal>, <literal>tun</literal>,
+ <literal>veth</literal>. Valid kinds are given by netlink's <literal>IFLA_INFO_KIND</literal>
+ attribute, so this is not comprehensive.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry id='property'>
<term><varname>Property=</varname></term>
<listitem>
<para>Matches against the hostname or machine ID of the host. See <varname>ConditionHost=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
- If an empty string is assigned, then previously assigned value is cleared.
+ If an empty string is assigned, the previously assigned value is cleared.
</para>
</listitem>
</varlistentry>
whether it is a specific implementation. See <varname>ConditionVirtualization=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
- If an empty string is assigned, then previously assigned value is cleared.
+ If an empty string is assigned, the previously assigned value is cleared.
</para>
</listitem>
</varlistentry>
<varname>ConditionKernelCommandLine=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
- If an empty string is assigned, then previously assigned value is cleared.
+ If an empty string is assigned, the previously assigned value is cleared.
</para>
</listitem>
</varlistentry>
expression. See <varname>ConditionKernelVersion=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
- If an empty string is assigned, then previously assigned value is cleared.
+ If an empty string is assigned, the previously assigned value is cleared.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id='credential'>
+ <term><varname>Credential=</varname></term>
+ <listitem>
+ <para>Checks whether the specified credential was passed to the
+ <filename>systemd-udevd.service</filename> service. See <ulink
+ url="https://systemd.io/CREDENTIALS">System and Service Credentials</ulink> for details. When
+ prefixed with an exclamation mark (<literal>!</literal>), the result is negated. If an empty
+ string is assigned, the previously assigned value is cleared.
</para>
</listitem>
</varlistentry>
<varname>ConditionArchitecture=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
- If an empty string is assigned, then previously assigned value is cleared.
+ If an empty string is assigned, the previously assigned value is cleared.
</para>
</listitem>
</varlistentry>
<varname>ConditionFirmware=</varname> in
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
- If an empty string is assigned, then previously assigned value is cleared.
+ If an empty string is assigned, the previously assigned value is cleared.
</para>
</listitem>
</varlistentry>
must either be unset, empty, disabled, or all policies configured there must fail. Also see the
example below with <literal>Name=dmz0</literal>.</para>
- <para>Note that specifying a name that the kernel might use for another
- interface (for example <literal>eth0</literal>) is dangerous because the
- name assignment done by udev will race with the assignment done by the
- kernel, and only one interface may use the name. Depending on the order of
- operations, either udev or the kernel will win, making the naming
- unpredictable. It is best to use some different prefix, for example
- <literal>internal0</literal>/<literal>external0</literal> or
- <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.
- </para>
+ <para>Note that specifying a name that the kernel might use for another interface (for example
+ <literal>eth0</literal>) is dangerous because the name assignment done by udev will race with the
+ assignment done by the kernel, and only one interface may use the name. Depending on the order of
+ operations, either udev or the kernel will win, making the naming unpredictable. It is best to use
+ some different prefix, for example <literal>internal0</literal>/<literal>external0</literal> or
+ <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.</para>
+
+ <para>Interface names must have a minimum length of 1 character and a maximum length of 15
+ characters, and may contain any 7bit ASCII character, with the exception of control characters,
+ <literal>:</literal>, <literal>/</literal> and <literal>%</literal>. While <literal>.</literal> is
+ an allowed character, it's recommended to avoid it when naming interfaces as various tools (such as
+ <citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>) use
+ it as separator character. Also, fully numeric interface names are not allowed (in order to avoid
+ ambiguity with interface specification by numeric indexes), as are the special strings
+ <literal>.</literal>, <literal>..</literal>, <literal>all</literal> and
+ <literal>default</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
If the empty string is assigned to this option, the list is reset, and all prior assignments
have no effect. If the kernel does not support the alternative names, then this setting will
be ignored.</para>
+
+ <para>Alternative interface names may be used to identify interfaces in various tools. In contrast
+ to the primary name (as configured with <varname>Name=</varname> above) there may be multiple
+ alternative names referring to the same interface. Alternative names may have a maximum length of
+ 127 characters, in contrast to the 15 allowed for the primary interface name, but otherwise are
+ subject to the same naming constraints.</para>
</listitem>
</varlistentry>
<varlistentry>
<varlistentry>
<term><varname>TransmitVLANSTAGHardwareAcceleration=</varname></term>
<listitem>
- <para>Takes a boolean. If set to true, transmit VLAN STAG HW acceleration is enabled.
+ <para>Takes a boolean. If set to true, transmit VLAN STAG hardware acceleration is enabled.
When unset, the kernel's default will be used.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>MDI=</varname></term>
+ <listitem>
+ <para>Specifies the medium dependent interface (MDI) mode for the interface. A MDI describes
+ the interface from a physical layer implementation to the physical medium used to carry the
+ transmission. Takes one of the following words: <literal>straight</literal> (or equivalently:
+ <literal>mdi</literal>), <literal>crossover</literal> (or equivalently:
+ <literal>mdi-x</literal>, <literal>mdix</literal>), and <literal>auto</literal>. When
+ <literal>straight</literal>, the MDI straight through mode will be used. When
+ <literal>crossover</literal>, the MDI crossover (MDI-X) mode will be used. When
+ <literal>auto</literal>, the MDI status is automatically detected. Defaults to unset, and the
+ kernel's default will be used.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>SR-IOVVirtualFunctions=</varname></term>
<listitem>
<example>
<title>/usr/lib/systemd/network/99-default.link</title>
- <para>The link file <filename>99-default.link</filename> that is
- shipped with systemd defines the default naming policy for
- links.</para>
+ <para>The link file <filename>99-default.link</filename> that is shipped with systemd defines the
+ default policies for the interface name, alternative names, and MAC address of links.</para>
- <programlisting>[Link]
-NamePolicy=kernel database onboard slot path
+ <programlisting>[Match]
+OriginalName=*
+
+[Link]
+NamePolicy=keep kernel database onboard slot path
+AlternativeNamesPolicy=database onboard slot path
MACAddressPolicy=persistent</programlisting>
</example>
<para><varname>NamePolicy=</varname> is not set, so <varname>Name=</varname> takes effect. We use the
<literal>10-</literal> prefix to order this file early in the list. Note that it needs to be before
- <literal>99-link</literal>, i.e. it needs a numerical prefix, to have any effect at all.</para>
+ <filename>99-default.link</filename>, i.e. it needs a numerical prefix, to have any effect at all.</para>
+ </example>
+
+ <example>
+ <title>(Re-)applying a .link file to an interface</title>
+
+ <para>After a new .link file has been created, or an exisiting .link file modified, the new settings
+ may be applied to the matching interface with the following commands:</para>
+
+ <programlisting>$ sudo udevadm control --reload
+$ sudo ip link set eth0 down
+$ sudo udevadm trigger --verbose --settle --action add /sys/class/net/eth0</programlisting>
+
+ <para>You may also need to stop the service that manages the network interface, e.g.
+ <filename>systemd-networkd.service</filename> or <filename>NetworkManager.service</filename> before
+ the above operation, and then restart the service after that. For more details about
+ <command>udevadm</command> command, see
+ <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
</example>
<example>
</citerefentry>,
<citerefentry>
<refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum>
</citerefentry>
</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff