1passt(1)                    General Commands Manual                   passt(1)
2
3
4

NAME

6       passt  -  Unprivileged  user-mode  network connectivity for virtual ma‐
7       chines
8       pasta - Unprivileged user-mode network connectivity for  network  name‐
9       spaces
10
11

SYNOPSIS

13       passt [OPTION]...
14       pasta [OPTION]... [COMMAND [ARG]...]
15       pasta [OPTION]... PID
16       pasta [OPTION]... --netns [PATH|NAME]
17
18

DESCRIPTION

20   passt
21       passt (Plug A Simple Socket Transport) provides full, quasi-native net‐
22       work connectivity to virtual machines in  user-mode  without  requiring
23       any capabilities or privileges.
24
25       The data plane implements a translation layer between a Layer-2 virtual
26       network interface and native Layer-4 (TCP, UDP, ping)  sockets  on  the
27       host,  giving  the  illusion that application processes residing on the
28       guest are running on the local host, from a networking perspective.
29
30       Built-in ARP, DHCP, NDP, and DHCPv6  implementations  are  designed  to
31       provide  the  guest with a network configuration that tightly resembles
32       the host native configuration. With the default options, guest and host
33       share IP addresses, routes, and port bindings.
34
35       Port  forwarding  and  translation allow networking services running in
36       the guest to be reachable from both local and remote hosts.
37
38       Unlike slirp4netns(1), passt doesn't implement a full  TCP  stack:  the
39       TCP  translation  layer  has no stateful data buffering and operates by
40       reflecting one peer's observed parameters (congestion window size,  ac‐
41       knowledged data, etc.)  to the corresponding peer.
42
43       Currently,  the  only  supported  hypervisor  is qemu(1), connecting to
44       passt by means of a UNIX domain socket. This is supported starting from
45       qemu 7.2. For older qemu versions, see the qrap(1) wrapper.
46
47
48   pasta
49       pasta (Pack A Subtle Tap Abstraction) provides equivalent functionality
50       to network namespaces, as the one offered  by  passt  for  virtual  ma‐
51       chines.
52
53       If  PID  or --netns are given, pasta associates to an existing user and
54       network namespace. Otherwise, pasta creates  a  new  user  and  network
55       namespace,  and spawns the given command or a default shell within this
56       context. A tap device within the network namespace is created  to  pro‐
57       vide network connectivity.
58
59       For local TCP and UDP traffic only, pasta also implements a bypass path
60       directly mapping Layer-4 sockets between init  and  target  namespaces,
61       for performance reasons.
62
63

OPTIONS

65       -d, --debug
66              Be verbose, don't log to the system logger.
67
68
69       --trace
70              Be extra verbose, show single packets. Implies --debug.
71
72
73       -q, --quiet
74              Don't print informational messages.
75
76
77       -f, --foreground
78              Don't  run  in  background. This implies that the process is not
79              moved to a detached PID namespace after  starting,  because  the
80              PID itself cannot change.  Default is to fork into background.
81
82
83       -e, --stderr
84              Log to standard error too.  Default is to log to the system log‐
85              ger only, if started from an interactive terminal, and  to  both
86              system logger and standard error otherwise.
87
88
89       -l, --log-file PATH
90              Log  to  file PATH, not to standard error, and not to the system
91              logger.
92
93
94       --log-size SIZE
95              Limit log file size to SIZE bytes. When the log  file  is  full,
96              make room for new entries by removing old ones at the beginning.
97              This limit is mandatory.  Default is 1048576 (1 MiB).
98
99
100       --runas UID|UID:GID|LOGIN|LOGIN:GROUP
101              Attempt to change to given UID and corresponding group if UID is
102              given, or to given UID and given GID if both are given. Alterna‐
103              tively, login name, or login name and group name can be  passed.
104              This  requires  privileges  (either  initial  effective UID 0 or
105              CAP_SETUID capability) to work.  Default is to  change  to  user
106              nobody if started as root.
107
108
109       -h, --help
110              Display a help message and exit.
111
112
113       --version
114              Show version and exit.
115
116
117       -p, --pcap file
118              Capture  tap-facing (that is, guest-side or namespace-side) net‐
119              work packets to file in pcap format.
120
121
122       -P, --pid file
123              Write own PID to file once initialisation is done, before  fork‐
124              ing to background (if configured to do so).
125
126
127       -m, --mtu mtu
128              Assign mtu via DHCP (option 26) and NDP (option type 5).  By de‐
129              fault, no MTU options will be sent.
130
131
132       -a, --address addr
133              Assign IPv4 addr via DHCP (yiaddr), or addr via  DHCPv6  (option
134              5) and an addr-based prefix via NDP Router Advertisement (option
135              type 3) for an IPv6 addr.  This option  can  be  specified  zero
136              (for  defaults) to two times (once for IPv4, once for IPv6).  By
137              default, assigned IPv4 and IPv6 addresses  are  taken  from  the
138              host interfaces with the first default route for the correspond‐
139              ing IP version.
140
141
142       -n, --netmask mask
143              Assign IPv4 netmask mask, expressed as dot-decimal or number  of
144              bits,  via  DHCP (option 1).  By default, the netmask associated
145              to the host address  matching  the  assigned  one  is  used.  If
146              there's  no  matching address on the host, the netmask is deter‐
147              mined according to the CIDR block of the assigned  address  (RFC
148              4632).
149
150
151       -M, --mac-addr addr
152              Use  source  MAC address addr when communicating to the guest or
153              to the target namespace.  Default is to use the MAC  address  of
154              the interface with the first IPv4 default route on the host.
155
156
157       -g, --gateway addr
158              Assign IPv4 addr as default gateway via DHCP (option 3), or IPv6
159              addr as source for NDP Router Advertisement and DHCPv6 messages.
160              This  option  can  be specified zero (for defaults) to two times
161              (once for IPv4, once for IPv6).  By default, IPv4 and  IPv6  ad‐
162              dresses are taken from the host interface with the first default
163              route for the corresponding IP version.
164
165              Note: these addresses are also used as source address for  pack‐
166              ets  directed  to  the guest or to the target namespace having a
167              loopback or local source address,  to  allow  mapping  of  local
168              traffic  to  guest and target namespace. See the NOTES below for
169              more details about this mechanism.
170
171
172       -i, --interface name
173              Use host interface name to derive addresses and routes.  Default
174              is  to use the interfaces with the first default routes for each
175              IP version.
176
177
178       -D, --dns addr
179              Use addr (IPv4 or IPv6) for DHCP, DHCPv6, NDP or DNS forwarding,
180              as configured (see options --no-dhcp-dns, --dhcp-dns, --dns-for‐
181              ward) instead of reading addresses from /etc/resolv.conf.   This
182              option can be specified multiple times.  Specifying -D none dis‐
183              ables usage of DNS addresses altogether.
184
185
186       --dns-forward addr
187              Map addr (IPv4 or IPv6) as seen from guest or namespace  to  the
188              first  configured  DNS resolver (with corresponding IP version).
189              Mapping is limited to UDP traffic directed to port 53,  and  DNS
190              answers are translated back with a reverse mapping.  This option
191              can be specified zero to two times  (once  for  IPv4,  once  for
192              IPv6).
193
194
195       -S, --search list
196              Use space-separated list for DHCP, DHCPv6, and NDP purposes, in‐
197              stead of reading  entries  from  /etc/resolv.conf.  See  options
198              --no-dhcp-search  and  --dhcp-search. --search none disables the
199              DNS domain search list altogether (if you need to search  a  do‐
200              main called "none" you can use --search none.).
201
202
203       --no-dhcp-dns addr
204              In passt mode, do not assign IPv4 addresses via DHCP (option 23)
205              or IPv6 addresses via NDP Router Advertisement (option type  25)
206              and  DHCPv6  (option  23) as DNS resolvers.  By default, all the
207              configured addresses are passed.
208
209
210       --dhcp-dns addr
211              In pasta mode, assign IPv4 addresses via  DHCP  (option  23)  or
212              IPv6 addresses via NDP Router Advertisement (option type 25) and
213              DHCPv6 (option 23) as DNS resolvers.  By default, configured ad‐
214              dresses, if any, are not passed.
215
216
217       --no-dhcp-search addr
218              In  passt mode, do not send the DNS domain search list addresses
219              via DHCP (option 119), via NDP Router Advertisement (option type
220              31)  and  DHCPv6 (option 24).  By default, the DNS domain search
221              list resulting from configuration is passed.
222
223
224       --dhcp-search addr
225              In pasta mode, send the DNS domain  search  list  addresses  via
226              DHCP (option 119), via NDP Router Advertisement (option type 31)
227              and DHCPv6 (option 24).  By default, the DNS domain search  list
228              resulting from configuration is not passed.
229
230
231       --no-tcp
232              Disable the TCP protocol handler. No TCP connections will be ac‐
233              cepted host-side, and TCP packets coming from  guest  or  target
234              namespace will be silently dropped.
235
236
237       --no-udp
238              Disable the UDP protocol handler. No UDP traffic coming from the
239              host side will be forwarded, and UDP packets coming  from  guest
240              or target namespace will be silently dropped.
241
242
243       --no-icmp
244              Disable  the  ICMP/ICMPv6 echo handler. ICMP and ICMPv6 echo re‐
245              quests coming from guest or target namespace  will  be  silently
246              dropped.
247
248
249       --no-dhcp
250              Disable  the DHCP server. DHCP client requests coming from guest
251              or target namespace will be silently dropped.
252
253
254       --no-ndp
255              Disable NDP responses. NDP messages coming from guest or  target
256              namespace will be ignored.
257
258
259       --no-dhcpv6
260              Disable  the  DHCPv6  server. DHCPv6 client requests coming from
261              guest or target namespace will be silently dropped.
262
263
264       --no-ra
265              Disable Router Advertisements. Router Solicitations coming  from
266              guest or target namespace will be ignored.
267
268
269       --no-map-gw
270              Don't  remap TCP connections and untracked UDP traffic, with the
271              gateway address as destination, to the host.
272
273
274       -4, --ipv4-only
275              Enable IPv4-only operation. IPv6 traffic will  be  ignored.   By
276              default,  IPv6  operation is enabled as long as at least an IPv6
277              default route and an interface address are configured on a given
278              host interface.
279
280
281       -4, --ipv6-only
282              Enable  IPv6-only  operation.  IPv4 traffic will be ignored.  By
283              default, IPv4 operation is enabled as long as at least  an  IPv4
284              default route and an interface address are configured on a given
285              host interface.
286
287
288   passt-only options
289       -s, --socket path
290              Path for UNIX domain socket used by qemu(1) or qrap(1)  to  con‐
291              nect to passt.  Default is to probe a free socket, not accepting
292              connections,    starting     from     /tmp/passt_1.socket     to
293              /tmp/passt_64.socket.
294
295
296       -1, --one-off
297              Quit  after  handling  a single client connection, that is, once
298              the client closes the socket, or once we get a socket error.
299
300
301       -t, --tcp-ports spec
302              Configure TCP port forwarding to guest. spec can be one of:
303
304
305              none   Don't forward any ports
306
307
308              all    Forward all unbound, non-ephemeral ports, as permitted by
309                     current capabilities.  For low (< 1024) ports, see NOTES.
310
311
312              ports  A  comma-separated  list of ports, optionally ranged with
313                     -, and, optionally, with target ports after  :,  if  they
314                     differ.  Specific  addresses  can be bound as well, sepa‐
315                     rated by /, and also, since Linux 5.7,  limited  to  spe‐
316                     cific interfaces, prefixed by %. Within given ranges, se‐
317                     lected ports and ranges can be excluded by an  additional
318                     specification  prefixed by ~.  Specifying excluded ranges
319                     only implies that all other ports are  forwarded.   Exam‐
320                     ples:
321
322                     -t 22  Forward local port 22 to 22 on the guest
323
324                     -t 22:23
325                            Forward local port 22 to port 23 on the guest
326
327                     -t 22,25
328                            Forward  local  ports 22 and 25 to ports 22 and 25
329                            on the guest
330
331                     -t 22-80
332                            Forward local ports  22  to  80  to  corresponding
333                            ports on the guest
334
335                     -t 22-80-32:90
336                            Forward  local  ports  22  to  80 to corresponding
337                            ports on the guest plus 10
338
339                     -t 192.0.2.1/22
340                            Forward local port 22, bound to 192.0.2.1, to port
341                            22 on the guest
342
343                     -t 192.0.2.1%eth0/22
344                            Forward  local port 22, bound to 192.0.2.1 and in‐
345                            terface eth0, to port 22
346
347                     -t 2000-5000,~3000-3010
348                            Forward local ports 2000 to 5000, but not 3000  to
349                            3010
350
351                     -t 192.0.2.1/20-30,~25
352                            Forward  local ports 20 to 24, and 26 to 30, bound
353                            to 192.0.2.1
354
355                     -t ~20000-20010
356                            Forward all ports to the  guest,  except  for  the
357                            range from 20000 to 20010
358
359              Default is none.
360
361
362       -u, --udp-ports spec
363              Configure UDP port forwarding to guest. spec is as described for
364              TCP above.
365
366              Note: unless overridden, UDP ports with numbers corresponding to
367              forwarded  TCP port numbers are forwarded too, without, however,
368              any port translation. IPv6 bound ports are  also  forwarded  for
369              IPv4.
370
371              Default is none.
372
373
374   pasta-only options
375       -I, --ns-ifname name
376              Name of tap interface to be created in target namespace.  By de‐
377              fault, the same interface name as the external, routable  inter‐
378              face is used.
379
380
381       -t, --tcp-ports spec
382              Configure TCP port forwarding to namespace. spec can be one of:
383
384
385              none   Don't forward any ports
386
387
388              auto   Dynamically  forward  ports  bound  in the namespace. The
389                     list of ports is periodically derived (every second) from
390                     listening   sockets   reported   by   /proc/net/tcp   and
391                     /proc/net/tcp6, see proc(5).
392
393
394              ports  A comma-separated list of ports, optionally  ranged  with
395                     -,  and,  optionally,  with target ports after :, if they
396                     differ. Specific addresses can be bound  as  well,  sepa‐
397                     rated  by  /,  and also, since Linux 5.7, limited to spe‐
398                     cific interfaces, prefixed by %. Within given ranges, se‐
399                     lected  ports and ranges can be excluded by an additional
400                     specification prefixed by ~.  Specifying excluded  ranges
401                     only  implies  that all other ports are forwarded.  Exam‐
402                     ples:
403
404                     -t 22  Forward local port 22 to 22 in  the  target  name‐
405                            space
406
407                     -t 22:23
408                            Forward  local  port  22  to port 23 in the target
409                            namespace
410
411                     -t 22,25
412                            Forward local ports 22 and 25 to ports 22  and  25
413                            in the target namespace
414
415                     -t 22-80
416                            Forward  local  ports  22  to  80 to corresponding
417                            ports in the target namespace
418
419                     -t 22-80-32:90
420                            Forward local ports  22  to  80  to  corresponding
421                            ports plus 10 in the target namespace
422
423                     -t 192.0.2.1/22
424                            Forward local port 22, bound to 192.0.2.1, to port
425                            22 in the target namespace
426
427                     -t 192.0.2.1%eth0/22
428                            Forward local port 22, bound to 192.0.2.1 and  in‐
429                            terface eth0, to port 22
430
431                     -t 2000-5000,~3000-3010
432                            Forward  local ports 2000 to 5000, but not 3000 to
433                            3010
434
435                     -t 192.0.2.1/20-30,~25
436                            Forward local ports 20 to 24, and 26 to 30,  bound
437                            to 192.0.2.1
438
439                     -t ~20000-20010
440                            Forward all ports to the namespace, except for the
441                            range from 20000 to 20010
442
443              IPv6 bound ports are also forwarded for IPv4.
444
445              Default is auto.
446
447
448       -u, --udp-ports spec
449              Configure UDP port forwarding to namespace. spec is as described
450              for  TCP  above, and the list of ports is derived from listening
451              sockets  reported  by  /proc/net/udp  and  /proc/net/udp6,   see
452              proc(5), when pasta starts (not periodically).
453
454              Note: unless overridden, UDP ports with numbers corresponding to
455              forwarded TCP port numbers are forwarded too, without,  however,
456              any port translation.
457
458              IPv6 bound ports are also forwarded for IPv4.
459
460              Default is auto.
461
462
463       -T, --tcp-ns spec
464              Configure  TCP  port  forwarding  from  target namespace to init
465              namespace.  spec is as described above for TCP.
466
467              Default is auto.
468
469
470       -U, --udp-ns spec
471              Configure UDP port forwarding  from  target  namespace  to  init
472              namespace.  spec is as described above for UDP.
473
474              Default is auto.
475
476
477       --userns spec
478              Target user namespace to join, as a path. If PID is given, with‐
479              out this option, the user namespace will be the one of the  cor‐
480              responding process.
481
482
483       --netns spec
484              Target  network  namespace to join, as a path or a name.  A name
485              is treated as with  ip-netns(8)  as  equivalent  to  a  path  in
486              /run/netns.
487
488              This option can't be specified with a PID.
489
490
491       --netns-only
492              Join  only a target network namespace, not a user namespace, and
493              don't create one for sandboxing purposes either. This is implied
494              if PATH or NAME are given without --userns.
495
496
497       --no-netns-quit
498              If the target network namespace is bound to the filesystem (that
499              is, if PATH or NAME are given as target), do not exit  once  the
500              network namespace is deleted.
501
502
503       --config-net
504              Configure  networking  in  the  namespace:  set up addresses and
505              routes as configured or sourced from the host, and bring up  the
506              tap interface.
507
508
509       --ns-mac-addr addr
510              Configure  MAC  address  addr  on the tap interface in the name‐
511              space.
512
513              Default is to let the tap driver build a  pseudorandom  hardware
514              address.
515
516

EXAMPLES

518   pasta
519       Create and use a new, connected, user and network namespace
520              $ iperf3 -s -D
521              $ ./pasta
522              Outbound interface: eth0, namespace interface: eth0
523              ARP:
524                  address: 28:16:ad:39:a9:ea
525              DHCP:
526                  assign: 192.168.1.118
527                  mask: 255.255.255.0
528                  router: 192.168.1.1
529              NDP/DHCPv6:
530                  assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
531                  router: fe80::62e3:27ff:fe33:2b01
532              #
533              # dhclient -4 --no-pid
534              # dhclient -6 --no-pid
535              # ip address show
536              1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
537                  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
538                  inet 127.0.0.1/8 scope host lo
539                     valid_lft forever preferred_lft forever
540                  inet6 ::1/128 scope host
541                     valid_lft forever preferred_lft forever
542              2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UNKNOWN group default qlen 1000
543                  link/ether 5e:90:02:eb:b0:2a brd ff:ff:ff:ff:ff:ff
544                  inet 192.168.1.118/24 brd 192.168.1.255 scope global eth0
545                     valid_lft forever preferred_lft forever
546                  inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global
547                     valid_lft forever preferred_lft forever
548                  inet6 2a02:6d40:3ca5:2001:5c90:2ff:feeb:b02a/64 scope global dynamic mngtmpaddr
549                     valid_lft 3591sec preferred_lft 3591sec
550                  inet6 fe80::5c90:2ff:feeb:b02a/64 scope link
551                     valid_lft forever preferred_lft forever
552              # ip route show
553              default via 192.168.1.1 dev eth0
554              192.168.1.0/24 dev eth0 proto kernel scope link src 192.168.1.118
555              # ip -6 route show
556              2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17 dev eth0 proto kernel metric 256 pref medium
557              2a02:6d40:3ca5:2001::/64 dev eth0 proto kernel metric 256 expires 3584sec pref medium
558              fe80::/64 dev eth0 proto kernel metric 256 pref medium
559              default via fe80::62e3:27ff:fe33:2b01 dev eth0 proto ra metric 1024 expires 3584sec pref medium
560              # iperf3 -c 127.0.0.1 -t1
561              Connecting to host 127.0.0.1, port 5201
562              [  5] local 127.0.0.1 port 51938 connected to 127.0.0.1 port 5201
563              [ ID] Interval           Transfer     Bitrate         Retr  Cwnd
564              [  5]   0.00-1.00   sec  4.46 GBytes  38.3 Gbits/sec    0   3.93 MBytes
565              - - - - - - - - - - - - - - - - - - - - - - - - -
566              [ ID] Interval           Transfer     Bitrate         Retr
567              [  5]   0.00-1.00   sec  4.46 GBytes  38.3 Gbits/sec    0             sender
568              [  5]   0.00-1.41   sec  4.45 GBytes  27.1 Gbits/sec                  receiver
569
570              iperf Done.
571              # iperf3 -c ::1 -t1
572              Connecting to host ::1, port 5201
573              [  5] local ::1 port 50108 connected to ::1 port 5201
574              [ ID] Interval           Transfer     Bitrate         Retr  Cwnd
575              [  5]   0.00-1.00   sec  4.35 GBytes  37.4 Gbits/sec    0   4.99 MBytes
576              - - - - - - - - - - - - - - - - - - - - - - - - -
577              [ ID] Interval           Transfer     Bitrate         Retr
578              [  5]   0.00-1.00   sec  4.35 GBytes  37.4 Gbits/sec    0             sender
579              [  5]   0.00-1.41   sec  4.35 GBytes  26.4 Gbits/sec                  receiver
580
581              iperf Done.
582              # ping -c1 -4 spaghetti.pizza
583              PING spaghetti.pizza (172.67.192.217) 56(84) bytes of data.
584              64 bytes from 172.67.192.217: icmp_seq=1 ttl=255 time=37.3 ms
585
586              --- spaghetti.pizza ping statistics ---
587              1 packets transmitted, 1 received, 0% packet loss, time 0ms
588              # ping -c1 -6 spaghetti.pizza
589              PING spaghetti.pizza(2606:4700:3034::6815:147a (2606:4700:3034::6815:147a)) 56 data bytes
590              64 bytes from 2606:4700:3034::6815:147a: icmp_seq=1 ttl=255 time=35.6 ms
591
592              --- spaghetti.pizza ping statistics ---
593              1 packets transmitted, 1 received, 0% packet loss, time 0ms
594              rtt min/avg/max/mdev = 35.605/35.605/35.605/0.000 ms
595              # logout
596              $
597
598
599       Connect an existing user and network namespace
600              $ unshare -rUn
601              # echo $$
602              2446678
603
604                   [From another terminal]
605              $ ./pasta 2446678
606              Outbound interface: eth0, namespace interface: eth0
607              ARP:
608                  address: 28:16:ad:39:a9:ea
609              DHCP:
610                  assign: 192.168.1.118
611                  mask: 255.255.255.0
612                  router: 192.168.1.1
613              NDP/DHCPv6:
614                  assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
615                  router: fe80::62e3:27ff:fe33:2b01
616
617                   [Back to the original terminal]
618              # dhclient -4 --no-pid
619              # dhclient -6 --no-pid
620              # ip address show
621              1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
622                  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
623                  inet 127.0.0.1/8 scope host lo
624                     valid_lft forever preferred_lft forever
625                  inet6 ::1/128 scope host
626                     valid_lft forever preferred_lft forever
627              2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UNKNOWN group default qlen 1000
628                  link/ether fa:c1:2a:27:92:a9 brd ff:ff:ff:ff:ff:ff
629                  inet 192.168.1.118/24 brd 192.168.1.255 scope global eth0
630                     valid_lft forever preferred_lft forever
631                  inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global
632                     valid_lft forever preferred_lft forever
633                  inet6 2a02:6d40:3ca5:2001:f8c1:2aff:fe27:92a9/64 scope global dynamic mngtmpaddr
634                     valid_lft 3594sec preferred_lft 3594sec
635                  inet6 fe80::f8c1:2aff:fe27:92a9/64 scope link
636                     valid_lft forever preferred_lft forever
637
638
639   passt
640       Start and connect a guest with basic port forwarding
641              $ ./passt -f -t 2222:22
642              Outbound interface: eth0
643              ARP:
644                  address: 28:16:ad:39:a9:ea
645              DHCP:
646                  assign: 192.168.1.118
647                  mask: 255.255.255.0
648                  router: 192.168.1.1
649                      search:
650                          redhat.com
651              NDP/DHCPv6:
652                  assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
653                  router: fe80::62e3:27ff:fe33:2b01
654                      search:
655                          redhat.com
656              UNIX domain socket bound at /tmp/passt_1.socket
657
658              You can now start qrap:
659                  ./qrap 5 qemu-system-x86_64 ... -net socket,fd=5 -net nic,model=virtio
660              or directly qemu, patched with:
661                  qemu/0001-net-Allow-also-UNIX-domain-sockets-to-be-used-as-net.patch
662              as follows:
663                  qemu-system-x86_64 ... -net socket,connect=/tmp/passt_1.socket -net nic,model=virtio
664
665                   [From another terminal]
666              $ ./qrap 5 qemu-system-x86_64 test.qcow2 -m 1024 -display none -nodefaults -nographic -net socket,fd=5 -net nic,model=virtio
667              Connected to /tmp/passt_1.socket
668
669                   [Back to the original terminal]
670              passt: DHCP: ack to request
671              passt:     from 52:54:00:12:34:56
672              passt: NDP: received NS, sending NA
673              passt: NDP: received RS, sending RA
674              passt: DHCPv6: received SOLICIT, sending ADVERTISE
675              passt: NDP: received NS, sending NA
676              passt: DHCPv6: received REQUEST/RENEW/CONFIRM, sending REPLY
677              passt: NDP: received NS, sending NA
678
679                   [From yet another terminal]
680              $ ssh -p 2222 root@localhost
681              root@localhost's password:
682                   [...]
683              # ip address show
684              1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
685                  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
686                  inet 127.0.0.1/8 scope host lo
687                     valid_lft forever preferred_lft forever
688                  inet6 ::1/128 scope host
689                     valid_lft forever preferred_lft forever
690              2: ens2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UP group default qlen 1000
691                  link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
692                  inet 192.168.1.118/24 brd 192.168.1.255 scope global noprefixroute ens2
693                     valid_lft forever preferred_lft forever
694                  inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global noprefixroute
695                     valid_lft forever preferred_lft forever
696                  inet6 2a02:6d40:3ca5:2001:b019:9ae2:a2fe:e6b4/64 scope global dynamic noprefixroute
697                     valid_lft 3588sec preferred_lft 3588sec
698                  inet6 fe80::1f98:d09f:9309:9e77/64 scope link noprefixroute
699                     valid_lft forever preferred_lft forever
700
701

NOTES

703   Handling of traffic with local destination and source addresses
704       Both  passt and pasta can bind on ports with a local address, depending
705       on the configuration. Local destination or source addresses need to  be
706       changed  before packets are delivered to the guest or target namespace:
707       most operating systems would drop packets  received  from  non-loopback
708       interfaces  with  local  addresses, and it would also be impossible for
709       guest or target namespace to route answers back.
710
711       For convenience, and somewhat arbitrarily, the source address on  these
712       packets  is translated to the address of the default IPv4 or IPv6 gate‐
713       way -- this is known to be an existing, valid address on the same  sub‐
714       net.
715
716       Loopback  destination  addresses are instead translated to the observed
717       external address of the guest or target namespace. For IPv6 packets, if
718       usage  of  a link-local address by guest or namespace has ever been ob‐
719       served, and the original destination address is also a  link-local  ad‐
720       dress, the observed link-local address is used. Otherwise, the observed
721       global address is used. For both IPv4 and IPv6, if  no  addresses  have
722       been seen yet, the configured addresses will be used instead.
723
724       For  example,  if  passt  or pasta receive a connection from 127.0.0.1,
725       with destination 127.0.0.10, and the default IPv4 gateway is 192.0.2.1,
726       while  the  last  observed  source  address  from guest or namespace is
727       192.0.2.2, this will be translated to a connection  from  192.0.2.1  to
728       192.0.2.2.
729
730       Similarly,  for  traffic  coming  from guest or namespace, packets with
731       destination address corresponding to  the  default  gateway  will  have
732       their destination address translated to a loopback address, if and only
733       if a packet, in the opposite direction, with a loopback destination  or
734       source address, port-wise matching for UDP, or connection-wise for TCP,
735       has been recently forwarded to guest or namespace. This  behaviour  can
736       be disabled with --no-map-gw.
737
738
739   Handling of local traffic in pasta
740       Depending  on  the  configuration, pasta can bind to local ports in the
741       init namespace, in the target namespace, or both, and  forward  connec‐
742       tions and packets to corresponding ports in the other namespace.
743
744       To  avoid  unnecessary  overhead, these connections and packets are not
745       forwarded through the tap device connecting the namespaces: pasta  cre‐
746       ates  a socket in the destination namespace, with matching Layer-4 pro‐
747       tocol, and uses it to forward local data. For TCP,  data  is  forwarded
748       between  the  originating socket and the new socket using the splice(2)
749       system call, and for UDP, a pair of recvmmsg(2) and sendmmsg(2)  system
750       calls deals with packet transfers.
751
752       This bypass only applies to local connections and traffic, because it's
753       not possible to bind sockets to foreign addresses.
754
755
756   Binding to low numbered ports (well-known or system ports, up to 1023)
757       If the port forwarding configuration requires  binding  to  ports  with
758       numbers  lower than 1024, passt and pasta will try to bind to them, but
759       will fail, unless, either:
760
761
762       • the sys.net.ipv4.ip_unprivileged_port_start sysctl is set to the num‐
763         ber of the lowest port passt and pasta need. For example, as root:
764
765              sysctl -w net.ipv4.ip_unprivileged_port_start=443
766
767         Note: this is the recommended way of enabling passt and pasta to bind
768         to ports with numbers below 1024.
769
770
771       • or the CAP_NET_BIND_SERVICE Linux capability  is  granted,  see  ser‐
772         vices(5) and capabilities(7).
773
774         This is, in general, not the recommended way, because passt and pasta
775         might be used as vector to effectively use this capability  from  an‐
776         other process.
777
778         However,  if  your  environment  is sufficiently controlled by an LSM
779         (Linux Security Module) such as AppArmor, SELinux, Smack  or  TOMOYO,
780         and  no other processes can interact in such a way in virtue of this,
781         granting this capability to passt and pasta only can effectively pre‐
782         vent other processes from utilising it.
783
784         Note  that  this will not work for automatic detection and forwarding
785         of ports with pasta, because pasta will relinquish this capability at
786         runtime.
787
788         To grant this capability, you can issue, as root:
789
790              for p in $(which passt passt.avx2); do
791                   setcap 'cap_net_bind_service=+ep' "${p}"
792              done
793
794
795
796   ICMP/ICMPv6 Echo sockets
797       ICMP and ICMPv6 Echo requests coming from guest or target namespace are
798       handled using so-called "ping" sockets, introduced in Linux 2.6.30.  To
799       preserve  the  original identifier (see RFC 792, page 14, for ICMP, and
800       RFC 4443, section 4.1, for ICMPv6), passt and pasta try to  bind  these
801       sockets  using  the observed source identifier as "port" -- that corre‐
802       sponds to Echo identifiers for "ping" sockets.
803
804       As bind(2) failures were seen  with  particularly  restrictive  SELinux
805       policies, a fall-back mechanism maps different identifiers to different
806       sockets, and identifiers in replies will be mapped back to the original
807       identifier  of the request. However, if bind(2) fails and the fall-back
808       mechanism is used, echo requests will be forwarded with different,  al‐
809       beit unique, identifiers.
810
811       For ICMP and ICMPv6 Echo requests to work, the ping_group_range parame‐
812       ter needs to include the PID of passt or pasta, see icmp(7).
813
814
815   pasta and loopback interface
816       As pasta connects to an existing namespace, or once it  creates  a  new
817       namespace,  it  will  also  ensure  that the loopback interface, lo, is
818       brought up. This is needed to bind ports using the loopback address  in
819       the namespace.
820
821
822   TCP sending window and TCP_INFO before Linux 5.3
823       To  synchronise the TCP sending window from host Layer-4 sockets to the
824       TCP parameters announced in TCP segments sent over the  Layer-2  inter‐
825       face,  passt  and  pasta routinely query the size of the sending window
826       seen by the kernel on  the  corresponding  socket  using  the  TCP_INFO
827       socket  option,  see tcp(7). Before Linux 5.3, i.e. before Linux kernel
828       commit 8f7baad7f035 ("tcp: Add snd_wnd to TCP_INFO"), the sending  win‐
829       dow (snd_wnd field) is not available.
830
831       If the sending window cannot be queried, it will always be announced as
832       the current sending buffer size to  guest  or  target  namespace.  This
833       might affect throughput of TCP connections.
834
835

LIMITATIONS

837       Currently, IGMP/MLD proxying (RFC 4605) and support for SCTP (RFC 4960)
838       are not implemented.
839
840       TCP Selective Acknowledgment (RFC 2018), as well as Protection  Against
841       Wrapped  Sequences  (PAWS) and Round-Trip Time Measurement (RTTM), both
842       described by RFC 7232, are currently not implemented.
843
844

AUTHORS

846       Stefano Brivio <sbrivio@redhat.com>, David  Gibson  <david@gibson.drop‐
847       bear.id.au>.
848
849

REPORTING BUGS

851       Please      report     issues     on     the     bug     tracker     at
852       https://passt.top/passt/bugs,  or  send  a  message   to   the   passt-
853       user@passt.top mailing list, see https://passt.top/passt/lists.
854
855
857       Copyright (c) 2020-2022 Red Hat GmbH.
858
859       passt  and  pasta  are  free software: you can redistribute them and/or
860       modify them under the terms of the GNU Affero General Public License as
861       published  by the Free Software Foundation, either version 3 of the Li‐
862       cense, or (at your option) any later version.
863
864

SEE ALSO

866       namespaces(7), qemu(1), qrap(1), slirp4netns(1).
867
868       High-level        documentation         is         available         at
869       https://passt.top/passt/about/.
870
871
872
873                                                                      passt(1)
Impressum