~stappers/dnsmasqmlpc

This thread contains a patchset. You're looking at the original emails, but you may wish to use the patch review UI. Review patch
2 2

[PATCH 0/1] manpage fixes

Paul Donald <newtwen@gmail.com>
Details
Message ID
<20250109142317.85802-1-newtwen@gmail.com>
Sender timestamp
1736436169
DKIM signature
pass
Download raw message

Paul Donald (1):
  Clean up some of the man page formatting.

 man/dnsmasq.8 | 210 +++++++++++++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 97 deletions(-)

-- 
2.47.1

[PATCH 1/1] Clean up some of the man page formatting.

Paul Donald <newtwen@gmail.com>
Details
Message ID
<20250109142317.85802-2-newtwen@gmail.com>
In-Reply-To
<20250109142317.85802-1-newtwen@gmail.com> (view parent)
Sender timestamp
1736436170
DKIM signature
pass
Download raw message
Patch: +113 -97
Some writing was improved for clarity, especially regarding the use of
tags which can be confusing and difficult to grasp.
---
 man/dnsmasq.8 | 210 +++++++++++++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 97 deletions(-)

diff --git a/man/dnsmasq.8 b/man/dnsmasq.8
index e7c7947..d5b003d 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:<tag> construct sets the tag
The \fBset:<tag>\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:<tag>" is allowed). When a host matches any
\fBset:<tag>\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:<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:<tag>\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 <hwaddr>,
<client_id> or <hostname> still needs to be specified (can be a wildcard).
<client_id> or <hostname> 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>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-class>],][<opt>|option:<opt-name>|option6:<opt>|option6:<opt-name>],[<value>[,<value>]]
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:<option-name>" The option numbers are
or other options specified. The option to be sent may be given as a
decimal number or as \fBoption:<option-name>\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:<tag>,<option number>|option:<option name>|vi-encap:<enterprise>[,<value>]
Without a value, set the tag if the client sends a DHCP
option of the given number or name. When a value is given, set the tag only if
the option is sent and matches the value. The value may be of the form
Without \fB<value>\fP, set \fB<tag>\fP if the client sends a DHCP
\fBoption\fP of the given number or name. With \fB<value>\fP, set \fB<tag>\fP only if
the client sends the \fBoption\fP matching or containing \fB<value>\fP. 

The value may be of the form
"01:ff:*:02" in which case the value must match (apart from wildcards)
but the option sent may have unmatched data past the end of the
value. The value may also be of the same form as in 
.B --dhcp-option
in which case the option sent is treated as an array, and one element
must match, so
must match.
.B --dhcp-match=set:efi-ia32,option:client-arch,6
will set the tag "efi-ia32" if the the number 6 appears in the list of
sets the tag \fBefi-ia32\fP if the number \fB6\fP appears in the list of
architectures sent by the client in option 93. (See RFC 4578 for
details.)  If the value is a string, substring matching is used.
details.) If the value is a string, substring matching is used.

The special form with vi-encap:<enterprise number> matches against
vendor-identifying vendor classes for the specified enterprise. Please
see RFC 3925 for more details of these rare and interesting beasts.
.TP
.B --dhcp-name-match=set:<tag>,<name>[*]
Set the tag if the given name is supplied by a DHCP client. There may be a single trailing wildcard *, which has the usual meaning. Combined with dhcp-ignore or dhcp-ignore-names this gives the ability to ignore certain clients by name, or disallow certain hostnames from being claimed by a client.
Set a \fB<tag>\fP if the given \fB<name>\fP is supplied by a DHCP client. There may be a single trailing wildcard *, with a glob meaning. Combined with \fBdhcp-ignore\fP or \fBdhcp-ignore-names\fP this gives the ability to ignore certain clients by name, or disallow certain hostnames from being claimed by a client.
.TP
.B --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
Perform boolean operations on tags. Any tag appearing as set:<tag> is set if
all the tags which appear as tag:<tag> are set, (or unset when tag:!<tag> is used)
If no tag:<tag> appears set:<tag> tags are set unconditionally.
Any number of set: and tag: forms may appear, in any order. 
\fB--tag-if\fP lines are executed in order, so if the tag in tag:<tag> is a
Perform boolean operations on tags. All \fBset:<tag>\fP tags are set if
all \fBtag:<tag>\fP are already set, (or unset when \fBtag:!<tag>\fP is used).
If no \fBtag:<tag>\fP appears, \fBset:<tag>\fP tags are set unconditionally.
Any number of \fBset:\fP and \fBtag:\fP forms may appear, in any order. 
\fB--tag-if\fP lines are executed in order, so if the tag in \fBtag:<tag>\fP is a
tag set by another
.B --tag-if,
the line which sets the tag must precede the one which tests it.
the line which sets the tag must precede the line which tests it.

As an extension, the tag:<tag> clauses support limited wildcard matching,
similar to the matching in the \fB--interface\fP directive.  This allows, for
example, using \fB--tag-if=set:ppp,tag:ppp*\fP to set the tag 'ppp' for all requests
received on any matching interface (ppp0, ppp1, etc).  This can be used in conjunction
with the tag:!<tag> format meaning that no tag matching the wildcard may be set.
As an extension, the \fBtag:<tag>\fP clauses support limited wildcard matching,
similar to the matching in the \fB--interface\fP directive. This allows the
example \fB--tag-if=set:ppp,tag:ppp*\fP to set the tag 'ppp' for all requests
received on any matching interface (ppp0, ppp1, etc). This can be used in conjunction
with the \fBtag:!<tag>\fP format meaning that no tag matching the wildcard may be set.
.TP
.B \-J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
When all the given tags appear in the tag set ignore the host and do
When all the given tags appear in the tag set, ignore the host and do
not allocate it a DHCP lease.
.TP
.B --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
@@ -2416,48 +2413,67 @@ the CNAME. To work around this, add the CNAME to /etc/hosts so that
the CNAME is shadowed too.

.PP
The tag system works as follows: For each DHCP request, dnsmasq
collects a set of valid tags from active configuration lines which
include set:<tag>, including one from the 
.B --dhcp-range
used to allocate the address, one from any matching 
.B --dhcp-host
(and "known" or "known-othernet" if a \fB--dhcp-host\fP matches)
The tag "bootp" is set for BOOTP requests, and a tag whose name is the 
name of the interface on which the request arrived is also set.
The tag system works as follows: dnsmasq tags each DHCP request
with tags from applicable configuration lines containing \fBset:<tag>\fP i.e. 

\fBset:<tag>\fP from the \fB--dhcp-range\fP used to allocate the address;

\fBset:<tag>\fP from any matching \fB--dhcp-host\fP (plus the tag \fBknown\fP or 
\fBknown-othernet\fP).

BOOTP requests are tagged \fBbootp\fP. Each request is also tagged with the name of  
the interface on which the request arrived.

Each configuration line containing one or more \fBtag:<tag>\fP constructs
applies when all its tags exist on the request. That is:

Configuration tag:A applies to a request set:tagged A.

Configuration tag:B applies to a request set:tagged B.

Configuration tag:A+B doesn't apply to a request set:tagged A.

Configuration tag:A+B doesn't apply to a request set:tagged B.

Configurations tag:A+B, tag:A, tag:B apply to a request set:tagged A+B.

\fBset:<tag>\fP constructs in \fB--dhcp-range\fP and \fB--dhcp-host\fP tag requests.

Use \fBtag:<tag>\fPs in \fB--dhcp-option\fPs to match \fBset:<tag>\fP and apply configurations.

A \fB--dhcp-option\fP with \fBtag:<tag>\fP is preferred over an untagged 
\fB--dhcp-option\fP, provided that \fBall\fP its tags match somewhere in the
set gathered above. 

The tag prefix '!' means 'not'.
\fB--dhcp-option=tag:!purple,3,1.2.3.4\fP sends the option when the request 
is not tagged with purple. (The shell metacharacter '!' must be escaped on the
command line but not in a configuration file).

When selecting \fB--dhcp-option\fPs, a \fB--dhcp-range\fP tag is second class 
to other tags, to make it easy to override options for
individual hosts, so:

Any configuration lines which include one or more tag:<tag> constructs
will only be valid if all that tags are matched in the set derived
above. Typically this is \fB--dhcp-option\fP.
.B --dhcp-option
which has tags will be used in preference  to an untagged 
.B --dhcp-option,
provided that _all_ the tags match somewhere in the
set collected as described above. The prefix '!' on a tag means 'not'
so \fB--dhcp-option=tag:!purple,3,1.2.3.4\fP sends the option when the
tag purple is not in the set of valid tags. (If using this in a
command line rather than a configuration file, be sure to escape !,
which is a shell metacharacter)

When selecting \fB--dhcp-options\fP, a tag from \fB--dhcp-range\fP is second class
relative to other tags, to make it easy to override options for
individual hosts, so 
.B --dhcp-range=set:interface1,......

.B --dhcp-host=set:myhost,.....

.B --dhcp-option=tag:interface1,option:nis-domain,"domain1"

.B --dhcp-option=tag:myhost,option:nis-domain,"domain2"
will set the NIS-domain to domain1 for hosts in the range, but
override that to domain2 for a particular host.

sets the NIS-domain to domain1 for hosts in the range, but
to domain2 for a particular host that may or may not fall in the range.

.PP
Note that for 
.B --dhcp-range
both tag:<tag> and set:<tag> are allowed, to both select the range in
Note that for \fB--dhcp-range\fP both 
\fBtag:<tag>\fP and 
\fBset:<tag>\fP are possible, in order to both select the range in
use based on (eg) \fB--dhcp-host\fP, and to affect the options sent, based on
the range selected.

This system evolved from an earlier, more limited one and for backward
compatibility "net:" may be used instead of "tag:" and "set:" may be
The tag system evolved from an earlier, more limited system. For backward
compatibility, "net:" may be used instead of "tag:" and "set:" may be
omitted. (Except in 
.B --dhcp-host,
where "net:" may be used instead of "set:".) For the same reason, '#'
@@ -2475,7 +2491,7 @@ configuration option is present to activate the DHCP server
on a particular network. (Setting \fB--bootp-dynamic\fP removes the need for
static address mappings.) The filename
parameter in a BOOTP request is used as a tag,
as is the tag "bootp", allowing some control over the options returned to
as is the tag \fBbootp\fP, allowing some control over the options returned to
different classes of hosts.

.SH AUTHORITATIVE CONFIGURATION
-- 
2.47.1

Re: [PATCH 1/1] Clean up some of the man page formatting.

Details
Message ID
<Z4rOhVK1r1f1tMpv@gpm.stappers.nl>
In-Reply-To
<20250109142317.85802-2-newtwen@gmail.com> (view parent)
Sender timestamp
1737153685
DKIM signature
missing
Download raw message
On Thu, Jan 09, 2025 at 03:22:50PM +0100, Paul Donald wrote:
> Some writing was improved for clarity, especially regarding the use of
> tags which can be confusing and difficult to grasp.

Nice. Thanks.


I'll raise it at dnsmasq mailinglist. (Already done ;-)


Groeten
Geert Stappers


P.S.

Mailinglist patch collector addres ~stappers/dnsmasqmlpc@lists.sr.ht
doesn't do "subscriber" checks, dnsmasq-discuss@lists.thekelleys.org.uk does.
-- 
Silence is hard to parse
Reply to thread Export thread (mbox)