Pull request: all: add a dhcp server page

Merge in DNS/adguard-home-wiki from 2386-dhcp to master

Updates AdguardTeam/AdGuardHome#2386.
Updates AdguardTeam/AdGuardHome#2370.

Squashed commit of the following:

commit 1523d30a01a73f506ad679282c241aab49bfa17f
Author: Ainar Garipov <A.Garipov@AdGuard.COM>
Date:   Mon Dec 28 18:29:57 2020 +0300

    all: add a dhcp server page

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)
 
 <a id="command-line"></a>
 
@@ -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).
+  - `interface_name` - network interface name (`eth0`, `en0`, and so on).
-  - `dhcpv4` - DHCPv4 settings
+  - `dhcpv4` - DHCPv4 settings.
     - `gateway_ip` - gateway IP address.
     - `subnet_mask` - subnet mask.
-    - `range_start` - start IP address of the controlled range.
+    - `range_start`, `range_end` - the start and the end of the leased IP
-    - `range_end` - end IP address of the controlled range.
+      address range.
-    - `lease_duration` - lease duration in seconds. If 0, using default duration (24 hours).
+    - `lease_duration` - lease duration in seconds.  If `0`, use the default
-    - `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]
+      duration of 24 hours.
-  - `dhcpv6` - DHCPv6 settings
+    - `options` - custom DHCP options.  See the [DHCP] article section on these
-    - `range_start` - the first IP address to be assigned to a client
+      options for more information.
-    - `lease_duration` - lease TTL in seconds
+  - `dhcpv6` - DHCPv6 settings.
-    - `ra_slaac_only` - send RA packets forcing the clients to use SLAAC
+    - `range_start` - the first IP address to be assigned to a client.
-    - `ra_allow_slaac` - send RA packets making the clients to choose between SLAAC and DHCPv6
+    - `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/`.
-
-<a id="dhcp-options"></a>
-
-## 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

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.
+
+##  <a id="prereq" href="#prereq">Prerequisites</a>
+
+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.
+
+##  <a id="default" href="#default">Default Options</a>
+
+By default, *AdGuard Home* will set itself as the DNS server for the DHCP
+clients.  The default lease time is 24 hours.
+
+##  <a id="config" href="#config">Configuration</a>
+
+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.
+
+ ###  <a id="config-4" href="#config-4">The `dhcp.dhcpv4.options` Array Field</a>
+
+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.
+
+ ###  <a id="config-6" href="#config-6">DHCPv6 Options</a>
+
+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
+
+##  <a id="autohosts" href="#autohosts">Automatic Hosts</a>
+
+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.

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)

__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)