From 046bfa2af0820b6f3a52ec3c63e58ccac957484d Mon Sep 17 00:00:00 2001 From: Paul Donald Date: Fri, 31 Jan 2025 21:52:55 +0100 Subject: [PATCH] Clean up some of the man page formatting. Some writing was improved for clarity, especially regarding the use of tags which can be confusing and difficult to grasp. --- man/dnsmasq.8 | 208 +++++++++++++++++++++++++++----------------------- 1 file changed, 112 insertions(+), 96 deletions(-) diff --git a/man/dnsmasq.8 b/man/dnsmasq.8 index 49f86aa..5e3ce3b 100644 --- a/man/dnsmasq.8 +++ b/man/dnsmasq.8 @@ -1188,7 +1188,7 @@ available, though it normally is for direct-connected clients, or clients using DHCP relays which support RFC 6939. -For DHCPv4, the special option id:* means "ignore any client-id +For DHCPv4, the special option \fBid:*\fP means "ignore any client-id and use MAC addresses only." This is useful when a client presents a client-id sometimes but not others. @@ -1216,36 +1216,34 @@ the result is undefined. A corollary to this is that the name associated with a does not appear in the DNS until the host obtains a DHCP lease. -The special keyword "ignore" -tells dnsmasq to never offer a DHCP lease to a machine. The machine -can be specified by hardware address, client ID or hostname, for -instance -.B --dhcp-host=00:20:e0:3b:13:af,ignore -This is -useful when there is another DHCP server on the network which should +The special keyword \fBignore\fP tells dnsmasq never to offer a DHCP lease +to a machine. The machine +can be specified by hardware address, client ID or hostname. For +example: \fB--dhcp-host=00:20:e0:3b:13:af,ignore\fP. +This can be useful when there is another DHCP server on the network which should be used by some machines. -The set: construct sets the tag +The \fBset:\fP construct sets the tag whenever this \fB--dhcp-host\fP directive is in use. This can be used to selectively send DHCP options just for this host. More than one tag can be set in a \fB--dhcp-host\fP directive (but not in other places where -"set:" is allowed). When a host matches any +\fBset:\fP is allowed). When a host matches any \fB--dhcp-host\fP directive (or one implied by /etc/ethers) then the special -tag "known" is set. This allows dnsmasq to be configured to +tag \fBknown\fP is set. This allows dnsmasq to be configured to ignore requests from unknown machines using -.B --dhcp-ignore=tag:!known +\fB--dhcp-ignore=tag:!known\fP. If the host matches only a \fB--dhcp-host\fP directive which cannot -be used because it specifies an address on different subnet, the tag "known-othernet" is set. +be used because it specifies an address on a different subnet, the tag \fBknown-othernet\fP is set. -The tag: construct filters which dhcp-host directives are used; more than -one can be provided, in this case the request must match all of them. Tagged +The \fBtag:\fP construct filters which dhcp-host directives are used. More than +one tag can be provided. In this case, the request must match all tags. Tagged directives are used in preference to untagged ones. Note that one of , - or still needs to be specified (can be a wildcard). + or still must be specified (can be a wildcard). Ethernet addresses (but not client-ids) may have wildcard bytes, so for example .B --dhcp-host=00:20:e0:3b:13:*,ignore -will cause dnsmasq to ignore a range of hardware addresses. Note that +will cause dnsmasq to ignore the given range of hardware addresses. Note that the "*" will need to be escaped or quoted on a command line, but not in the configuration file. @@ -1259,11 +1257,11 @@ is 6. As a special case, in DHCPv4, it is possible to include more than one hardware address. eg: -.B --dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2 +\fB--dhcp-host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2\fP. This allows an IP address to be associated with multiple hardware addresses, and gives dnsmasq permission to abandon a DHCP lease to one of the hardware addresses when another one asks for -a lease. Beware that this is a dangerous thing to do, it will only +a lease. Beware that this is a dangerous thing to do: it will only work reliably if only one of the hardware addresses is active at any time and there is no way for dnsmasq to enforce this. It is, for instance, useful to allocate a stable IP address to a laptop which @@ -1310,27 +1308,25 @@ options containing the same information. /etc/ethers is re-read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers. .TP .B \-O, --dhcp-option=[tag:,[tag:,]][encap:,][vi-encap:,][vendor:[],][|option:|option6:|option6:],[[,]] -Specify different or extra options to DHCP clients. By default, +Send various extra options to DHCP clients. By default, dnsmasq sends some standard options to DHCP clients, the netmask and broadcast address are set to the same as the host running dnsmasq, and the DNS server and default route are set to the address of the machine running dnsmasq. (Equivalent rules apply for IPv6.) If the domain name option has been set, that is sent. This configuration allows these defaults to be overridden, -or other options specified. The option, to be sent may be given as a -decimal number or as "option:" The option numbers are +or other options specified. The option to be sent may be given as a +decimal number or as \fBoption:\fP. + +Option numbers are specified in RFC2132 and subsequent RFCs. The set of option-names -known by dnsmasq can be discovered by running "dnsmasq --help dhcp". -For example, to set the default route option to -192.168.4.4, do -.B --dhcp-option=3,192.168.4.4 -or -.B --dhcp-option = option:router, 192.168.4.4 -and to set the time-server address to 192.168.0.4, do -.B --dhcp-option = 42,192.168.0.4 -or -.B --dhcp-option = option:ntp-server, 192.168.0.4 -The special address 0.0.0.0 is taken to mean "the address of the -machine running dnsmasq". +known by dnsmasq can be discovered by running \fBdnsmasq --help dhcp\fP. +For example, to set the default route option to 192.168.4.4, use +\fB--dhcp-option=3,192.168.4.4\fP or +\fB--dhcp-option=option:router,192.168.4.4\fP +and to set the time-server address to 192.168.0.4, use +\fB--dhcp-option=42,192.168.0.4\fP or +\fB--dhcp-option=option:ntp-server,192.168.0.4\fP. +The special address 0.0.0.0 means "the address of the system running dnsmasq". An option without data is valid, and includes just the option without data. (There is only one option with a zero length data field currently defined for DHCPv4, 80:rapid commit, so this feature is not very useful in practice). Options for which dnsmasq normally @@ -1351,30 +1347,29 @@ to option 120 are handled as per RFC 3361. Dotted-quad IP addresses which are followed by a slash and then a netmask size are encoded as described in RFC 3442. -IPv6 options are specified using the -.B option6: +IPv6 options are specified using the \fBoption6:\fP keyword, followed by the option number or option name. The IPv6 option name space is disjoint from the IPv4 option name space. IPv6 addresses in options must be bracketed with square brackets, eg. -.B --dhcp-option=option6:ntp-server,[1234::56] +\fB --dhcp-option=option6:ntp-server,[1234::56]\fP. For IPv6, [::] means "the global address of the machine running dnsmasq", whilst [fd00::] is replaced with the ULA, if it exists, and [fe80::] with the link-local address. -Be careful: no checking is done that the correct type of data for the -option number is sent, it is quite possible to -persuade dnsmasq to generate illegal DHCP packets with injudicious use -of this flag. When the value is a decimal number, dnsmasq must determine how +Be careful: data-type suitability for the option number sent is not checked. +It is quite possible to persuade dnsmasq to generate illegal DHCP packets with +injudicious use of this flag. +When the value is a decimal number, dnsmasq must determine how large the data item is. It does this by examining the option number and/or the value, but can be overridden by appending a single letter flag as follows: b = one byte, s = two bytes, i = four bytes. This is mainly useful with encapsulated vendor class options (see below) where dnsmasq cannot -determine data size from the option number. Option data which +determine data size from the option number. Option data which consists solely of periods and digits will be interpreted by dnsmasq as an IP address, and inserted into an option as such. To force a literal string, use quotes. For instance when using option 66 to send -a literal IP address as TFTP server name, it is necessary to do -.B --dhcp-option=66,"1.2.3.4" +a literal IP address as TFTP server name, it is necessary to do +\fB--dhcp-option=66,"1.2.3.4"\fP. Encapsulated Vendor-class options may also be specified (IPv4 only) using \fB--dhcp-option\fP: for instance @@ -1403,7 +1398,7 @@ Vendor Options" as specified by RFC3925. These are denoted like this: The number in the vi-encap: section is the IANA enterprise number used to identify this option. This form of encapsulation is supported in IPv6. - + The address 0.0.0.0 is not treated specially in encapsulated options. .TP @@ -1529,45 +1524,47 @@ via relays. If a list of IP addresses is given, only interactions via relays at those addresses are affected. .TP .B --dhcp-match=set:,