mirror of
https://passt.top/passt
synced 2024-12-22 13:45:32 +00:00
0b25cac94e
Although it's not 100% explicit in the man page, addresses given to the --dns option are intended to be addresses as seen by the guest. This differs from addresses taken from the host's /etc/resolv.conf, which must be translated to guest accessible versions in some cases. Our implementation is currently inconsistent on this: when using --dns-forward, you must usually also give --dns with the matching address, which is meaningful only in the guest's address view. However if you give --dns with a loopback addres, it will be translated like a host view address. Move the remapping logic for DNS addresses out of add_dns4() and add_dns6() into add_dns_resolv() so that it is only applied for host nameserver addresses, not for nameservers given explicitly with --dns. Signed-off-by: David Gibson <david@gibson.dropbear.id.au> Signed-off-by: Stefano Brivio <sbrivio@redhat.com>
1003 lines
36 KiB
Groff
1003 lines
36 KiB
Groff
.\" SPDX-License-Identifier: GPL-2.0-or-later
|
|
.\" Copyright (c) 2020-2022 Red Hat GmbH
|
|
.\" Author: Stefano Brivio <sbrivio@redhat.com>
|
|
.TH passt 1
|
|
|
|
.SH NAME
|
|
.B passt
|
|
\- Unprivileged user-mode network connectivity for virtual machines
|
|
.br
|
|
.B pasta
|
|
\- Unprivileged user-mode network connectivity for network namespaces
|
|
|
|
.SH SYNOPSIS
|
|
.B passt
|
|
[\fIOPTION\fR]...
|
|
.br
|
|
.B pasta
|
|
[\fIOPTION\fR]... [\fICOMMAND\fR [\fIARG\fR]...]
|
|
.br
|
|
.B pasta
|
|
[\fIOPTION\fR]... \fIPID\fR
|
|
.br
|
|
.B pasta
|
|
[\fIOPTION\fR]... \fB--netns\fR [\fIPATH\fR|\fINAME\fR]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.SS passt
|
|
|
|
.B passt
|
|
(\fIP\fRlug \fIA\fR \fIS\fRimple \fIS\fRocket \fIT\fRransport) provides full,
|
|
quasi-native network connectivity to virtual machines in user-mode without
|
|
requiring any capabilities or privileges.
|
|
|
|
The data plane implements a translation layer between a Layer-2 virtual network
|
|
interface and native Layer-4 (TCP, UDP, ping) sockets on the host, giving the
|
|
illusion that application processes residing on the guest are running on the
|
|
local host, from a networking perspective.
|
|
|
|
Built-in ARP, DHCP, NDP, and DHCPv6 implementations are designed to provide the
|
|
guest with a network configuration that tightly resembles the host native
|
|
configuration. With the default options, guest and host share IP addresses,
|
|
routes, and port bindings.
|
|
|
|
Port forwarding and translation allow networking services running in the guest
|
|
to be reachable from both local and remote hosts.
|
|
|
|
Unlike \fBslirp4netns\fR(1), \fBpasst\fR doesn't implement a full TCP stack: the
|
|
TCP translation layer has no stateful data buffering and operates by reflecting
|
|
one peer's observed parameters (congestion window size, acknowledged data, etc.)
|
|
to the corresponding peer.
|
|
|
|
Currently, the only supported hypervisor is \fBqemu\fR(1), connecting to
|
|
\fBpasst\fR by means of a UNIX domain socket. This is supported starting from
|
|
qemu 7.2. For older qemu versions, see the \fBqrap\fR(1) wrapper.
|
|
|
|
.SS pasta
|
|
|
|
.B pasta
|
|
(\fIP\fRack \fIA\fR \fIS\fRubtle \fIT\fRap \fIA\fRbstraction) provides
|
|
equivalent functionality to network namespaces, as the one offered by
|
|
\fBpasst\fR for virtual machines.
|
|
|
|
If PID or --netns are given, \fBpasta\fR associates to an existing
|
|
user and network namespace. Otherwise, \fBpasta\fR creates a new user
|
|
and network namespace, and spawns the given command or a default shell
|
|
within this context. A \fItap\fR device within the network namespace
|
|
is created to provide network connectivity.
|
|
|
|
For local TCP and UDP traffic only, \fBpasta\fR also implements a bypass path
|
|
directly mapping Layer-4 sockets between \fIinit\fR and target namespaces,
|
|
for performance reasons.
|
|
|
|
.SH OPTIONS
|
|
|
|
Unless otherwise noted below, \fBif conflicting or multiple options are given,
|
|
the last one takes effect.\fR
|
|
|
|
.TP
|
|
.BR \-d ", " \-\-debug
|
|
Be verbose, don't log to the system logger.
|
|
|
|
.TP
|
|
.BR \-\-trace
|
|
Be extra verbose, show single packets. Implies \fB--debug\fR.
|
|
|
|
.TP
|
|
.BR \-q ", " \-\-quiet
|
|
Don't print informational messages.
|
|
|
|
.TP
|
|
.BR \-f ", " \-\-foreground
|
|
Don't run in background. This implies that the process is not moved to a
|
|
detached PID namespace after starting, because the PID itself cannot change.
|
|
Default is to fork into background.
|
|
|
|
.TP
|
|
.BR \-e ", " \-\-stderr
|
|
This option has no effect, and is maintained for compatibility purposes only.
|
|
|
|
Note that this configuration option is \fBdeprecated\fR and will be removed in a
|
|
future version.
|
|
|
|
.TP
|
|
.BR \-l ", " \-\-log-file " " \fIPATH\fR
|
|
Log to file \fIPATH\fR, and not to the system logger.
|
|
|
|
Specifying this option multiple times does \fInot\fR lead to multiple log files:
|
|
the last given option takes effect.
|
|
|
|
.TP
|
|
.BR \-\-log-size " " \fISIZE\fR
|
|
Limit log file size to \fISIZE\fR bytes. When the log file is full, make room
|
|
for new entries by removing old ones at the beginning. This limit is mandatory.
|
|
Default is 1048576 (1 MiB).
|
|
|
|
.TP
|
|
.BR \-\-runas " " \fIUID\fR|\fIUID:GID\fR|\fILOGIN\fR|\fILOGIN:GROUP\fR
|
|
Attempt to change to given UID and corresponding group if UID is given,
|
|
or to given UID and given GID if both are given. Alternatively, login name, or
|
|
login name and group name can be passed. This requires privileges (either
|
|
initial effective UID 0 or CAP_SETUID capability) to work.
|
|
Default is to change to user \fInobody\fR if started as root.
|
|
|
|
.TP
|
|
.BR \-h ", " \-\-help
|
|
Display a help message and exit.
|
|
|
|
.TP
|
|
.BR \-\-version
|
|
Show version and exit.
|
|
|
|
.TP
|
|
.BR \-p ", " \-\-pcap " " \fIfile
|
|
Capture tap-facing (that is, guest-side or namespace-side) network packets to
|
|
\fIfile\fR in \fBpcap\fR format.
|
|
|
|
Specifying this option multiple times does \fInot\fR lead to multiple capture
|
|
files: the last given option takes effect.
|
|
|
|
.TP
|
|
.BR \-P ", " \-\-pid " " \fIfile
|
|
Write own PID to \fIfile\fR once initialisation is done, before forking to
|
|
background (if configured to do so).
|
|
|
|
.TP
|
|
.BR \-m ", " \-\-mtu " " \fImtu
|
|
Assign \fImtu\fR via DHCP (option 26) and NDP (option type 5). A zero value
|
|
disables assignment.
|
|
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
|
|
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.
|
|
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.
|
|
|
|
.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).
|
|
|
|
.TP
|
|
.BR \-M ", " \-\-mac-addr " " \fIaddr
|
|
Use source MAC address \fIaddr\fR when communicating to the guest or to the
|
|
target namespace.
|
|
Default is to use the MAC address of the interface with the first IPv4 default
|
|
route on the host.
|
|
|
|
.TP
|
|
.BR \-g ", " \-\-gateway " " \fIaddr
|
|
Assign IPv4 \fIaddr\fR as default gateway via DHCP (option 3), or IPv6
|
|
\fIaddr\fR as source for NDP Router Advertisement and DHCPv6 messages.
|
|
This option can be specified zero (for defaults) to two times (once for IPv4,
|
|
once for IPv6).
|
|
By default, IPv4 and IPv6 gateways are taken from the host interface with the
|
|
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.
|
|
|
|
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,
|
|
to allow mapping of local traffic to guest and target namespace. See the
|
|
\fBNOTES\fR below for more details about this mechanism.
|
|
|
|
.TP
|
|
.BR \-i ", " \-\-interface " " \fIname
|
|
Use host interface \fIname\fR to derive addresses and routes.
|
|
Default is to use the interfaces specified by \fB--outbound-if4\fR and
|
|
\fB--outbound-if6\fR, for IPv4 and IPv6 addresses and routes, respectively.
|
|
|
|
If no interfaces are given, the interface with the first default routes for each
|
|
IP version is selected. If no default routes are available and there is just one
|
|
interface with any route, that interface will be chosen instead.
|
|
|
|
.TP
|
|
.BR \-o ", " \-\-outbound " " \fIaddr
|
|
Use an IPv4 \fIaddr\fR as source address for IPv4 outbound TCP connections, UDP
|
|
flows, ICMP requests, or an IPv6 \fIaddr\fR for IPv6 ones, by binding outbound
|
|
sockets to it.
|
|
This option can be specified zero (for defaults) to two times (once for IPv4,
|
|
once for IPv6).
|
|
By default, the source address is selected by the routing tables.
|
|
|
|
.TP
|
|
.BR \-\-outbound-if4 " " \fIname
|
|
Bind IPv4 outbound sockets to host interface \fIname\fR, and, unless another
|
|
interface is specified via \fB-i\fR, \fB--interface\fR, use this interface to
|
|
derive IPv4 addresses and routes.
|
|
|
|
By default, the interface given by the default route is selected. If no default
|
|
routes are available and there is just one interface with any route, that
|
|
interface will be chosen instead.
|
|
|
|
.TP
|
|
.BR \-\-outbound-if6 " " \fIname
|
|
Bind IPv6 outbound sockets to host interface \fIname\fR, and, unless another
|
|
interface is specified via \fB-i\fR, \fB--interface\fR, use this interface to
|
|
derive IPv6 addresses and routes.
|
|
|
|
By default, the interface given by the default route is selected. If no default
|
|
routes are available and there is just one interface with any route, that
|
|
interface will be chosen instead.
|
|
|
|
.TP
|
|
.BR \-D ", " \-\-dns " " \fIaddr
|
|
Instruct the guest (via DHCP, DHVPv6 or NDP) to use \fIaddr\fR (IPv4
|
|
or IPv6) as a nameserver, as configured (see options
|
|
\fB--no-dhcp-dns\fR, \fB--dhcp-dns\fR) instead of reading addresses
|
|
from \fI/etc/resolv.conf\fR. This option can be specified multiple
|
|
times. Specifying \fB-D none\fR disables usage of DNS addresses
|
|
altogether. Unlike addresses from \fI/etc/resolv.conf\fR, \fIaddr\fR
|
|
is given to the guest without remapping. For example \fB--dns
|
|
127.0.0.1\fR will instruct the guest to use itself as nameserver, not
|
|
the host.
|
|
|
|
.TP
|
|
.BR \-\-dns-forward " " \fIaddr
|
|
Map \fIaddr\fR (IPv4 or IPv6) as seen from guest or namespace to the
|
|
first configured DNS resolver (with corresponding IP version). Maps
|
|
only UDP and TCP traffic to port 53 or port 853. Replies are
|
|
translated back with a reverse mapping. This option can be specified
|
|
zero to two times (once for IPv4, once for IPv6).
|
|
|
|
.TP
|
|
.BR \-S ", " \-\-search " " \fIlist
|
|
Use space-separated \fIlist\fR for DHCP, DHCPv6, and NDP purposes, instead of
|
|
reading entries from \fI/etc/resolv.conf\fR. See options \fB--no-dhcp-search\fR
|
|
and \fB--dhcp-search\fR. \fB--search none\fR disables the DNS domain search
|
|
list altogether (if you need to search a domain called "none" you can use
|
|
\fB--search none.\fR).
|
|
|
|
.TP
|
|
.BR \-\-no-dhcp-dns
|
|
In \fIpasst\fR mode, do not assign IPv4 addresses via DHCP (option 23) or IPv6
|
|
addresses via NDP Router Advertisement (option type 25) and DHCPv6 (option 23)
|
|
as DNS resolvers.
|
|
By default, all the configured addresses are passed.
|
|
|
|
.TP
|
|
.BR \-\-dhcp-dns
|
|
In \fIpasta\fR mode, assign IPv4 addresses via DHCP (option 23) or IPv6
|
|
addresses via NDP Router Advertisement (option type 25) and DHCPv6 (option 23)
|
|
as DNS resolvers.
|
|
By default, configured addresses, if any, are not passed.
|
|
|
|
.TP
|
|
.BR \-\-no-dhcp-search
|
|
In \fIpasst\fR mode, do not send the DNS domain search list addresses via DHCP
|
|
(option 119), via NDP Router Advertisement (option type 31) and DHCPv6 (option
|
|
24).
|
|
By default, the DNS domain search list resulting from configuration is passed.
|
|
|
|
.TP
|
|
.BR \-\-dhcp-search
|
|
In \fIpasta\fR mode, send the DNS domain search list addresses via DHCP (option
|
|
119), via NDP Router Advertisement (option type 31) and DHCPv6 (option 24).
|
|
By default, the DNS domain search list resulting from configuration is not
|
|
passed.
|
|
|
|
.TP
|
|
.BR \-\-no-tcp
|
|
Disable the TCP protocol handler. No TCP connections will be accepted host-side,
|
|
and TCP packets coming from guest or target namespace will be silently dropped.
|
|
|
|
.TP
|
|
.BR \-\-no-udp
|
|
Disable the UDP protocol handler. No UDP traffic coming from the host side will
|
|
be forwarded, and UDP packets coming from guest or target namespace will be
|
|
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.
|
|
|
|
.TP
|
|
.BR \-\-no-dhcp
|
|
Disable the DHCP server. DHCP client requests coming from guest or target
|
|
namespace will be silently dropped. Implied if there is no gateway on the
|
|
selected IPv4 default route.
|
|
|
|
.TP
|
|
.BR \-\-no-ndp
|
|
Disable NDP responses. NDP messages coming from guest or target namespace will
|
|
be ignored.
|
|
|
|
.TP
|
|
.BR \-\-no-dhcpv6
|
|
Disable the DHCPv6 server. DHCPv6 client requests coming from guest or target
|
|
namespace will be silently dropped.
|
|
|
|
.TP
|
|
.BR \-\-no-ra
|
|
Disable Router Advertisements. Router Solicitations coming from guest or target
|
|
namespace will be ignored.
|
|
|
|
.TP
|
|
.BR \-\-no-map-gw
|
|
Don't remap TCP connections and untracked UDP traffic, with the gateway address
|
|
as destination, to the host. Implied if there is no gateway on the selected
|
|
default route, or if there is no default route, for any of the enabled address
|
|
families.
|
|
|
|
.TP
|
|
.BR \-4 ", " \-\-ipv4-only
|
|
Enable IPv4-only operation. IPv6 traffic will be ignored.
|
|
By default, IPv6 operation is enabled as long as at least an IPv6 route and an
|
|
interface address are configured on a given host interface.
|
|
|
|
.TP
|
|
.BR \-6 ", " \-\-ipv6-only
|
|
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 " " \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 \-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.
|
|
|
|
.TP
|
|
.BR \-t ", " \-\-tcp-ports " " \fIspec
|
|
Configure TCP port forwarding to guest. \fIspec\fR can be one of:
|
|
.RS
|
|
|
|
.TP
|
|
.BR none
|
|
Don't forward any ports
|
|
|
|
.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.
|
|
|
|
.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.
|
|
|
|
Examples:
|
|
.RS
|
|
.TP
|
|
-t 22
|
|
Forward local port 22 to port 22 on the guest
|
|
.TP
|
|
-t 22:23
|
|
Forward local port 22 to port 23 on the guest
|
|
.TP
|
|
-t 22,25
|
|
Forward local ports 22 and 25 to ports 22 and 25 on the guest
|
|
.TP
|
|
-t 22-80
|
|
Forward local ports between 22 and 80 to corresponding ports on the guest
|
|
.TP
|
|
-t 22-80:32-90
|
|
Forward local ports between 22 and 80 to ports between 32 and 90 on the guest
|
|
.TP
|
|
-t 192.0.2.1/22
|
|
Forward local port 22, bound to 192.0.2.1, to port 22 on the guest
|
|
.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 guest, except for the range from 20000 to 20010
|
|
.RE
|
|
|
|
Default is \fBnone\fR.
|
|
.RE
|
|
|
|
.TP
|
|
.BR \-u ", " \-\-udp-ports " " \fIspec
|
|
Configure UDP port forwarding to guest. \fIspec\fR is as described for TCP
|
|
above.
|
|
|
|
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.
|
|
|
|
.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.
|
|
|
|
.TP
|
|
.BR \-t ", " \-\-tcp-ports " " \fIspec
|
|
Configure TCP port forwarding to namespace. \fIspec\fR can be one of:
|
|
.RS
|
|
|
|
.TP
|
|
.BR none
|
|
Don't forward any ports
|
|
|
|
.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).
|
|
|
|
.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.
|
|
|
|
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
|
|
|
|
IPv6 bound ports are also forwarded for IPv4.
|
|
|
|
Default is \fBauto\fR.
|
|
.RE
|
|
|
|
.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).
|
|
|
|
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 \fBauto\fR.
|
|
|
|
.TP
|
|
.BR \-T ", " \-\-tcp-ns " " \fIspec
|
|
Configure TCP port forwarding from target namespace to init namespace.
|
|
\fIspec\fR is as described above for TCP.
|
|
|
|
Default is \fBauto\fR.
|
|
|
|
.TP
|
|
.BR \-U ", " \-\-udp-ns " " \fIspec
|
|
Configure UDP port forwarding from target namespace to init namespace.
|
|
\fIspec\fR is as described above for UDP.
|
|
|
|
Default is \fBauto\fR.
|
|
|
|
.TP
|
|
.BR \-\-userns " " \fIspec
|
|
Target user namespace to join, as a path. If PID is given, without this option,
|
|
the user namespace will be the one of the corresponding process.
|
|
|
|
.TP
|
|
.BR \-\-netns " " \fIspec
|
|
Target network namespace to join, as a path or a name. A name is treated as
|
|
with \fBip-netns(8)\fR as equivalent to a path in \fI/run/netns\fR.
|
|
|
|
This option can't be specified with a PID.
|
|
|
|
.TP
|
|
.BR \-\-netns-only
|
|
Join only a target network namespace, not a user namespace, and don't create one
|
|
for sandboxing purposes either. This is implied if PATH or NAME are given
|
|
without \-\-userns.
|
|
|
|
.TP
|
|
.BR \-\-no-netns-quit
|
|
Do not exit once the target namespace reference is removed.
|
|
|
|
Without this option, \fBpasta\fR will terminate if the target network namespace
|
|
is bound to the filesystem, and the given path is deleted, or if the target
|
|
network namespace is represented by a procfs entry, and that entry is deleted,
|
|
representing the fact that a process with the given PID terminated.
|
|
|
|
.TP
|
|
.BR \-\-config-net
|
|
Configure networking in the namespace: set up addresses and routes as configured
|
|
or sourced from the host, and bring up the tap interface.
|
|
|
|
.TP
|
|
.BR \-\-no-copy-routes " " (DEPRECATED)
|
|
With \-\-config-net, do not copy all the routes associated to the interface we
|
|
derive addresses and routes from: set up only the default gateway. Implied by
|
|
-g, \-\-gateway, for the corresponding IP version only.
|
|
|
|
Default is to copy all the routing entries from the interface in the outer
|
|
namespace to the target namespace, translating the output interface attribute to
|
|
the outbound interface in the namespace.
|
|
|
|
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 \-\-no-copy-addrs " " (DEPRECATED)
|
|
With \-\-config-net, do not copy all the addresses associated to the interface
|
|
we derive addresses and routes from: set up a single one. Implied by \-a,
|
|
\-\-address, for the corresponding IP version only.
|
|
|
|
Default is to copy all the addresses, except for link-local ones, from the
|
|
interface from the outer namespace to the target namespace.
|
|
|
|
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 \-\-ns-mac-addr " " \fIaddr
|
|
Configure MAC address \fIaddr\fR on the tap interface in the namespace.
|
|
|
|
Default is to let the tap driver build a pseudorandom hardware address.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.SS \fBpasta
|
|
.BR "Create and use a new, connected, user and network namespace"
|
|
.RS
|
|
.nf
|
|
$ iperf3 -s -D
|
|
$ ./pasta
|
|
Outbound interface: eth0, namespace interface: eth0
|
|
ARP:
|
|
address: 28:16:ad:39:a9:ea
|
|
DHCP:
|
|
assign: 192.168.1.118
|
|
mask: 255.255.255.0
|
|
router: 192.168.1.1
|
|
NDP/DHCPv6:
|
|
assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
|
|
router: fe80::62e3:27ff:fe33:2b01
|
|
#
|
|
# dhclient -4 --no-pid
|
|
# dhclient -6 --no-pid
|
|
# ip address show
|
|
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
|
|
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
|
|
inet 127.0.0.1/8 scope host lo
|
|
valid_lft forever preferred_lft forever
|
|
inet6 ::1/128 scope host
|
|
valid_lft forever preferred_lft forever
|
|
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UNKNOWN group default qlen 1000
|
|
link/ether 5e:90:02:eb:b0:2a brd ff:ff:ff:ff:ff:ff
|
|
inet 192.168.1.118/24 brd 192.168.1.255 scope global eth0
|
|
valid_lft forever preferred_lft forever
|
|
inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global
|
|
valid_lft forever preferred_lft forever
|
|
inet6 2a02:6d40:3ca5:2001:5c90:2ff:feeb:b02a/64 scope global dynamic mngtmpaddr
|
|
valid_lft 3591sec preferred_lft 3591sec
|
|
inet6 fe80::5c90:2ff:feeb:b02a/64 scope link
|
|
valid_lft forever preferred_lft forever
|
|
# ip route show
|
|
default via 192.168.1.1 dev eth0
|
|
192.168.1.0/24 dev eth0 proto kernel scope link src 192.168.1.118
|
|
# ip -6 route show
|
|
2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17 dev eth0 proto kernel metric 256 pref medium
|
|
2a02:6d40:3ca5:2001::/64 dev eth0 proto kernel metric 256 expires 3584sec pref medium
|
|
fe80::/64 dev eth0 proto kernel metric 256 pref medium
|
|
default via fe80::62e3:27ff:fe33:2b01 dev eth0 proto ra metric 1024 expires 3584sec pref medium
|
|
# iperf3 -c 127.0.0.1 -t1
|
|
Connecting to host 127.0.0.1, port 5201
|
|
[ 5] local 127.0.0.1 port 51938 connected to 127.0.0.1 port 5201
|
|
[ ID] Interval Transfer Bitrate Retr Cwnd
|
|
[ 5] 0.00-1.00 sec 4.46 GBytes 38.3 Gbits/sec 0 3.93 MBytes
|
|
- - - - - - - - - - - - - - - - - - - - - - - - -
|
|
[ ID] Interval Transfer Bitrate Retr
|
|
[ 5] 0.00-1.00 sec 4.46 GBytes 38.3 Gbits/sec 0 sender
|
|
[ 5] 0.00-1.41 sec 4.45 GBytes 27.1 Gbits/sec receiver
|
|
|
|
iperf Done.
|
|
# iperf3 -c ::1 -t1
|
|
Connecting to host ::1, port 5201
|
|
[ 5] local ::1 port 50108 connected to ::1 port 5201
|
|
[ ID] Interval Transfer Bitrate Retr Cwnd
|
|
[ 5] 0.00-1.00 sec 4.35 GBytes 37.4 Gbits/sec 0 4.99 MBytes
|
|
- - - - - - - - - - - - - - - - - - - - - - - - -
|
|
[ ID] Interval Transfer Bitrate Retr
|
|
[ 5] 0.00-1.00 sec 4.35 GBytes 37.4 Gbits/sec 0 sender
|
|
[ 5] 0.00-1.41 sec 4.35 GBytes 26.4 Gbits/sec receiver
|
|
|
|
iperf Done.
|
|
# ping -c1 -4 spaghetti.pizza
|
|
PING spaghetti.pizza (172.67.192.217) 56(84) bytes of data.
|
|
64 bytes from 172.67.192.217: icmp_seq=1 ttl=255 time=37.3 ms
|
|
|
|
--- spaghetti.pizza ping statistics ---
|
|
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
|
# ping -c1 -6 spaghetti.pizza
|
|
PING spaghetti.pizza(2606:4700:3034::6815:147a (2606:4700:3034::6815:147a)) 56 data bytes
|
|
64 bytes from 2606:4700:3034::6815:147a: icmp_seq=1 ttl=255 time=35.6 ms
|
|
|
|
--- spaghetti.pizza ping statistics ---
|
|
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
|
rtt min/avg/max/mdev = 35.605/35.605/35.605/0.000 ms
|
|
# logout
|
|
$
|
|
|
|
.RE
|
|
.fi
|
|
|
|
.BR "Connect an existing user and network namespace"
|
|
.RS
|
|
.nf
|
|
$ unshare -rUn
|
|
# echo $$
|
|
2446678
|
|
|
|
.fi
|
|
.BR " [From another terminal]"
|
|
.nf
|
|
$ ./pasta 2446678
|
|
Outbound interface: eth0, namespace interface: eth0
|
|
ARP:
|
|
address: 28:16:ad:39:a9:ea
|
|
DHCP:
|
|
assign: 192.168.1.118
|
|
mask: 255.255.255.0
|
|
router: 192.168.1.1
|
|
NDP/DHCPv6:
|
|
assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
|
|
router: fe80::62e3:27ff:fe33:2b01
|
|
|
|
.fi
|
|
.BR " [Back to the original terminal]"
|
|
.nf
|
|
# dhclient -4 --no-pid
|
|
# dhclient -6 --no-pid
|
|
# ip address show
|
|
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
|
|
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
|
|
inet 127.0.0.1/8 scope host lo
|
|
valid_lft forever preferred_lft forever
|
|
inet6 ::1/128 scope host
|
|
valid_lft forever preferred_lft forever
|
|
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UNKNOWN group default qlen 1000
|
|
link/ether fa:c1:2a:27:92:a9 brd ff:ff:ff:ff:ff:ff
|
|
inet 192.168.1.118/24 brd 192.168.1.255 scope global eth0
|
|
valid_lft forever preferred_lft forever
|
|
inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global
|
|
valid_lft forever preferred_lft forever
|
|
inet6 2a02:6d40:3ca5:2001:f8c1:2aff:fe27:92a9/64 scope global dynamic mngtmpaddr
|
|
valid_lft 3594sec preferred_lft 3594sec
|
|
inet6 fe80::f8c1:2aff:fe27:92a9/64 scope link
|
|
valid_lft forever preferred_lft forever
|
|
.fi
|
|
.RE
|
|
|
|
.SS \fBpasst
|
|
.BR "Start and connect a guest with basic port forwarding"
|
|
.RS
|
|
.nf
|
|
$ ./passt -f -t 2222:22
|
|
Outbound interface: eth0
|
|
ARP:
|
|
address: 28:16:ad:39:a9:ea
|
|
DHCP:
|
|
assign: 192.168.1.118
|
|
mask: 255.255.255.0
|
|
router: 192.168.1.1
|
|
search:
|
|
redhat.com
|
|
NDP/DHCPv6:
|
|
assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
|
|
router: fe80::62e3:27ff:fe33:2b01
|
|
search:
|
|
redhat.com
|
|
UNIX domain socket bound at /tmp/passt_1.socket
|
|
|
|
You can now start qrap:
|
|
./qrap 5 qemu-system-x86_64 ... -net socket,fd=5 -net nic,model=virtio
|
|
or directly qemu, patched with:
|
|
qemu/0001-net-Allow-also-UNIX-domain-sockets-to-be-used-as-net.patch
|
|
as follows:
|
|
qemu-system-x86_64 ... -net socket,connect=/tmp/passt_1.socket -net nic,model=virtio
|
|
|
|
.fi
|
|
.BR " [From another terminal]"
|
|
.nf
|
|
$ ./qrap 5 qemu-system-x86_64 test.qcow2 -m 1024 -display none -nodefaults -nographic -net socket,fd=5 -net nic,model=virtio
|
|
Connected to /tmp/passt_1.socket
|
|
|
|
.fi
|
|
.BR " [Back to the original terminal]"
|
|
.nf
|
|
passt: DHCP: ack to request
|
|
passt: from 52:54:00:12:34:56
|
|
passt: NDP: received NS, sending NA
|
|
passt: NDP: received RS, sending RA
|
|
passt: DHCPv6: received SOLICIT, sending ADVERTISE
|
|
passt: NDP: received NS, sending NA
|
|
passt: DHCPv6: received REQUEST/RENEW/CONFIRM, sending REPLY
|
|
passt: NDP: received NS, sending NA
|
|
|
|
.fi
|
|
.BR " [From yet another terminal]"
|
|
.nf
|
|
$ ssh -p 2222 root@localhost
|
|
root@localhost's password:
|
|
.fi
|
|
.BR " [...]"
|
|
.nf
|
|
# ip address show
|
|
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
|
|
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
|
|
inet 127.0.0.1/8 scope host lo
|
|
valid_lft forever preferred_lft forever
|
|
inet6 ::1/128 scope host
|
|
valid_lft forever preferred_lft forever
|
|
2: ens2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UP group default qlen 1000
|
|
link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
|
|
inet 192.168.1.118/24 brd 192.168.1.255 scope global noprefixroute ens2
|
|
valid_lft forever preferred_lft forever
|
|
inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global noprefixroute
|
|
valid_lft forever preferred_lft forever
|
|
inet6 2a02:6d40:3ca5:2001:b019:9ae2:a2fe:e6b4/64 scope global dynamic noprefixroute
|
|
valid_lft 3588sec preferred_lft 3588sec
|
|
inet6 fe80::1f98:d09f:9309:9e77/64 scope link noprefixroute
|
|
valid_lft forever preferred_lft forever
|
|
.fi
|
|
.RE
|
|
|
|
.SH NOTES
|
|
|
|
.SS Handling of traffic with local destination and source addresses
|
|
|
|
Both \fBpasst\fR and \fBpasta\fR can bind on ports with a local address,
|
|
depending on the configuration. Local destination or source addresses need to be
|
|
changed before packets are delivered to the guest or target namespace: most
|
|
operating systems would drop packets received from non-loopback interfaces with
|
|
local addresses, and it would also be impossible for guest or target namespace
|
|
to route answers back.
|
|
|
|
For convenience, and somewhat arbitrarily, the source address on these packets
|
|
is translated to the address of the default IPv4 or IPv6 gateway (if any) --
|
|
this is known to be an existing, valid address on the same subnet.
|
|
|
|
Loopback destination addresses are instead translated to the observed external
|
|
address of the guest or target namespace. For IPv6 packets, if usage of a
|
|
link-local address by guest or namespace has ever been observed, and the
|
|
original destination address is also a link-local address, the observed
|
|
link-local address is used. Otherwise, the observed global address is used. For
|
|
both IPv4 and IPv6, if no addresses have been seen yet, the configured addresses
|
|
will be used instead.
|
|
|
|
For example, if \fBpasst\fR or \fBpasta\fR receive a connection from 127.0.0.1,
|
|
with destination 127.0.0.10, and the default IPv4 gateway is 192.0.2.1, while
|
|
the last observed source address from guest or namespace is 192.0.2.2, this will
|
|
be translated to a connection from 192.0.2.1 to 192.0.2.2.
|
|
|
|
Similarly, for traffic coming from guest or namespace, packets with destination
|
|
address corresponding to the default gateway will have their destination address
|
|
translated to a loopback address, if and only if a packet, in the opposite
|
|
direction, with a loopback destination or source address, port-wise matching for
|
|
UDP, or connection-wise for TCP, has been recently forwarded to guest or
|
|
namespace. This behaviour can be disabled with \-\-no\-map\-gw.
|
|
|
|
.SS Handling of local traffic in pasta
|
|
|
|
Depending on the configuration, \fBpasta\fR can bind to local ports in the init
|
|
namespace, in the target namespace, or both, and forward connections and packets
|
|
to corresponding ports in the other namespace.
|
|
|
|
To avoid unnecessary overhead, these connections and packets are not forwarded
|
|
through the tap device connecting the namespaces: \fBpasta\fR creates a socket
|
|
in the destination namespace, with matching Layer-4 protocol, and uses it to
|
|
forward local data. For TCP, data is forwarded between the originating socket
|
|
and the new socket using the \fBsplice\fR(2) system call, and for UDP, a pair
|
|
of \fBrecvmmsg\fR(2) and \fBsendmmsg\fR(2) system calls deals with packet
|
|
transfers.
|
|
|
|
This bypass only applies to local connections and traffic, because it's not
|
|
possible to bind sockets to foreign addresses.
|
|
|
|
.SS Binding to low numbered ports (well-known or system ports, up to 1023)
|
|
|
|
If the port forwarding configuration requires binding to ports with numbers
|
|
lower than 1024, \fBpasst\fR and \fBpasta\fR will try to bind to them, but will
|
|
fail, unless, either:
|
|
|
|
.IP \(bu 2
|
|
the \fIsys.net.ipv4.ip_unprivileged_port_start\fR sysctl is set to the number
|
|
of the lowest port \fBpasst\fR and \fBpasta\fR need. For example, as root:
|
|
|
|
.nf
|
|
sysctl -w net.ipv4.ip_unprivileged_port_start=443
|
|
.fi
|
|
|
|
\fBNote\fR: this is the recommended way of enabling \fBpasst\fR and \fBpasta\fR
|
|
to bind to ports with numbers below 1024.
|
|
|
|
.IP \(bu
|
|
or the \fICAP_NET_BIND_SERVICE\fR Linux capability is granted, see
|
|
\fBservices\fR(5) and \fBcapabilities\fR(7).
|
|
|
|
This is, in general, \fBnot the recommended way\fR, because \fBpasst\fR and
|
|
\fBpasta\fR might be used as vector to effectively use this capability from
|
|
another process.
|
|
|
|
However, if your environment is sufficiently controlled by an LSM (Linux
|
|
Security Module) such as \fIAppArmor\fR, \fISELinux\fR, \fISmack\fR or
|
|
\fITOMOYO\fR, and no other processes can interact in such a way in virtue of
|
|
this, granting this capability to \fBpasst\fR and \fBpasta\fR only can
|
|
effectively prevent other processes from utilising it.
|
|
|
|
Note that this will not work for automatic detection and forwarding of ports
|
|
with \fBpasta\fR, because \fBpasta\fR will relinquish this capability at
|
|
runtime.
|
|
|
|
To grant this capability, you can issue, as root:
|
|
|
|
.nf
|
|
for p in $(which passt passt.avx2); do
|
|
setcap 'cap_net_bind_service=+ep' "${p}"
|
|
done
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.SS ICMP/ICMPv6 Echo sockets
|
|
|
|
ICMP and ICMPv6 Echo requests coming from guest or target namespace are handled
|
|
using so-called "ping" sockets, introduced in Linux 2.6.30. To preserve the
|
|
original identifier (see RFC 792, page 14, for ICMP, and RFC 4443, section 4.1,
|
|
for ICMPv6), \fBpasst\fR and \fBpasta\fR try to bind these sockets using the
|
|
observed source identifier as "port" -- that corresponds to Echo identifiers
|
|
for "ping" sockets.
|
|
|
|
As \fBbind\fR(2) failures were seen with particularly restrictive SELinux
|
|
policies, a fall-back mechanism maps different identifiers to different sockets,
|
|
and identifiers in replies will be mapped back to the original identifier of the
|
|
request. However, if \fBbind\fR(2) fails and the fall-back mechanism is used,
|
|
echo requests will be forwarded with different, albeit unique, identifiers.
|
|
|
|
For ICMP and ICMPv6 Echo requests to work, the \fIping_group_range\fR parameter
|
|
needs to include the PID of \fBpasst\fR or \fBpasta\fR, see \fBicmp\fR(7).
|
|
|
|
.SS pasta and loopback interface
|
|
|
|
As \fBpasta\fR connects to an existing namespace, or once it creates a new
|
|
namespace, it will also ensure that the loopback interface, \fIlo\fR, is brought
|
|
up. This is needed to bind ports using the loopback address in the namespace.
|
|
|
|
.SS TCP sending window and \fITCP_INFO\fB before Linux 5.3
|
|
|
|
To synchronise the TCP sending window from host Layer-4 sockets to the TCP
|
|
parameters announced in TCP segments sent over the Layer-2 interface,
|
|
\fBpasst\fR and \fBpasta\fR routinely query the size of the sending window seen
|
|
by the kernel on the corresponding socket using the \fITCP_INFO\fR socket
|
|
option, see \fBtcp\fR(7). Before Linux 5.3, i.e. before Linux kernel commit
|
|
8f7baad7f035 ("tcp: Add snd_wnd to TCP_INFO"), the sending window
|
|
(\fIsnd_wnd\fR field) is not available.
|
|
|
|
If the sending window cannot be queried, it will always be announced as the
|
|
current sending buffer size to guest or target namespace. This might affect
|
|
throughput of TCP connections.
|
|
|
|
.SH LIMITATIONS
|
|
|
|
Currently, IGMP/MLD proxying (RFC 4605) and support for SCTP (RFC 4960) are not
|
|
implemented.
|
|
|
|
TCP Selective Acknowledgment (RFC 2018), as well as Protection Against Wrapped
|
|
Sequences (PAWS) and Round-Trip Time Measurement (RTTM), both described by RFC
|
|
7232, are currently not implemented.
|
|
|
|
.SH AUTHORS
|
|
|
|
Stefano Brivio <sbrivio@redhat.com>, David Gibson <david@gibson.dropbear.id.au>.
|
|
|
|
.SH REPORTING BUGS
|
|
|
|
Please report issues on the bug tracker at https://passt.top/passt/bugs, or
|
|
send a message to the passt-user@passt.top mailing list, see
|
|
https://passt.top/passt/lists.
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Copyright (c) 2020-2022 Red Hat GmbH.
|
|
|
|
\fBpasst\fR and \fBpasta\fR are free software: you can redistribute them and/or
|
|
modify them under the terms of the GNU General Public License as
|
|
published by the Free Software Foundation, either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBnamespaces\fR(7), \fBqemu\fR(1), \fBqrap\fR(1), \fBslirp4netns\fR(1).
|
|
|
|
High-level documentation is available at https://passt.top/passt/about/.
|