peter/infix
1
0
Fork 0
mirror of https://github.com/kernelkit/infix.git synced 2026-08-02 05:43:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc: add documentation for DHCPv4 server

Browse Source 
Fixes #798

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2025-01-31 13:56:40 +01:00
parent 95cfcaa2fe
commit 52e957d47f
3 changed files with 273 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/dhcp.md
+171
View File
@@ -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.
doc/networking.md
+21 -22
View File
@@ -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
doc/system.md
+81 -28
View File
@@ -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