Re: [PATCH v3 6/6] doc: Add --dhcp-boot and --dhcp-opt to man page

[Stefano Brivio <sbrivio@redhat.com>]

On Mon,  1 Jun 2026 13:07:56 +0530
Anshu Kumari <anskuma@redhat.com> wrote:

> Document the new --dhcp-boot and --dhcp-opt command-line options in
> the passt(1) man page, including supported option codes grouped by
> value type and usage examples.
> 
> Link: https://bugs.passt.top/show_bug.cgi?id=192
> Signed-off-by: Anshu Kumari <anskuma@redhat.com>
> ---
> v3:
>   - Removed options 33, 55, 61, 119 from supported codes list
>   - Added note: "If the same name option code is given more than once,
>     the last value wins".
> 
> v2:
>   - Updated --dhcp-boot description.
>   - Highlighted cross-referenced options with \fB...\fR.
>   - Updated IP list format from "space-separated within quotes" to "comma-separated".
>   - option 121 dropped.
>   - Added option 55 to string options list.
>   - Removed --dhcp-boot override reference from --dhcp-opt description.
> ---
>  passt.1 | 41 +++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
> 
> diff --git a/passt.1 b/passt.1
> index 908fd4a..57e2cc1 100644
> --- a/passt.1
> +++ b/passt.1
> @@ -430,6 +430,47 @@ Send \fIname\fR as DHCP option 12 (hostname).
>  FQDN to configure the client with.
>  Send \fIname\fR as Client FQDN: DHCP option 81 and DHCPv6 option 39.
>  
> +.TP
> +.BR \-\-dhcp-boot " " \fIurl
> +Convenience shorthand for \fB\-\-dhcp-opt\fR 67,\fIurl\fR.
> +Sets the boot file name (DHCP option 67) for network boot.
> +For UEFI HTTP boot, also set the vendor class identifier using
> +\fB\-\-dhcp-opt\fR 60,HTTPClient.

This is ambiguous. The man page is written in an imperative style in
the sense of what the tool is supposed to do, but this becomes a
recommendation to the user instead (this sentence says "set" and not
"sets" but that's very easy to miss, and ambiguous nevertheless).

This would be clearer I think:

For UEFI HTTP boot, the vendor class identifier also needs to be set
using ...

> +
> +.TP
> +.BR \-\-dhcp-opt " " \fICODE\fR,\fIVALUE\fR
> +Set a DHCP option by numeric code. The value format is determined automatically
> +from the option code. Multiple IPv4 addresses are comma-separated.
> +This option can be specified multiple times. If the same option code is
> +given more than once, the last value wins. Options set with
> +\fB\-\-dhcp-opt\fR override built-in values.
> +Only the following option codes are supported (unsupported codes cause an error):

By the way, eventually, I think it would be nice to support those as
hex encoding, maybe with a --dhcp-opt-raw parameter taking a length
value (also comma-separated, say, CODE,LENGTH,VALUE).

I guess it's beyond the scope of this series though.

> +.RS
> +.TP
> +.B IPv4 address options
> +1 (Subnet Mask), 16 (Swap Server), 28 (Broadcast Address), 50 (Requested IP),
> +54 (Server Identifier)
> +.TP
> +.B IPv4 address list options (comma-separated)
> +3 (Router), 4 (Time Server), 5 (Name Server), 6 (DNS), 7 (Log Server),
> +8 (Cookie Server), 9 (LPR Server), 10 (Impress Server),
> +11 (Resource Location Server), 41 (NIS Servers),
> +42 (NTP Servers), 44 (NetBIOS Name Server)
> +.TP
> +.B Integer options
> +2 (Time Offset, 32-bit), 13 (Boot File Size, 16-bit), 19 (IP Forwarding, 8-bit),
> +23 (Default IP TTL, 8-bit), 26 (Interface MTU, 16-bit),
> +37 (TCP Default TTL, 8-bit), 38 (TCP Keepalive Interval, 32-bit),
> +51 (IP Address Lease Time, 32-bit),
> +53 (DHCP Message Type, 8-bit), 57 (Max DHCP Message Size, 16-bit),
> +58 (Renewal Time, 32-bit), 59 (Rebinding Time, 32-bit)
> +.TP
> +.B String options
> +12 (Host Name), 15 (Domain Name), 17 (Root Path), 40 (NIS Domain Name),
> +60 (Vendor Class Identifier), 66 (TFTP Server Name),
> +67 (Bootfile Name), 252 (WPAD URL)
> +.RE
> +
>  .TP
>  .BR \-t ", " \-\-tcp-ports " " \fIspec
>  Configure TCP port forwarding to guest or namespace. \fIspec\fR can be one of:

The rest looks good to me.

-- 
Stefano