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=gZmhEz4U; dkim-atps=neutral Received: from mail.ozlabs.org (mail.ozlabs.org [IPv6:2404:9400:2221:ea00::3]) by passt.top (Postfix) with ESMTPS id 3B3A85A0657 for ; Fri, 17 Apr 2026 07:05:36 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202602; t=1776402331; bh=3H2O8V8W+ErIjAFWB2JHsu+13rL+bFbK8M1oth/21ug=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=gZmhEz4UXv+i/clE6/RMVCrBP9dhhKBcrPM7R5txWNTSm6hPAKAMBajdzrbrC815A thpnfgOl6ySwQn0NAv6MX3UOmfeLslQ2B5pBEu/4bjKAqSKMWvElQvwPubD0YjldSY +ljTU5eCg3L48KJ8Nsqb6CB8mR8ypQk1fYJ6eKYLJLwnTN1P/aQyfWWiyc03mw9NOV fBnLGwHqg5W983KdYN/A8ZbAFP9KDrn57bB220SA8ZGA64vDnAclzP6NmixZqtssvK nVUUgHgRyWK9eigMj76kf7SFPqGzaevgVoXXfFyWzYKsJy3s4JYmFzmi88uOj8X5nW SY06TOEY/fNbw== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4fxjWH6bgqz4wSj; Fri, 17 Apr 2026 15:05:31 +1000 (AEST) From: David Gibson To: passt-dev@passt.top, Stefano Brivio Subject: [PATCH v3 01/11] doc: Rework man page description of port specifiers Date: Fri, 17 Apr 2026 15:05:10 +1000 Message-ID: <20260417050520.102247-2-david@gibson.dropbear.id.au> X-Mailer: git-send-email 2.53.0 In-Reply-To: <20260417050520.102247-1-david@gibson.dropbear.id.au> References: <20260417050520.102247-1-david@gibson.dropbear.id.au> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Message-ID-Hash: FOUQACANNCHVVIWX6P74C7XBLYKM3P4A X-Message-ID-Hash: FOUQACANNCHVVIWX6P74C7XBLYKM3P4A 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: David Gibson 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: 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 cea124a5..6b5d2bd1 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..c47452ce 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. Don't forward port numbers between \fIfirst\fR and +\fIlast\fR. This takes precedences over include ranges. +.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 -- 2.53.0