Re: [PATCH v2 15/23] doc: Rework man page description of port specifiers

[Stefano Brivio <sbrivio@redhat.com>]

On Fri, 10 Apr 2026 11:03:01 +1000
David Gibson <david@gibson.dropbear.id.au> wrote:

> Currently the man page describes the internal syntax of port specifiers
> in prose, which isn't particularly easy to follow.  Rework it to use
> more syntax "diagrams" to show how it works.  This will also allow us to
> more easily update the manual page for some coming changes in syntax.
> 
> usage() output is updated similarly, though more briefly.
> 
> Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
> ---
>  conf.c  | 10 +++++-----
>  passt.1 | 32 ++++++++++++++++++++++----------
>  2 files changed, 27 insertions(+), 15 deletions(-)
> 
> diff --git a/conf.c b/conf.c
> index c3655824..5d6517c3 100644
> --- a/conf.c
> +++ b/conf.c
> @@ -1041,11 +1041,11 @@ static void usage(const char *name, FILE *f, int status)
>  		"      'none': don't forward any ports\n"
>  		"      'all': forward all unbound, non-ephemeral ports\n"
>  		"%s"
> -		"      a comma-separated list, optionally ranged with '-'\n"
> -		"        and optional target ports after ':', with optional\n"
> -		"        address specification suffixed by '/' and optional\n"
> -		"        interface prefixed by '%%'. Ranges can be reduced by\n"
> -		"        excluding ports or ranges prefixed by '~'\n"
> +		"      [ADDR[%%IFACE]/]PORTS: forward specific ports\n"
> +		"        PORTS is a comma-separated list of ports, optionally\n"
> +		"        ranged with '-' and optional target ports after ':'.\n"
> +		"        Ranges can be reduced by excluding ports or ranges\n"
> +		"        prefixed by '~'\n"
>  		"        Examples:\n"
>  		"        -t 22		Forward local port 22 to 22 on %s\n"
>  		"        -t 22:23	Forward local port 22 to 23 on %s\n"
> diff --git a/passt.1 b/passt.1
> index 7da4fe5f..d329f8f0 100644
> --- a/passt.1
> +++ b/passt.1
> @@ -447,16 +447,28 @@ periodically derived (every second) from listening sockets reported by
>  \fI/proc/net/tcp\fR and \fI/proc/net/tcp6\fR, see \fBproc\fR(5).
>  
>  .TP
> -.BR ports
> -A comma-separated list of ports, optionally ranged with \fI-\fR, and,
> -optionally, with target ports after \fI:\fR, if they differ. Specific addresses
> -can be bound as well, separated by \fI/\fR, and also, since Linux 5.7, limited
> -to specific interfaces, prefixed by \fI%\fR. Within given ranges, selected ports
> -and ranges can be excluded by an additional specification prefixed by \fI~\fR.
> -
> -Specifying excluded ranges only implies that all other ports are forwarded. In
> -this case, no failures are reported for unavailable ports, unless no ports could
> -be forwarded at all.
> +[\fIaddress\fR[\fB%\fR\fIinterface\fR]\fB/\fR]\fIports\fR ...
> +Specific ports to forward.  Optionally, a specific listening address
> +and interface name (since Linux 5.7) can be specified.  \fIports\fR is
> +a comma-separated list of entries which may be any of:
> +.RS
> +.TP
> +\fIfirst\fR[\fB-\fR\fIlast\fR][\fB:\fR\fItofirst\fR[\fB-\fR\fItolast\fR]]
> +Include range. Forward port numbers between \fIfirst\fR and \fIlast\fR
> +(inclusive) to ports between \fItofirst\fR and \fItolast\fR.  If
> +\fItofirst\fR and \fItolast\fR are omitted, assume the same as
> +\fIfirst\fR and \fIlast\fR.  If \fIlast\fR is omitted, assume the same
> +as \fIfirst\fR.
> +
> +.TP
> +\fB~\fR\fIfirst\fR[\fB-\fR\fIlast\fR]
> +Exclude range.  Exclude port numbers between \fIfirst\fR and
> +\fIlast\fR from.  This takes precedences over include ranges.

..."from the set of all non-ephemeral ports permitted by current
capabilities"?

Or simply drop " from", because it should be clear from the paragraph
below?

> +.RE
> +
> +Specifying excluded ranges only implies that all other non-ephemeral
> +ports are forwarded. In this case, no failures are reported for
> +unavailable ports, unless no ports could be forwarded at all.
>  
>  Examples:
>  .RS

-- 
Stefano