1passt(1) General Commands Manual passt(1)
2
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
13 passt [OPTION]...
14 pasta [OPTION]... [COMMAND [ARG]...]
15 pasta [OPTION]... PID
16 pasta [OPTION]... --netns [PATH|NAME]
17
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 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 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 Port forwarding and translation allow networking services running in
36 the guest to be reachable from both local and remote hosts.
37 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 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 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 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 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
65 -d, --debug
66 Be verbose, don't log to the system logger.
67 --trace
70 Be extra verbose, show single packets. Implies --debug.
71 -q, --quiet
74 Don't print informational messages.
75 -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 -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 -l, --log-file PATH
90 Log to file PATH, not to standard error, and not to the system
91 logger.
92 --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 --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 -h, --help
110 Display a help message and exit.
111 --version
114 Show version and exit.
115 -p, --pcap file
118 Capture tap-facing (that is, guest-side or namespace-side) net‐
119 work packets to file in pcap format.
120 -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 -m, --mtu mtu
128 Assign mtu via DHCP (option 26) and NDP (option type 5). A zero
129 value disables assignment. By default, the advertised MTU is
130 65520 bytes, that is, the maximum 802.3 MTU minus the length of
131 a 802.3 header, rounded to 32 bits (IPv4 words).
132 -a, --address addr
135 Assign IPv4 addr via DHCP (yiaddr), or addr via DHCPv6 (option
136 5) and an addr-based prefix via NDP Router Advertisement (option
137 type 3) for an IPv6 addr. This option can be specified zero
138 (for defaults) to two times (once for IPv4, once for IPv6). By
139 default, assigned IPv4 and IPv6 addresses are taken from the
140 host interfaces with the first default route for the correspond‐
141 ing IP version.
142 -n, --netmask mask
145 Assign IPv4 netmask mask, expressed as dot-decimal or number of
146 bits, via DHCP (option 1). By default, the netmask associated
147 to the host address matching the assigned one is used. If
148 there's no matching address on the host, the netmask is deter‐
149 mined according to the CIDR block of the assigned address (RFC
150 4632).
151 -M, --mac-addr addr
154 Use source MAC address addr when communicating to the guest or
155 to the target namespace. Default is to use the MAC address of
156 the interface with the first IPv4 default route on the host.
157 -g, --gateway addr
160 Assign IPv4 addr as default gateway via DHCP (option 3), or IPv6
161 addr as source for NDP Router Advertisement and DHCPv6 messages.
162 This option can be specified zero (for defaults) to two times
163 (once for IPv4, once for IPv6). By default, IPv4 and IPv6 ad‐
164 dresses are taken from the host interface with the first default
165 route for the corresponding IP version.
166 Note: these addresses are also used as source address for pack‐
168 ets directed to the guest or to the target namespace having a
169 loopback or local source address, to allow mapping of local
170 traffic to guest and target namespace. See the NOTES below for
171 more details about this mechanism.
172 -i, --interface name
175 Use host interface name to derive addresses and routes. Default
176 is to use the interfaces specified by --outbound-if4 and --out‐
177 bound-if6, for IPv4 and IPv6 addresses and routes, respectively.
178 If no interfaces are given, the interface with the first default
179 routes for each IP version is selected.
180 -o, --outbound addr
183 Use an IPv4 addr as source address for IPv4 outbound TCP connec‐
184 tions, UDP flows, ICMP requests, or an IPv6 addr for IPv6 ones,
185 by binding outbound sockets to it. This option can be specified
186 zero (for defaults) to two times (once for IPv4, once for IPv6).
187 By default, the source address is selected by the routing ta‐
188 bles.
189 --outbound-if4 name
192 Bind IPv4 outbound sockets to host interface name, and, unless
193 another interface is specified via -i, --interface, use this in‐
194 terface to derive IPv4 addresses and routes. By default, the
195 interface given by the default route is selected.
196 --outbound-if6 name
199 Bind IPv6 outbound sockets to host interface name, and, unless
200 another interface is specified via -i, --interface, use this in‐
201 terface to derive IPv6 addresses and routes. By default, the
202 interface given by the default route is selected.
203 -D, --dns addr
206 Use addr (IPv4 or IPv6) for DHCP, DHCPv6, NDP or DNS forwarding,
207 as configured (see options --no-dhcp-dns, --dhcp-dns, --dns-for‐
208 ward) instead of reading addresses from /etc/resolv.conf. This
209 option can be specified multiple times. Specifying -D none dis‐
210 ables usage of DNS addresses altogether.
211 --dns-forward addr
214 Map addr (IPv4 or IPv6) as seen from guest or namespace to the
215 first configured DNS resolver (with corresponding IP version).
216 Mapping is limited to UDP traffic directed to port 53, and DNS
217 answers are translated back with a reverse mapping. This option
218 can be specified zero to two times (once for IPv4, once for
219 IPv6).
220 -S, --search list
223 Use space-separated list for DHCP, DHCPv6, and NDP purposes, in‐
224 stead of reading entries from /etc/resolv.conf. See options
225 --no-dhcp-search and --dhcp-search. --search none disables the
226 DNS domain search list altogether (if you need to search a do‐
227 main called "none" you can use --search none.).
228 --no-dhcp-dns addr
231 In passt mode, do not assign IPv4 addresses via DHCP (option 23)
232 or IPv6 addresses via NDP Router Advertisement (option type 25)
233 and DHCPv6 (option 23) as DNS resolvers. By default, all the
234 configured addresses are passed.
235 --dhcp-dns addr
238 In pasta mode, assign IPv4 addresses via DHCP (option 23) or
239 IPv6 addresses via NDP Router Advertisement (option type 25) and
240 DHCPv6 (option 23) as DNS resolvers. By default, configured ad‐
241 dresses, if any, are not passed.
242 --no-dhcp-search addr
245 In passt mode, do not send the DNS domain search list addresses
246 via DHCP (option 119), via NDP Router Advertisement (option type
247 31) and DHCPv6 (option 24). By default, the DNS domain search
248 list resulting from configuration is passed.
249 --dhcp-search addr
252 In pasta mode, send the DNS domain search list addresses via
253 DHCP (option 119), via NDP Router Advertisement (option type 31)
254 and DHCPv6 (option 24). By default, the DNS domain search list
255 resulting from configuration is not passed.
256 --no-tcp
259 Disable the TCP protocol handler. No TCP connections will be ac‐
260 cepted host-side, and TCP packets coming from guest or target
261 namespace will be silently dropped.
262 --no-udp
265 Disable the UDP protocol handler. No UDP traffic coming from the
266 host side will be forwarded, and UDP packets coming from guest
267 or target namespace will be silently dropped.
268 --no-icmp
271 Disable the ICMP/ICMPv6 echo handler. ICMP and ICMPv6 echo re‐
272 quests coming from guest or target namespace will be silently
273 dropped.
274 --no-dhcp
277 Disable the DHCP server. DHCP client requests coming from guest
278 or target namespace will be silently dropped. Implied if there
279 is no gateway on the selected IPv4 default route.
280 --no-ndp
283 Disable NDP responses. NDP messages coming from guest or target
284 namespace will be ignored.
285 --no-dhcpv6
288 Disable the DHCPv6 server. DHCPv6 client requests coming from
289 guest or target namespace will be silently dropped.
290 --no-ra
293 Disable Router Advertisements. Router Solicitations coming from
294 guest or target namespace will be ignored.
295 --no-map-gw
298 Don't remap TCP connections and untracked UDP traffic, with the
299 gateway address as destination, to the host. Implied if there is
300 no gateway on the selected default route for any of the enabled
301 address families.
302 -4, --ipv4-only
305 Enable IPv4-only operation. IPv6 traffic will be ignored. By
306 default, IPv6 operation is enabled as long as at least an IPv6
307 default route and an interface address are configured on a given
308 host interface.
309 -6, --ipv6-only
312 Enable IPv6-only operation. IPv4 traffic will be ignored. By
313 default, IPv4 operation is enabled as long as at least an IPv4
314 default route and an interface address are configured on a given
315 host interface.
316 passt-only options
319 -s, --socket path
320 Path for UNIX domain socket used by qemu(1) or qrap(1) to con‐
321 nect to passt. Default is to probe a free socket, not accepting
322 connections, starting from /tmp/passt_1.socket to
323 /tmp/passt_64.socket.
324 -F, --fd FD
327 Pass a pre-opened, connected socket to passt. Usually the socket
328 is opened in the parent process and passt inherits it when run
329 as a child. This allows the parent process to open sockets using
330 another address family or requiring special privileges.
331 This option implies the behaviour described for --one-off, once
333 this socket is closed.
334 -1, --one-off
337 Quit after handling a single client connection, that is, once
338 the client closes the socket, or once we get a socket error.
339 -t, --tcp-ports spec
342 Configure TCP port forwarding to guest. spec can be one of:
343 none Don't forward any ports
346 all Forward all unbound, non-ephemeral ports, as permitted by
349 current capabilities. For low (< 1024) ports, see NOTES.
350 ports A comma-separated list of ports, optionally ranged with
353 -, and, optionally, with target ports after :, if they
354 differ. Specific addresses can be bound as well, sepa‐
355 rated by /, and also, since Linux 5.7, limited to spe‐
356 cific interfaces, prefixed by %. Within given ranges, se‐
357 lected ports and ranges can be excluded by an additional
358 specification prefixed by ~. Specifying excluded ranges
359 only implies that all other ports are forwarded. Exam‐
360 ples:
361 -t 22 Forward local port 22 to port 22 on the guest
363 -t 22:23
365 Forward local port 22 to port 23 on the guest
366 -t 22,25
368 Forward local ports 22 and 25 to ports 22 and 25
369 on the guest
370 -t 22-80
372 Forward local ports between 22 and 80 to corre‐
373 sponding ports on the guest
374 -t 22-80:32-90
376 Forward local ports between 22 and 80 to ports be‐
377 tween 32 and 90 on the guest
378 -t 192.0.2.1/22
380 Forward local port 22, bound to 192.0.2.1, to port
381 22 on the guest
382 -t 192.0.2.1%eth0/22
384 Forward local port 22, bound to 192.0.2.1 and in‐
385 terface eth0, to port 22
386 -t %eth0/22
388 Forward local port 22, bound to any address on in‐
389 terface eth0, to port 22
390 -t 2000-5000,~3000-3010
392 Forward local ports between 2000 and 5000, except
393 for those between 3000 and 3010
394 -t 192.0.2.1/20-30,~25
396 For the local address 192.0.2.1, forward ports be‐
397 tween 20 and 24 and between 26 and 30
398 -t ~20000-20010
400 Forward all ports to the guest, except for the
401 range from 20000 to 20010
402 Default is none.
404 -u, --udp-ports spec
407 Configure UDP port forwarding to guest. spec is as described for
408 TCP above.
409 Note: unless overridden, UDP ports with numbers corresponding to
411 forwarded TCP port numbers are forwarded too, without, however,
412 any port translation. IPv6 bound ports are also forwarded for
413 IPv4.
414 Default is none.
416 pasta-only options
419 -I, --ns-ifname name
420 Name of tap interface to be created in target namespace. By de‐
421 fault, the same interface name as the external, routable inter‐
422 face is used.
423 -t, --tcp-ports spec
426 Configure TCP port forwarding to namespace. spec can be one of:
427 none Don't forward any ports
430 auto Dynamically forward ports bound in the namespace. The
433 list of ports is periodically derived (every second) from
434 listening sockets reported by /proc/net/tcp and
435 /proc/net/tcp6, see proc(5).
436 ports A comma-separated list of ports, optionally ranged with
439 -, and, optionally, with target ports after :, if they
440 differ. Specific addresses can be bound as well, sepa‐
441 rated by /, and also, since Linux 5.7, limited to spe‐
442 cific interfaces, prefixed by %. Within given ranges, se‐
443 lected ports and ranges can be excluded by an additional
444 specification prefixed by ~. Specifying excluded ranges
445 only implies that all other ports are forwarded. Exam‐
446 ples:
447 -t 22 Forward local port 22 to 22 in the target name‐
449 space
450 -t 22:23
452 Forward local port 22 to port 23 in the target
453 namespace
454 -t 22,25
456 Forward local ports 22 and 25 to ports 22 and 25
457 in the target namespace
458 -t 22-80
460 Forward local ports between 22 and 80 to corre‐
461 sponding ports in the target namespace
462 -t 22-80:32-90
464 Forward local ports between 22 and 80 to ports be‐
465 tween 32 and 90 in the target namespace
466 -t 192.0.2.1/22
468 Forward local port 22, bound to 192.0.2.1, to port
469 22 in the target namespace
470 -t 192.0.2.1%eth0/22
472 Forward local port 22, bound to 192.0.2.1 and in‐
473 terface eth0, to port 22
474 -t %eth0/22
476 Forward local port 22, bound to any address on in‐
477 terface eth0, to port 22
478 -t 2000-5000,~3000-3010
480 Forward local ports between 2000 and 5000, except
481 for those between 3000 and 3010
482 -t 192.0.2.1/20-30,~25
484 For the local address 192.0.2.1, forward ports be‐
485 tween 20 and 24 and between 26 and 30
486 -t ~20000-20010
488 Forward all ports to the namespace, except for
489 those between 20000 and 20010
490 IPv6 bound ports are also forwarded for IPv4.
492 Default is auto.
494 -u, --udp-ports spec
497 Configure UDP port forwarding to namespace. spec is as described
498 for TCP above, and the list of ports is derived from listening
499 sockets reported by /proc/net/udp and /proc/net/udp6, see
500 proc(5).
501 Note: unless overridden, UDP ports with numbers corresponding to
503 forwarded TCP port numbers are forwarded too, without, however,
504 any port translation.
505 IPv6 bound ports are also forwarded for IPv4.
507 Default is auto.
509 -T, --tcp-ns spec
512 Configure TCP port forwarding from target namespace to init
513 namespace. spec is as described above for TCP.
514 Default is auto.
516 -U, --udp-ns spec
519 Configure UDP port forwarding from target namespace to init
520 namespace. spec is as described above for UDP.
521 Default is auto.
523 --userns spec
526 Target user namespace to join, as a path. If PID is given, with‐
527 out this option, the user namespace will be the one of the cor‐
528 responding process.
529 --netns spec
532 Target network namespace to join, as a path or a name. A name
533 is treated as with ip-netns(8) as equivalent to a path in
534 /run/netns.
535 This option can't be specified with a PID.
537 --netns-only
540 Join only a target network namespace, not a user namespace, and
541 don't create one for sandboxing purposes either. This is implied
542 if PATH or NAME are given without --userns.
543 --no-netns-quit
546 If the target network namespace is bound to the filesystem (that
547 is, if PATH or NAME are given as target), do not exit once the
548 network namespace is deleted.
549 --config-net
552 Configure networking in the namespace: set up addresses and
553 routes as configured or sourced from the host, and bring up the
554 tap interface.
555 --no-copy-routes (DEPRECATED)
558 With --config-net, do not copy all the routes associated to the
559 interface we derive addresses and routes from: set up only the
560 default gateway. Implied by -g, --gateway.
561 Default is to copy all the routing entries from the interface in
563 the outer namespace to the target namespace, translating the
564 output interface attribute to the outbound interface in the
565 namespace.
566 Note that this configuration option is deprecated and will be
568 removed in a future version. It is not expected to be of any
569 use, and it simply reflects a legacy behaviour. If you have any
570 use for this, refer to REPORTING BUGS below.
571 --no-copy-addrs (DEPRECATED)
574 With --config-net, do not copy all the addresses associated to
575 the interface we derive addresses and routes from: set up a sin‐
576 gle one. Implied by -a, --address.
577 Default is to copy all the addresses, except for link-local
579 ones, from the interface from the outer namespace to the target
580 namespace.
581 Note that this configuration option is deprecated and will be
583 removed in a future version. It is not expected to be of any
584 use, and it simply reflects a legacy behaviour. If you have any
585 use for this, refer to REPORTING BUGS below.
586 --ns-mac-addr addr
589 Configure MAC address addr on the tap interface in the name‐
590 space.
591 Default is to let the tap driver build a pseudorandom hardware
593 address.
594
597 pasta
598 Create and use a new, connected, user and network namespace
599 $ iperf3 -s -D
600 $ ./pasta
601 Outbound interface: eth0, namespace interface: eth0
602 ARP:
603 address: 28:16:ad:39:a9:ea
604 DHCP:
605 assign: 192.168.1.118
606 mask: 255.255.255.0
607 router: 192.168.1.1
608 NDP/DHCPv6:
609 assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
610 router: fe80::62e3:27ff:fe33:2b01
611 #
612 # dhclient -4 --no-pid
613 # dhclient -6 --no-pid
614 # ip address show
615 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
616 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
617 inet 127.0.0.1/8 scope host lo
618 valid_lft forever preferred_lft forever
619 inet6 ::1/128 scope host
620 valid_lft forever preferred_lft forever
621 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UNKNOWN group default qlen 1000
622 link/ether 5e:90:02:eb:b0:2a brd ff:ff:ff:ff:ff:ff
623 inet 192.168.1.118/24 brd 192.168.1.255 scope global eth0
624 valid_lft forever preferred_lft forever
625 inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global
626 valid_lft forever preferred_lft forever
627 inet6 2a02:6d40:3ca5:2001:5c90:2ff:feeb:b02a/64 scope global dynamic mngtmpaddr
628 valid_lft 3591sec preferred_lft 3591sec
629 inet6 fe80::5c90:2ff:feeb:b02a/64 scope link
630 valid_lft forever preferred_lft forever
631 # ip route show
632 default via 192.168.1.1 dev eth0
633 192.168.1.0/24 dev eth0 proto kernel scope link src 192.168.1.118
634 # ip -6 route show
635 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17 dev eth0 proto kernel metric 256 pref medium
636 2a02:6d40:3ca5:2001::/64 dev eth0 proto kernel metric 256 expires 3584sec pref medium
637 fe80::/64 dev eth0 proto kernel metric 256 pref medium
638 default via fe80::62e3:27ff:fe33:2b01 dev eth0 proto ra metric 1024 expires 3584sec pref medium
639 # iperf3 -c 127.0.0.1 -t1
640 Connecting to host 127.0.0.1, port 5201
641 [ 5] local 127.0.0.1 port 51938 connected to 127.0.0.1 port 5201
642 [ ID] Interval Transfer Bitrate Retr Cwnd
643 [ 5] 0.00-1.00 sec 4.46 GBytes 38.3 Gbits/sec 0 3.93 MBytes
644 - - - - - - - - - - - - - - - - - - - - - - - - -
645 [ ID] Interval Transfer Bitrate Retr
646 [ 5] 0.00-1.00 sec 4.46 GBytes 38.3 Gbits/sec 0 sender
647 [ 5] 0.00-1.41 sec 4.45 GBytes 27.1 Gbits/sec receiver
648 iperf Done.
650 # iperf3 -c ::1 -t1
651 Connecting to host ::1, port 5201
652 [ 5] local ::1 port 50108 connected to ::1 port 5201
653 [ ID] Interval Transfer Bitrate Retr Cwnd
654 [ 5] 0.00-1.00 sec 4.35 GBytes 37.4 Gbits/sec 0 4.99 MBytes
655 - - - - - - - - - - - - - - - - - - - - - - - - -
656 [ ID] Interval Transfer Bitrate Retr
657 [ 5] 0.00-1.00 sec 4.35 GBytes 37.4 Gbits/sec 0 sender
658 [ 5] 0.00-1.41 sec 4.35 GBytes 26.4 Gbits/sec receiver
659 iperf Done.
661 # ping -c1 -4 spaghetti.pizza
662 PING spaghetti.pizza (172.67.192.217) 56(84) bytes of data.
663 64 bytes from 172.67.192.217: icmp_seq=1 ttl=255 time=37.3 ms
664 --- spaghetti.pizza ping statistics ---
666 1 packets transmitted, 1 received, 0% packet loss, time 0ms
667 # ping -c1 -6 spaghetti.pizza
668 PING spaghetti.pizza(2606:4700:3034::6815:147a (2606:4700:3034::6815:147a)) 56 data bytes
669 64 bytes from 2606:4700:3034::6815:147a: icmp_seq=1 ttl=255 time=35.6 ms
670 --- spaghetti.pizza ping statistics ---
672 1 packets transmitted, 1 received, 0% packet loss, time 0ms
673 rtt min/avg/max/mdev = 35.605/35.605/35.605/0.000 ms
674 # logout
675 $
676 Connect an existing user and network namespace
679 $ unshare -rUn
680 # echo $$
681 2446678
682 [From another terminal]
684 $ ./pasta 2446678
685 Outbound interface: eth0, namespace interface: eth0
686 ARP:
687 address: 28:16:ad:39:a9:ea
688 DHCP:
689 assign: 192.168.1.118
690 mask: 255.255.255.0
691 router: 192.168.1.1
692 NDP/DHCPv6:
693 assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
694 router: fe80::62e3:27ff:fe33:2b01
695 [Back to the original terminal]
697 # dhclient -4 --no-pid
698 # dhclient -6 --no-pid
699 # ip address show
700 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
701 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
702 inet 127.0.0.1/8 scope host lo
703 valid_lft forever preferred_lft forever
704 inet6 ::1/128 scope host
705 valid_lft forever preferred_lft forever
706 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UNKNOWN group default qlen 1000
707 link/ether fa:c1:2a:27:92:a9 brd ff:ff:ff:ff:ff:ff
708 inet 192.168.1.118/24 brd 192.168.1.255 scope global eth0
709 valid_lft forever preferred_lft forever
710 inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global
711 valid_lft forever preferred_lft forever
712 inet6 2a02:6d40:3ca5:2001:f8c1:2aff:fe27:92a9/64 scope global dynamic mngtmpaddr
713 valid_lft 3594sec preferred_lft 3594sec
714 inet6 fe80::f8c1:2aff:fe27:92a9/64 scope link
715 valid_lft forever preferred_lft forever
716 passt
719 Start and connect a guest with basic port forwarding
720 $ ./passt -f -t 2222:22
721 Outbound interface: eth0
722 ARP:
723 address: 28:16:ad:39:a9:ea
724 DHCP:
725 assign: 192.168.1.118
726 mask: 255.255.255.0
727 router: 192.168.1.1
728 search:
729 redhat.com
730 NDP/DHCPv6:
731 assign: 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17
732 router: fe80::62e3:27ff:fe33:2b01
733 search:
734 redhat.com
735 UNIX domain socket bound at /tmp/passt_1.socket
736 You can now start qrap:
738 ./qrap 5 qemu-system-x86_64 ... -net socket,fd=5 -net nic,model=virtio
739 or directly qemu, patched with:
740 qemu/0001-net-Allow-also-UNIX-domain-sockets-to-be-used-as-net.patch
741 as follows:
742 qemu-system-x86_64 ... -net socket,connect=/tmp/passt_1.socket -net nic,model=virtio
743 [From another terminal]
745 $ ./qrap 5 qemu-system-x86_64 test.qcow2 -m 1024 -display none -nodefaults -nographic -net socket,fd=5 -net nic,model=virtio
746 Connected to /tmp/passt_1.socket
747 [Back to the original terminal]
749 passt: DHCP: ack to request
750 passt: from 52:54:00:12:34:56
751 passt: NDP: received NS, sending NA
752 passt: NDP: received RS, sending RA
753 passt: DHCPv6: received SOLICIT, sending ADVERTISE
754 passt: NDP: received NS, sending NA
755 passt: DHCPv6: received REQUEST/RENEW/CONFIRM, sending REPLY
756 passt: NDP: received NS, sending NA
757 [From yet another terminal]
759 $ ssh -p 2222 root@localhost
760 root@localhost's password:
761 [...]
762 # ip address show
763 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
764 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
765 inet 127.0.0.1/8 scope host lo
766 valid_lft forever preferred_lft forever
767 inet6 ::1/128 scope host
768 valid_lft forever preferred_lft forever
769 2: ens2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 65520 qdisc pfifo_fast state UP group default qlen 1000
770 link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
771 inet 192.168.1.118/24 brd 192.168.1.255 scope global noprefixroute ens2
772 valid_lft forever preferred_lft forever
773 inet6 2a02:6d40:3ca5:2001:b81d:fa4a:8cdd:cf17/128 scope global noprefixroute
774 valid_lft forever preferred_lft forever
775 inet6 2a02:6d40:3ca5:2001:b019:9ae2:a2fe:e6b4/64 scope global dynamic noprefixroute
776 valid_lft 3588sec preferred_lft 3588sec
777 inet6 fe80::1f98:d09f:9309:9e77/64 scope link noprefixroute
778 valid_lft forever preferred_lft forever
779
782 Handling of traffic with local destination and source addresses
783 Both passt and pasta can bind on ports with a local address, depending
784 on the configuration. Local destination or source addresses need to be
785 changed before packets are delivered to the guest or target namespace:
786 most operating systems would drop packets received from non-loopback
787 interfaces with local addresses, and it would also be impossible for
788 guest or target namespace to route answers back.
789 For convenience, and somewhat arbitrarily, the source address on these
791 packets is translated to the address of the default IPv4 or IPv6 gate‐
792 way -- this is known to be an existing, valid address on the same sub‐
793 net.
794 Loopback destination addresses are instead translated to the observed
796 external address of the guest or target namespace. For IPv6 packets, if
797 usage of a link-local address by guest or namespace has ever been ob‐
798 served, and the original destination address is also a link-local ad‐
799 dress, the observed link-local address is used. Otherwise, the observed
800 global address is used. For both IPv4 and IPv6, if no addresses have
801 been seen yet, the configured addresses will be used instead.
802 For example, if passt or pasta receive a connection from 127.0.0.1,
804 with destination 127.0.0.10, and the default IPv4 gateway is 192.0.2.1,
805 while the last observed source address from guest or namespace is
806 192.0.2.2, this will be translated to a connection from 192.0.2.1 to
807 192.0.2.2.
808 Similarly, for traffic coming from guest or namespace, packets with
810 destination address corresponding to the default gateway will have
811 their destination address translated to a loopback address, if and only
812 if a packet, in the opposite direction, with a loopback destination or
813 source address, port-wise matching for UDP, or connection-wise for TCP,
814 has been recently forwarded to guest or namespace. This behaviour can
815 be disabled with --no-map-gw.
816 Handling of local traffic in pasta
819 Depending on the configuration, pasta can bind to local ports in the
820 init namespace, in the target namespace, or both, and forward connec‐
821 tions and packets to corresponding ports in the other namespace.
822 To avoid unnecessary overhead, these connections and packets are not
824 forwarded through the tap device connecting the namespaces: pasta cre‐
825 ates a socket in the destination namespace, with matching Layer-4 pro‐
826 tocol, and uses it to forward local data. For TCP, data is forwarded
827 between the originating socket and the new socket using the splice(2)
828 system call, and for UDP, a pair of recvmmsg(2) and sendmmsg(2) system
829 calls deals with packet transfers.
830 This bypass only applies to local connections and traffic, because it's
832 not possible to bind sockets to foreign addresses.
833 Binding to low numbered ports (well-known or system ports, up to 1023)
836 If the port forwarding configuration requires binding to ports with
837 numbers lower than 1024, passt and pasta will try to bind to them, but
838 will fail, unless, either:
839 • the sys.net.ipv4.ip_unprivileged_port_start sysctl is set to the num‐
842 ber of the lowest port passt and pasta need. For example, as root:
843 sysctl -w net.ipv4.ip_unprivileged_port_start=443
845 Note: this is the recommended way of enabling passt and pasta to bind
847 to ports with numbers below 1024.
848 • or the CAP_NET_BIND_SERVICE Linux capability is granted, see ser‐
851 vices(5) and capabilities(7).
852 This is, in general, not the recommended way, because passt and pasta
854 might be used as vector to effectively use this capability from an‐
855 other process.
856 However, if your environment is sufficiently controlled by an LSM
858 (Linux Security Module) such as AppArmor, SELinux, Smack or TOMOYO,
859 and no other processes can interact in such a way in virtue of this,
860 granting this capability to passt and pasta only can effectively pre‐
861 vent other processes from utilising it.
862 Note that this will not work for automatic detection and forwarding
864 of ports with pasta, because pasta will relinquish this capability at
865 runtime.
866 To grant this capability, you can issue, as root:
868 for p in $(which passt passt.avx2); do
870 setcap 'cap_net_bind_service=+ep' "${p}"
871 done
872 ICMP/ICMPv6 Echo sockets
876 ICMP and ICMPv6 Echo requests coming from guest or target namespace are
877 handled using so-called "ping" sockets, introduced in Linux 2.6.30. To
878 preserve the original identifier (see RFC 792, page 14, for ICMP, and
879 RFC 4443, section 4.1, for ICMPv6), passt and pasta try to bind these
880 sockets using the observed source identifier as "port" -- that corre‐
881 sponds to Echo identifiers for "ping" sockets.
882 As bind(2) failures were seen with particularly restrictive SELinux
884 policies, a fall-back mechanism maps different identifiers to different
885 sockets, and identifiers in replies will be mapped back to the original
886 identifier of the request. However, if bind(2) fails and the fall-back
887 mechanism is used, echo requests will be forwarded with different, al‐
888 beit unique, identifiers.
889 For ICMP and ICMPv6 Echo requests to work, the ping_group_range parame‐
891 ter needs to include the PID of passt or pasta, see icmp(7).
892 pasta and loopback interface
895 As pasta connects to an existing namespace, or once it creates a new
896 namespace, it will also ensure that the loopback interface, lo, is
897 brought up. This is needed to bind ports using the loopback address in
898 the namespace.
899 TCP sending window and TCP_INFO before Linux 5.3
902 To synchronise the TCP sending window from host Layer-4 sockets to the
903 TCP parameters announced in TCP segments sent over the Layer-2 inter‐
904 face, passt and pasta routinely query the size of the sending window
905 seen by the kernel on the corresponding socket using the TCP_INFO
906 socket option, see tcp(7). Before Linux 5.3, i.e. before Linux kernel
907 commit 8f7baad7f035 ("tcp: Add snd_wnd to TCP_INFO"), the sending win‐
908 dow (snd_wnd field) is not available.
909 If the sending window cannot be queried, it will always be announced as
911 the current sending buffer size to guest or target namespace. This
912 might affect throughput of TCP connections.
913
916 Currently, IGMP/MLD proxying (RFC 4605) and support for SCTP (RFC 4960)
917 are not implemented.
918 TCP Selective Acknowledgment (RFC 2018), as well as Protection Against
920 Wrapped Sequences (PAWS) and Round-Trip Time Measurement (RTTM), both
921 described by RFC 7232, are currently not implemented.
922
925 Stefano Brivio <sbrivio@redhat.com>, David Gibson <david@gibson.drop‐
926 bear.id.au>.
927
930 Please report issues on the bug tracker at
931 https://passt.top/passt/bugs, or send a message to the passt-
932 user@passt.top mailing list, see https://passt.top/passt/lists.
933
936 Copyright (c) 2020-2022 Red Hat GmbH.
937 passt and pasta are free software: you can redistribute them and/or
939 modify them under the terms of the GNU Affero General Public License as
940 published by the Free Software Foundation, either version 3 of the Li‐
941 cense, or (at your option) any later version.
942
945 namespaces(7), qemu(1), qrap(1), slirp4netns(1).
946 High-level documentation is available at
948 https://passt.top/passt/about/.
949 passt(1)