From: Zbigniew Jędrzejewski-Szmek Date: Fri, 14 May 2021 06:58:44 +0000 (+0200) Subject: man: reorder items in [DHCPv4] and [DHCPv6] sections X-Git-Tag: v249-rc1~228^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c3696a9111a0803d6ee9273d8e9a4649704d2388;p=thirdparty%2Fsystemd.git man: reorder items in [DHCPv4] and [DHCPv6] sections The settings were listen in a completely random order, also different between the v4 and v6 sections. Order by "options sent", "options received", "communication settings" in both sections. Also minor formatting changes are done, e.g. "=" is added in various places. --- diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 5c1c6e118ee..15ba1dfb06d 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1616,56 +1616,101 @@ IPv6Token=prefixstable:2002:da8:1:: DHCP= setting described above: + + + - UseDNS= + SendHostname= - When true (the default), the DNS servers received from the DHCP server will be used. + When true (the default), the machine's hostname will be sent to the DHCP server. + Note that the machine's hostname must consist only of 7-bit ASCII lower-case characters and + no spaces or dots, and be formatted as a valid DNS domain name. Otherwise, the hostname is not + sent even if this is set to true. + + - This corresponds to the - option in resolv.conf5. + + Hostname= + + Use this value for the hostname which is sent to the DHCP server, instead of machine's hostname. + Note that the specified hostname must consist only of 7-bit ASCII lower-case characters and + no spaces or dots, and be formatted as a valid DNS domain name. + - RoutesToDNS= + MUDURL= - When true, the routes to the DNS servers received from the DHCP server will be - configured. When UseDNS= is disabled, this setting is ignored. - Defaults to true. + When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to the + DHCPv4 server. Takes a URL of length up to 255 characters. A superficial verification that the + string is a valid URL will be performed. DHCPv4 clients are intended to have at most one MUD URL + associated with them. See RFC 8520. + + + MUD is an embedded software standard defined by the IETF that allows IoT device makers to + advertise device specifications, including the intended communication patterns for their device + when it connects to the network. The network can then use this to author a context-specific + access policy, so the device functions only within those parameters. + - UseNTP= + ClientIdentifier= - When true (the default), the NTP servers received from the DHCP server will be used by - systemd-timesyncd.service. + The DHCPv4 client identifier to use. Takes one of , + or . If set to , the + MAC address of the link is used. If set to , an RFC4361-compliant Client + ID, which is the combination of IAID and DUID (see below), is used. If set to + , only DUID is used, this may not be RFC compliant, but some setups + may require to use this. Defaults to . + - RoutesToNTP= + VendorClassIdentifier= - When true, the routes to the NTP servers received from the DHCP server will be - configured. When UseNTP= is disabled, this setting is ignored. - Defaults to true. + The vendor class identifier used to identify vendor + type and configuration. + - UseSIP= + UserClass= - When true (the default), the SIP servers received from the DHCP server will be collected - and made available to client programs. + A DHCPv4 client can use UserClass option to identify the type or category of user or + applications it represents. The information contained in this option is a string that represents + the user class of which the client is a member. Each class sets an identifying string of + information to be used by the DHCP service to classify clients. Takes a whitespace-separated list + of strings. - UseMTU= + DUIDType= - When true, the interface maximum transmission unit - from the DHCP server will be used on the current link. - If MTUBytes= is set, then this setting is ignored. - Defaults to false. + Override the global DUIDType= setting for this network. See + networkd.conf5 + for a description of possible values. + + + DUIDRawData= + + Override the global DUIDRawData= setting for this network. See + networkd.conf5 + for a description of possible values. + + + + + IAID= + + The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned + integer. + + + Anonymize= @@ -1674,7 +1719,7 @@ IPv6Token=prefixstable:2002:da8:1:: DHCP Clients) to minimize disclosure of identifying information. Defaults to false. This option should only be set to true when MACAddressPolicy= is - set to random (see + set to (see systemd.link5). @@ -1689,166 +1734,142 @@ IPv6Token=prefixstable:2002:da8:1:: though most of the requested data is not actually used. - - SendHostname= - - When true (the default), the machine's hostname will be sent to the DHCP server. - Note that the machine's hostname must consist only of 7-bit ASCII lower-case characters and - no spaces or dots, and be formatted as a valid DNS domain name. Otherwise, the hostname is not - sent even if this is set to true. - - - MUDURL= + RequestOptions= - When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to the - DHCPv4 server. Takes a URL of length up to 255 characters. A superficial verification that the - string is a valid URL will be performed. DHCPv4 clients are intended to have at most one MUD URL - associated with them. See RFC 8520. - - - MUD is an embedded software standard defined by the IETF that allows IoT device makers to - advertise device specifications, including the intended communication patterns for their device - when it connects to the network. The network can then use this to author a context-specific - access policy, so the device functions only within those parameters. + Sets request options to be sent to the server in the DHCPv4 request options list. A + whitespace-separated list of integers in the range 1…254. Defaults to unset. - UseHostname= + SendOption= - When true (the default), the hostname received from - the DHCP server will be set as the transient hostname of the system. - + Send an arbitrary raw option in the DHCPv4 request. Takes a DHCP option number, data type + and data separated with a colon + (option:type:value). + The option number must be an integer in the range 1…254. The type takes one of + uint8, uint16, uint32, + ipv4address, or string. Special characters in the data + string may be escaped using C-style + escapes. This setting can be specified multiple times. If an empty string is specified, + then all options specified earlier are cleared. Defaults to unset. + - Hostname= + SendVendorOption= - Use this value for the hostname which is sent to the DHCP server, instead of machine's hostname. - Note that the specified hostname must consist only of 7-bit ASCII lower-case characters and - no spaces or dots, and be formatted as a valid DNS domain name. + Send an arbitrary vendor option in the DHCPv4 request. Takes a DHCP option number, data + type and data separated with a colon + (option:type:value). + The option number must be an integer in the range 1…254. The type takes one of + uint8, uint16, uint32, + ipv4address, or string. Special characters in the data + string may be escaped using C-style + escapes. This setting can be specified multiple times. If an empty string is specified, + then all options specified earlier are cleared. Defaults to unset. - - UseDomains= - - Takes a boolean, or the special value route. When true, the domain name - received from the DHCP server will be used as DNS search domain over this link, similar to the effect of - the setting. If set to route, the domain name received from - the DHCP server will be used for routing DNS queries only, but not for searching, similar to the effect of - the setting when the argument is prefixed with ~. Defaults to - false. - It is recommended to enable this option only on trusted networks, as setting this affects resolution - of all hostnames, in particular of single-label names. It is generally safer to use the supplied domain - only as routing domain, rather than as search domain, in order to not have it affect local resolution of - single-label names. + - When set to true, this setting corresponds to the option in resolv.conf5. - - - - UseRoutes= - - When true (the default), the static routes will be requested from the DHCP server and added to the - routing table with a metric of 1024, and a scope of "global", "link" or "host", depending on the route's - destination and gateway. If the destination is on the local host, e.g., 127.x.x.x, or the same as the - link's own address, the scope will be set to "host". Otherwise if the gateway is null (a direct route), a - "link" scope will be used. For anything else, scope defaults to "global". - - - UseGateway= + UseDNS= - When true, the gateway will be requested from the DHCP server and added to the routing table with a - metric of 1024, and a scope of "link". When unset, the value specified with - is used. + When true (the default), the DNS servers received from the DHCP server will be used. + + This corresponds to the + option in resolv.conf5. - - UseTimezone= - When true, the timezone received from the - DHCP server will be set as timezone of the local - system. Defaults to no. - - ClientIdentifier= + RoutesToDNS= - The DHCPv4 client identifier to use. Takes one of mac, duid or duid-only. - If set to mac, the MAC address of the link is used. - If set to duid, an RFC4361-compliant Client ID, which is the combination of IAID and DUID (see below), is used. - If set to duid-only, only DUID is used, this may not be RFC compliant, but some setups may require to use this. - Defaults to duid. + When true, the routes to the DNS servers received from the DHCP server will be + configured. When UseDNS= is disabled, this setting is ignored. + Defaults to true. - VendorClassIdentifier= + UseNTP= - The vendor class identifier used to identify vendor - type and configuration. + When true (the default), the NTP servers received from the DHCP server will be used by + systemd-timesyncd.service. - UserClass= + RoutesToNTP= - A DHCPv4 client can use UserClass option to identify the type or category of user or applications - it represents. The information contained in this option is a string that represents the user class of which - the client is a member. Each class sets an identifying string of information to be used by the DHCP - service to classify clients. Takes a whitespace-separated list of strings. + When true, the routes to the NTP servers received from the DHCP server will be + configured. When UseNTP= is disabled, this setting is ignored. + Defaults to true. - MaxAttempts= + UseSIP= - Specifies how many times the DHCPv4 client configuration should be attempted. Takes a - number or infinity. Defaults to infinity. Note that the - time between retries is increased exponentially, up to approximately one per minute, so the - network will not be overloaded even if this number is high. The default is suitable in most - circumstances. + When true (the default), the SIP servers received from the DHCP server will be collected + and made available to client programs. - DUIDType= + UseMTU= - Override the global DUIDType setting for this network. See - networkd.conf5 - for a description of possible values. + When true, the interface maximum transmission unit from the DHCP server will be used on the + current link. If MTUBytes= is set, then this setting is ignored. Defaults to + false. - DUIDRawData= + UseHostname= - Override the global DUIDRawData setting for this network. See - networkd.conf5 - for a description of possible values. + When true (the default), the hostname received from the DHCP server will be set as the + transient hostname of the system. - IAID= + UseDomains= - The DHCP Identity Association Identifier (IAID) for the interface, a 32-bit unsigned integer. + Takes a boolean, or the special value . When true, the domain name + received from the DHCP server will be used as DNS search domain over this link, similar to the + effect of the setting. If set to , the domain + name received from the DHCP server will be used for routing DNS queries only, but not for + searching, similar to the effect of the setting when the argument is + prefixed with ~. Defaults to false. + + It is recommended to enable this option only on trusted networks, as setting this affects + resolution of all hostnames, in particular of single-label names. It is generally safer to use + the supplied domain only as routing domain, rather than as search domain, in order to not have it + affect local resolution of single-label names. + + When set to true, this setting corresponds to the option in + resolv.conf5. + - RequestBroadcast= + UseRoutes= - Request the server to use broadcast messages before - the IP address has been configured. This is necessary for - devices that cannot receive RAW packets, or that cannot - receive packets at all before an IP address has been - configured. On the other hand, this must not be enabled on - networks where broadcasts are filtered out. + When true (the default), the static routes will be requested from the DHCP server and added + to the routing table with a metric of 1024, and a scope of , + or , depending on the route's destination and + gateway. If the destination is on the local host, e.g., 127.x.x.x, or the same as the link's own + address, the scope will be set to . Otherwise if the gateway is null (a + direct route), a scope will be used. For anything else, scope defaults to + . @@ -1880,13 +1901,21 @@ IPv6Token=prefixstable:2002:da8:1:: - ListenPort= + UseGateway= - Allow setting custom port for the DHCP client to listen on. + When true, the gateway will be requested from the DHCP server and added to the routing + table with a metric of 1024, and a scope of . When unset, the value specified + with UseRoutes= is used. - + + UseTimezone= + When true, the timezone received from the DHCP server will be set as timezone of + the local system. Defaults to false. + + + FallbackLeaseLifetimeSec= Allows to set DHCPv4 lease lifetime when DHCPv4 server does not send the lease lifetime. @@ -1895,81 +1924,74 @@ IPv6Token=prefixstable:2002:da8:1:: + + - SendRelease= + RequestBroadcast= - When true, the DHCPv4 client sends a DHCP release packet when it stops. - Defaults to true. + Request the server to use broadcast messages before the IP address has been configured. + This is necessary for devices that cannot receive RAW packets, or that cannot receive packets at + all before an IP address has been configured. On the other hand, this must not be enabled on + networks where broadcasts are filtered out. - SendDecline= + MaxAttempts= - A boolean. When true, the DHCPv4 client receives the IP address from the - DHCP server. After a new IP is received, the DHCPv4 client performs IPv4 Duplicate Address - Detection. If duplicate use is detected, the DHCPv4 client rejects the IP by sending a - DHCPDECLINE packet and tries to obtain an IP address again. See RFC 5224. Defaults to - unset. + Specifies how many times the DHCPv4 client configuration should be attempted. Takes a + number or infinity. Defaults to infinity. Note that the + time between retries is increased exponentially, up to approximately one per minute, so the + network will not be overloaded even if this number is high. The default is suitable in most + circumstances. - DenyList= - - A whitespace-separated list of IPv4 addresses. DHCP offers from servers in the list are rejected. Note that - if AllowList= is configured then DenyList= is ignored. - + ListenPort= + + Allow setting custom port for the DHCP client to listen on. + - AllowList= - - A whitespace-separated list of IPv4 addresses. DHCP offers from servers in the list are accepted. - + DenyList= + + A whitespace-separated list of IPv4 addresses. DHCP offers from servers in the list are + rejected. Note that if AllowList= is configured then + DenyList= is ignored. + - RequestOptions= + AllowList= - Sets request options to be sent to the server in the DHCPv4 request options list. A - whitespace-separated list of integers in the range 1…254. Defaults to unset. + A whitespace-separated list of IPv4 addresses. DHCP offers from servers in the list are + accepted. - SendOption= + SendRelease= - Send an arbitrary raw option in the DHCPv4 request. Takes a DHCP option number, data type - and data separated with a colon - (option:type:value). - The option number must be an integer in the range 1…254. The type takes one of - uint8, uint16, uint32, - ipv4address, or string. Special characters in the data - string may be escaped using C-style - escapes. This setting can be specified multiple times. If an empty string is specified, - then all options specified earlier are cleared. Defaults to unset. + When true, the DHCPv4 client sends a DHCP release packet when it stops. Defaults to + true. - SendVendorOption= + SendDecline= - Send an arbitrary vendor option in the DHCPv4 request. Takes a DHCP option number, data - type and data separated with a colon - (option:type:value). - The option number must be an integer in the range 1…254. The type takes one of - uint8, uint16, uint32, - ipv4address, or string. Special characters in the data - string may be escaped using C-style - escapes. This setting can be specified multiple times. If an empty string is specified, - then all options specified earlier are cleared. Defaults to unset. + A boolean. When true, the DHCPv4 client receives the IP address from the + DHCP server. After a new IP is received, the DHCPv4 client performs IPv4 Duplicate Address + Detection. If duplicate use is detected, the DHCPv4 client rejects the IP by sending a + DHCPDECLINE packet and tries to obtain an IP address again. See RFC 5224. Defaults to + unset. - + + @@ -1978,88 +2000,67 @@ IPv6Token=prefixstable:2002:da8:1:: DHCP= setting described above, or invoked by the IPv6 Router Advertisement: - - UseAddress= - - When true (the default), the IP addresses provided by the DHCPv6 server will be - assigned. - - + + - UseDNS= - UseNTP= - UseHostname= - UseDomains= + MUDURL= IAID= DUIDType= DUIDRawData= + RequestOptions= As in the [DHCPv4] section. - RapidCommit= - - Takes a boolean. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through - a rapid two-message exchange (solicit and reply). When the rapid commit option is enabled by both - the DHCPv6 client and the DHCPv6 server, the two-message exchange is used, rather than the default - four-message exchange (solicit, advertise, request, and reply). The two-message exchange provides - faster client configuration and is beneficial in environments in which networks are under a heavy load. - See RFC 3315 for details. - Defaults to true. - - - - - MUDURL= + SendOption= - When configured, the specified Manufacturer Usage Description (MUD) URL will be sent to - the DHCPv6 server. The syntax and semantics are the same as for MUDURL= in the - [DHCPv4] section described above. + As in the [DHCPv4] section, however because DHCPv6 uses 16-bit fields to store option + numbers, the option number is an integer in the range 1…65536. - RequestOptions= + SendVendorOption= - When configured, allows to set arbitrary request options in the DHCPv6 request options list - that will be sent to the DHCPv6 server. A whitespace-separated list of integers in the range - 1…254. Defaults to unset. + Send an arbitrary vendor option in the DHCPv6 request. Takes an enterprise identifier, DHCP + option number, data type, and data separated with a colon (enterprise + identifier:option:type:value). + Enterprise identifier is an unsigned integer in the range 1…4294967294. The option number must be + an integer in the range 1…254. Data type takes one of uint8, + uint16, uint32, ipv4address, + ipv6address, or string. Special characters in the data + string may be escaped using C-style + escapes. This setting can be specified multiple times. If an empty string is specified, + then all options specified earlier are cleared. Defaults to unset. - SendVendorOption= + UserClass= - Send an arbitrary vendor option in the DHCPv6 request. Takes an enterprise identifier, DHCP - option number, data type, and data separated with a colon (enterprise - identifier:option:type: - value). Enterprise identifier is an unsigned integer in the - range 1–4294967294. The option number must be an integer in the range 1–254. Data type takes one - of uint8, uint16, uint32, - ipv4address, ipv6address, or - string. Special characters in the data string may be escaped using A DHCPv6 client can use User Class option to identify the type or category of user or + applications it represents. The information contained in this option is a string that represents + the user class of which the client is a member. Each class sets an identifying string of + information to be used by the DHCP service to classify clients. Special characters in the data + string may be escaped using C-style escapes. This setting can be specified multiple times. If an empty string is specified, - then all options specified earlier are cleared. Defaults to unset. + then all options specified earlier are cleared. Takes a whitespace-separated list of + strings. Note that currently NUL bytes are not allowed. - ForceDHCPv6PDOtherInformation= + VendorClass= - Takes a boolean that enforces DHCPv6 stateful mode when the 'Other information' bit is set in - Router Advertisement messages. By default setting only the 'O' bit in Router Advertisements - makes DHCPv6 request network information in a stateless manner using a two-message Information - Request and Information Reply message exchange. - RFC 7084, requirement WPD-4, updates - this behavior for a Customer Edge router so that stateful DHCPv6 Prefix Delegation is also - requested when only the 'O' bit is set in Router Advertisements. This option enables such a CE - behavior as it is impossible to automatically distinguish the intention of the 'O' bit otherwise. - By default this option is set to 'false', enable it if no prefixes are delegated when the device - should be acting as a CE router. + A DHCPv6 client can use VendorClass option to identify the vendor that manufactured the + hardware on which the client is running. The information contained in the data area of this + option is contained in one or more opaque fields that identify details of the hardware + configuration. Takes a whitespace-separated list of strings. @@ -2073,45 +2074,63 @@ IPv6Token=prefixstable:2002:da8:1:: + + - WithoutRA= + UseAddress= - Allows DHCPv6 client to start without router advertisements's managed or other address - configuration flag. Takes one of solicit or - information-request. Defaults to unset. + When true (the default), the IP addresses provided by the DHCPv6 server will be + assigned. - SendOption= + UseDNS= + UseNTP= + UseHostname= + UseDomains= - As in the [DHCPv4] section, however because DHCPv6 uses 16-bit fields to store - option numbers, the option number is an integer in the range 1…65536. + As in the [DHCPv4] section. + + - UserClass= + ForceDHCPv6PDOtherInformation= - A DHCPv6 client can use User Class option to identify the type or category of user or applications - it represents. The information contained in this option is a string that represents the user class of which - the client is a member. Each class sets an identifying string of information to be used by the DHCP - service to classify clients. Special characters in the data string may be escaped using - C-style - escapes. This setting can be specified multiple times. If an empty string is specified, - then all options specified earlier are cleared. Takes a whitespace-separated list of strings. Note that - currently NUL bytes are not allowed. + Takes a boolean that enforces DHCPv6 stateful mode when the 'Other information' bit is set in + Router Advertisement messages. By default setting only the 'O' bit in Router Advertisements + makes DHCPv6 request network information in a stateless manner using a two-message Information + Request and Information Reply message exchange. + RFC 7084, requirement WPD-4, updates + this behavior for a Customer Edge router so that stateful DHCPv6 Prefix Delegation is also + requested when only the 'O' bit is set in Router Advertisements. This option enables such a CE + behavior as it is impossible to automatically distinguish the intention of the 'O' bit otherwise. + By default this option is set to false, enable it if no prefixes are delegated when the device + should be acting as a CE router. - VendorClass= + WithoutRA= + + Allows DHCPv6 client to start without router advertisements's managed or other address + configuration flag. Takes one of solicit or + information-request. Defaults to unset. + + + + + RapidCommit= - A DHCPv6 client can use VendorClass option to identify the vendor that - manufactured the hardware on which the client is running. The information - contained in the data area of this option is contained in one or more opaque - fields that identify details of the hardware configuration. Takes a - whitespace-separated list of strings. + Takes a boolean. The DHCPv6 client can obtain configuration parameters from a DHCPv6 server through + a rapid two-message exchange (solicit and reply). When the rapid commit option is enabled by both + the DHCPv6 client and the DHCPv6 server, the two-message exchange is used, rather than the default + four-message exchange (solicit, advertise, request, and reply). The two-message exchange provides + faster client configuration and is beneficial in environments in which networks are under a heavy load. + See RFC 3315 for details. + Defaults to true.