diff options
Diffstat (limited to 'passt.1')
| -rw-r--r-- | passt.1 | 304 |
1 files changed, 166 insertions, 138 deletions
@@ -85,6 +85,11 @@ Be verbose, don't log to the system logger. Be extra verbose, show single packets. Implies \fB--debug\fR. .TP +.BR \-\-stats " " \fIDELAY\fR +Display events statistics with a minimum \fIDELAY\fR seconds between updates. +If there is no event, statistics are not displayed. + +.TP .BR \-q ", " \-\-quiet Don't print informational messages. @@ -151,26 +156,35 @@ By default, the advertised MTU is 65520 bytes, that is, the maximum 802.3 MTU minus the length of a 802.3 header, rounded to 32 bits (IPv4 words). .TP -.BR \-a ", " \-\-address " " \fIaddr +.BR \-a ", " \-\-address " " \fIaddr\fR[/\fIprefix_len\fR] Assign IPv4 \fIaddr\fR via DHCP (\fByiaddr\fR), or \fIaddr\fR via DHCPv6 (option 5) and an \fIaddr\fR-based prefix via NDP Router Advertisement (option type 3) for an IPv6 \fIaddr\fR. +An optional /\fIprefix_len\fR (0-32 for IPv4, 0-128 for IPv6) can be +appended in CIDR notation (e.g. 192.0.2.1/24). This is an alternative to +using the \fB-n\fR, \fB--netmask\fR option. Mixing CIDR notation with +\fB-n\fR results in an error. +If a prefix length is assigned to an IPv6 address using this method, it will +in the current code version be overridden by the default value of 64. This option can be specified zero (for defaults) to two times (once for IPv4, once for IPv6). By default, assigned IPv4 and IPv6 addresses are taken from the host interfaces with the first default route, if any, for the corresponding IP version. If no default routes are available and there is any interface with any route for a given IP version, the first of these interfaces will be chosen instead. If no -such interface exists, the link-local address 169.254.2.1 is assigned for IPv4, -and no additional address will be assigned for IPv6. +such interface exists for a given IP version, the link-local address 169.254.2.1 +is assigned for IPv4, and no additional address will be assigned for IPv6. .TP .BR \-n ", " \-\-netmask " " \fImask Assign IPv4 netmask \fImask\fR, expressed as dot-decimal or number of bits, via -DHCP (option 1). -By default, the netmask associated to the host address matching the assigned one -is used. If there's no matching address on the host, the netmask is determined -according to the CIDR block of the assigned address (RFC 4632). +DHCP (option 1). Alternatively, the prefix length can be specified using CIDR +notation with the \fB-a\fR, \fB--address\fR option (e.g. \fB-a\fR 192.0.2.1/24). +Mixing \fB-n\fR with CIDR notation results in an error. +If no address is indicated, the netmask associated with the adopted host address, +if any, is used. If an address is indicated, but without a prefix length, the +netmask is determined based on the corresponding network class. In all other +cases, the netmask is determined by using the indicated prefix length. .TP .BR \-M ", " \-\-mac-addr " " \fIaddr @@ -189,9 +203,9 @@ first default route, if any, for the corresponding IP version. If the default route is a multipath one, the gateway is the first nexthop router returned by the kernel which has the highest weight in the set of paths. If no default routes are available and there is just one interface with any route, that -interface will be chosen instead. If no such interface exists, the link-local -address 169.254.2.2 is used for IPv4, and the link-local address fe80::1 is used -for IPv6. +interface will be chosen instead. If no such interface exists for a given IP +version, the link-local address 169.254.2.2 is used for IPv4, and the link-local +address fe80::1 is used for IPv6. Note: these addresses are also used as source address for packets directed to the guest or to the target namespace having a loopback or local source address, @@ -319,8 +333,8 @@ silently dropped. .TP .BR \-\-no-icmp -Disable the ICMP/ICMPv6 echo handler. ICMP and ICMPv6 echo requests coming from -guest or target namespace will be silently dropped. +Disable the ICMP/ICMPv6 protocol handler. ICMP and ICMPv6 requests coming from +guest or target namespace will be silently dropped. Implies \fB--no-ndp\fR. .TP .BR \-\-no-dhcp @@ -330,8 +344,8 @@ selected IPv4 default route. .TP .BR \-\-no-ndp -Disable NDP responses. NDP messages coming from guest or target namespace will -be ignored. +Disable Neighbor Discovery. NDP messages coming from guest or target +namespace will be ignored. No initial NDP message will be sent. .TP .BR \-\-no-dhcpv6 @@ -401,85 +415,96 @@ Enable IPv6-only operation. IPv4 traffic will be ignored. By default, IPv4 operation is enabled as long as at least an IPv4 route and an interface address are configured on a given host interface. -.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. +.BR \-H ", " \-\-hostname " " \fIname +Hostname to configure the client with. +Send \fIname\fR as DHCP option 12 (hostname). .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. +.BR \-\-fqdn " " \fIname +FQDN to configure the client with. +Send \fIname\fR as Client FQDN: DHCP option 81 and DHCPv6 option 39. .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. +.BR \-t ", " \-\-tcp-ports " " \fIspec +Configure TCP port forwarding to guest or namespace. \fIspec\fR can be one of: +.RS .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. +.BR none +Don't forward any ports .TP -.BR \-t ", " \-\-tcp-ports " " \fIspec -Configure TCP port forwarding to guest. \fIspec\fR can be one of: +[\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 +may be either: .RS +.TP +\fBall\fR +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. +.RE +.RS +or a comma-separated list of entries which may be any of: .TP -.BR none -Don't forward any ports +\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 -.BR all -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. +\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. .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 auto +\fBpasta\fR only. Only forward ports in the specified set if the +target ports are 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). +.RE -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. +Specifying excluded ranges only implies that all other non-ephemeral +ports are forwarded. Specifying no ranges at all implies forwarding +all non-ephemeral ports permitted by current capabilities. In this +case, no failures are reported for unavailable ports, unless no ports +could be forwarded at all. Examples: .RS .TP +-t all +Forward all unbound, non-ephemeral ports as permitted by current +capabilities to the corresponding port on the guest or namespace +.TP +-t ::1/all +For the local address ::1, forward all unbound, non-ephemeral ports as +permitted by current capabilities +.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 @@ -497,9 +522,20 @@ and 30 .TP -t ~20000-20010 Forward all ports to the guest, except for the range from 20000 to 20010 +.TP +-t auto +Automatically forward any ports which are bound in the namespace +.TP +-t ::1/auto +Automatically forward any ports which are bound in the namespace, +listening only on local port ::1 +.TP +-t 8000-8010,auto +Forward ports in the range 8000-8010 if and only if they are bound in +the namespace .RE -Default is \fBnone\fR. +Default is \fBnone\fR for \fBpasst\fR and \fBauto\fR for \fBpasta\fR. .RE .TP @@ -511,101 +547,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. + +.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. -IPv6 bound ports are also forwarded for IPv4. +\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. -Default is \fBauto\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 @@ -700,6 +722,11 @@ Default is to let the tap driver build a pseudorandom hardware address. Disable the bypass path for inbound, local traffic. See the section \fBHandling of local traffic in pasta\fR in the \fBNOTES\fR for more details. +.TP +.BR \-\-splice-only +Do not create a tap device in the namespace. In this mode, \fIpasta\fR only +forwards loopback traffic between namespaces. + .SH EXAMPLES .SS \fBpasta @@ -1062,8 +1089,9 @@ throughput of TCP connections. .SS Local mode for disconnected setups If \fBpasst\fR and \fBpasta\fR fail to find a host interface with a configured -address, other than loopback addresses, they will, obviously, not attempt to -source addresses or routes from the host. +address for a given IP version, other than loopback addresses, they will, +obviously, not attempt to source addresses or routes from the host, for that +IP version. In this case, unless configured otherwise, they will assign the IPv4 link-local address 169.254.2.1 to the guest or target namespace, and no IPv6 address. The |