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=jHYB5B+/; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by passt.top (Postfix) with ESMTPS id 8C6B85A0265 for ; Thu, 16 Apr 2026 00:04:43 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1776290682; 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=l/6edgPr9pPNJQBZR3YLEkjtwtX3StMwvoFagM/fs7A=; b=jHYB5B+/2DtPACRiCexwrbtxD2ubBhXBW1htG4tqmCTsGwwabfu6dM0DlJ6EfuYvfVXWBx UmWqaYn4jS3Ph4kw+J0SrjSB3wxBdJwbCkKlUyng5IA30ek7e2cYWBOG/gUr35EQGOmB3F PRcRmUQWO4c/8SdnIsvHQ0d3l/iUxu8= Received: from mail-wm1-f70.google.com (mail-wm1-f70.google.com [209.85.128.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-187-TZ4g0kJdOYOkekx6T9JRXw-1; Wed, 15 Apr 2026 18:04:41 -0400 X-MC-Unique: TZ4g0kJdOYOkekx6T9JRXw-1 X-Mimecast-MFC-AGG-ID: TZ4g0kJdOYOkekx6T9JRXw_1776290680 Received: by mail-wm1-f70.google.com with SMTP id 5b1f17b1804b1-4836abfc742so55864705e9.0 for ; Wed, 15 Apr 2026 15:04:40 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1776290679; x=1776895479; 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=l/6edgPr9pPNJQBZR3YLEkjtwtX3StMwvoFagM/fs7A=; b=p+gQ0B0iBfs6gpEZTcwXwLN568OWs2WPgc8moXS4ki2ilnfd05XiBIVrJMnnZ3pAPz cLjWM+UzM+pHeAEmAdJehbS3zYy9oExYpDsjHow8rSQmO7Glv5flMJYPkqhUFmJrLD2X GejIFHDdIPe/EikRRCjFpMTPILrQJGKKnLdHeA7aI7G/j3S2+kMs9m5/vbFJjVtHiuTb NDl57OCX7ODT2fSS4Pif7FEV0FSq8DH2A539KNvBwxqhxHLOrtYra8qOq5KmrC0/TqZh e8UPPsyw2sWd4USLJv8oq7Vy/yup7WzlQBhs5t2w0Ln7G/SLSAO77RitBW6ykna/dUry uAnA== X-Gm-Message-State: AOJu0YxuLl3B37HdYI4gHE+G4RbrV2fEtg2Sx9n2VEvjqHtj9wjh54G7 Bf9G7nIc5MdF1/LUBR/NDV7FB9ALyBVSjyRGeLxPVxR6C7tIH2Fd+XJrLy6j7ZfAuMT4w2WE9xp Zq18ASMzie9dexLyqDhl990VpMFzbHUOSwu8odThGuXgAvnSJm4cgWAOB8AmfyA== X-Gm-Gg: AeBDievOelHby0OXpyEMthmC0WKbV5AVK7nIt1MwPpLsRRheqYz0AIVBjLWJtrNHw20 sWVNDnaW7Cn9SqgsQmVHcmFTS7I89dd6wYWsChoMtrF+heqqQ5A1A3uvRKmVCj3rm3WUjZk+iQs aDIfwTOamZ1pjBXO0B3yJpx/jt1gJDYi0Dt2mKi4BVvaEOZmpXQXnaMseKu1UEP+vFsYbBVSICO F2RnAm35ybdAA8pCZWTlv1jS5quPfwZZw9HYI+5oyAQxiOF3zZZt7fIq+GpSbp51zsg2XkQEkkf iznzl+HZPjiozDqxeS2YIQJ39/xp92i1+pgNlza0FPoVgFhRQKOPhtFlZmmJ+weRCxVkgfh8rMu gITsF5pym05V+Czcj8UKwBhv499+OifUtzK3xEhomNNfxqAlCZQ== X-Received: by 2002:a05:600c:c0cc:b0:480:1c69:9d36 with SMTP id 5b1f17b1804b1-488d68af13dmr214785805e9.17.1776290679433; Wed, 15 Apr 2026 15:04:39 -0700 (PDT) X-Received: by 2002:a05:600c:c0cc:b0:480:1c69:9d36 with SMTP id 5b1f17b1804b1-488d68af13dmr214785655e9.17.1776290678917; Wed, 15 Apr 2026 15:04:38 -0700 (PDT) Received: from maya.myfinge.rs (ifcgrfdd.trafficplex.cloud. [176.103.220.4]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-488f584e243sm1003265e9.10.2026.04.15.15.04.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 15 Apr 2026 15:04:38 -0700 (PDT) From: Stefano Brivio To: David Gibson Subject: Re: [PATCH v2 15/23] doc: Rework man page description of port specifiers Message-ID: <20260416000437.3115b822@elisabeth> In-Reply-To: <20260410010309.736855-16-david@gibson.dropbear.id.au> References: <20260410010309.736855-1-david@gibson.dropbear.id.au> <20260410010309.736855-16-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: Thu, 16 Apr 2026 00:04:38 +0200 (CEST) X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: o3KP7Rh8m_phAFLGEYA8zo0zDusmAI_WTIGFKvkdsio_1776290680 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Message-ID-Hash: H46ZD6O7OA727Y2EQ3YNPJQE7J4SP7A2 X-Message-ID-Hash: H46ZD6O7OA727Y2EQ3YNPJQE7J4SP7A2 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 Fri, 10 Apr 2026 11:03:01 +1000 David Gibson wrote: > 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. > > usage() output is updated similarly, though more briefly. > > Signed-off-by: David Gibson > --- > conf.c | 10 +++++----- > passt.1 | 32 ++++++++++++++++++++++---------- > 2 files changed, 27 insertions(+), 15 deletions(-) > > 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, int 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 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, > -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. > - > -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. > +[\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\fR]] > +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. ..."from the set of all non-ephemeral ports permitted by current capabilities"? Or simply drop " from", because it should be clear from the paragraph below? > +.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. > > Examples: > .RS -- Stefano