man/systemd.network.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2013 Tom Gundersen
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd.network" conditional='ENABLE_NETWORKD'>
  25
  26   <refentryinfo>
  27     <title>systemd.network</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Tom</firstname>
  34         <surname>Gundersen</surname>
  35         <email>teg@jklm.no</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd.network</refentrytitle>
  42     <manvolnum>5</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd.network</refname>
  47     <refpurpose>Network configuration</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <para><filename><replaceable>network</replaceable>.network</filename></para>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56
  57     <para>Network setup is performed by
  58     <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  59     </para>
  60
  61     <para>Network files must have the extension
  62     <filename>.network</filename>; other extensions are ignored.
  63     Networks are applied to links whenever the links appear.</para>
  64
  65     <para>The <filename>.network</filename> files are read from the
  66     files located in the system network directory
  67     <filename>/usr/lib/systemd/network</filename>, the volatile
  68     runtime network directory
  69     <filename>/run/systemd/network</filename> and the local
  70     administration network directory
  71     <filename>/etc/systemd/network</filename>. All configuration files
  72     are collectively sorted and processed in lexical order, regardless
  73     of the directories in which they live. However, files with
  74     identical filenames replace each other. Files in
  75     <filename>/etc</filename> have the highest priority, files in
  76     <filename>/run</filename> take precedence over files with the same
  77     name in <filename>/usr/lib</filename>. This can be used to
  78     override a system-supplied configuration file with a local file if
  79     needed. As a special case, an empty file (file size 0) or symlink
  80     with the same name pointing to <filename>/dev/null</filename>
  81     disables the configuration file entirely (it is "masked").</para>
  82   </refsect1>
  83
  84   <refsect1>
  85     <title>[Match] Section Options</title>
  86
  87       <para>The network file contains a <literal>[Match]</literal>
  88       section, which determines if a given network file may be applied
  89       to a given device; and a <literal>[Network]</literal> section
  90       specifying how the device should be configured. The first (in
  91       lexical order) of the network files that matches a given device
  92       is applied, all later files are ignored, even if they match as
  93       well.</para>
  94
  95       <para>A network file is said to match a device if each of the
  96       entries in the <literal>[Match]</literal> section matches, or if
  97       the section is empty. The following keys are accepted:</para>
  98
  99       <variablelist class='network-directives'>
 100         <varlistentry>
 101           <term><varname>MACAddress=</varname></term>
 102           <listitem>
 103             <para>The hardware address.</para>
 104           </listitem>
 105         </varlistentry>
 106         <varlistentry>
 107           <term><varname>Path=</varname></term>
 108           <listitem>
 109             <para>A whitespace-separated list of shell-style globs
 110             matching the persistent path, as exposed by the udev
 111             property <literal>ID_PATH</literal>.</para>
 112           </listitem>
 113         </varlistentry>
 114         <varlistentry>
 115           <term><varname>Driver=</varname></term>
 116           <listitem>
 117             <para>A whitespace-separated list of shell-style globs
 118             matching the driver currently bound to the device, as
 119             exposed by the udev property <literal>DRIVER</literal>
 120             of its parent device, or if that is not set the driver
 121             as exposed by <literal>ethtool -i</literal> of the
 122             device itself.</para>
 123           </listitem>
 124         </varlistentry>
 125         <varlistentry>
 126           <term><varname>Type=</varname></term>
 127           <listitem>
 128             <para>A whitespace-separated list of shell-style globs
 129             matching the device type, as exposed by the udev property
 130             <literal>DEVTYPE</literal>.</para>
 131           </listitem>
 132         </varlistentry>
 133         <varlistentry>
 134           <term><varname>Name=</varname></term>
 135           <listitem>
 136             <para>A whitespace-separated list of shell-style globs
 137             matching the device name, as exposed by the udev property
 138             <literal>INTERFACE</literal>.</para>
 139           </listitem>
 140         </varlistentry>
 141         <varlistentry>
 142           <term><varname>Host=</varname></term>
 143           <listitem>
 144             <para>Matches against the hostname or machine ID of the
 145             host. See <literal>ConditionHost=</literal> in
 146             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 147             for details.
 148             </para>
 149           </listitem>
 150         </varlistentry>
 151         <varlistentry>
 152           <term><varname>Virtualization=</varname></term>
 153           <listitem>
 154             <para>Checks whether the system is executed in a virtualized
 155             environment and optionally test whether it is a specific
 156             implementation. See <literal>ConditionVirtualization=</literal> in
 157             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 158             for details.
 159             </para>
 160           </listitem>
 161         </varlistentry>
 162         <varlistentry>
 163           <term><varname>KernelCommandLine=</varname></term>
 164           <listitem>
 165             <para>Checks whether a specific kernel command line option is
 166             set (or if prefixed with the exclamation mark unset). See
 167             <literal>ConditionKernelCommandLine=</literal> in
 168             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 169             for details.
 170             </para>
 171           </listitem>
 172         </varlistentry>
 173         <varlistentry>
 174           <term><varname>Architecture=</varname></term>
 175           <listitem>
 176             <para>Checks whether the system is running on a specific
 177             architecture. See <literal>ConditionArchitecture=</literal> in
 178             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 179             for details.
 180             </para>
 181           </listitem>
 182         </varlistentry>
 183       </variablelist>
 184
 185   </refsect1>
 186
 187   <refsect1>
 188     <title>[Link] Section Options</title>
 189
 190     <para> The <literal>[Link]</literal> section accepts the following keys:</para>
 191
 192     <variablelist class='network-directives'>
 193       <varlistentry>
 194         <term><varname>MACAddress=</varname></term>
 195         <listitem>
 196           <para>The hardware address.</para>
 197         </listitem>
 198       </varlistentry>
 199       <varlistentry>
 200         <term><varname>MTUBytes=</varname></term>
 201         <listitem>
 202           <para>The maximum transmission unit in bytes to set for the
 203           device. The usual suffixes K, M, G, are supported and are
 204           understood to the base of 1024.</para>
 205           <para>Note that if IPv6 is enabled on the interface, and the MTU is chosen
 206           below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value.</para>
 207         </listitem>
 208       </varlistentry>
 209       <varlistentry>
 210         <term><varname>IAID=</varname></term>
 211         <listitem>
 212           <para>Identity Association Identifier for the interface, a 32-bit unsigned integer.</para>
 213         </listitem>
 214       </varlistentry>
 215       <varlistentry>
 216       <listitem>
 217         <para>Note that an interface without any static IPv6 addresses configured, and neither
 218         DHCPv6 nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be
 219         automatically disabled for that interface by writing "1" to
 220         <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>.
 221         </para>
 222       </listitem>
 223       </varlistentry>
 224     </variablelist>
 225   </refsect1>
 226
 227   <refsect1>
 228     <title>[Network] Section Options</title>
 229
 230       <para>The <literal>[Network]</literal> section accepts the following keys:</para>
 231
 232       <variablelist class='network-directives'>
 233         <varlistentry>
 234           <term><varname>Description=</varname></term>
 235           <listitem>
 236             <para>A description of the device. This is only used for
 237             presentation purposes.</para>
 238           </listitem>
 239         </varlistentry>
 240         <varlistentry>
 241           <term><varname>DHCP=</varname></term>
 242           <listitem>
 243             <para>Enables DHCPv4 and/or DHCPv6 client support. Accepts
 244             <literal>yes</literal>, <literal>no</literal>,
 245             <literal>ipv4</literal>, or <literal>ipv6</literal>.</para>
 246
 247             <para>Note that DHCPv6 will by default be triggered by Router
 248             Advertisement, if that is enabled, regardless of this parameter.
 249             By enabling DHCPv6 support explicitly, the DHCPv6 client will
 250             be started regardless of the presence of routers on the link,
 251             or what flags the routers pass. See
 252             <literal>IPv6AcceptRouterAdvertisements=</literal>.</para>
 253
 254             <para>Furthermore, note that by default the domain name
 255             specified through DHCP is not used for name resolution.
 256             See option <option>UseDomains=</option> below.</para>
 257           </listitem>
 258         </varlistentry>
 259         <varlistentry>
 260           <term><varname>DHCPServer=</varname></term>
 261           <listitem>
 262             <para>A boolean. Enables DHCPv4 server support. Defaults
 263             to <literal>no</literal>. Further settings for the DHCP
 264             server may be set in the <literal>[DHCPServer]</literal>
 265             section described below.</para>
 266           </listitem>
 267         </varlistentry>
 268         <varlistentry>
 269           <term><varname>LinkLocalAddressing=</varname></term>
 270           <listitem>
 271             <para>Enables link-local address autoconfiguration. Accepts
 272             <literal>yes</literal>, <literal>no</literal>,
 273             <literal>ipv4</literal>, or <literal>ipv6</literal>. Defaults to
 274             <literal>ipv6</literal>.</para>
 275           </listitem>
 276         </varlistentry>
 277         <varlistentry>
 278           <term><varname>IPv4LLRoute=</varname></term>
 279           <listitem>
 280             <para>A boolean. When true, sets up the route needed for
 281             non-IPv4LL hosts to communicate with IPv4LL-only hosts. Defaults
 282             to false.
 283             </para>
 284           </listitem>
 285         </varlistentry>
 286         <varlistentry>
 287           <term><varname>IPv6Token=</varname></term>
 288           <listitem>
 289             <para>An IPv6 address with the top 64 bits unset. When set, indicates the
 290             64-bit interface part of SLAAC IPv6 addresses for this link. Note that
 291             the token is only ever used for SLAAC, and not for DHCPv6 addresses, even
 292             in the case DHCP is requested by router advertisement. By default, the
 293             token is autogenerated.</para>
 294           </listitem>
 295         </varlistentry>
 296         <varlistentry>
 297           <term><varname>LLMNR=</varname></term>
 298           <listitem>
 299             <para>A boolean or <literal>resolve</literal>. When true,
 300             enables <ulink
 301             url="https://tools.ietf.org/html/rfc4795">Link-Local
 302             Multicast Name Resolution</ulink> on the link. When set to
 303             <literal>resolve</literal>, only resolution is enabled,
 304             but not host registration and announcement. Defaults to
 305             true. This setting is read by
 306             <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 307           </listitem>
 308         </varlistentry>
 309         <varlistentry>
 310           <term><varname>MulticastDNS=</varname></term>
 311           <listitem>
 312             <para>A boolean or <literal>resolve</literal>. When true,
 313             enables <ulink
 314             url="https://tools.ietf.org/html/rfc6762">Multicast
 315             DNS</ulink> support on the link. When set to
 316             <literal>resolve</literal>, only resolution is enabled,
 317             but not host or service registration and
 318             announcement. Defaults to false. This setting is read by
 319             <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 320           </listitem>
 321         </varlistentry>
 322         <varlistentry>
 323           <term><varname>DNSSEC=</varname></term>
 324           <listitem>
 325             <para>A boolean or
 326             <literal>allow-downgrade</literal>. When true, enables
 327             <ulink
 328             url="https://tools.ietf.org/html/rfc4033">DNSSEC</ulink>
 329             DNS validation support on the link. When set to
 330             <literal>allow-downgrade</literal>, compatibility with
 331             non-DNSSEC capable networks is increased, by automatically
 332             turning off DNSEC in this case. This option defines a
 333             per-interface setting for
 334             <citerefentry><refentrytitle>resolved.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>'s
 335             global <varname>DNSSEC=</varname> option. Defaults to
 336             false. This setting is read by
 337             <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 338           </listitem>
 339         </varlistentry>
 340         <varlistentry>
 341           <term><varname>DNSSECNegativeTrustAnchors=</varname></term>
 342           <listitem><para>A space-separated list of DNSSEC negative
 343           trust anchor domains. If specified and DNSSEC is enabled,
 344           look-ups done via the interface's DNS server will be subject
 345           to the list of negative trust anchors, and not require
 346           authentication for the specified domains, or anything below
 347           it. Use this to disable DNSSEC authentication for specific
 348           private domains, that cannot be proven valid using the
 349           Internet DNS hierarchy. Defaults to the empty list. This
 350           setting is read by
 351           <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 352           </listitem>
 353         </varlistentry>
 354         <varlistentry>
 355           <term><varname>LLDP=</varname></term>
 356           <listitem>
 357             <para>Controls support for Ethernet LLDP packet reception. LLDP is a link-layer protocol commonly
 358             implemented on professional routers and bridges which announces which physical port a system is connected
 359             to, as well as other related data. Accepts a boolean or the special value
 360             <literal>routers-only</literal>. When true, incoming LLDP packets are accepted and a database of all LLDP
 361             neighbors maintained. If <literal>routers-only</literal> is set only LLDP data of various types of routers
 362             is collected and LLDP data about other types of devices ignored (such as stations, telephones and
 363             others). If false, LLDP reception is disabled. Defaults to <literal>routers-only</literal>. Use
 364             <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> to query the
 365             collected neighbor data. LLDP is only available on Ethernet links. See <varname>EmitLLDP=</varname> below
 366             for enabling LLDP packet emission from the local system.
 367             </para>
 368           </listitem>
 369         </varlistentry>
 370         <varlistentry>
 371           <term><varname>EmitLLDP=</varname></term>
 372           <listitem>
 373             <para>Controls support for Ethernet LLDP packet emission. Accepts a boolean parameter and defaults to
 374             false. If enabled a short LLDP packet with information about the local system is sent out in regular
 375             intervals on the link. The LLDP packet will contain information about the local host name, the local
 376             machine ID (as stored in
 377             <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>) and the
 378             local interface name, as well as the pretty hostname of the system (as set in
 379             <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>). LLDP
 380             emission is only available on Ethernet links. Note that this setting passed data suitable for
 381             identification of host to the network and should thus not be used on untrusted networks, where such
 382             identification data should not be made available. Use this option to enable other systems to identify on
 383             which interface they are connected to this system. See <varname>LLDP=</varname> above for an option to
 384             enable LLDP reception.</para>
 385           </listitem>
 386         </varlistentry>
 387         <varlistentry>
 388           <term><varname>BindCarrier=</varname></term>
 389           <listitem>
 390             <para>A link name or a list of link names. When set, controls the behavior of the current
 391             link. When all links in the list are in an operational down state, the current link is brought
 392             down. When at least one link has carrier, the current interface is brought up.
 393             </para>
 394           </listitem>
 395         </varlistentry>
 396         <varlistentry>
 397           <term><varname>Address=</varname></term>
 398           <listitem>
 399             <para>A static IPv4 or IPv6 address and its prefix length,
 400             separated by a <literal>/</literal> character. Specify
 401             this key more than once to configure several addresses.
 402             The format of the address must be as described in
 403             <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 404             This is a short-hand for an [Address] section only
 405             containing an Address key (see below). This option may be
 406             specified more than once.
 407             </para>
 408
 409             <para>If the specified address is 0.0.0.0 (for IPv4) or
 410             [::] (for IPv6), a new address range of the requested size
 411             is automatically allocated from a system-wide pool of
 412             unused ranges. The allocated range is checked against all
 413             current network interfaces and all known network
 414             configuration files to avoid address range conflicts. The
 415             default system-wide pool consists of 192.168.0.0/16,
 416             172.16.0.0/12 and 10.0.0.0/8 for IPv4, and fc00::/7 for
 417             IPv6. This functionality is useful to manage a large
 418             number of dynamically created network interfaces with the
 419             same network configuration and automatic address range
 420             assignment.</para>
 421
 422           </listitem>
 423         </varlistentry>
 424         <varlistentry>
 425           <term><varname>Gateway=</varname></term>
 426           <listitem>
 427             <para>The gateway address, which must be in the format
 428             described in
 429             <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 430             This is a short-hand for a [Route] section only containing
 431             a Gateway key. This option may be specified more than
 432             once.</para>
 433           </listitem>
 434         </varlistentry>
 435         <varlistentry>
 436           <term><varname>DNS=</varname></term>
 437           <listitem>
 438             <para>A DNS server address, which must be in the format
 439             described in
 440             <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 441             This option may be specified more than once. This setting is read by
 442             <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 443           </listitem>
 444         </varlistentry>
 445         <varlistentry>
 446           <term><varname>Domains=</varname></term>
 447           <listitem>
 448             <para>The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which
 449             are used as search suffixes for extending single-label host names (host names containing no dots) to become
 450             fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of
 451             the specified search domains are appended to it in turn, converting it into a fully qualified domain name,
 452             until one of them may be successfully resolved.</para>
 453
 454             <para>The specified domains are also used for routing of DNS queries: look-ups for host names ending in the
 455             domains specified here are preferably routed to the DNS servers configured for this interface. If a domain
 456             name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for
 457             DNS query routing purposes only and is not used in the described domain search logic. By specifying a
 458             routing domain of <literal>~.</literal> (the tilde indicating definition of a routing domain, the dot
 459             referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to
 460             route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is
 461             particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each
 462             interface.</para>
 463
 464             <para>This setting is read by
 465             <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 466           </listitem>
 467         </varlistentry>
 468         <varlistentry>
 469           <term><varname>NTP=</varname></term>
 470           <listitem>
 471             <para>An NTP server address. This option may be specified more than once. This setting is read by
 472             <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 473           </listitem>
 474         </varlistentry>
 475         <varlistentry>
 476           <term><varname>IPForward=</varname></term>
 477           <listitem><para>Configures IP packet forwarding for the
 478           system. If enabled, incoming packets on any network
 479           interface will be forwarded to any other interfaces
 480           according to the routing table. Takes either a boolean
 481           argument, or the values <literal>ipv4</literal> or
 482           <literal>ipv6</literal>, which only enable IP packet
 483           forwarding for the specified address family.  This controls
 484           the <filename>net.ipv4.ip_forward</filename> and
 485           <filename>net.ipv6.conf.all.forwarding</filename> sysctl
 486           options of the network interface (see <ulink
 487           url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink>
 488           for details about sysctl options). Defaults to
 489           <literal>no</literal>.</para>
 490
 491           <para>Note: this setting controls a global kernel option,
 492           and does so one way only: if a network that has this setting
 493           enabled is set up the global setting is turned on.  However,
 494           it is never turned off again, even after all networks with
 495           this setting enabled are shut down again.</para>
 496
 497           <para>To allow IP packet forwarding only between specific
 498           network interfaces use a firewall.</para>
 499           </listitem>
 500         </varlistentry>
 501         <varlistentry>
 502           <term><varname>IPMasquerade=</varname></term>
 503           <listitem><para>Configures IP masquerading for the network
 504           interface. If enabled, packets forwarded from the network
 505           interface will be appear as coming from the local host.
 506           Takes a boolean argument. Implies
 507           <varname>IPForward=ipv4</varname>. Defaults to
 508           <literal>no</literal>.</para></listitem>
 509         </varlistentry>
 510         <varlistentry>
 511           <term><varname>IPv6PrivacyExtensions=</varname></term>
 512           <listitem><para>Configures use of stateless temporary
 513           addresses that change over time (see <ulink
 514           url="https://tools.ietf.org/html/rfc4941">RFC 4941</ulink>,
 515           Privacy Extensions for Stateless Address Autoconfiguration
 516           in IPv6). Takes a boolean or the special values
 517           <literal>prefer-public</literal> and
 518           <literal>kernel</literal>. When true, enables the privacy
 519           extensions and prefers temporary addresses over public
 520           addresses. When <literal>prefer-public</literal>, enables the
 521           privacy extensions, but prefers public addresses over
 522           temporary addresses. When false, the privacy extensions
 523           remain disabled. When <literal>kernel</literal>, the kernel's
 524           default setting will be left in place.  Defaults to
 525           <literal>no</literal>.</para></listitem>
 526         </varlistentry>
 527         <varlistentry>
 528           <term><varname>IPv6AcceptRouterAdvertisements=</varname></term>
 529           <listitem><para>Force the setting of the <filename>accept_ra</filename>
 530           (router advertisements) setting for the interface.
 531           When unset, the kernel default is used, and router
 532           advertisements are accepted only when local forwarding
 533           is disabled for that interface.
 534           When router advertisements are accepted, they will
 535           trigger the start of the DHCPv6 client if the relevant
 536           flags are passed, or if no routers are found on the link.
 537           Takes a boolean. If true, router advertisements are
 538           accepted, when false, router advertisements are ignored,
 539           independently of the local forwarding state.</para>
 540
 541           <para>See
 542           <ulink url="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt">ip-sysctl.txt</ulink>
 543           in the kernel documentation, but note that systemd's
 544           setting of <constant>1</constant> corresponds to
 545           kernel's setting of <constant>2</constant>.</para>
 546         </listitem>
 547         </varlistentry>
 548         <varlistentry>
 549           <term><varname>IPv6DuplicateAddressDetection=</varname></term>
 550           <listitem><para>Configures the amount of IPv6 Duplicate
 551           Address Detection (DAD) probes to send. Defaults to unset.
 552         </para></listitem>
 553         </varlistentry>
 554         <varlistentry>
 555           <term><varname>IPv6HopLimit=</varname></term>
 556           <listitem><para>Configures IPv6 Hop Limit. For each router that
 557           forwards the packet, the hop limit is decremented by 1. When the
 558           hop limit field reaches zero, the packet is discarded.
 559           Defaults to unset.
 560         </para></listitem>
 561         </varlistentry>
 562         <varlistentry>
 563           <term><varname>ProxyARP=</varname></term>
 564           <listitem><para>A boolean. Configures proxy ARP. Proxy ARP is the technique in which one host,
 565           usually a router, answers ARP requests intended for another machine. By "faking" its identity,
 566           the router accepts responsibility for routing packets to the "real" destination. (see <ulink
 567           url="https://tools.ietf.org/html/rfc1027">RFC 1027</ulink>.
 568           Defaults to unset.
 569         </para></listitem>
 570         </varlistentry>
 571         <varlistentry>
 572           <term><varname>Bridge=</varname></term>
 573           <listitem>
 574             <para>The name of the bridge to add the link to.</para>
 575           </listitem>
 576         </varlistentry>
 577         <varlistentry>
 578           <term><varname>Bond=</varname></term>
 579           <listitem>
 580             <para>The name of the bond to add the link to.</para>
 581           </listitem>
 582         </varlistentry>
 583         <varlistentry>
 584           <term><varname>VLAN=</varname></term>
 585           <listitem>
 586             <para>The name of a VLAN to create on the link. This
 587             option may be specified more than once.</para>
 588           </listitem>
 589         </varlistentry>
 590         <varlistentry>
 591           <term><varname>MACVLAN=</varname></term>
 592           <listitem>
 593             <para>The name of a MACVLAN to create on the link. This
 594             option may be specified more than once.</para>
 595           </listitem>
 596         </varlistentry>
 597         <varlistentry>
 598           <term><varname>VXLAN=</varname></term>
 599           <listitem>
 600             <para>The name of a VXLAN to create on the link. This
 601             option may be specified more than once.</para>
 602           </listitem>
 603         </varlistentry>
 604         <varlistentry>
 605           <term><varname>Tunnel=</varname></term>
 606           <listitem>
 607             <para>The name of a Tunnel to create on the link. This
 608             option may be specified more than once.</para>
 609           </listitem>
 610         </varlistentry>
 611       </variablelist>
 612
 613   </refsect1>
 614
 615   <refsect1>
 616     <title>[Address] Section Options</title>
 617
 618       <para>An <literal>[Address]</literal> section accepts the
 619       following keys. Specify several <literal>[Address]</literal>
 620       sections to configure several addresses.</para>
 621
 622       <variablelist class='network-directives'>
 623         <varlistentry>
 624           <term><varname>Address=</varname></term>
 625           <listitem>
 626             <para>As in the <literal>[Network]</literal> section. This
 627             key is mandatory.</para>
 628           </listitem>
 629         </varlistentry>
 630         <varlistentry>
 631           <term><varname>Peer=</varname></term>
 632           <listitem>
 633             <para>The peer address in a point-to-point connection.
 634             Accepts the same format as the <literal>Address</literal>
 635             key.</para>
 636           </listitem>
 637         </varlistentry>
 638         <varlistentry>
 639           <term><varname>Broadcast=</varname></term>
 640           <listitem>
 641             <para>The broadcast address, which must be in the format
 642             described in
 643             <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 644             This key only applies to IPv4 addresses. If it is not
 645             given, it is derived from the <literal>Address</literal>
 646             key.</para>
 647           </listitem>
 648         </varlistentry>
 649         <varlistentry>
 650           <term><varname>Label=</varname></term>
 651           <listitem>
 652             <para>An address label.</para>
 653           </listitem>
 654         </varlistentry>
 655       </variablelist>
 656   </refsect1>
 657
 658   <refsect1>
 659     <title>[Route] Section Options</title>
 660       <para>The <literal>[Route]</literal> section accepts the
 661       following keys. Specify several <literal>[Route]</literal>
 662       sections to configure several routes.</para>
 663
 664       <variablelist class='network-directives'>
 665         <varlistentry>
 666           <term><varname>Gateway=</varname></term>
 667           <listitem>
 668             <para>As in the <literal>[Network]</literal> section.</para>
 669           </listitem>
 670         </varlistentry>
 671         <varlistentry>
 672           <term><varname>Destination=</varname></term>
 673           <listitem>
 674             <para>The destination prefix of the route. Possibly
 675             followed by a slash and the prefix length. If omitted, a
 676             full-length host route is assumed.</para>
 677           </listitem>
 678         </varlistentry>
 679         <varlistentry>
 680           <term><varname>Source=</varname></term>
 681           <listitem>
 682             <para>The source prefix of the route. Possibly followed by
 683             a slash and the prefix length. If omitted, a full-length
 684             host route is assumed.</para>
 685           </listitem>
 686         </varlistentry>
 687         <varlistentry>
 688           <term><varname>Metric=</varname></term>
 689           <listitem>
 690             <para>The metric of the route (an unsigned integer).</para>
 691           </listitem>
 692         </varlistentry>
 693         <varlistentry>
 694           <term><varname>Scope=</varname></term>
 695           <listitem>
 696             <para>The scope of the route, which can be <literal>global</literal>,
 697             <literal>link</literal> or <literal>host</literal>. Defaults to
 698             <literal>global</literal>.</para>
 699           </listitem>
 700         </varlistentry>
 701         <varlistentry>
 702           <term><varname>PreferredSource=</varname></term>
 703           <listitem>
 704             <para>The preferred source address of the route. The address
 705             must be in the format described in
 706             <citerefentry project='man-pages'><refentrytitle>inet_pton</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 707           </listitem>
 708         </varlistentry>
 709       </variablelist>
 710   </refsect1>
 711
 712   <refsect1>
 713     <title>[DHCP] Section Options</title>
 714       <para>The <literal>[DHCP]</literal> section configures the
 715       DHCPv4 and DHCP6 client, if it is enabled with the
 716       <varname>DHCP=</varname> setting described above:</para>
 717
 718       <variablelist class='network-directives'>
 719         <varlistentry>
 720           <term><varname>UseDNS=</varname></term>
 721           <listitem>
 722             <para>When true (the default), the DNS servers received
 723             from the DHCP server will be used and take precedence over
 724             any statically configured ones.</para>
 725
 726             <para>This corresponds to the <option>nameserver</option>
 727             option in <citerefentry
 728             project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 729           </listitem>
 730         </varlistentry>
 731         <varlistentry>
 732           <term><varname>UseNTP=</varname></term>
 733           <listitem>
 734             <para>When true (the default), the NTP servers received
 735             from the DHCP server will be used by systemd-timesyncd
 736             and take precedence over any statically configured ones.</para>
 737           </listitem>
 738         </varlistentry>
 739         <varlistentry>
 740           <term><varname>UseMTU=</varname></term>
 741           <listitem>
 742             <para>When true, the interface maximum transmission unit
 743             from the DHCP server will be used on the current link.
 744             Defaults to false.</para>
 745           </listitem>
 746         </varlistentry>
 747         <varlistentry>
 748           <term><varname>SendHostname=</varname></term>
 749           <listitem>
 750             <para>When true (the default), the machine's hostname will
 751             be sent to the DHCP server.</para>
 752           </listitem>
 753         </varlistentry>
 754         <varlistentry>
 755           <term><varname>UseHostname=</varname></term>
 756           <listitem>
 757             <para>When true (the default), the hostname received from
 758             the DHCP server will be set as the transient hostname of the system
 759             </para>
 760           </listitem>
 761         </varlistentry>
 762         <varlistentry>
 763         <term><varname>Hostname=</varname></term>
 764         <listitem>
 765           <para>Use this value for the hostname which is sent to the
 766           DHCP server, instead of machine's hostname.</para>
 767         </listitem>
 768       </varlistentry>
 769         <varlistentry>
 770           <term><varname>UseDomains=</varname></term>
 771           <listitem>
 772             <para>Takes a boolean argument, or the special value <literal>route</literal>. When true, the domain name
 773             received from the DHCP server will be used as DNS search domain over this link, similar to the effect of
 774             the <option>Domains=</option> setting. If set to <literal>route</literal>, the domain name received from
 775             the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of
 776             the <option>Domains=</option> setting when the argument is prefixed with <literal>~</literal>. Defaults to
 777             false.</para>
 778
 779             <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution
 780             of all host names, in particular to single-label names. It is generally safer to use the supplied domain
 781             only as routing domain, rather than as search domain, in order to not have it affect local resolution of
 782             single-label names.</para>
 783
 784             <para>When set to true, this setting corresponds to the <option>domain</option> option in <citerefentry
 785             project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 786           </listitem>
 787         </varlistentry>
 788         <varlistentry>
 789           <term><varname>UseRoutes=</varname></term>
 790           <listitem>
 791             <para>When true (the default), the static routes will be
 792             requested from the DHCP server and added to the routing
 793             table with a metric of 1024.</para>
 794           </listitem>
 795         </varlistentry>
 796
 797         <varlistentry>
 798           <term><varname>UseTimezone=</varname></term>
 799
 800           <listitem><para>When true, the timezone received from the
 801           DHCP server will be set as timezone of the local
 802           system. Defaults to <literal>no</literal>.</para></listitem>
 803         </varlistentry>
 804
 805         <varlistentry>
 806           <term><varname>CriticalConnection=</varname></term>
 807           <listitem>
 808             <para>When true, the connection will never be torn down
 809             even if the DHCP lease expires. This is contrary to the
 810             DHCP specification, but may be the best choice if, say,
 811             the root filesystem relies on this connection. Defaults to
 812             false.</para>
 813           </listitem>
 814         </varlistentry>
 815         <varlistentry>
 816           <term><varname>ClientIdentifier=</varname></term>
 817           <listitem>
 818             <para>The DHCPv4 client identifier to use. Either <literal>mac</literal> to use the MAC address of the link
 819             or <literal>duid</literal> (the default, see below) to use a RFC4361-compliant Client ID.</para>
 820           </listitem>
 821         </varlistentry>
 822         <varlistentry>
 823           <term><varname>VendorClassIdentifier=</varname></term>
 824           <listitem>
 825             <para>The vendor class identifier used to identify vendor
 826             type and configuration.</para>
 827           </listitem>
 828         </varlistentry>
 829         <varlistentry>
 830           <term><varname>DUIDRawData=</varname></term>
 831           <listitem><para>Specifies the DHCP DUID bytes as a single newline-terminated, hexadecimal string, with each
 832           byte separated by a ':'.  A DHCPv6 client sends the DHCP Unique Identifier (DUID) and the interface Identity
 833           Association Identifier (IAID) to a DHCP server when acquiring a dynamic IPv6 address. Similar, DHCPv4 clients
 834           send the IAID and DUID to the DHCP server when acquiring a dynamic IPv4 address if
 835           <option>ClientIdentifier=duid</option>. IAID and DUID allows a DHCP server to uniquely identify the machine
 836           and the interface requesting a DHCP IP address.</para>
 837
 838           <para>The DUID value specified here takes precedence over the DUID that systemd-networkd generates
 839           using the machine-id from the <filename>/etc/machine-id</filename> file, as well as the
 840           global DUID that may be specified in <citerefentry><refentrytitle>networkd.conf
 841           </refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 842
 843           <para>The configured DHCP DUID should conform to the specification in
 844           <ulink url="http://tools.ietf.org/html/rfc3315#section-9">RFC 3315</ulink>,
 845           <ulink url="http://tools.ietf.org/html/rfc6355">RFC 6355</ulink>.</para>
 846           </listitem>
 847         </varlistentry>
 848         <varlistentry>
 849           <term><varname>RequestBroadcast=</varname></term>
 850           <listitem>
 851             <para>Request the server to use broadcast messages before
 852             the IP address has been configured. This is necessary for
 853             devices that cannot receive RAW packets, or that cannot
 854             receive packets at all before an IP address has been
 855             configured. On the other hand, this must not be enabled on
 856             networks where broadcasts are filtered out.</para>
 857           </listitem>
 858         </varlistentry>
 859         <varlistentry>
 860           <term><varname>RouteMetric=</varname></term>
 861           <listitem>
 862             <para>Set the routing metric for routes specified by the
 863             DHCP server.</para>
 864           </listitem>
 865         </varlistentry>
 866       </variablelist>
 867     </refsect1>
 868
 869   <refsect1>
 870     <title>[DHCPServer] Section Options</title>
 871     <para>The <literal>[DHCPServer]</literal> section contains
 872     settings for the DHCP server, if enabled via the
 873     <varname>DHCPServer=</varname> option described above:</para>
 874
 875     <variablelist class='network-directives'>
 876
 877       <varlistentry>
 878         <term><varname>PoolOffset=</varname></term>
 879         <term><varname>PoolSize=</varname></term>
 880
 881         <listitem><para>Configures the pool of addresses to hand out. The pool
 882         is a contiguous sequence of IP addresses in the subnet configured for
 883         the server address, which does not include the subnet nor the broadcast
 884         address. <varname>PoolOffset=</varname> takes the offset of the pool
 885         from the start of subnet, or zero to use the default value.
 886         <varname>PoolSize=</varname> takes the number of IP addresses in the
 887         pool or zero to use the default value. By default, the pool starts at
 888         the first address after the subnet address and takes up the rest of
 889         the subnet, excluding the broadcast address. If the pool includes
 890         the server address (the default), this is reserved and not handed
 891         out to clients.</para></listitem>
 892       </varlistentry>
 893
 894       <varlistentry>
 895         <term><varname>DefaultLeaseTimeSec=</varname></term>
 896         <term><varname>MaxLeaseTimeSec=</varname></term>
 897
 898         <listitem><para>Control the default and maximum DHCP lease
 899         time to pass to clients. These settings take time values in seconds or
 900         another common time unit, depending on the suffix. The default
 901         lease time is used for clients that did not ask for a specific
 902         lease time. If a client asks for a lease time longer than the
 903         maximum lease time, it is automatically shortened to the
 904         specified time. The default lease time defaults to 1h, the
 905         maximum lease time to 12h. Shorter lease times are beneficial
 906         if the configuration data in DHCP leases changes frequently
 907         and clients shall learn the new settings with shorter
 908         latencies. Longer lease times reduce the generated DHCP
 909         network traffic.</para></listitem>
 910       </varlistentry>
 911
 912       <varlistentry>
 913         <term><varname>EmitDNS=</varname></term>
 914         <term><varname>DNS=</varname></term>
 915
 916         <listitem><para>Configures whether the DHCP leases handed out
 917         to clients shall contain DNS server information. The
 918         <varname>EmitDNS=</varname> setting takes a boolean argument
 919         and defaults to <literal>yes</literal>. The DNS servers to
 920         pass to clients may be configured with the
 921         <varname>DNS=</varname> option, which takes a list of IPv4
 922         addresses. If the <varname>EmitDNS=</varname> option is
 923         enabled but no servers configured, the servers are
 924         automatically propagated from an "uplink" interface that has
 925         appropriate servers set. The "uplink" interface is determined
 926         by the default route of the system with the highest
 927         priority. Note that this information is acquired at the time
 928         the lease is handed out, and does not take uplink interfaces
 929         into account that acquire DNS or NTP server information at a
 930         later point. DNS server propagation does not take
 931         <filename>/etc/resolv.conf</filename> into account. Also, note
 932         that the leases are not refreshed if the uplink network
 933         configuration changes. To ensure clients regularly acquire the
 934         most current uplink DNS server information, it is thus
 935         advisable to shorten the DHCP lease time via
 936         <varname>MaxLeaseTimeSec=</varname> described
 937         above.</para></listitem>
 938       </varlistentry>
 939
 940       <varlistentry>
 941         <term><varname>EmitNTP=</varname></term>
 942         <term><varname>NTP=</varname></term>
 943
 944         <listitem><para>Similar to the <varname>EmitDNS=</varname> and
 945         <varname>DNS=</varname> settings described above, these
 946         settings configure whether and what NTP server information
 947         shall be emitted as part of the DHCP lease. The same syntax,
 948         propagation semantics and defaults apply as for
 949         <varname>EmitDNS=</varname> and
 950         <varname>DNS=</varname>.</para></listitem>
 951       </varlistentry>
 952
 953       <varlistentry>
 954         <term><varname>EmitTimezone=</varname></term>
 955         <term><varname>Timezone=</varname></term>
 956
 957         <listitem><para>Configures whether the DHCP leases handed out
 958         to clients shall contain timezone information. The
 959         <varname>EmitTimezone=</varname> setting takes a boolean
 960         argument and defaults to <literal>yes</literal>. The
 961         <varname>Timezone=</varname> setting takes a timezone string
 962         (such as <literal>Europe/Berlin</literal> or
 963         <literal>UTC</literal>) to pass to clients. If no explicit
 964         timezone is set, the system timezone of the local host is
 965         propagated, as determined by the
 966         <filename>/etc/localtime</filename> symlink.</para></listitem>
 967       </varlistentry>
 968
 969     </variablelist>
 970   </refsect1>
 971
 972   <refsect1>
 973     <title>[Bridge] Section Options</title>
 974       <para>The <literal>[Bridge]</literal> section accepts the
 975       following keys.</para>
 976       <variablelist class='network-directives'>
 977         <varlistentry>
 978           <term><varname>UnicastFlood=</varname></term>
 979           <listitem>
 980             <para>A boolean. Controls whether the bridge should flood
 981             traffic for which an FDB entry is missing and the destination
 982             is unknown through this port. Defaults to on.
 983             </para>
 984           </listitem>
 985         </varlistentry>
 986         <varlistentry>
 987           <term><varname>HairPin=</varname></term>
 988           <listitem>
 989             <para>A boolean. Configures whether traffic may be sent back
 990             out of the port on which it was received. By default, this
 991             flag is false, and the bridge will not forward traffic back
 992             out of the receiving port.</para>
 993           </listitem>
 994         </varlistentry>
 995         <varlistentry>
 996           <term><varname>UseBPDU=</varname></term>
 997           <listitem>
 998             <para>A boolean. Configures whether STP Bridge Protocol Data Units will be
 999             processed by the bridge port. Defaults to yes.</para>
1000           </listitem>
1001         </varlistentry>
1002         <varlistentry>
1003           <term><varname>FastLeave=</varname></term>
1004           <listitem>
1005             <para>A boolean. This flag allows the bridge to immediately stop multicast
1006             traffic on a port that receives an IGMP Leave message. It is only used with
1007             IGMP snooping if enabled on the bridge. Defaults to off.</para>
1008           </listitem>
1009         </varlistentry>
1010         <varlistentry>
1011           <term><varname>AllowPortToBeRoot=</varname></term>
1012           <listitem>
1013             <para>A boolean. Configures whether a given port is allowed to
1014             become a root port. Only used when STP is enabled on the bridge.
1015             Defaults to on.</para>
1016           </listitem>
1017         </varlistentry>
1018         <varlistentry>
1019           <term><varname>Cost=</varname></term>
1020           <listitem>
1021             <para>Sets the "cost" of sending packets of this interface.
1022             Each port in a bridge may have a different speed and the cost
1023             is used to decide which link to use. Faster interfaces
1024             should have lower costs.</para>
1025           </listitem>
1026         </varlistentry>
1027       </variablelist>
1028   </refsect1>
1029   <refsect1>
1030     <title>[BridgeFDB] Section Options</title>
1031       <para>The <literal>[BridgeFDB]</literal> section manages the
1032       forwarding database table of a port and accepts the following
1033       keys. Specify several <literal>[BridgeFDB]</literal> sections to
1034       configure several static MAC table entries.</para>
1035
1036       <variablelist class='network-directives'>
1037         <varlistentry>
1038           <term><varname>MACAddress=</varname></term>
1039           <listitem>
1040             <para>As in the <literal>[Network]</literal> section. This
1041             key is mandatory.</para>
1042           </listitem>
1043         </varlistentry>
1044         <varlistentry>
1045           <term><varname>VLANId=</varname></term>
1046           <listitem>
1047             <para>The VLAN ID for the new static MAC table entry. If
1048             omitted, no VLAN ID info is appended to the new static MAC
1049             table entry.</para>
1050           </listitem>
1051         </varlistentry>
1052       </variablelist>
1053   </refsect1>
1054
1055   <refsect1>
1056     <title>Example</title>
1057     <example>
1058       <title>/etc/systemd/network/50-static.network</title>
1059
1060       <programlisting>[Match]
1061 Name=enp2s0
1062
1063 [Network]
1064 Address=192.168.0.15/24
1065 Gateway=192.168.0.1</programlisting>
1066     </example>
1067
1068     <example>
1069       <title>/etc/systemd/network/80-dhcp.network</title>
1070
1071       <programlisting>[Match]
1072 Name=en*
1073
1074 [Network]
1075 DHCP=yes</programlisting>
1076     </example>
1077
1078     <example>
1079       <title>/etc/systemd/network/25-bridge-static.network</title>
1080
1081       <programlisting>[Match]
1082 Name=bridge0
1083
1084 [Network]
1085 Address=192.168.0.15/24
1086 Gateway=192.168.0.1
1087 DNS=192.168.0.1</programlisting>
1088     </example>
1089
1090     <example>
1091       <title>/etc/systemd/network/25-bridge-slave-interface.network</title>
1092
1093       <programlisting>[Match]
1094 Name=enp2s0
1095
1096 [Network]
1097 Bridge=bridge0</programlisting>
1098     </example>
1099     <example>
1100       <title>/etc/systemd/network/25-ipip.network</title>
1101
1102       <programlisting>[Match]
1103 Name=em1
1104
1105 [Network]
1106 Tunnel=ipip-tun</programlisting>
1107     </example>
1108
1109     <example>
1110       <title>/etc/systemd/network/25-sit.network</title>
1111
1112       <programlisting>[Match]
1113 Name=em1
1114
1115 [Network]
1116 Tunnel=sit-tun</programlisting>
1117     </example>
1118
1119     <example>
1120       <title>/etc/systemd/network/25-gre.network</title>
1121
1122       <programlisting>[Match]
1123 Name=em1
1124
1125 [Network]
1126 Tunnel=gre-tun</programlisting>
1127     </example>
1128
1129     <example>
1130       <title>/etc/systemd/network/25-vti.network</title>
1131
1132       <programlisting>[Match]
1133 Name=em1
1134
1135 [Network]
1136 Tunnel=vti-tun</programlisting>
1137     </example>
1138
1139     <example>
1140       <title>/etc/systemd/network/25-bond.network</title>
1141
1142       <programlisting>[Match]
1143 Name=bond1
1144
1145 [Network]
1146 DHCP=yes
1147 </programlisting>
1148     </example>
1149
1150   </refsect1>
1151
1152   <refsect1>
1153     <title>See Also</title>
1154     <para>
1155       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1156       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1157       <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1158       <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1159       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
1160     </para>
1161   </refsect1>
1162
1163 </refentry>