The man page currently has two fairly large, near-identical sections
separately describing the -t and -u options for passt and pasta. This is
bulky and potentially confusing. It will make this information more
tedious to update as we alter what's possible here with the forwarding
table. Consolidate both descriptions to a single one in the common
options, noting the few passt/pasta difference inline.
There's similar duplication usage(), consolidate that as well.
Signed-off-by: David Gibson
---
conf.c | 72 ++++++++----------
passt.1 | 230 ++++++++++++++++++--------------------------------------
2 files changed, 105 insertions(+), 197 deletions(-)
diff --git a/conf.c b/conf.c
index f3b36bb6..64ee8f00 100644
--- a/conf.c
+++ b/conf.c
@@ -888,6 +888,8 @@ static void conf_ip6_local(struct ip6_ctx *ip6)
*/
static void usage(const char *name, FILE *f, int status)
{
+ const char *guest, *fwd_default;
+
if (strstr(name, "pasta")) {
FPRINTF(f, "Usage: %s [OPTION]... [COMMAND] [ARGS]...\n", name);
FPRINTF(f, " %s [OPTION]... PID\n", name);
@@ -897,8 +899,14 @@ static void usage(const char *name, FILE *f, int status)
"Without PID or --netns, run the given command or a\n"
"default shell in a new network and user namespace, and\n"
"connect it via pasta.\n");
+
+ guest = "namespace";
+ fwd_default = "auto";
} else {
FPRINTF(f, "Usage: %s [OPTION]...\n", name);
+
+ guest = "guest";
+ fwd_default = "none";
}
FPRINTF(f,
@@ -1023,70 +1031,50 @@ static void usage(const char *name, FILE *f, int status)
" --freebind Bind to any address for forwarding\n"
" --no-map-gw Don't map gateway address to host\n"
" -4, --ipv4-only Enable IPv4 operation only\n"
- " -6, --ipv6-only Enable IPv6 operation only\n");
-
- if (strstr(name, "pasta"))
- goto pasta_opts;
-
- FPRINTF(f,
- " -1, --one-off Quit after handling one single client\n"
- " -t, --tcp-ports SPEC TCP port forwarding to guest\n"
+ " -6, --ipv6-only Enable IPv6 operation only\n"
+ " -t, --tcp-ports SPEC TCP port forwarding to %s\n"
" can be specified multiple times\n"
" SPEC can be:\n"
" '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"
" Examples:\n"
- " -t 22 Forward local port 22 to 22 on guest\n"
- " -t 22:23 Forward local port 22 to 23 on guest\n"
+ " -t 22 Forward local port 22 to 22 on %s\n"
+ " -t 22:23 Forward local port 22 to 23 on %s\n"
" -t 22,25 Forward ports 22, 25 to ports 22, 25\n"
" -t 22-80 Forward ports 22 to 80\n"
" -t 22-80:32-90 Forward ports 22 to 80 to\n"
" corresponding port numbers plus 10\n"
- " -t 192.0.2.1/5 Bind port 5 of 192.0.2.1 to guest\n"
+ " -t 192.0.2.1/5 Bind port 5 of 192.0.2.1 to %s\n"
" -t 5-25,~10-20 Forward ports 5 to 9, and 21 to 25\n"
" -t ~25 Forward all ports except for 25\n"
- " default: none\n"
- " -u, --udp-ports SPEC UDP port forwarding to guest\n"
+ " default: %s\n"
+ " -u, --udp-ports SPEC UDP port forwarding to %s\n"
" SPEC is as described for TCP above\n"
- " default: none\n");
+ " default: %s\n",
+ guest,
+ strstr(name, "pasta") ?
+ " 'auto': forward all ports currently bound in namespace\n"
+ :
+ " 'all': forward all unbound, non-ephemeral ports\n",
+ guest, guest, guest, fwd_default, guest, fwd_default);
+
+ if (strstr(name, "pasta"))
+ goto pasta_opts;
+
+ FPRINTF(f,
+ " -1, --one-off Quit after handling one single client\n"
+ );
passt_exit(status);
pasta_opts:
FPRINTF(f,
- " -t, --tcp-ports SPEC TCP port forwarding to namespace\n"
- " can be specified multiple times\n"
- " SPEC can be:\n"
- " 'none': don't forward any ports\n"
- " 'auto': forward all ports currently bound in namespace\n"
- " 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 '%%'. Examples:\n"
- " -t 22 Forward local port 22 to port 22 in netns\n"
- " -t 22:23 Forward local port 22 to port 23\n"
- " -t 22,25 Forward ports 22, 25 to ports 22, 25\n"
- " -t 22-80 Forward ports 22 to 80\n"
- " -t 22-80:32-90 Forward ports 22 to 80 to\n"
- " corresponding port numbers plus 10\n"
- " -t 192.0.2.1/5 Bind port 5 of 192.0.2.1 to namespace\n"
- " -t 5-25,~10-20 Forward ports 5 to 9, and 21 to 25\n"
- " -t ~25 Forward all bound ports except for 25\n"
- " default: auto\n"
- " IPv6 bound ports are also forwarded for IPv4\n"
- " -u, --udp-ports SPEC UDP port forwarding to namespace\n"
- " SPEC is as described for TCP above\n"
- " default: auto\n"
- " IPv6 bound ports are also forwarded for IPv4\n"
- " unless specified, with '-t auto', UDP ports with numbers\n"
- " corresponding to forwarded TCP port numbers are\n"
- " forwarded too\n"
" -T, --tcp-ns SPEC TCP port forwarding to init namespace\n"
" SPEC is as described above\n"
" default: auto\n"
diff --git a/passt.1 b/passt.1
index 13e8df9d..976f3f0c 100644
--- a/passt.1
+++ b/passt.1
@@ -425,81 +425,9 @@ Send \fIname\fR as DHCP option 12 (hostname).
FQDN to configure the client with.
Send \fIname\fR as Client FQDN: DHCP option 81 and DHCPv6 option 39.
-.SS \fBpasst\fR-only options
-
-.TP
-.BR \-s ", " \-\-socket-path ", " \-\-socket " " \fIpath
-Path for UNIX domain socket used by \fBqemu\fR(1) or \fBqrap\fR(1) to connect to
-\fBpasst\fR.
-Default is to probe a free socket, not accepting connections, starting from
-\fI/tmp/passt_1.socket\fR to \fI/tmp/passt_64.socket\fR.
-
-.TP
-.BR \-\-vhost-user
-Enable vhost-user. The vhost-user command socket is provided by \fB--socket\fR.
-
-.TP
-.BR \-\-print-capabilities
-Print back-end capabilities in JSON format, only meaningful for vhost-user mode.
-
-.TP
-.BR \-\-repair-path " " \fIpath
-Path for UNIX domain socket used by the \fBpasst-repair\fR(1) helper to connect
-to \fBpasst\fR in order to set or clear the TCP_REPAIR option on sockets, during
-migration. \fB--repair-path none\fR disables this interface (if you need to
-specify a socket path called "none" you can prefix the path by \fI./\fR).
-
-Default, for \-\-vhost-user mode only, is to append \fI.repair\fR to the path
-chosen for the hypervisor UNIX domain socket. No socket is created if not in
-\-\-vhost-user mode.
-
-.TP
-.BR \-\-migrate-exit " " (DEPRECATED)
-Exit after a completed migration as source. By default, \fBpasst\fR keeps
-running and the migrated guest can continue using its connection, or a new guest
-can connect.
-
-Note that this configuration option is \fBdeprecated\fR and will be removed in a
-future version. It is not expected to be of any use, and it simply reflects a
-legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR
-below.
-
-.TP
-.BR \-\-migrate-no-linger " " (DEPRECATED)
-Close TCP sockets on the source instance once migration completes.
-
-By default, sockets are kept open, and events on data sockets are ignored, so
-that any further message reaching sockets after the source migrated is silently
-ignored, to avoid connection resets in case data is received after migration.
-
-Note that this configuration option is \fBdeprecated\fR and will be removed in a
-future version. It is not expected to be of any use, and it simply reflects a
-legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR
-below.
-
-.TP
-.BR \-F ", " \-\-fd " " \fIFD
-Pass a pre-opened, connected socket to \fBpasst\fR. Usually the socket is opened
-in the parent process and \fBpasst\fR inherits it when run as a child. This
-allows the parent process to open sockets using another address family or
-requiring special privileges.
-
-This option implies the behaviour described for \-\-one-off, once this socket
-is closed.
-
-.TP
-.BR \-1 ", " \-\-one-off
-Quit after handling a single client connection, that is, once the client closes
-the socket, or once we get a socket error.
-
-\fBNote\fR: this option has no effect after \fBpasst\fR completes a migration as
-source, because, in that case, exiting would close sockets for active
-connections, which would in turn cause connection resets if any further data is
-received. See also the description of \fI\-\-migrate-no-linger\fR.
-
.TP
.BR \-t ", " \-\-tcp-ports " " \fIspec
-Configure TCP port forwarding to guest. \fIspec\fR can be one of:
+Configure TCP port forwarding to guest or namespace. \fIspec\fR can be one of:
.RS
.TP
@@ -507,11 +435,17 @@ Configure TCP port forwarding to guest. \fIspec\fR can be one of:
Don't forward any ports
.TP
-.BR all
+.BR all " " (\fBpasst\fR " " only)
Forward all unbound, non-ephemeral ports, as permitted by current capabilities.
For low (< 1024) ports, see \fBNOTES\fR. No failures are reported for
unavailable ports, unless no ports could be forwarded at all.
+.TP
+.BR auto " " (\fBpasta\fR " " only)
+Dynamically forward ports bound in the namespace. The list of ports is
+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,
@@ -528,22 +462,22 @@ Examples:
.RS
.TP
-t 22
-Forward local port 22 to port 22 on the guest
+Forward local port 22 to port 22 on the guest or namespace
.TP
-t 22:23
-Forward local port 22 to port 23 on the guest
+Forward local port 22 to port 23 on the guest or namespace
.TP
-t 22,25
-Forward local ports 22 and 25 to ports 22 and 25 on the guest
+Forward local ports 22 and 25 to ports 22 and 25 on the guest or namespace
.TP
-t 22-80
-Forward local ports between 22 and 80 to corresponding ports on the guest
+Forward local ports between 22 and 80 to corresponding ports on the guest or namespace
.TP
-t 22-80:32-90
-Forward local ports between 22 and 80 to ports between 32 and 90 on the guest
+Forward local ports between 22 and 80 to ports between 32 and 90 on the guest or namespace
.TP
-t 192.0.2.1/22
-Forward local port 22, bound to 192.0.2.1, to port 22 on the guest
+Forward local port 22, bound to 192.0.2.1, to port 22 on the guest or namespace
.TP
-t 192.0.2.1%eth0/22
Forward local port 22, bound to 192.0.2.1 and interface eth0, to port 22
@@ -563,7 +497,7 @@ and 30
Forward all ports to the guest, except for the range from 20000 to 20010
.RE
-Default is \fBnone\fR.
+Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR.
.RE
.TP
@@ -575,101 +509,87 @@ Note: unless overridden, UDP ports with numbers corresponding to forwarded TCP
port numbers are forwarded too, without, however, any port translation. IPv6
bound ports are also forwarded for IPv4.
-Default is \fBnone\fR.
+Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR.
-.SS \fBpasta\fR-only options
+.SS \fBpasst\fR-only options
.TP
-.BR \-I ", " \-\-ns-ifname " " \fIname
-Name of tap interface to be created in target namespace.
-By default, the same interface name as the external, routable interface is used.
-If no such interface exists, the name \fItap0\fR will be used instead.
+.BR \-s ", " \-\-socket-path ", " \-\-socket " " \fIpath
+Path for UNIX domain socket used by \fBqemu\fR(1) or \fBqrap\fR(1) to connect to
+\fBpasst\fR.
+Default is to probe a free socket, not accepting connections, starting from
+\fI/tmp/passt_1.socket\fR to \fI/tmp/passt_64.socket\fR.
.TP
-.BR \-t ", " \-\-tcp-ports " " \fIspec
-Configure TCP port forwarding to namespace. \fIspec\fR can be one of:
-.RS
+.BR \-\-vhost-user
+Enable vhost-user. The vhost-user command socket is provided by \fB--socket\fR.
.TP
-.BR none
-Don't forward any ports
+.BR \-\-print-capabilities
+Print back-end capabilities in JSON format, only meaningful for vhost-user mode.
.TP
-.BR auto
-Dynamically forward ports bound in the namespace. The list of ports is
-periodically derived (every second) from listening sockets reported by
-\fI/proc/net/tcp\fR and \fI/proc/net/tcp6\fR, see \fBproc\fR(5).
+.BR \-\-repair-path " " \fIpath
+Path for UNIX domain socket used by the \fBpasst-repair\fR(1) helper to connect
+to \fBpasst\fR in order to set or clear the TCP_REPAIR option on sockets, during
+migration. \fB--repair-path none\fR disables this interface (if you need to
+specify a socket path called "none" you can prefix the path by \fI./\fR).
+
+Default, for \-\-vhost-user mode only, is to append \fI.repair\fR to the path
+chosen for the hypervisor UNIX domain socket. No socket is created if not in
+\-\-vhost-user mode.
.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.
+.BR \-\-migrate-exit " " (DEPRECATED)
+Exit after a completed migration as source. By default, \fBpasst\fR keeps
+running and the migrated guest can continue using its connection, or a new guest
+can connect.
-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.
+Note that this configuration option is \fBdeprecated\fR and will be removed in a
+future version. It is not expected to be of any use, and it simply reflects a
+legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR
+below.
-Examples:
-.RS
-.TP
--t 22
-Forward local port 22 to 22 in the target namespace
-.TP
--t 22:23
-Forward local port 22 to port 23 in the target namespace
-.TP
--t 22,25
-Forward local ports 22 and 25 to ports 22 and 25 in the target namespace
-.TP
--t 22-80
-Forward local ports between 22 and 80 to corresponding ports in the target
-namespace
-.TP
--t 22-80:32-90
-Forward local ports between 22 and 80 to ports between 32 and 90 in the target
-namespace
-.TP
--t 192.0.2.1/22
-Forward local port 22, bound to 192.0.2.1, to port 22 in the target namespace
-.TP
--t 192.0.2.1%eth0/22
-Forward local port 22, bound to 192.0.2.1 and interface eth0, to port 22
-.TP
--t %eth0/22
-Forward local port 22, bound to any address on interface eth0, to port 22
-.TP
--t 2000-5000,~3000-3010
-Forward local ports between 2000 and 5000, except for those between 3000 and
-3010
-.TP
--t 192.0.2.1/20-30,~25
-For the local address 192.0.2.1, forward ports between 20 and 24 and between 26
-and 30
.TP
--t ~20000-20010
-Forward all ports to the namespace, except for those between 20000 and 20010
-.RE
+.BR \-\-migrate-no-linger " " (DEPRECATED)
+Close TCP sockets on the source instance once migration completes.
-IPv6 bound ports are also forwarded for IPv4.
+By default, sockets are kept open, and events on data sockets are ignored, so
+that any further message reaching sockets after the source migrated is silently
+ignored, to avoid connection resets in case data is received after migration.
-Default is \fBauto\fR.
-.RE
+Note that this configuration option is \fBdeprecated\fR and will be removed in a
+future version. It is not expected to be of any use, and it simply reflects a
+legacy behaviour. If you have any use for this, refer to \fBREPORTING BUGS\fR
+below.
.TP
-.BR \-u ", " \-\-udp-ports " " \fIspec
-Configure UDP port forwarding to namespace. \fIspec\fR is as described for TCP
-above, and the list of ports is derived from listening sockets reported by
-\fI/proc/net/udp\fR and \fI/proc/net/udp6\fR, see \fBproc\fR(5).
+.BR \-F ", " \-\-fd " " \fIFD
+Pass a pre-opened, connected socket to \fBpasst\fR. Usually the socket is opened
+in the parent process and \fBpasst\fR inherits it when run as a child. This
+allows the parent process to open sockets using another address family or
+requiring special privileges.
-Note: unless overridden, UDP ports with numbers corresponding to forwarded TCP
-port numbers are forwarded too, without, however, any port translation.
+This option implies the behaviour described for \-\-one-off, once this socket
+is closed.
-IPv6 bound ports are also forwarded for IPv4.
+.TP
+.BR \-1 ", " \-\-one-off
+Quit after handling a single client connection, that is, once the client closes
+the socket, or once we get a socket error.
-Default is \fBauto\fR.
+\fBNote\fR: this option has no effect after \fBpasst\fR completes a migration as
+source, because, in that case, exiting would close sockets for active
+connections, which would in turn cause connection resets if any further data is
+received. See also the description of \fI\-\-migrate-no-linger\fR.
+
+.SS \fBpasta\fR-only options
+
+.TP
+.BR \-I ", " \-\-ns-ifname " " \fIname
+Name of tap interface to be created in target namespace.
+By default, the same interface name as the external, routable interface is used.
+If no such interface exists, the name \fItap0\fR will be used instead.
.TP
.BR \-T ", " \-\-tcp-ns " " \fIspec
--
2.53.0