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

[David Gibson <david@gibson.dropbear.id.au>]

[-- Attachment #1: Type: text/plain, Size: 4647 bytes --]

On Thu, Apr 16, 2026 at 12:04:38AM +0200, Stefano Brivio wrote:
> 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?

Uh, yeah, not entirely sure what I was going for there.  I've changed
this to

\fB~\fR\fIfirst\fR[\fB-\fR\fIlast\fR]
Exclude range.  Don't forward port numbers between \fIfirst\fR and
\fIlast\fR.  This takes precedences over include ranges.


> 
> > +.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
> 

-- 
David Gibson (he or they)	| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you, not the other way
				| around.
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]