From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: passt.top; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=Npwq62TY; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by passt.top (Postfix) with ESMTPS id E28BD5A0262 for ; Wed, 08 Apr 2026 01:16:04 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1775603763; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=kC8+phfd52dJww7LUt2KovAYWUyfCxg7NU6G3+PnF+8=; b=Npwq62TYTqb4GkpANW07CvSKhIPCIfZ7mKoY3DI6SgdR4X4pL6g4ZNuQQ+YP0DyastXd3P eTbsjvMosbmYNqiBoP/vCXbCNYUjz6dGPZd/8BIT6d9Fx0exBKpK2pzFJPA3ULHtoo4W9I SzptqXdmiFc83IiJvnNHhxgP2NXT6Q0= Received: from mail-wr1-f70.google.com (mail-wr1-f70.google.com [209.85.221.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-624-HHZBTN7AMQOIZSGq9EBjWg-1; Tue, 07 Apr 2026 19:16:02 -0400 X-MC-Unique: HHZBTN7AMQOIZSGq9EBjWg-1 X-Mimecast-MFC-AGG-ID: HHZBTN7AMQOIZSGq9EBjWg_1775603761 Received: by mail-wr1-f70.google.com with SMTP id ffacd0b85a97d-43b8f9374dfso170888f8f.0 for ; Tue, 07 Apr 2026 16:16:02 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1775603761; x=1776208561; h=date:content-transfer-encoding:mime-version:organization:references :in-reply-to:message-id:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=kC8+phfd52dJww7LUt2KovAYWUyfCxg7NU6G3+PnF+8=; b=BlNS9IfSNNokxH9+6RsjJvtr2CmlzEPsYu8t+Rzt0EuLVjPlpNRBpM6Fo+8633tnQn 2oJQeSyznZn9SQjuhrVlJlC13ToZRw3FdmEBB/a/x65k4Zq+vSvSv1c5vJo6QcuSzN18 lvr5tVHJb83SVVeDiJva6Lk4ctfL6teTosA284TCvsizynX30i++PmHnLH9UPaepYMre RgiXbQA7uUuJhNqHZIcLMCZcwbTflY/xcyRrz6kam63UZ2sCizYZwJBSYFd+6S57Kefh hgV9nhPSyo5SSKkSa0L9LvC50yE7YhXsuiCkm63Wq31D1E9WQlNpyt/TnrfjNLOccSm0 +T4g== X-Gm-Message-State: AOJu0YyL7LqPg1EF13Ck07Bs0iIILNWlMgE5Gkz6GGVPri/dd8FODHso LykOq5l331Do38BndQjSdBTtWJgzLR65ExzdYmLPTF3829Bj2VSbfTdb8XYKgfdAZFgde5lQ6Uf zuqxl68HlKDHU3jM3SA+hrDZnWuOh9uMaeM/Q5J+yvxxm27MMtNJq4w== X-Gm-Gg: AeBDies7vmnh0/FGhhmW/CuH4e0R15pyR1gaLfrX+UoQ5O986g1Vv76JLw/UF4y/bRh HKvWshSCCRuQWJmHDF/RNyLDXr2gwMFZzuExEddwcDSSGmxz9Bk6009ccCRgDZOJaSUVMP1ChEP ZUr0+daK+M/6fABIa5oFQWndItMgCadwvbcLRurvgpAlu5BYtyj0PYJu86pTyLXXrtb0JHuhnMF r8mvYysA8ByF6p3c7aUjFWmBngJp3HT6S9J6uuV26hNv4Wp5FYtO4jpm35JK2+qiMz4Ik2Hsp2B e1Xd+uc1QQaocGmZZVy9ol2kVSus0S+o3Z2MdDuoWtgkSCWCUZixs6JWBDZuojkbAiKWyzkarAV XKa0E4038BipEhA/8CZQ0f22pVNThwP/+K3OxGTiqvXhrD2hIag== X-Received: by 2002:a5d:5f56:0:b0:43b:5091:39db with SMTP id ffacd0b85a97d-43d28fe1d79mr29116455f8f.13.1775603761034; Tue, 07 Apr 2026 16:16:01 -0700 (PDT) X-Received: by 2002:a5d:5f56:0:b0:43b:5091:39db with SMTP id ffacd0b85a97d-43d28fe1d79mr29116427f8f.13.1775603760396; Tue, 07 Apr 2026 16:16:00 -0700 (PDT) Received: from maya.myfinge.rs (ifcgrfdd.trafficplex.cloud. [176.103.220.4]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-43d1e4f1a99sm56600652f8f.32.2026.04.07.16.14.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 07 Apr 2026 16:14:56 -0700 (PDT) From: Stefano Brivio To: David Gibson Subject: Re: [PATCH 04/18] doc: Consolidate -[tu] option descriptions for passt and pasta Message-ID: <20260408011440.0e22829b@elisabeth> In-Reply-To: <20260407031630.2457081-5-david@gibson.dropbear.id.au> References: <20260407031630.2457081-1-david@gibson.dropbear.id.au> <20260407031630.2457081-5-david@gibson.dropbear.id.au> Organization: Red Hat X-Mailer: Claws Mail 4.2.0 (GTK 3.24.49; x86_64-pc-linux-gnu) MIME-Version: 1.0 Date: Wed, 08 Apr 2026 01:14:41 +0200 (CEST) X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: dze2a-X8h9J-ci3NDyS4iWugjnOJh9FqTqDS6Rg7HPY_1775603761 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Message-ID-Hash: 4HDNT3U7GKP43K6VIFC4NXOQ5XH3W6IO X-Message-ID-Hash: 4HDNT3U7GKP43K6VIFC4NXOQ5XH3W6IO X-MailFrom: sbrivio@redhat.com 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: 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. > " 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, > 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. -- Stefano