Provided by: passt_0.0~git20230627.289301b-1_amd64 bug

NAME

       passt - Unprivileged user-mode network connectivity for virtual machines
       pasta - Unprivileged user-mode network connectivity for network namespaces

SYNOPSIS

       passt [OPTION]...
       pasta [OPTION]... [COMMAND [ARG]...]
       pasta [OPTION]... PID
       pasta [OPTION]... --netns [PATH|NAME]

DESCRIPTION

   passt
       passt (Plug A Simple Socket Transport) 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 slirp4netns(1), passt 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 qemu(1), connecting to passt  by  means  of  a
       UNIX domain socket. This is supported starting from qemu 7.2. For older qemu versions, see
       the qrap(1) wrapper.

   pasta
       pasta (Pack A  Subtle  Tap  Abstraction)  provides  equivalent  functionality  to  network
       namespaces, as the one offered by passt for virtual machines.

       If  PID  or --netns are given, pasta associates to an existing user and network namespace.
       Otherwise, pasta creates a new user and network namespace, and spawns the given command or
       a  default shell within this context. A tap device within the network namespace is created
       to provide network connectivity.

       For local TCP and UDP traffic only, pasta also implements a bypass path  directly  mapping
       Layer-4 sockets between init and target namespaces, for performance reasons.

OPTIONS

       -d, --debug
              Be verbose, don't log to the system logger.

       --trace
              Be extra verbose, show single packets. Implies --debug.

       -q, --quiet
              Don't print informational messages.

       -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.

       -e, --stderr
              Log to standard error too.  Default is to log to the system logger only, if started
              from an interactive  terminal,  and  to  both  system  logger  and  standard  error
              otherwise.

       -l, --log-file PATH
              Log to file PATH, not to standard error, and not to the system logger.

       --log-size SIZE
              Limit  log  file  size  to SIZE 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).

       --runas UID|UID:GID|LOGIN|LOGIN:GROUP
              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 nobody if  started
              as root.

       -h, --help
              Display a help message and exit.

       --version
              Show version and exit.

       -p, --pcap file
              Capture  tap-facing (that is, guest-side or namespace-side) network packets to file
              in pcap format.

       -P, --pid file
              Write own PID to file once initialisation is done, before forking to background (if
              configured to do so).

       -m, --mtu mtu
              Assign  mtu  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).

       -a, --address addr
              Assign IPv4 addr via DHCP (yiaddr), or addr via DHCPv6 (option 5) and an addr-based
              prefix via NDP Router Advertisement (option type 3) for an IPv6 addr.  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 for the corresponding IP version.

       -n, --netmask mask
              Assign  IPv4  netmask  mask,  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).

       -M, --mac-addr addr
              Use source MAC address addr 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.

       -g, --gateway addr
              Assign IPv4 addr as default gateway via DHCP (option 3), or IPv6 addr 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  addresses  are taken from the host interface with the first default route for
              the corresponding IP version.

              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  NOTES  below
              for more details about this mechanism.

       -i, --interface name
              Use  host  interface  name  to  derive addresses and routes.  Default is to use the
              interfaces specified by  --outbound-if4  and  --outbound-if6,  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.

       -o, --outbound addr
              Use an IPv4 addr as source address for IPv4 outbound TCP  connections,  UDP  flows,
              ICMP  requests,  or  an IPv6 addr 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.

       --outbound-if4 name
              Bind IPv4 outbound sockets to host interface name, and, unless another interface is
              specified via -i, --interface, use this interface  to  derive  IPv4  addresses  and
              routes.  By default, the interface given by the default route is selected.

       --outbound-if6 name
              Bind IPv6 outbound sockets to host interface name, and, unless another interface is
              specified via -i, --interface, use this interface  to  derive  IPv6  addresses  and
              routes.  By default, the interface given by the default route is selected.

       -D, --dns addr
              Use addr (IPv4 or IPv6) for DHCP, DHCPv6, NDP or DNS forwarding, as configured (see
              options --no-dhcp-dns, --dhcp-dns, --dns-forward) instead of reading addresses from
              /etc/resolv.conf.  This option can be specified multiple times.  Specifying -D none
              disables usage of DNS addresses altogether.

       --dns-forward addr
              Map addr (IPv4 or IPv6) as seen from guest or namespace to the first configured DNS
              resolver  (with  corresponding  IP  version).  Mapping  is  limited  to UDP traffic
              directed to port 53, and DNS answers are translated back with  a  reverse  mapping.
              This option can be specified zero to two times (once for IPv4, once for IPv6).

       -S, --search list
              Use  space-separated  list  for  DHCP, DHCPv6, and NDP purposes, instead of reading
              entries from /etc/resolv.conf.  See  options  --no-dhcp-search  and  --dhcp-search.
              --search none disables the DNS domain search list altogether (if you need to search
              a domain called "none" you can use --search none.).

       --no-dhcp-dns addr
              In passt 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.

       --dhcp-dns addr
              In pasta 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.

       --no-dhcp-search addr
              In passt 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.

       --dhcp-search addr
              In pasta 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.

       --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.

       --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.

       --no-icmp
              Disable  the  ICMP/ICMPv6  echo  handler. ICMP and ICMPv6 echo requests coming from
              guest or target namespace will be silently dropped.

       --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.

       --no-ndp
              Disable NDP responses. NDP messages coming from guest or target namespace  will  be
              ignored.

       --no-dhcpv6
              Disable  the  DHCPv6  server.  DHCPv6  client  requests coming from guest or target
              namespace will be silently dropped.

       --no-ra
              Disable Router Advertisements. Router Solicitations coming  from  guest  or  target
              namespace will be ignored.

       --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 for any of the enabled address families.

       -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 default  route  and  an  interface
              address are configured on a given host interface.

       -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 default  route  and  an  interface
              address are configured on a given host interface.

   passt-only options
       -s, --socket path
              Path  for  UNIX  domain  socket  used  by  qemu(1)  or qrap(1) to connect to passt.
              Default is to probe  a  free  socket,  not  accepting  connections,  starting  from
              /tmp/passt_1.socket to /tmp/passt_64.socket.

       -F, --fd FD
              Pass  a  pre-opened, connected socket to passt. Usually the socket is opened in the
              parent process and passt 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.

       -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.

       -t, --tcp-ports spec
              Configure TCP port forwarding to guest. spec can be one of:

              none   Don't forward any ports

              all    Forward  all  unbound,  non-ephemeral  ports,  as   permitted   by   current
                     capabilities.  For low (< 1024) ports, see NOTES.

              ports  A  comma-separated list of ports, optionally ranged with -, and, optionally,
                     with target ports after :, if they differ. Specific addresses can  be  bound
                     as  well,  separated  by  /,  and also, since Linux 5.7, limited to specific
                     interfaces, prefixed by %. Within given ranges, selected  ports  and  ranges
                     can  be  excluded  by an additional specification prefixed by ~.  Specifying
                     excluded ranges only implies that all other ports are forwarded.  Examples:

                     -t 22  Forward local port 22 to port 22 on the guest

                     -t 22:23
                            Forward local port 22 to port 23 on the guest

                     -t 22,25
                            Forward local ports 22 and 25 to ports 22 and 25 on the guest

                     -t 22-80
                            Forward local ports between 22 and 80 to corresponding ports  on  the
                            guest

                     -t 22-80:32-90
                            Forward  local  ports between 22 and 80 to ports between 32 and 90 on
                            the guest

                     -t 192.0.2.1/22
                            Forward local port 22, bound to 192.0.2.1, to port 22 on the guest

                     -t 192.0.2.1%eth0/22
                            Forward local port 22, bound to 192.0.2.1 and interface eth0, to port
                            22

                     -t %eth0/22
                            Forward  local  port  22,  bound to any address on interface eth0, to
                            port 22

                     -t 2000-5000,~3000-3010
                            Forward local ports between 2000 and 5000, except for  those  between
                            3000 and 3010

                     -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

                     -t ~20000-20010
                            Forward all ports to the guest, except for the range  from  20000  to
                            20010

              Default is none.

       -u, --udp-ports spec
              Configure UDP port forwarding to guest. spec 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 none.

   pasta-only options
       -I, --ns-ifname name
              Name  of  tap  interface  to  be created in target namespace.  By default, the same
              interface name as the external, routable interface is used.

       -t, --tcp-ports spec
              Configure TCP port forwarding to namespace. spec can be one of:

              none   Don't forward any ports

              auto   Dynamically forward ports bound in the  namespace.  The  list  of  ports  is
                     periodically  derived  (every  second)  from  listening  sockets reported by
                     /proc/net/tcp and /proc/net/tcp6, see proc(5).

              ports  A comma-separated list of ports, optionally ranged with -, and,  optionally,
                     with  target  ports after :, if they differ. Specific addresses can be bound
                     as well, separated by /, and also, since  Linux  5.7,  limited  to  specific
                     interfaces,  prefixed  by  %. Within given ranges, selected ports and ranges
                     can be excluded by an additional specification prefixed  by  ~.   Specifying
                     excluded ranges only implies that all other ports are forwarded.  Examples:

                     -t 22  Forward local port 22 to 22 in the target namespace

                     -t 22:23
                            Forward local port 22 to port 23 in the target namespace

                     -t 22,25
                            Forward  local  ports  22  and  25  to  ports 22 and 25 in the target
                            namespace

                     -t 22-80
                            Forward local ports between 22 and 80 to corresponding ports  in  the
                            target namespace

                     -t 22-80:32-90
                            Forward  local  ports between 22 and 80 to ports between 32 and 90 in
                            the target namespace

                     -t 192.0.2.1/22
                            Forward local port 22, bound to 192.0.2.1, to port 22 in  the  target
                            namespace

                     -t 192.0.2.1%eth0/22
                            Forward local port 22, bound to 192.0.2.1 and interface eth0, to port
                            22

                     -t %eth0/22
                            Forward local port 22, bound to any address  on  interface  eth0,  to
                            port 22

                     -t 2000-5000,~3000-3010
                            Forward  local  ports between 2000 and 5000, except for those between
                            3000 and 3010

                     -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

                     -t ~20000-20010
                            Forward  all  ports  to the namespace, except for those between 20000
                            and 20010

              IPv6 bound ports are also forwarded for IPv4.

              Default is auto.

       -u, --udp-ports spec
              Configure UDP port forwarding to namespace. spec is as described for TCP above, and
              the  list  of ports is derived from listening sockets reported by /proc/net/udp and
              /proc/net/udp6, see proc(5), when pasta starts (not periodically).

              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 auto.

       -T, --tcp-ns spec
              Configure  TCP port forwarding from target namespace to init namespace.  spec is as
              described above for TCP.

              Default is auto.

       -U, --udp-ns spec
              Configure UDP port forwarding from target namespace to init namespace.  spec is  as
              described above for UDP.

              Default is auto.

       --userns spec
              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.

       --netns spec
              Target network namespace to join, as a path or a name.  A name is treated  as  with
              ip-netns(8) as equivalent to a path in /run/netns.

              This option can't be specified with a PID.

       --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.

       --no-netns-quit
              If  the  target  network  namespace is bound to the filesystem (that is, if PATH or
              NAME are given as target), do not exit once the network namespace is deleted.

       --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.

       --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.

              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 deprecated 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 REPORTING BUGS below.

       --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.

              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 deprecated 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 REPORTING BUGS below.

       --ns-mac-addr addr
              Configure MAC address addr on the tap interface in the namespace.

              Default is to let the tap driver build a pseudorandom hardware address.

EXAMPLES

   pasta
       Create and use a new, connected, user and network namespace
              $ 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
              $

       Connect an existing user and network namespace
              $ unshare -rUn
              # echo $$
              2446678

                   [From another terminal]
              $ ./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

                   [Back to the original terminal]
              # 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

   passt
       Start and connect a guest with basic port forwarding
              $ ./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

                   [From another terminal]
              $ ./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

                   [Back to the original terminal]
              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

                   [From yet another terminal]
              $ ssh -p 2222 root@localhost
              root@localhost's password:
                   [...]
              # 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

NOTES

   Handling of traffic with local destination and source addresses
       Both  passt  and  pasta  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 -- 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 passt or pasta 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.

   Handling of local traffic in pasta
       Depending on the configuration, pasta 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: pasta 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 splice(2) system
       call, and for UDP, a pair of recvmmsg(2) and sendmmsg(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.

   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, passt and pasta will try to bind to them, but will fail, unless, either:

       • the  sys.net.ipv4.ip_unprivileged_port_start  sysctl  is set to the number of the lowest
         port passt and pasta need. For example, as root:

              sysctl -w net.ipv4.ip_unprivileged_port_start=443

         Note: this is the recommended way of enabling passt and pasta  to  bind  to  ports  with
         numbers below 1024.

       • or   the   CAP_NET_BIND_SERVICE   Linux  capability  is  granted,  see  services(5)  and
         capabilities(7).

         This is, in general, not the recommended way, because passt and pasta 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 AppArmor, SELinux, Smack or TOMOYO, and no other processes can  interact
         in  such  a  way in virtue of this, granting this capability to passt and pasta only can
         effectively prevent other processes from utilising it.

         Note that this will not work for automatic detection and forwarding of ports with pasta,
         because pasta will relinquish this capability at runtime.

         To grant this capability, you can issue, as root:

              for p in $(which passt passt.avx2); do
                   setcap 'cap_net_bind_service=+ep' "${p}"
              done

   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), passt and pasta
       try to bind these  sockets  using  the  observed  source  identifier  as  "port"  --  that
       corresponds to Echo identifiers for "ping" sockets.

       As  bind(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 bind(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 ping_group_range parameter needs to include
       the PID of passt or pasta, see icmp(7).

   pasta and loopback interface
       As pasta connects to an existing namespace, or once it creates a new  namespace,  it  will
       also  ensure  that the loopback interface, lo, is brought up. This is needed to bind ports
       using the loopback address in the namespace.

   TCP sending window and TCP_INFO 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, passt and pasta routinely query
       the size of the sending window seen by the kernel on the corresponding  socket  using  the
       TCP_INFO  socket  option,  see  tcp(7).  Before Linux 5.3, i.e. before Linux kernel commit
       8f7baad7f035 ("tcp: Add snd_wnd to TCP_INFO"), the sending window (snd_wnd 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.

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.

AUTHORS

       Stefano Brivio <sbrivio@redhat.com>, David Gibson <david@gibson.dropbear.id.au>.

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.

COPYRIGHT

       Copyright (c) 2020-2022 Red Hat GmbH.

       passt  and pasta are free software: you can redistribute them and/or modify them under the
       terms of the GNU  Affero  General  Public  License  as  published  by  the  Free  Software
       Foundation, either version 3 of the License, or (at your option) any later version.

SEE ALSO

       namespaces(7), qemu(1), qrap(1), slirp4netns(1).

       High-level documentation is available at https://passt.top/passt/about/.

                                                                                         passt(1)