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

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

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

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 <david@gibson.dropbear.id.au> 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 <david@gibson.dropbear.id.au>
> > ---
> >  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

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