From 52e957d47f40e855dc236759b5f0afe73e9c0b2e Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Mon, 27 Jan 2025 18:08:31 +0100 Subject: [PATCH] doc: add documentation for DHCPv4 server Fixes #798 Signed-off-by: Joachim Wiberg --- doc/dhcp.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++ doc/networking.md | 43 ++++++------ doc/system.md | 109 +++++++++++++++++++++-------- 3 files changed, 273 insertions(+), 50 deletions(-) create mode 100644 doc/dhcp.md diff --git a/doc/dhcp.md b/doc/dhcp.md new file mode 100644 index 00000000..323c83ee --- /dev/null +++ b/doc/dhcp.md @@ -0,0 +1,171 @@ +DHCP Server +=========== + +The DHCPv4 server provides automatic IP address assignment and network +configuration for clients. It supports address pools, static host +assignments, and customizable DHCP options. It also serves as a DNS +proxy for local subnets and can even forward queries to upstream DNS +servers[^1]. + +> [!NOTE] +> When using the CLI, the system automatically enables essential options +> like DNS servers and default gateway based on the system's network +> configuration. These options can be disabled, changed or overridden, +> at any level: global, subnet, or per-host. + + +## Basic Configuration + +The following example configures a DHCP server for subnet 192.168.2.0/24 +with an address pool: + +``` +admin@example:/> configure +admin@example:/config/> edit dhcp-server +admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave +``` + +When setting up the server from the CLI, the system automatically adds a +few default DHCP options that will be sent to clients: both DNS server +and default gateway will use the system address on the matching +interface. + +``` +admin@example:/> show running-config + "infix-dhcp-server:dhcp-server": { + "subnet": [ + { + "subnet": "192.168.2.0/24", + "option": [ + { + "id": "dns-server", + "address": "auto" + }, + { + "id": "router", + "address": "auto" + } + ], + "pool": { + "start-address": "192.168.2.100", + "end-address": "192.168.2.200" + } + } + ] + } +``` + +> [!IMPORTANT] +> Remember to set up an interface in this subnet, avoid using addresses +> in the DHCP pool, or reserved for static hosts. In Class C networks +> the router usually has address `.1`. Depending on the use-case, you +> may also want to set up routing. + + +## Static Host Assignment + +To reserve specific IP addresses for clients based on their MAC address, +hostname, or client ID: + +``` +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit host 192.168.2.10 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/host/192.168.2.10/> set match mac-address 00:11:22:33:44:55 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/host/192.168.2.10/> set hostname printer +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/host/192.168.2.10/> leave +``` + +Match hosts using a client identifier instead of MAC address: + +``` +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> edit host 192.168.1.50 +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/> edit match +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/match/> set client-id hex c0:ff:ee +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/match/> leave +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/> set lease-time infinite +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/host/192.168.1.50/> leave +``` + +The `hex` prefix here ensures matching of client ID is done using the +hexadecimal octets `c0:ff:ee`, three bytes. Without the prefix the +ASCII string "c0:ff:ee", eight bytes, is used. + +> [!NOTE] +> The DHCP server is fully RFC conformant, in the case of option 61 this +> means that using the `hex` prefix will require the client to set the +> `htype` field of the option to `00`. See RFC 2132 for details. + + +## Custom DHCP Options + +Configure additional DHCP options globally, per subnet, or per host: + +``` +admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option dns-server +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> set address 8.8.8.8 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> leave +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option ntp-server +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> set address 192.168.2.1 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> leave +``` + +When configuring, e.g., `dns-server`, or `router` options with the value +`auto`, the system uses the IP address from the interface matching the +subnet. For example: + +``` +admin@example:/> show interfaces brief +Interface Status Address +eth0 UP 192.168.1.1/24 +eth1 UP 192.168.2.1/24 + +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> edit option dns-server +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> set address auto +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> leave +``` + +In this case, clients in subnet 192.168.1.0/24 will receive 192.168.1.1 +as their DNS server address. + + +## Multiple Subnets + +Configure DHCP for multiple networks: + +``` +admin@example:/> configure +admin@example:/config/> edit dhcp-server +admin@example:/config/dhcp-server/> edit subnet 192.168.1.0/24 +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> set pool start-address 192.168.1.100 end-address 192.168.1.200 +admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> leave +admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200 +admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave +``` + + +## Monitoring + +View active leases and server statistics: + +``` +admin@example:/> show dhcp-server +IP ADDRESS MAC HOSTNAME CLIENT ID EXPIRES +192.168.2.22 00:a0:85:00:02:05 00:c0:ff:ee 3591s +192.168.1.11 00:a0:85:00:04:06 foo 01:00:a0:85:00:04:06 3591s + +admin@example:/> show dhcp-server statistics +DHCP offers sent : 6 +DHCP ACK messages sent : 5 +DHCP NAK messages sent : 0 +DHCP decline messages received : 0 +DHCP discover messages received : 6 +DHCP request messages received : 5 +DHCP release messages received : 6 +DHCP inform messages received : 6 +``` + + +[^1]: This requires the system DNS resolver to be configured. diff --git a/doc/networking.md b/doc/networking.md index feed42ed..fcbc70a7 100644 --- a/doc/networking.md +++ b/doc/networking.md @@ -664,31 +664,31 @@ are listed below. Configurable options can be disabled on a per client interface basis, some options, like `clientid` and option 81, are possible to set the value of as well. -| **Opt** | **Name** | **Cfg** | **Description** | -|---------|------------------|---------|-----------------------------------------------------| -| 1 | `subnet` | No | Request IP address and netmask | -| 3 | `router` | Yes | Default route(s), see also option 121 and 249 | -| 6 | `dns` | Yes | DNS server(s), static ones take precedence | -| 12 | `hostname` | Yes | DHCP cannot set hostname, only for informing server | -| 15 | `domain` | Yes | Default domain name, for name resolution | -| 28 | `broadcast` | Yes | Broadcast address, calculated if disabled | -| 42 | `ntpsrv` | Yes | NTP server(s), static ones take precedence | -| 50 | `address` | Yes | Request (previously cached) address | -| 61 | `clientid` | Yes | Default MAC address (and option 12) | -| 81 | `fqdn` | Yes | Similar to option 12, request FQDN update in DNS | -| 119 | `search` | Yes | Request domain search list | -| 121 | `staticroutes` | Yes | Classless static routes | -| 249 | `msstaticroutes` | Yes | Microsoft static route | -| | | | | +| **Opt** | **Name** | **Cfg** | **Description** | +|---------|-----------------------------|---------|-----------------------------------------------------| +| 1 | `netmask` | No | Request IP address and netmask | +| 3 | `router` | Yes | Default route(s), see also option 121 and 249 | +| 6 | `dns-server` | Yes | DNS server(s), static ones take precedence | +| 12 | `hostname` | Yes | DHCP cannot set hostname, only for informing server | +| 15 | `domain` | Yes | Default domain name, for name resolution | +| 28 | `broadcast` | Yes | Broadcast address, calculated if disabled | +| 42 | `ntp-server` | Yes | NTP server(s), static ones take precedence | +| 50 | `address` | Yes | Request (previously cached) address | +| 61 | `client-id` | Yes | Default MAC address (and option 12) | +| 81 | `fqdn` | Yes | Similar to option 12, request FQDN update in DNS | +| 119 | `search` | Yes | Request domain search list | +| 121 | `classless-static-route` | Yes | Classless static routes | +| 249 | `ms-classless-static-route` | Yes | Microsoft static route, same as option 121 | +| | | | | -**Default:** `router`, `dns`, `domain`, `broadcast`, `ntpsrv`, `search`, - `address`, `staticroutes`, `msstaticroutes` +**Default:** `router`, `dns-server`, `domain`, `broadcast`, `ntp-server`, `search`, + `address`, `classless-static-route`, `ms-classless-static-route` When configuring a DHCP client, ensure that the NTP client is enabled -for the `ntpsrv` DHCP option to be processed correctly. If the NTP +for the `ntp-server` DHCP option to be processed correctly. If the NTP client is not enabled, any NTP servers provided by the DHCP server will -be ignored. For details on how to enable the NTP client, see the -[NTP Client Configuration](system.md#ntp-client-configuration) section. +be ignored. For details on how to enable the NTP client, see the [NTP +Client Configuration](system.md#ntp-client-configuration) section. > [!IMPORTANT] > Per [RFC3442][4], if the DHCP server returns both a Classless Static @@ -781,7 +781,6 @@ will be used, otherwise it falls back to the default algorithm. admin@example:/> configure admin@example:/config/> edit dhcp-client admin@example:/config/dhcp-client/> set client-if eth0 - admin@example:/config/dhcp-client/> set enabled true admin@example:/config/dhcp-client/> leave admin@example:/> show interfaces INTERFACE PROTOCOL STATE DATA diff --git a/doc/system.md b/doc/system.md index 81dd8d77..02d9b644 100644 --- a/doc/system.md +++ b/doc/system.md @@ -11,9 +11,10 @@ specific string followed by the last three octets of the system base MAC address, e.g., `switch-12-34-56`. An example of how to change the hostname is included below. -> **Note:** when issuing `leave` to activate your changes, remember to -> also save your settings, `copy running-config startup-config`. See -> the [CLI Introduction](cli/introduction.md) for a background. +> [!NOTE] +> When issuing `leave` to activate your changes, remember to also save +> your settings, `copy running-config startup-config`. See the [CLI +> Introduction](cli/introduction.md) for a background. ## Changing Password @@ -39,7 +40,8 @@ the `do password encrypt` command. This launches the admin-exec command to hash, and optionally salt, your password. This encrypted string can then be used with `set password ...`. -> **Tip:** if you are having trouble thinking of a password, Infix has a +> [!TIP] +> If you are having trouble thinking of a password, there is a nifty > `password generate` command in admin-exec context which generates > random passwords using the UNIX command `pwgen`. Use the `do` prefix > when inside any configuration context to access admin-exec commands. @@ -65,9 +67,10 @@ key-data AAAAB3NzaC1yc2EAAAADAQABAAABgQC8iBL42yeMBioFay7lty1C4ZDTHcHyo739gc91rTT admin@host:/config/system/authentication/user/admin/authorized-key/example@host/> leave ``` -> **Note:** the `ssh-keygen` program already base64 encodes the public -> key data, so there is no need to use the `text-editor` command, `set` -> does the job. +> [!NOTE] +> The `ssh-keygen` program already base64 encodes the public key data, +> so there is no need to use the `text-editor` command, `set` does the +> job. ## Multiple Users @@ -145,7 +148,7 @@ is committed by issuing the `leave` command. admin@host:/config/> edit system admin@host:/config/system/> set hostname example admin@host:/config/system/> leave -admin@host:/> +admin@example:/> ``` The hostname is advertised over mDNS-SD in the `.local` domain. If @@ -154,8 +157,24 @@ case, mDNS will advertise a "uniqified" variant, usually suffixing with an index, e.g., `example-1.local`. Use an mDNS browser to scan for available devices on your LAN. -> **Note:** critical services like syslog, mDNS, LLDP, and similar that -> advertise the hostname, are restarted when the hostname is changed. +In some cases you may want to set the device's *domain name* as well. +This is handled the same way: + +``` +admin@host:/config/> edit system +admin@host:/config/system/> set hostname foo.example.com +admin@host:/config/system/> leave +admin@foo:/> +``` + +Both host and domain name are stored in the system files `/etc/hosts` +and `/etc/hostname`. The latter is exclusively for the host name. The +domain *may* be used by the system DHCP server when handing out leases +to clients, it is up to the clients to request the domain name *option*. + +> [!NOTE] +> Critical services like syslog, mDNS, LLDP, and similar that advertise +> the hostname, are restarted when the hostname is changed. ## Changing Login Banner @@ -164,8 +183,9 @@ The `motd-banner` setting is an Infix augment and an example of a `binary` type setting that can be changed interactively with the built-in [`text-editor` command](cli/text-editor.md). -> **Tip:** see the next section for how to change the editor used -> to something you may be more familiar with. +> [!TIP] +> See the next section for how to change the editor used to something +> you may be more familiar with. ``` admin@host:/config/> edit system @@ -196,24 +216,55 @@ admin@host:/config/system/> leave admin@host:/> ``` -> **Note:** as usual, configuration changes only take effect after -> issuing the `leave` command. I.e., you must change the editor first, -> and then re-enter configure context to use your editor of choice. +> [!IMPORTANT] +> Configuration changes only take effect after issuing the `leave` +> command. I.e., you must change the editor first, and then re-enter +> configure context to use your editor of choice. + + +## DNS Resolver Configuration + +The system supports both static and dynamic (DHCP) DNS setup. The +locally configured (static) server is preferred over any acquired +from a DHCP client. + +``` +admin@host:/> configure +admin@host:/config/> edit system dns-resolver +admin@host:/config/system/dns-resolver/> set server google udp-and-tcp address 8.8.8.8 +admin@host:/config/system/dns-resolver/> show +server google { + udp-and-tcp { + address 8.8.8.8; + } +} +admin@host:/config/system/dns-resolver/> leave +``` + +It is also possible to configure resolver options like timeout and +retry attempts. See the YANG model for details, or use the built-in +help system in the CLI. + +> [!NOTE] +> When acting as a DHCP server and DNS proxy for other devices, any +> local DNS server configured here is automatically used as upstream DNS +> server. ## NTP Client Configuration -Below is an example configuration for enabling NTP -with a specific server and the `iburst` option for faster initial -synchronization. +Below is an example configuration for enabling NTP with a specific +server and the `iburst` option for faster initial synchronization. ``` admin@host:/> configure -admin@host:/config/> set system ntp enabled -admin@host:/config/> set system ntp server ntp-pool -admin@host:/config/> set system ntp server ntp-pool udp address pool.ntp.org -admin@host:/config/> set system ntp server ntp-pool iburst -admin@host:/config/> set system ntp server ntp-pool prefer +admin@host:/config/> edit system ntp +admin@host:/config/system/ntp/> set enabled +admin@host:/config/system/ntp/> set server ntp-pool +admin@host:/config/system/ntp/> set server ntp-pool udp address pool.ntp.org +admin@host:/config/system/ntp/> set server ntp-pool iburst +admin@host:/config/system/ntp/> set server ntp-pool prefer +admin@host:/config/system/ntp/> leave ``` This configuration enables the NTP client and sets the NTP server to @@ -227,6 +278,7 @@ metrics (default config). * `prefer true`: The NTP client will try to use the preferred server as the primary source unless it becomes unreachable or unusable. + ### Show NTP Sources The status for NTP sources is availble in YANG and accessable with @@ -242,8 +294,9 @@ ADDRESS MODE STATE STRATUM POLL-INTERVAL ``` ### Show NTP Status -To check the status of NTP synchronization (only availble in CLI), use the following command: +To check the status of NTP synchronization (only availble in CLI), use +the following command: ``` admin@host:/> show ntp tracking @@ -266,11 +319,11 @@ admin@host:/> This output provides detailed information about the NTP status, including reference ID, stratum, time offsets, frequency, and root delay. - -> The system uses `chronyd` for Network Time Protocol (NTP) -> synchronization. The output shown here is best explained in the -> [Chrony documentation](https://chrony-project.org/doc/4.6.1/chronyc.html). +> [!TIP] +> The system uses `chronyd` Network Time Protocol (NTP) daemon. The +> output shown here is best explained in the [Chrony documentation][4]. [1]: https://www.rfc-editor.org/rfc/rfc7317 [2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/infix-system%402024-02-29.yang [3]: https://www.rfc-editor.org/rfc/rfc8341 +[4]: https://chrony-project.org/doc/4.6.1/chronyc.html