man: document DHCP relay configuration

diff --git a/man/networkd.conf.xml b/man/networkd.conf.xml
index f611e244f5aaf831120334418f7fc8ea0a697772..8dd1181508d3993bd271782fce7b5c4053fb7dc5 100644 (file)
--- a/man/networkd.conf.xml
+++ b/man/networkd.conf.xml
@@ -393,6 +393,67 @@ DUIDRawData=00:00:ab:11:f9:2a:c2:77:29:f9:5c:00</programlisting>
     </variablelist>
   </refsect1>
 
+  <refsect1>
+    <title>[DHCPRelay] Section Options</title>
+    <para>The [DHCPRelay] section contains host-wide settings for the DHCP relay agent.</para>
+
+    <variablelist class='network-directives'>
+
+      <varlistentry>
+        <term><varname>ServerAddress=</varname></term>
+        <listitem>
+          <para>Specifies the IPv4 address of the upstream DHCP server. This is required for the host to act
+          as a DHCP relay agent.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>OverrideServerIdentifier=</varname></term>
+        <listitem>
+          <para>Takes a boolean value. When enabled, the Server Identifier Override sub-option and the Relay
+          Agent Flags sub-option in the Relay Agent Information option will be appended to the DHCP message
+          forwarded to the upstream DHCP server. Defaults to false.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>RemoteId=</varname></term>
+        <listitem>
+          <para>Specifies the remote ID, which is typically used by DHCP servers to identify the DHCP relay
+          agent. Takes a data type and data separated with a colon
+          (<literal><replaceable>type</replaceable>:<replaceable>value</replaceable></literal>). The type
+          takes one of <literal>uint8</literal>, <literal>uint16</literal>, <literal>uint32</literal>,
+          <literal>ipv4address</literal>, <literal>ipv6address</literal>, or <literal>string</literal>.
+          Special characters in the data string may be escaped using
+          <ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C-style escapes</ulink>.
+          If unset, a UUID generated from the local machine ID will be used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ExtraOption=</varname></term>
+        <listitem>
+          <para>Specifies an extra sub-option in the Relay Agent Information option, which is appended to
+          DHCP messages forwarded to the upstream DHCP server. Takes a sub-option code, data type, and data
+          separated with a colon
+          (<literal><replaceable>code</replaceable>:<replaceable>type</replaceable>:<replaceable>value</replaceable></literal>).
+          The code is an integer in 1…254. See <varname>RemoteId=</varname> in the above for the acceptable
+          type and data. This setting can be specified multiple times. When an empty string is specified,
+          all previous assignments are cleared. Defaults to unset, and no extra sub-option will be appended.
+          </para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
   <refsect1>
     <title>[DHCPServer] Section Options</title>
 

diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index d62e4d62329eda6e9ed452095d601df2df87d5bc..fcb700bff03aa88eac7aadca6a66bc9cdf9127a4 100644 (file)
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -435,6 +435,26 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>DHCPRelay=</varname></term>
+        <listitem>
+          <para>Takes one of <literal>upstream</literal> or <literal>downstream</literal>. When specified,
+          the host acts as a DHCP relay agent. When set to <literal>upstream</literal>, the interface behaves
+          as an upstream interface of the DHCP relay agent. When set to <literal>downstream</literal>, the
+          interface behaves as a downstream interface of the DHCP relay agent. To make the DHCP relay agent
+          work, at least one upstream interface and one downstream interface must be configured on the host.
+          This requires <varname>ServerAddress=</varname> in the [DHCPRelay] section to be configured in
+          <filename>networkd.conf</filename>. If <varname>ServerAddress=</varname> is not configured, this
+          setting is ignored. See
+          <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+          for more details about <varname>ServerAddress=</varname> and other host-wide settings.
+          Also, further per-interface settings can be configured in the [DHCPRelay] section described below.
+          Defaults to unset, and the interface is not used for DHCP relay forwarding.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>DHCPServer=</varname></term>
         <listitem>
@@ -3868,6 +3888,104 @@ Token=prefixstable:2002:da8:1::</programlisting></para>
     </variablelist>
   </refsect1>
 
+  <refsect1>
+    <title>[DHCPRelay] Section Options</title>
+    <para>The [DHCPRelay] section contains per-interface settings for the DHCP relay agent. The settings in
+    this section are only used when <varname>DHCPRelay=</varname> in the [Network] section is configured.
+    </para>
+
+    <variablelist class='network-directives'>
+
+      <varlistentry>
+        <term><varname>AgentAddress=</varname></term>
+        <listitem>
+          <para>Takes an IPv4 address. The specified address is used as the source IP address of packets
+          forwarded to the upstream DHCP server. The address may also be used for the Server Identifier
+          Override sub-option and the Link Selection sub-option in the Relay Agent Information option
+          appended to DHCP messages forwarded to the upstream DHCP server. This setting applies to both
+          upstream and downstream interfaces. Defaults to unset. If unset, a statically configured IPv4
+          address in the .network file is selected automatically. When multiple static IPv4 addresses are
+          configured, it is recommended to specify this setting explicitly.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>GatewayAddress=</varname></term>
+        <listitem>
+          <para>Takes an IPv4 address. The specified address is set to the <literal>giaddr</literal> field of
+          the DHCP message header when the DHCP message is forwarded to the upstream DHCP server. This is
+          used only when <varname>DHCPRelay=downstream</varname>, and ignored otherwise. Defaults to unset,
+          and the same address specified with <varname>AgentAddress=</varname> will be used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>CircuitId=</varname></term>
+        <listitem>
+          <para>Specifies the circuit ID of the downstream interface. This is set as the Circuit ID
+          sub-option in the Relay Agent Information option in the forwarded DHCP message. Takes a data type
+          and data separated with a colon
+          (<literal><replaceable>type</replaceable>:<replaceable>value</replaceable></literal>). The type
+          takes one of <literal>uint8</literal>, <literal>uint16</literal>, <literal>uint32</literal>,
+          <literal>ipv4address</literal>, <literal>ipv6address</literal>, or <literal>string</literal>.
+          Special characters in the data string may be escaped using
+          <ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C-style escapes</ulink>.
+          This is used only when <varname>DHCPRelay=downstream</varname>, and ignored otherwise. If unset,
+          the name of the interface will be used.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>VirtualSubnetSelection=</varname></term>
+        <listitem>
+          <para>Specifies a unique identifier used by the DHCP server to select the downstream subnet
+          independently of giaddr. This value is used as the Virtual Subnet Selection sub-option in the Relay
+          Agent Information option in the forwarded DHCP message. Takes a value in the same format as
+          <varname>CircuitId=</varname>. This is used only when <varname>DHCPRelay=downstream</varname>, and
+          ignored otherwise. Defaults to unset, and the sub-option is not set.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ExtraOption=</varname></term>
+        <listitem>
+          <para>Specifies an extra sub-option in the Relay Agent Information option, which is appended to
+          DHCP messages forwarded to the upstream DHCP server. Takes a sub-option code, data type, and data
+          separated with a colon
+          (<literal><replaceable>code</replaceable>:<replaceable>type</replaceable>:<replaceable>value</replaceable></literal>).
+          The code is an integer in 1…254. See <varname>CircuitId=</varname> in the above for the acceptable
+          type and data. This setting can be specified multiple times. When an empty string is specified,
+          all previous assignments are cleared. This is used only when
+          <varname>DHCPRelay=downstream</varname>, and ignored otherwise. Defaults to unset, and no extra
+          sub-option will be appended.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>InterfacePriority=</varname></term>
+        <listitem>
+          <para>Specifies the priority of the upstream interface. Takes an integer value. When the host has
+          multiple upstream interfaces, the upstream interface with the highest (largest) priority will be
+          used for forwarding DHCP messages to the upstream DHCP server. When multiple interfaces have the
+          same priority, which interface is used is unspecified. This is used only when
+          <varname>DHCPRelay=upstream</varname>, and ignored otherwise. Defaults to zero.</para>
+
+          <xi:include href="version-info.xml" xpointer="v261"/>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
   <refsect1>
     <title>[DHCPServer] Section Options</title>
     <para>The [DHCPServer] section contains settings for the DHCP server, if enabled via the