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=HEosU78R; 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 D87E35A026E for ; Mon, 20 Apr 2026 15:31:58 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1776691917; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:autocrypt:autocrypt; bh=++reEggdmTx45r7ew5Dr/J35R/khPuU+m7XQdCi4/1g=; b=HEosU78Rlia/RHaG8zYpVvlap2oXGITkgUhNo4ji2yDnGeIFYV0EUcHb44BUuMSe2RUCdM 2hk5U8kXAIPFq3ghyelenrhCdB1Nn0EC7ruZxFc39gOHdrolPE8xvn4QZguBu1kC6qw40U MXemBQK2t6UBW35eBrSOiLbBdMO56bE= Received: from mail-pf1-f200.google.com (mail-pf1-f200.google.com [209.85.210.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-55-GsO0mWeqNw6bWIrlAHbEQQ-1; Mon, 20 Apr 2026 09:31:53 -0400 X-MC-Unique: GsO0mWeqNw6bWIrlAHbEQQ-1 X-Mimecast-MFC-AGG-ID: GsO0mWeqNw6bWIrlAHbEQQ_1776691912 Received: by mail-pf1-f200.google.com with SMTP id d2e1a72fcca58-82f5f48458eso1715680b3a.3 for ; Mon, 20 Apr 2026 06:31:53 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1776691912; x=1777296712; h=content-transfer-encoding:in-reply-to:autocrypt:from :content-language:references:to:subject:user-agent:mime-version:date :message-id:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=++reEggdmTx45r7ew5Dr/J35R/khPuU+m7XQdCi4/1g=; b=mCZx2v5MBmOKVcGSkaP/roC0jhQtxulCgN3Y3YNB51M9HtkKOGJmOAddieW4JZr6ee u/P5meHRIsU7aqW4EtrnoFhi0D3CfelDerUzY2yUDcagISqH2xF5lXHChInLILijWDJQ /fhVa7447VJlTJIENhfoKXEhlU6JkONxVjOaUKEj/Uqppe8iEtzA6d0kvC8Dm3TAzEWx +hhqGxWeUijqOKBlbf3W4eBOHPJqkQcd6qBmWobYQPqcbbWPviwAD4jj8kZqJwUlR86B +WbEwlYbbqcN/tSJMY8tbC3IBGx+yxIz9wMW///tHyCMSW4HqQc2bfUhrRfUtQ2QJ73G PFCg== X-Forwarded-Encrypted: i=1; AFNElJ9ThK1CtGzL14OPp2c98MSCC2eOgVSEuBI6ep2+NMbjeSSdSaPgIDmpguytcTavCFpb179mHHTt7dI=@passt.top X-Gm-Message-State: AOJu0YxNEl59zLzuFC22IZflzt8z4rI1XmPfGyS/TtEFHFpcpSrk3s2k tVw7cObefzcmbdpLVwmBTbWVmmyGL69C1ueUpTfRVV56syYSQhqMKHEoHzencb2aLt68f9OYP9K yx6G7UhkNeYKcKAYfVXlGXhJtBK1gkeCeDCmKLuRZtVWnTsBy5XvyoP5QAYNnYg== X-Gm-Gg: AeBDiet7chGtGIgWT48CYBAvztKQcIuzQW69O0jo2wJfDDDb9I3lK7tUvjRIfVlhcYJ Rw1WExFPuHeWNgE+6dPSh/FbGAx6MYwSq95+4SevOjKS0F1sPp5QGV1ku2+xHbj/YtBFEKsM7YP bT4epNy5f4Odvz9Gef2+CjKIHaqhd6E6Mgqv02UM+4DSwDK63JMdT9x1mKgeYk1vlwL8lJef1VL v9JJI81+CEe8kMPsXjwo1JRSlVJ3J3d0zzR8JySm0eYHqvPT/Y1vCBWxAISmNOReEO4C7DDsKsd cW7QXJLAid59a1/tEtXqk2WO2Rfycvkgi9nSZ2e+eKC0AALXNMNOw2hgnEFvWntydSVYI9V4jfo rYncJYeXM8G8XqFiCsDDvlLS7cxd2qiYfe8BdTVkeGBvAeZ/S4c5MOfY/36JFSzA3Mg== X-Received: by 2002:a05:6a00:2d01:b0:82c:9c47:fefb with SMTP id d2e1a72fcca58-82f8c8448bamr13535159b3a.20.1776691911903; Mon, 20 Apr 2026 06:31:51 -0700 (PDT) X-Received: by 2002:a05:6a00:2d01:b0:82c:9c47:fefb with SMTP id d2e1a72fcca58-82f8c8448bamr13535105b3a.20.1776691911204; Mon, 20 Apr 2026 06:31:51 -0700 (PDT) Received: from [192.168.100.100] (82-64-211-94.subs.proxad.net. [82.64.211.94]) by smtp.gmail.com with ESMTPSA id d2e1a72fcca58-82f8ec05391sm11245236b3a.56.2026.04.20.06.31.48 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 20 Apr 2026 06:31:50 -0700 (PDT) Message-ID: <281ef2a2-b06c-4130-8225-c87b8bdbb9f5@redhat.com> Date: Mon, 20 Apr 2026 15:31:44 +0200 MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Subject: Re: [PATCH v3 01/11] doc: Rework man page description of port specifiers To: David Gibson , passt-dev@passt.top, Stefano Brivio References: <20260417050520.102247-1-david@gibson.dropbear.id.au> <20260417050520.102247-2-david@gibson.dropbear.id.au> From: Laurent Vivier Autocrypt: addr=lvivier@redhat.com; keydata= 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 In-Reply-To: <20260417050520.102247-2-david@gibson.dropbear.id.au> X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: lZpl1IisFJPLx2O5rIkesiPIowOVMfqaibeO9tERdzw_1776691912 X-Mimecast-Originator: redhat.com Content-Language: en-US Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Message-ID-Hash: 47NUYQ2DVLCCAOJVZZWMXQCMS4NRE2EH X-Message-ID-Hash: 47NUYQ2DVLCCAOJVZZWMXQCMS4NRE2EH X-MailFrom: lvivier@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 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 4/17/26 07:05, 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 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 Reviewed-by: Laurent Vivier