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=W9W86q+A; dkim-atps=neutral Received: from mail.ozlabs.org (gandalf.ozlabs.org [150.107.74.76]) by passt.top (Postfix) with ESMTPS id 587555A0265 for ; Thu, 16 Apr 2026 03:47:26 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202602; t=1776304043; bh=nq1ET1axbpzABV14rcusMIhThZFFSomsh28qfkUf+fo=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=W9W86q+A/6HOLSoTREUsTTdOzOAy0DzCYcZAY8NCSuKLcQq8G2pf5bahD3kfaRubZ fUTZgPfw7qCoNQiG8HGP1Yvkg5yHlcqXlYSY25ubZARH5Cgw5eAKlQUPBrccm0zhz8 rXrSfZtEapkjMbs7MmyHUFUiLh9r+8+t90tXAz0KZFYwe/csLDdQ/ryGruoAN7RMzF mr+neC9vAApQcVEEAkoVegRMyV+nCDbTyrhmtGD0G1tA3094HOKdoIu6La3SsArdZl z+yhcYBlEAUxfYDhQDvyD5Ln9tRhbSQtf4Km+d4otS8z/cR/jxsu49oqzT5wc7RqyD tbfDOS07uYBuA== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4fx1974vk6z4wTL; Thu, 16 Apr 2026 11:47:23 +1000 (AEST) Date: Thu, 16 Apr 2026 11:34:10 +1000 From: David Gibson To: Stefano Brivio Subject: Re: [PATCH v2 15/23] doc: Rework man page description of port specifiers Message-ID: References: <20260410010309.736855-1-david@gibson.dropbear.id.au> <20260410010309.736855-16-david@gibson.dropbear.id.au> <20260416000437.3115b822@elisabeth> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="pZmAiyork1zWze5L" Content-Disposition: inline In-Reply-To: <20260416000437.3115b822@elisabeth> Message-ID-Hash: S3CRG3CCPJISQEIQUKM2RFN5MQOILRJZ X-Message-ID-Hash: S3CRG3CCPJISQEIQUKM2RFN5MQOILRJZ 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: --pZmAiyork1zWze5L Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Thu, Apr 16, 2026 at 12:04:38AM +0200, Stefano Brivio wrote: > On Fri, 10 Apr 2026 11:03:01 +1000 > David Gibson wrote: >=20 > > 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. > >=20 > > usage() output is updated similarly, though more briefly. > >=20 > > Signed-off-by: David Gibson > > --- > > conf.c | 10 +++++----- > > passt.1 | 32 ++++++++++++++++++++++---------- > > 2 files changed, 27 insertions(+), 15 deletions(-) > >=20 > > 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, in= t 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 listenin= g sockets reported by > > \fI/proc/net/tcp\fR and \fI/proc/net/tcp6\fR, see \fBproc\fR(5). > > =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. > > - > > -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. > > +[\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\f= R]] > > +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. >=20 > ..."from the set of all non-ephemeral ports permitted by current > capabilities"? >=20 > Or simply drop " from", because it should be clear from the paragraph > below? Uh, yeah, not entirely sure what I was going for there. I've changed this to \fB~\fR\fIfirst\fR[\fB-\fR\fIlast\fR] Exclude range. Don't forward port numbers between \fIfirst\fR and \fIlast\fR. This takes precedences over include ranges. >=20 > > +.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. > > =20 > > Examples: > > .RS >=20 > --=20 > Stefano >=20 --=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 --pZmAiyork1zWze5L Content-Type: application/pgp-signature; name=signature.asc -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEO+dNsU4E3yXUXRK2zQJF27ox2GcFAmngPJEACgkQzQJF27ox 2GcI1w//WMXpjbj/eH/EgGFNmEOlaBUC0liL6HRcYwiq1HGekKzol1B00+GVC2oc hJbtC1Z7/x/tLsQG8nVD9RpcxxVg8barMqdOiAV087+6LbsYLTaR4lZXWffLzYAw FlWUS2KNZ7h7eeOjSwjrCNxFyY8fHeZFXSF6E+WpSp2pYJmoj+wnZHjPJ0K3CnTh mB53wpuwnCoBSFPEEGUPdG6I9n11BbRckDOf0uZ5DO7s6gMp6F7VAWLdKA7GZZ0K laBy+fImi3pvuewupRtptVyggKGspnFQdGyi0BBQAZfzGugxM9E/mY4ViqoKUOrk r30ys3VjZ5uyOGneNLB5GMxiAdfLoY9tNKR/BOFYXAJqd+NnGDrV3FkxHk//9VQP QsuqCSe6lcEjomPhAcaCRkvLOjepCghIO9UPpJ/UjcaT/CoLw72pisygiaNqrcW3 B2EwP4Gjhs5vY/jqPuoUKtf6KJ6hTackrJpFOd6IRfxmkI9KhDzMMDVu6nTe1cS3 rnazT11BOlXN2m9cu4Y1E5Z+JdzcdsgSnb1aTOJWjMwBGGaW2tc41qut4XdnxH6J O8Uo8HkF9Ef2Kxs88Y7Upl2w+udzpE6kj5j06dGu9Nsu88GOBQ8KOIiJ/8ouQnfw 4UlhvCNga7EzI/luyqnAo5XWXVfn7hs4kgwgSHClse/z5yh95iQ= =yKS/ -----END PGP SIGNATURE----- --pZmAiyork1zWze5L--