diff options
Diffstat (limited to 'passt.1')
| -rw-r--r-- | passt.1 | 230 |
1 files changed, 75 insertions, 155 deletions
@@ -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,12 +435,18 @@ 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, optionally, with target ports after \fI:\fR, if they differ. Specific addresses @@ -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 |