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=U8GH8zAA; dkim-atps=neutral Received: from mail.ozlabs.org (mail.ozlabs.org [IPv6:2404:9400:2221:ea00::3]) by passt.top (Postfix) with ESMTPS id ABBC85A0626 for ; Fri, 10 Apr 2026 03:03:24 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202602; t=1775782993; bh=vmK68k8JiQsFAVo9yY3Dt0GYqdBqA+oSTP19v9LP6Mc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=U8GH8zAAvdzaZ6DxNbGTgQFROFliSUlg0GGUrXpdhCBnjwOpSZn2VTYEYbCr6RLzE qcqid7eU3PS2d2DparTuQKrnmFLR1wci3gliOxXHH+uHuEnUpUM3ACC8Iylbd/nd8M PK2kra4VowkAZ7i4LbJ2xHsbeTpPUPjvi9a9apPlt1IdRQcrm35Vf8eCXUbymp7ekB vxK37Yi17q6ZLV8k+6gHYGyDF268S8rFyZ9yFNLlDshps+25dN6jGaM/uomsBLdhjg JMOni5Xn1qJ0pr0SOJUxMC25KSIhSvIyngXIQUUuAqA18aK3Ujo9FKx3xJ9jzfhHb8 VZzZPXb5o8zTg== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4fsJSx0rsnz4wTk; Fri, 10 Apr 2026 11:03:13 +1000 (AEST) From: David Gibson To: passt-dev@passt.top, Stefano Brivio Subject: [PATCH v2 15/23] doc: Rework man page description of port specifiers Date: Fri, 10 Apr 2026 11:03:01 +1000 Message-ID: <20260410010309.736855-16-david@gibson.dropbear.id.au> X-Mailer: git-send-email 2.53.0 In-Reply-To: <20260410010309.736855-1-david@gibson.dropbear.id.au> References: <20260410010309.736855-1-david@gibson.dropbear.id.au> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Message-ID-Hash: QCUHA6WNW7MU6RDRZD2FS6TCYBTJJLMQ X-Message-ID-Hash: QCUHA6WNW7MU6RDRZD2FS6TCYBTJJLMQ 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 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. +.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