diff --git a/Configuration.md b/Configuration.md index 1a3102f..e3370c1 100644 --- a/Configuration.md +++ b/Configuration.md @@ -11,7 +11,6 @@ Most of these settings can be changed via the web-based admin interface. However - [Configuration file](#configuration-file) - [Reset Web Password](#password-reset) - [Profiling with pprof](#pprof) -- [Additional DHCP options](#dhcp-options) @@ -224,21 +223,24 @@ Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possib - `name` — Name of the filter. If it's an adguard syntax filter it will get updated automatically, otherwise it stays unchanged. - `last_updated` — Time when the filter was last updated from server. - `ID` - filter ID (must be unique). -- `dhcp` - Built-in DHCP server configuration. +- `dhcp` - Built-in DHCP server configuration. See also the [DHCP] article. - `enabled` - DHCP server status. - - `interface_name` - network interface name (eth0, en0 and so on). - - `dhcpv4` - DHCPv4 settings + - `interface_name` - network interface name (`eth0`, `en0`, and so on). + - `dhcpv4` - DHCPv4 settings. - `gateway_ip` - gateway IP address. - `subnet_mask` - subnet mask. - - `range_start` - start IP address of the controlled range. - - `range_end` - end IP address of the controlled range. - - `lease_duration` - lease duration in seconds. If 0, using default duration (24 hours). - - `options` - custom options with arbitrary hex data (`DEC_CODE hex HEX_DATA`) or IP address (`DEC_CODE ip IP_ADDR`) where DEC_CODE is a decimal DHCPv4 option code in range [1..255] - - `dhcpv6` - DHCPv6 settings - - `range_start` - the first IP address to be assigned to a client - - `lease_duration` - lease TTL in seconds - - `ra_slaac_only` - send RA packets forcing the clients to use SLAAC - - `ra_allow_slaac` - send RA packets making the clients to choose between SLAAC and DHCPv6 + - `range_start`, `range_end` - the start and the end of the leased IP + address range. + - `lease_duration` - lease duration in seconds. If `0`, use the default + duration of 24 hours. + - `options` - custom DHCP options. See the [DHCP] article section on these + options for more information. + - `dhcpv6` - DHCPv6 settings. + - `range_start` - the first IP address to be assigned to a client. + - `lease_duration` - same as in v4 above. + - `ra_slaac_only` and `ra_allow_slaac` - send RA packets either forcing the + clients to use SLAAC or allowing them to choose. See the [DHCP] article + section on these options for more information. - `tls` - HTTPS/DOH/DOT settings. - `enabled` - encryption (DOT/DOH/HTTPS) status. - `server_name` - the hostname of your HTTPS/TLS server. @@ -268,6 +270,7 @@ Settings are stored in [YAML format](https://en.wikipedia.org/wiki/YAML), possib Removing an entry from settings file will reset it to the default value. Deleting the file will reset all settings to the default values. +[DHCP]: https://github.com/AdguardTeam/AdGuardHome/wiki/DHCP [DNSCrypt]: https://github.com/AdguardTeam/AdGuardHome/wiki/DNSCrypt [`dnscrypt`]: https://github.com/ameshkov/dnscrypt @@ -306,33 +309,3 @@ or with `go tool pprof`: go tool pprof -top http://localhost:6060/debug/pprof/heap For a list of supported profiles go to `http://localhost:6060/debug/pprof/`. - - - -## Additional DHCP options - -There are several configuration parameters for DHCP that can't be set via AGH administrator dashboard. - -`dhcp.dhcpv4.options` - list of DHCPv4 custom options - -Option with arbitrary hexadecimal data: - - DEC_CODE hex HEX_DATA - -where DEC_CODE is a decimal DHCPv4 option code in range [1..255] - -Option with IP data (only 1 IP is supported): - - DEC_CODE ip IP_ADDR - -Example: - - ... - options: - - 123 hex abcdef - - 123 ip 1.2.3.4 - -`dhcp.dhcpv6.ra_slaac_only` - if `true`, send RA packets forcing the clients to use SLAAC. -DHCPv6 server won't be started in this case. - -`dhcp.dhcpv6.ra_allow_slaac` - if `true`, send RA packets making the clients to choose between SLAAC and DHCPv6 diff --git a/DHCP.md b/DHCP.md new file mode 100644 index 0000000..f202dd5 --- /dev/null +++ b/DHCP.md @@ -0,0 +1,95 @@ + # *AdGuard Home* - DHCP Server + + * [Prerequisites](#prereq) + * [Default Options](#default) + * [Configuration](#config) + * [The `dhcp.dhcpv4.options` Array Field](#config-4) + * [DHCPv6 Options](#config-6) + * [Automatic Hosts](#autohosts) + +*AdGuard Home* can be used as a DHCP server. This page describes how to do that. + +## Prerequisites + +1. Make sure that you run an OS on which *AdGuard Home* supports DHCP. We + currently don't support DHCP on *Windows*. +1. Make sure that your machine has a static IP address. + +## Default Options + +By default, *AdGuard Home* will set itself as the DNS server for the DHCP +clients. The default lease time is 24 hours. + +## Configuration + +See the DHCP section in the [configuration] article for the overview of the DHCP +configuration options. There are several configuration parameters for DHCP that +can't be set via the *AdGuard Home* administrator dashboard. Those are +described below. + + ### The `dhcp.dhcpv4.options` Array Field + +The `options` field accepts two types of values: `hex` and `ip`. Both start +with the `CODE`, which MUST be an integer in the [1, 255] range. + +See [RFC 2132, sec. 3](https://tools.ietf.org/html/rfc2132#section-3). + +The `hex` format is: + +``` +CODE hex HEX_VALUE +``` + +For example, to set option `6`, the DNS server, to two IP addresses, `1.2.3.4` +and `1.2.3.5`, use: + +```yaml +# … +'dhcp': + # … + 'dhcpv4': + # … + 'options': + - '6 hex 0102030401020305' +``` + +The `ip` format is: + +``` +CODE ip IPV4_VALUE +``` + +For example, to set option `6`, the DNS server, to one IP address, `1.2.3.4`, +use: + +```yaml +# … +'dhcp': + # … + 'dhcpv4': + # … + 'options': + - '6 ip 1.2.3.4' +``` + +An easier format for multiple IP addresses is planned, see issue #2395. + + ### DHCPv6 Options + +The option `dhcp.dhcpv6.ra_slaac_only`, if `true`, sends RA packets forcing the +clients to use SLAAC. The DHCPv6 server won't be started in this case. + +The option `dhcp.dhcpv6.ra_allow_slaac`, if `true`, sends RA packets allowing +the clients to choose between SLAAC and DHCPv6. + +[configuration]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration + +## Automatic Hosts + +You can reach machines in the network more easily using the hostnames they send +in the DHCP requests with the `.lan` top-level domain. For example, if you have +a machine called “workstation” in the network, and it sends a DHCP request with +option 12 set to `workstation`, you can reach it over HTTP on the host +`http://workstation.lan`. + +Configuring custom TLDs instead of the `.lan` one is planned, see issue #2393. diff --git a/Home.md b/Home.md index 932d0e0..f1e4cf3 100644 --- a/Home.md +++ b/Home.md @@ -30,6 +30,7 @@ The wiki was just recently created, so there isn't much content (yet). * [Comparing AdGuard Home to other solutions](Comparison) * [AdGuard Home as a DNS-over-HTTPS or DNS-over-TLS server](Encryption) * [AdGuard Home as a DNSCrypt server](DNSCrypt) +* [AdGuard Home as a DHCP server](DHCP) * [How to install and run AdGuard Home on Raspberry Pi](Raspberry-Pi) * [How to install and run AdGuard Home on a Virtual Private Server](VPS) * [OpenRC service-script](OpenRC) diff --git a/__Sidebar.md b/__Sidebar.md index 87a0a39..8e770f5 100644 --- a/__Sidebar.md +++ b/__Sidebar.md @@ -7,6 +7,7 @@ * [Comparing AdGuard Home to other solutions](Comparison) * [AdGuard Home as a DNS-over-HTTPS or DNS-over-TLS server](Encryption) * [AdGuard Home as a DNSCrypt server](DNSCrypt) +* [AdGuard Home as a DHCP server](DHCP) * [How to install and run AdGuard Home on Raspberry Pi](Raspberry-Pi) * [How to install and run AdGuard Home on a Virtual Private Server](VPS) * [OpenRC service-script](OpenRC)