Re: [PATCH 04/18] doc: Consolidate -[tu] option descriptions for passt and pasta

On Wed, Apr 08, 2026 at 01:14:41AM +0200, Stefano Brivio wrote: 11;rgb:ffff/ffff/ffff> On Tue, 7 Apr 2026 13:16:16 +1000

David Gibson wrote:

...

The man page currently has two fairly large, near-identical sections

Not entirely identical also because:

...

separately describing the -t and -u options for passt and pasta. This is bulky and potentially confusing. It will make this information more tedious to update as we alter what's possible here with the forwarding table. Consolidate both descriptions to a single one in the common options, noting the few passt/pasta difference inline.

There's similar duplication usage(), consolidate that as well.

Signed-off-by: David Gibson --- conf.c | 54 +++++--------- passt.1 | 216 ++++++++++++++++++-------------------------------------- 2 files changed, 85 insertions(+), 185 deletions(-)

diff --git a/conf.c b/conf.c index f3b36bb6..751e500f 100644 --- a/conf.c +++ b/conf.c @@ -1023,18 +1023,12 @@ static void usage(const char *name, FILE *f, int status) " --freebind Bind to any address for forwarding\n" " --no-map-gw Don't map gateway address to host\n" " -4, --ipv4-only Enable IPv4 operation only\n" - " -6, --ipv6-only Enable IPv6 operation only\n"); - - if (strstr(name, "pasta")) - goto pasta_opts; - - FPRINTF(f, - " -1, --one-off Quit after handling one single client\n" + " -6, --ipv6-only Enable IPv6 operation only\n" " -t, --tcp-ports SPEC TCP port forwarding to guest\n" " can be specified multiple times\n" " SPEC can be:\n" " '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" @@ -1050,43 +1044,29 @@ static void usage(const char *name, FILE *f, int status) " -t 192.0.2.1/5 Bind port 5 of 192.0.2.1 to guest\n" " -t 5-25,~10-20 Forward ports 5 to 9, and 21 to 25\n" " -t ~25 Forward all ports except for 25\n" - " default: none\n" + " default: %s\n" " -u, --udp-ports SPEC UDP port forwarding to guest\n"

...this is "guest" for passt and "namespace" for pasta. Now, I know that you use those terms interchangeably and the code does as well, but this is directly visible to users so I think we shouldn't confuse them with "guests" for... containers.

To reaffirm the difference between terms used in the code and terms used in documentation, could we perhaps do something like:

char *guest = (mode == MODE_PASTA) ? "namespace" : "guest";

? And then use that later? It might be worth doing that for the "default" strings too.

Sure, done.

...

" SPEC is as described for TCP above\n" - " default: none\n"); + " default: %s\n", + strstr(name, "pasta") ? + " 'auto': forward all ports currently bound in namespace\n" + : + " 'all': forward all unbound, non-ephemeral ports\n", + strstr(name, "pasta") ? "auto" : "none", + strstr(name, "pasta") ? "auto" : "none"); + + if (strstr(name, "pasta")) + goto pasta_opts; + + FPRINTF(f, + " -1, --one-off Quit after handling one single client\n" + );

passt_exit(status);

pasta_opts:

FPRINTF(f, - " -t, --tcp-ports SPEC TCP port forwarding to namespace\n" - " can be specified multiple times\n" - " SPEC can be:\n" - " 'none': don't forward any ports\n" - " 'auto': forward all ports currently bound in namespace\n" - " 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 '%%'. Examples:\n" - " -t 22 Forward local port 22 to port 22 in netns\n" - " -t 22:23 Forward local port 22 to port 23\n" - " -t 22,25 Forward ports 22, 25 to ports 22, 25\n" - " -t 22-80 Forward ports 22 to 80\n" - " -t 22-80:32-90 Forward ports 22 to 80 to\n" - " corresponding port numbers plus 10\n" - " -t 192.0.2.1/5 Bind port 5 of 192.0.2.1 to namespace\n" - " -t 5-25,~10-20 Forward ports 5 to 9, and 21 to 25\n" - " -t ~25 Forward all bound ports except for 25\n" - " default: auto\n" - " IPv6 bound ports are also forwarded for IPv4\n" - " -u, --udp-ports SPEC UDP port forwarding to namespace\n" - " SPEC is as described for TCP above\n" - " default: auto\n" - " IPv6 bound ports are also forwarded for IPv4\n" - " unless specified, with '-t auto', UDP ports with numbers\n" - " corresponding to forwarded TCP port numbers are\n" - " forwarded too\n" " -T, --tcp-ns SPEC TCP port forwarding to init namespace\n" " SPEC is as described above\n" " default: auto\n" diff --git a/passt.1 b/passt.1 index 13e8df9d..a9a8a42a 100644 --- a/passt.1 +++ b/passt.1 @@ -425,78 +425,6 @@ 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.

-.SS \fBpasst\fR-only options - -.TP -.BR \-s ", " \-\-socket-path ", " \-\-socket " " \fIpath -Path for UNIX domain socket used by \fBqemu\fR(1) or \fBqrap\fR(1) to connect to -\fBpasst\fR. -Default is to probe a free socket, not accepting connections, starting from -\fI/tmp/passt_1.socket\fR to \fI/tmp/passt_64.socket\fR. - -.TP -.BR \-\-vhost-user -Enable vhost-user. The vhost-user command socket is provided by \fB--socket\fR. - -.TP -.BR \-\-print-capabilities -Print back-end capabilities in JSON format, only meaningful for vhost-user mode. - -.TP -.BR \-\-repair-path " " \fIpath -Path for UNIX domain socket used by the \fBpasst-repair\fR(1) helper to connect -to \fBpasst\fR in order to set or clear the TCP_REPAIR option on sockets, during -migration. \fB--repair-path none\fR disables this interface (if you need to -specify a socket path called "none" you can prefix the path by \fI./\fR). - -Default, for \-\-vhost-user mode only, is to append \fI.repair\fR to the path -chosen for the hypervisor UNIX domain socket. No socket is created if not in -\-\-vhost-user mode. - -.TP -.BR \-\-migrate-exit " " (DEPRECATED) -Exit after a completed migration as source. By default, \fBpasst\fR keeps -running and the migrated guest can continue using its connection, or a new guest -can connect. - -Note that this configuration option is \fBdeprecated\fR and will be removed in a -future version. It is not expected to be of any use, and it simply reflects a -legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR -below. - -.TP -.BR \-\-migrate-no-linger " " (DEPRECATED) -Close TCP sockets on the source instance once migration completes. - -By default, sockets are kept open, and events on data sockets are ignored, so -that any further message reaching sockets after the source migrated is silently -ignored, to avoid connection resets in case data is received after migration. - -Note that this configuration option is \fBdeprecated\fR and will be removed in a -future version. It is not expected to be of any use, and it simply reflects a -legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR -below. - -.TP -.BR \-F ", " \-\-fd " " \fIFD -Pass a pre-opened, connected socket to \fBpasst\fR. Usually the socket is opened -in the parent process and \fBpasst\fR inherits it when run as a child. This -allows the parent process to open sockets using another address family or -requiring special privileges. - -This option implies the behaviour described for \-\-one-off, once this socket -is closed. - -.TP -.BR \-1 ", " \-\-one-off -Quit after handling a single client connection, that is, once the client closes -the socket, or once we get a socket error. - -\fBNote\fR: this option has no effect after \fBpasst\fR completes a migration as -source, because, in that case, exiting would close sockets for active -connections, which would in turn cause connection resets if any further data is -received. See also the description of \fI\-\-migrate-no-linger\fR. - .TP .BR \-t ", " \-\-tcp-ports " " \fIspec Configure TCP port forwarding to guest. \fIspec\fR can be one of: @@ -507,11 +435,17 @@ Configure TCP port forwarding to guest. \fIspec\fR can be one of: Don't forward any ports

.TP -.BR all +.BR all (\fBpasst\fR only)

This is rendered as "passtonly". You need \fBpasst\fR " " only. While this one goes away in 5/18,

Fixed. (In fact I think I might have fixed that before, then accidentally discarded it; oops).

...

Forward all unbound, non-ephemeral ports, as permitted by current capabilities. For low (< 1024) ports, see \fBNOTES\fR. No failures are reported for unavailable ports, unless no ports could be forwarded at all.

+.TP +.BR auto (\fBpasta\fR only)

...this one doesn't.

...

+Dynamically forward ports bound in the namespace. The list of ports is +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, @@ -563,7 +497,7 @@ and 30 Forward all ports to the guest, except for the range from 20000 to 20010 .RE

-Default is \fBnone\fR. +Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR. .RE

.TP @@ -575,101 +509,87 @@ Note: unless overridden, UDP ports with numbers corresponding to forwarded TCP port numbers are forwarded too, without, however, any port translation. IPv6 bound ports are also forwarded for IPv4.

-Default is \fBnone\fR. +Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR.

-.SS \fBpasta\fR-only options +.SS \fBpasst\fR-only options

.TP -.BR \-I ", " \-\-ns-ifname " " \fIname -Name of tap interface to be created in target namespace. -By default, the same interface name as the external, routable interface is used. -If no such interface exists, the name \fItap0\fR will be used instead. +.BR \-s ", " \-\-socket-path ", " \-\-socket " " \fIpath +Path for UNIX domain socket used by \fBqemu\fR(1) or \fBqrap\fR(1) to connect to +\fBpasst\fR. +Default is to probe a free socket, not accepting connections, starting from +\fI/tmp/passt_1.socket\fR to \fI/tmp/passt_64.socket\fR.

.TP -.BR \-t ", " \-\-tcp-ports " " \fIspec -Configure TCP port forwarding to namespace. \fIspec\fR can be one of: -.RS +.BR \-\-vhost-user +Enable vhost-user. The vhost-user command socket is provided by \fB--socket\fR.

.TP -.BR none -Don't forward any ports +.BR \-\-print-capabilities +Print back-end capabilities in JSON format, only meaningful for vhost-user mode.

.TP -.BR auto -Dynamically forward ports bound in the namespace. The list of ports is -periodically derived (every second) from listening sockets reported by -\fI/proc/net/tcp\fR and \fI/proc/net/tcp6\fR, see \fBproc\fR(5). +.BR \-\-repair-path " " \fIpath +Path for UNIX domain socket used by the \fBpasst-repair\fR(1) helper to connect +to \fBpasst\fR in order to set or clear the TCP_REPAIR option on sockets, during +migration. \fB--repair-path none\fR disables this interface (if you need to +specify a socket path called "none" you can prefix the path by \fI./\fR). + +Default, for \-\-vhost-user mode only, is to append \fI.repair\fR to the path +chosen for the hypervisor UNIX domain socket. No socket is created if not in +\-\-vhost-user mode.

.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. +.BR \-\-migrate-exit " " (DEPRECATED) +Exit after a completed migration as source. By default, \fBpasst\fR keeps +running and the migrated guest can continue using its connection, or a new guest +can connect.

-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. +Note that this configuration option is \fBdeprecated\fR and will be removed in a +future version. It is not expected to be of any use, and it simply reflects a +legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR +below.

-Examples: -.RS -.TP --t 22 -Forward local port 22 to 22 in the target namespace

...the passt equivalent says "guest". I think we should replace all these occurrences by "guest or namespace" at this point.

I started doing that, but thought it looked awkwardly bulky, without adding much clarity, so I left it at least for the first draft (there are also some existing places in the man page which use "guest" to refer to either a VM or namespace). But, given your preference I've substituted "guest or namespace" for v2. -- 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