mirrors/AdGuardHome
1
0
Fork 0
mirror of https://github.com/AdguardTeam/AdGuardHome.git synced 2025-04-04 16:33:34 +03:00
Code Issues Projects Releases Packages Wiki Activity

Pull request: DHCP: describe options 

Merge in DNS/adguard-home-wiki from 4705-imp-opts to master

Squashed commit of the following:

commit e9ad1c83b8322ae8dbe6d8a388ca80d62bc75ae2
Author: Eugene Burkov <E.Burkov@AdGuard.COM>
Date:   Mon Sep 5 16:32:30 2022 +0300

    DHCP: fix typos, imp wording

commit bff0e56383fd2f7d57684ac1ea6a22f8e6b90c9f
Author: Eugene Burkov <E.Burkov@AdGuard.COM>
Date:   Mon Sep 5 13:21:12 2022 +0300

    DHCP: imp docs

commit eff212579b8b590475ab9a916353aaa5d73afd99
Author: Eugene Burkov <E.Burkov@AdGuard.COM>
Date:   Sat Sep 3 17:31:41 2022 +0300

    DHCP: desc options
Eugene Burkov 2022-09-05 16:55:10 +03:00
parent 6818cc75dd
commit 7aadbbfcbb
1 changed files with 129 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

199
DHCP.md

@ -38,101 +38,159 @@ below.
### <a id="config-4" href="#config-4">The `dhcp.dhcpv4.options` Array Field</a> ### <a id="config-4" href="#config-4">The `dhcp.dhcpv4.options` Array Field</a>
The `options` field accepts four types of values: `hex`, `ip`, `ips`, and The `options` field is used to explicitly specify the values for DHCP options
`text`. They all start with the `CODE`, which MUST be an integer in the [1, and modify the response. In accordance with *Section 4.3.1* of [RFC
255] range. See also [RFC 2132, sec. 3][rfc-2132]. 2131][rfc-2131], these options override the default options' values set by
Adguard Home and requested by a client. Which means that if you want to set
In accordance with [RFC 2131, sec. 4.3.1][rfc-2131], these options override the custom DNS server addresses using option `6` (Domain Name Server), you may want
default options' values set by Adguard Home and requested by a client. Which
means that if you want to set DNS server addresses using option `6`, you should
also add Adguard Home's own addresses there. Otherwise, AdGuard Home's also add Adguard Home's own addresses there. Otherwise, AdGuard Home's
filtering won't work for the DHCP clients who receive these DNS server filtering won't work for the DHCP clients who receive these DNS server
addresses. addresses.
Option `del` has been added in **v0.107.12**. It is used to unconditionally Any option begins with an option *code* written as decimal integer. See [RFC
remove options from the server's responses, which may lead to weird behaviors. 2132][rfc-2132] for the actual DHCP option codes and allowed lengths. The code
Use with caution. On example where this option is useful is when a client is followed by an option's *type* and *value*. Currently the following *types*
doesn't accept a lease because of an option, see [issue 4337]. are supported:
* The `hex` format is: * `bool` (since **v0.107.12**) accepts a human-readable form of a boolean
value, and has the length of 1 octet.
``` For example:
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 ```yaml
# … 'options':
'dhcp': - '19 bool 0' # Disable IP forwarding for hosts.
# … - '20 bool t' # Enable non-local source routing for hosts.
'dhcpv4': - '27 bool F' # Disable ahoming for hosts.
# … - '30 bool true' # Enable mask supplying for supporting hosts.
'options': - '36 bool False' # Make the hosts use RFC 894 for ethernet encapsulation.
- '6 hex 0102030401020305'
``` ```
* The `ip` format is: * `del` (since **v0.107.12**) is a no-value option and is used to
unconditionally remove options from the server's responses (which may lead
to weird behaviors, use with caution).
``` Since the list of options is interpreted sequentially from first to last,
CODE ip IPV4_VALUE the subsequent option may override the previous ones. So this:
```
For example, to set option `6`, the DNS server, to one IP address,
`1.2.3.4`, use:
```yaml ```yaml
# … 'options':
'dhcp': - '19 bool T'
# … - '19 del'
'dhcpv4': - '20 del'
# … - '20 bool F'
'options':
- '6 ip 1.2.3.4'
``` ```
* The `ips` format (since **v0.106.0**) is the same, but with comma-separated instructs to remove the option `19`, and to set the option `20` to `false`.
IP-addresses:
* `dur` (since **v0.107.12**) accepts a human-readable form of a duration in
range [0 – 4294967296 seconds (about 136 days)] and has a length of *4*
octets, just like a 32-bit unsigned integer.
Here is the example of setting the MTU aging timeout to 10 minutes:
```yaml ```yaml
# … 'options':
'dhcp': - '24 dur 10m'
# …
'dhcpv4':
# …
'options':
- '6 ips 1.2.3.4,5.6.7.8'
``` ```
* The `text` format (since **v0.106.0**) allows you to put arbitrary UTF-8 * `hex` accepts a sequence of hexadecimal numbers of an arbitrary length.
text as the option data. For example:
Here is the example of setting the plateau table for path MTU timeouts:
```yaml ```yaml
# … 'options':
'dhcp': - '25 hex 0044012801FC03EE05D407D211001FE645FA'
# …
'dhcpv4':
# …
'options':
- '252 text http://example.com'
``` ```
* The `del` format (since **v0.107.12**) allows you to remove an option. For * `ip` accepts an IPv4 address and has a length of *4* octets, just like an
example: IPv4 itself.
Here is the example of setting a broadcast address option:
```yaml ```yaml
# … 'options':
'dhcp': - '28 ip 192.168.0.255'
# …
'dhcpv4':
# …
'options':
- '61 del'
``` ```
[issue 4337]: https://github.com/adguardTeam/adGuardHome/issues/4337 * `ips` (since **v0.106.0**) accepts a comma-separated list if IPv4 addresses.
It has an arbitrary length, but is always a multiple of *4* octets.
Here is the example of setting the domain name servers to `1.2.3.4` and
`1.2.3.5`:
```yaml
'options':
- '6 ips 1.2.3.4,1.2.3.5'
```
* `text` (since **v0.106.0**) accepts an arbitrary UTF-8 encoded string and
has a length of encoded text.
Here is the example of setting the path to configuration file for WPAD:
```yaml
'options':
- '252 text http://server.domain/proxyconfig.pac'
```
* `u8` (since **v0.107.12**) accepts a decimal number in range [0 – 255] and
takes *1* octet, just like an unsigned 8-bit integer.
Here is the example of setting the TTL for Internet Protocol:
```yaml
'options':
- '23 u8 64'
```
* `u16` (since **v0.107.12**) accepts a decimal number in range [0 – 65535]
and takes *2* octets, just like an unsigned 16-bit integer.
Here is the example of setting the maximum datagram reassembly size to 576
bytes:
```yaml
'options':
- '22 u16 576'
```
**NOTE:** Thoroughly check that the option format and value are valid for the
chosen type in accordance with [RFC 2132][rfc-2132] or others. AdGuard Home does
not perform any option-specific validations.
Currently there is a set of options listed in *Appendix A* of [RFC
2131][rfc-2131] with the default values chosen according to the documents
mentioned there:
| Option | Value |
| -------------------------------- | --------------------------------------------- |
| IP Forwarding | Disabled |
| Non-Local Source Routing | Disabled |
| Maximum Datagram Reassembly Size | 576 bytes |
| Default IP Time-to-live | 64 seconds |
| Path MTU Aging Timeout Option | 10 minutes |
| Path MTU Plateau Table | See [Table 7.1 in RFC 1191][rfc-1191-tbl-7.1] |
| Interface MTU | 576 bytes |
| All subnets are local | False |
| Perform Mask Discovery | False |
| Mask Supplier | False |
| Perform Router Discovery | True |
| Router Solicitation Address | 224.0.0.2 |
| Broadcast Address | 255.255.255.255 |
| Use Trailer Encapsulation | False |
| ARP Cache Timeout | 1 minute |
| Ethernet Encapsulation version | RFC 894 |
| Default TCP TTL | 60 seconds |
| TCP Keepalive Interval | 2 hours |
| Put TCP Keepalive Garbage | True |
| Routers | `gateway_ip` from configuration |
| Subnet Mask | `subnet_mask` from configuration |
Some of these values may appear obsolete or may cause issues with some DHCP
client implementations among the many existing. In accordance with [RFC
2131][rfc-2131] the options, when not explicitly configured, are only returned
if requested by client within the option `55` (Parameter Request List).
### <a id="config-6" href="#config-6">DHCPv6 Options</a> ### <a id="config-6" href="#config-6">DHCPv6 Options</a>
@ -143,9 +201,10 @@ 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 option `dhcp.dhcpv6.ra_allow_slaac`, if `true`, sends RA packets allowing
the clients to choose between SLAAC and DHCPv6. the clients to choose between SLAAC and DHCPv6.
[configuration]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration [configuration]: https://github.com/AdguardTeam/AdGuardHome/wiki/Configuration
[rfc-2131]: https://tools.ietf.org/html/rfc2131#page-29 [rfc-1191-tbl-7.1]: https://datatracker.ietf.org/doc/html/rfc1191#section-7.1
[rfc-2132]: https://tools.ietf.org/html/rfc2132#section-3 [rfc-2131]: https://datatracker.ietf.org/doc/html/rfc2131
[rfc-2132]: https://datatracker.ietf.org/doc/html/rfc2132