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

On Fri, 10 Apr 2026 11:03:01 +1000 David Gibson 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 --- 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