From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=none (p=none dis=none) header.from=gibson.dropbear.id.au Authentication-Results: passt.top; dkim=pass (2048-bit key; secure) header.d=gibson.dropbear.id.au header.i=@gibson.dropbear.id.au header.a=rsa-sha256 header.s=202602 header.b=Ytvx4w9v; dkim-atps=neutral Received: from mail.ozlabs.org (mail.ozlabs.org [IPv6:2404:9400:2221:ea00::3]) by passt.top (Postfix) with ESMTPS id 1286C5A0272 for ; Wed, 08 Apr 2026 03:37:14 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202602; t=1775612229; bh=+X9Nw/JGUEHylGBZpgZr2KwBhCYwNAHw0qw/FmDNZH0=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=Ytvx4w9vqBtCOc72A7/+TpkxZt9ExP87caEvEZUn9II2WUJC0U9OrKq6iaSfoN+KW AovLBLJ2b457G7Jx3S85LsQCBgaP9A1I8hfMGS0cj1sMFqBYciQHytiOT6sm4ZRNWc hKAM64pWAZ+j2qZTE3rHk5FOqoS0tq1Jsudrgxssw3IWOFK5kBrtD1cvHR48sfZ7nc 3NEFYp/DqO0k1bFi5xesEod1ZY7DUd/+Y78isohMnu/lsGkogn533ZI2g2B4McBHyk CUJRJDc8u4IEkiVgTePVAO4MJzcBDfK7mF4kjv7aHWoiMBZl9oW6pEDtBZAPn/plXq 1lapu2FfXyKcg== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4fr5K171CLz4wby; Wed, 08 Apr 2026 11:37:09 +1000 (AEST) Date: Wed, 8 Apr 2026 11:23:09 +1000 From: David Gibson To: Stefano Brivio Subject: Re: [PATCH 04/18] doc: Consolidate -[tu] option descriptions for passt and pasta Message-ID: References: <20260407031630.2457081-1-david@gibson.dropbear.id.au> <20260407031630.2457081-5-david@gibson.dropbear.id.au> <20260408011440.0e22829b@elisabeth> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="GPn8B45RGbmpu+kS" Content-Disposition: inline In-Reply-To: <20260408011440.0e22829b@elisabeth> Message-ID-Hash: SGAOEMSFJUH6G4IKKUZZLNWB2BS6YLZK X-Message-ID-Hash: SGAOEMSFJUH6G4IKKUZZLNWB2BS6YLZK X-MailFrom: dgibson@gandalf.ozlabs.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: passt-dev@passt.top X-Mailman-Version: 3.3.8 Precedence: list List-Id: Development discussion and patches for passt Archived-At: Archived-At: List-Archive: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: --GPn8B45RGbmpu+kS Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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: >=20 > > The man page currently has two fairly large, near-identical sections >=20 > Not entirely identical also because: >=20 > > 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. > >=20 > > There's similar duplication usage(), consolidate that as well. > >=20 > > Signed-off-by: David Gibson > > --- > > conf.c | 54 +++++--------- > > passt.1 | 216 ++++++++++++++++++-------------------------------------- > > 2 files changed, 85 insertions(+), 185 deletions(-) > >=20 > > 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, in= t 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, in= t 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" >=20 > ...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. >=20 > To reaffirm the difference between terms used in the code and terms > used in documentation, could we perhaps do something like: >=20 > char *guest =3D (mode =3D=3D MODE_PASTA) ? "namespace" : "guest"; >=20 > ? And then use that later? It might be worth doing that for the > "default" strings too. Sure, done. >=20 > > " 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" > > + ); > > =20 > > passt_exit(status); > > =20 > > pasta_opts: > > =20 > > 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. > > =20 > > -.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--s= ocket\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 t= o connect > > -to \fBpasst\fR in order to set or clear the TCP_REPAIR option on socke= ts, during > > -migration. \fB--repair-path none\fR disables this interface (if you ne= ed to > > -specify a socket path called "none" you can prefix the path by \fI./\f= R). > > - > > -Default, for \-\-vhost-user mode only, is to append \fI.repair\fR to t= he 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 ke= eps > > -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 re= moved in a > > -future version. It is not expected to be of any use, and it simply ref= lects 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 igno= red, so > > -that any further message reaching sockets after the source migrated is= silently > > -ignored, to avoid connection resets in case data is received after mig= ration. > > - > > -Note that this configuration option is \fBdeprecated\fR and will be re= moved in a > > -future version. It is not expected to be of any use, and it simply ref= lects 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 clie= nt closes > > -the socket, or once we get a socket error. > > - > > -\fBNote\fR: this option has no effect after \fBpasst\fR completes a mi= gration as > > -source, because, in that case, exiting would close sockets for active > > -connections, which would in turn cause connection resets if any furthe= r 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\f= R can be one of: > > Don't forward any ports > > =20 > > .TP > > -.BR all > > +.BR all (\fBpasst\fR only) >=20 > 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 capa= bilities. > > For low (< 1024) ports, see \fBNOTES\fR. No failures are reported for > > unavailable ports, unless no ports could be forwarded at all. > > =20 > > +.TP > > +.BR auto (\fBpasta\fR only) >=20 > ...this one doesn't. >=20 > > +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 200= 10 > > .RE > > =20 > > -Default is \fBnone\fR. > > +Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR. > > .RE > > =20 > > .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= =2E IPv6 > > bound ports are also forwarded for IPv4. > > =20 > > -Default is \fBnone\fR. > > +Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR. > > =20 > > -.SS \fBpasta\fR-only options > > +.SS \fBpasst\fR-only options > > =20 > > .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 interfac= e 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. > > =20 > > .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--s= ocket\fR. > > =20 > > .TP > > -.BR none > > -Don't forward any ports > > +.BR \-\-print-capabilities > > +Print back-end capabilities in JSON format, only meaningful for vhost-= user mode. > > =20 > > .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 t= o connect > > +to \fBpasst\fR in order to set or clear the TCP_REPAIR option on socke= ts, during > > +migration. \fB--repair-path none\fR disables this interface (if you ne= ed to > > +specify a socket path called "none" you can prefix the path by \fI./\f= R). > > + > > +Default, for \-\-vhost-user mode only, is to append \fI.repair\fR to t= he path > > +chosen for the hypervisor UNIX domain socket. No socket is created if = not in > > +\-\-vhost-user mode. > > =20 > > .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, sele= cted 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 ke= eps > > +running and the migrated guest can continue using its connection, or a= new guest > > +can connect. > > =20 > > -Specifying excluded ranges only implies that all other ports are forwa= rded. In > > -this case, no failures are reported for unavailable ports, unless no p= orts could > > -be forwarded at all. > > +Note that this configuration option is \fBdeprecated\fR and will be re= moved in a > > +future version. It is not expected to be of any use, and it simply ref= lects a > > +legacy behaviour. If you have any use for this, refer to \fBREPORTING = BUGS\fR > > +below. > > =20 > > -Examples: > > -.RS > > -.TP > > --t 22 > > -Forward local port 22 to 22 in the target namespace >=20 > ...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. --=20 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 --GPn8B45RGbmpu+kS Content-Type: application/pgp-signature; name=signature.asc -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEO+dNsU4E3yXUXRK2zQJF27ox2GcFAmnVrfwACgkQzQJF27ox 2Gf7thAAlFCYOiySF7Boq21jEo3h/iv3nlMWryoDJuZtVGjiwAs3FRfO81L9+4d/ pTNVfNkxs1/zUfcGZpn41INm9RJCwhvdR+KzS2QH3VZSyFqPHaNk8SLjIA1pDfZT jzAl795KsblFDFrBI0uaF00dZrPOU0HLjMwDc0/Q1Wh91e/8cw/QXwbNEXe4b8j0 zEXDrhueh9tN4C8BIp3Zmf3xIW69/4za3F9+X2nxEHwXZyXF4voPA5CCTiP5M4H1 TfmaUaIXMGqKTb3lpcI6hxwxXJo06TgWkNqOQBkH1XngBW/zCRrraEkaMQffC0pG yOcivfZxGDRe0e9MVHmlTm0V9jHE2w7sdcxPLohhRHMk5vInz12LHwx/Dk7NZkir 5CchyZ5yHkfLSMb98Y6uKosOGQjhyC7IPgfm+C6F24XF5KxxozxQOglbD9VVbkDn pXBZDwfdJPfws/Po17VOmJTJ9CinC2qdhRcnTx25vUKdFoPK57LMCcrOdYxQ9HV9 eZQWF0YYBLUF4bi9gVT1L8A8ms/KfuuIHVSbrWnJVD0S1I/X64eTRPtyee9YLbBh BoMGOJxsBkdU2pBqzjZlY4RwsTbrbxgR5d2J6nrZQ10Jivx6p/KB8Sckwb2ENJrw 8Yp7gOP2ymvXDU6ckwuooc4DRvcNMbhYRfNzPgKZpzP5UOlK0Mk= =zsNk -----END PGP SIGNATURE----- --GPn8B45RGbmpu+kS--