OS Manuals

/usr/bin/passt

Plug A Simple Socket Transport

From passt 2026.10.02-r2 (enterprise-packages), captured 2026-11-08 by running passt --help (exit 0). permalink

Usage: /usr/bin/passt [OPTION]...

  -d, --debug		Be verbose
      --trace		Be extra verbose, implies --debug
  --stats DELAY  	Display events statistics
    minimum DELAY seconds between updates
  -q, --quiet		Don't print informational messages
  -f, --foreground	Don't run in background
    default: run in background
  -l, --log-file PATH	Log (only) to given file
  --log-size BYTES	Maximum size of log file
    default: 1 MiB
  --runas UID|UID:GID 	Run as given UID, GID, which can be
    numeric, or login and group names
    default: drop to user "nobody"
  -c, --conf-path PATH	Configuration socket path
  -h, --help		Display this help message and exit
  --version		Show version and exit
  -s, --socket, --socket-path PATH	UNIX domain socket path
    default: probe free path starting from /tmp/passt_1.socket
  --vhost-user		Enable vhost-user mode
    UNIX domain socket is provided by -s option
  --print-capabilities	print back-end capabilities in JSON format,
    only meaningful for vhost-user mode
  --repair-path PATH	path for passt-repair(1)
    default: append '.repair' to UNIX domain path
  --migrate-exit	DEPRECATED:
			source quits after migration
    default: source keeps running after migration
  --migrate-no-linger	DEPRECATED:
			close sockets on migration
    default: keep sockets open, ignore events
  -F, --fd FD		Use FD as pre-opened connected socket
  -p, --pcap FILE	Log tap-facing traffic to pcap file
  -P, --pid FILE	Write own PID to the given file
  -m, --mtu MTU	Assign MTU via DHCP/NDP
    a zero value disables assignment
    default: 65520: maximum 802.3 MTU minus 802.3 header
                    length, rounded to 32 bits (IPv4 words)
  -a, --address ADDR	Assign IPv4 or IPv6 address ADDR[/PREFIXLEN]
    can be specified zero to two times (for IPv4 and IPv6)
    default: use addresses from interface with default route
  -n, --netmask MASK	Assign IPv4 MASK, dot-decimal or bits
    default: netmask from matching address on the host
  -M, --mac-addr ADDR	Use source MAC address ADDR
    default: 9a:55:9a:55:9a:55 (locally administered)
  -g, --gateway ADDR	Pass IPv4 or IPv6 address as gateway
    default: gateway from interface with default route
  -i, --interface NAME	Interface for addresses and routes
    default: from --outbound-if4 and --outbound-if6, if any
             otherwise interface with first default route
  -o, --outbound ADDR	Bind to address as outbound source
    can be specified zero to two times (for IPv4 and IPv6)
    default: use source address from routing tables
  --outbound-if4 NAME	Bind to outbound interface for IPv4
    default: use interface from default route
  --outbound-if6 NAME	Bind to outbound interface for IPv6
    default: use interface from default route
  -D, --dns ADDR	Use IPv4 or IPv6 address as DNS
    can be specified multiple times
    a single, empty option disables DNS information
    default: use addresses from /etc/resolv.conf
  -S, --search LIST	Space-separated list, search domains
    a single, empty option disables the DNS search list
  -H, --hostname NAME 	Hostname to configure client with
  --fqdn NAME		FQDN to configure client with
    default: use search list from /etc/resolv.conf
  --no-dhcp-dns	No DNS list in DHCP/DHCPv6/NDP
  --no-dhcp-search	No list in DHCP/DHCPv6/NDP
  --map-host-loopback ADDR	Translate ADDR to refer to host
    can be specified zero to two times (for IPv4 and IPv6)
    default: gateway address
  --map-guest-addr ADDR	Translate ADDR to guest's address
    can be specified zero to two times (for IPv4 and IPv6)
    default: none
  --dns-forward ADDR	Forward DNS queries sent to ADDR
    can be specified zero to two times (for IPv4 and IPv6)
    default: don't forward DNS queries
  --dns-host ADDR	Host nameserver to direct queries to
    can be specified zero to two times (for IPv4 and IPv6)
    default: first nameserver from host's /etc/resolv.conf
  --no-tcp		Disable TCP protocol handler
  --no-udp		Disable UDP protocol handler
  --no-icmp		Disable ICMP/ICMPv6 protocol handler
  --no-dhcp		Disable DHCP server
  --no-ndp		Disable NDP responses
  --no-dhcpv6		Disable DHCPv6 server
  --no-ra		Disable router advertisements
  --freebind		Bind to any address for forwarding
  --no-map-gw		Don't map gateway address to host
  --chroot-fallback	Use chroot() if pivot_root() fails
  -4, --ipv4-only	Enable IPv4 operation only
  -6, --ipv6-only	Enable IPv6 operation only
  -t, --tcp-ports SPEC	TCP port forwarding to guest
    can be specified multiple times
    SPEC can be:
      'none': don't forward any ports
      [ADDR[%IFACE]/]PORTS: forward specific ports
        PORTS is a comma-separated list of ports or port
         ranges.  'all' indicates all unbound non-ephemeral
         ports.  Ranges can be reduced by excluding ports or
         ranges prefixed by '~'.
        Examples:
        -t all		Forward all ports
        -t ::1/all	Forward all ports from local address ::1
        -t 22		Forward local port 22 to 22 on guest
        -t 22:23	Forward local port 22 to 23 on guest
        -t 22,25	Forward ports 22, 25 to ports 22, 25
        -t 22-80  	Forward ports 22 to 80
        -t 22-80:32-90	Forward ports 22 to 80 to
			corresponding port numbers plus 10
        -t 192.0.2.1/5	Bind port 5 of 192.0.2.1 to guest
        -t 5-25,~10-20	Forward ports 5 to 9, and 21 to 25
        -t ~25		Forward all ports except for 25
    default: none
  -u, --udp-ports SPEC	UDP port forwarding to guest
    SPEC is as described for TCP above
    default: none
  -1, --one-off	Quit after handling one single client
Options (72)
OptionDescriptionSource
-d, --debugBe verbose, don't log to the system logger.help + man
--traceBe extra verbose, show single packets.help + man
--stats DELAYDisplay events statistics with a minimum DELAY seconds between updates.help + man
-q, --quietDon't print informational messages.help + man
-f, --foregroundDon't run in background default: run in backgroundhelp + man
-l, --log-file PATHLog to file PATH, and not to the system logger.help + man
--log-size BYTESMaximum size of log file default: 1 MiBhelp + man
--runas UID|UID:GIDAttempt to change to given UID and corresponding group if UID is given, or to given UID and given GID if both are given.help + man
-c, --conf-path PATHPath for configuration and control socket used by pesto(1) to dynamically update passt or pasta's configuration.help + man
-h, --helpDisplay this help message and exithelp + man
--versionShow version and exit.help + man
-s, --socket, --socket-path PATHUNIX domain socket path default: probe free path starting from /tmp/passt_1.sockethelp + man
--vhost-userEnable vhost-user mode UNIX domain socket is provided by -s optionhelp + man
--print-capabilitiesPrint back-end capabilities in JSON format, only meaningful for vhost-user mode.help + man
--repair-path PATHPath for UNIX domain socket used by the passt-repair(1) helper to connect to passt in order to set or clear the TCP_REPAIR option on sockets, during migration.help + man
--migrate-exit (DEPRECATED)DEPRECATED: source quits after migration default: source keeps running after migrationhelp + man
--migrate-no-linger (DEPRECATED)DEPRECATED: close sockets on migration default: keep sockets open, ignore eventshelp + man
-F, --fd FDPass a pre-opened, connected socket to passt.help + man
-p, --pcap FILECapture tap-facing (that is, guest-side or namespace-side) network packets to file in pcap format.help + man
-P, --pid FILEWrite own PID to file once initialisation is done, before forking to background (if configured to do so).help + man
-m, --mtu MTUAssign MTU via DHCP/NDP a zero value disables assignment default: 65520: maximum 802.3 MTU minus 802.3 header length, rounded to 32 bits (IPv4 words)help + man
-a, --address ADDRAssign IPv4 or IPv6 address ADDR[/PREFIXLEN] can be specified zero to two times (for IPv4 and IPv6) default: use addresses from interface with default routehelp
-n, --netmask MASKAssign IPv4 netmask mask, expressed as dot-decimal or number of bits, via DHCP (option 1).help + man
-M, --mac-addr ADDRUse source MAC address addr when communicating to the guest or to the target namespace.help + man
-g, --gateway ADDRAssign IPv4 addr as default gateway via DHCP (option 3), or IPv6 addr as source for NDP Router Advertisement and DHCPv6 messages.help + man
-i, --interface NAMEInterface for addresses and routes default: from --outbound-if4 and --outbound-if6, if any otherwise interface with first default routehelp + man
-o, --outbound ADDRUse 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.help + man
--outbound-if4 NAMEBind 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.help + man
--outbound-if6 NAMEBind 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.help + man
-D, --dns ADDRInstruct the guest (via DHCP, DHVPv6 or NDP) to use addr (IPv4 or IPv6) as a nameserver, as configured (see options --no-dhcp-dns, --dhcp-dns) instead of reading addresses from /etc/resolv.conf.help + man
-S, --search LISTUse space-separated list for DHCP, DHCPv6, and NDP purposes, instead of reading entries from /etc/resolv.conf.help + man
-H, --hostname NAMEHostname to configure the client with.help + man
--fqdn NAMEFQDN to configure client with default: use search list from /etc/resolv.confhelp + man
--no-dhcp-dnsIn 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.help + man
--no-dhcp-searchIn 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).help + man
--map-host-loopback ADDRTranslate ADDR to refer to host can be specified zero to two times (for IPv4 and IPv6) default: gateway addresshelp + man
--map-guest-addr ADDRTranslate ADDR to guest's address can be specified zero to two times (for IPv4 and IPv6) default: nonehelp + man
--dns-forward ADDRMap addr (IPv4 or IPv6) as seen from guest or namespace to the nameserver (with corresponding IP version) specified by the --dns-host option.help + man
--dns-host ADDRHost nameserver to direct queries to can be specified zero to two times (for IPv4 and IPv6) default: first nameserver from host's /etc/resolv.confhelp + man
--no-tcpDisable the TCP protocol handler.help + man
--no-udpDisable the UDP protocol handler.help + man
--no-icmpDisable the ICMP/ICMPv6 protocol handler.help + man
--no-dhcpDisable the DHCP server.help + man
--no-ndpDisable Neighbor Discovery.help + man
--no-dhcpv6Disable the DHCPv6 server.help + man
--no-raDisable Router Advertisements.help + man
--freebindAllow any binding address to be specified for -t and -u options.help + man
--no-map-gwDon't remap TCP connections and untracked UDP traffic, with the gateway address as destination, to the host.help + man
--chroot-fallbackEnable fallback to chroot() in case pivot_root(), used to switch to an empty filesystem for stricter isolation, returns an error.help + man
-4, --ipv4-onlyEnable IPv4-only operation.help + man
-6, --ipv6-onlyEnable IPv6-only operation.help + man
-t, --tcp-ports SPECTCP port forwarding to guest can be specified multiple times SPEC can be: 'none': don't forward any ports [ADDR[%IFACE]/]PORTS: forward specific ports PORTS is a comma-separated list of ports or port…help + man
-u, --udp-ports SPECUDP port forwarding to guest SPEC is as described for TCP above default: nonehelp + man
-1, --one-offQuit after handling a single client connection, that is, once the client closes the socket, or once we get a socket error.help + man
-e, --stderr (DEPRECATED)This option has no effect, and is maintained for compatibility purposes only. (in the manual page but not in --help)man
--dhcp-dnsIn 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. (in the manual page but not in --help)man
--dhcp-searchIn pasta mode, send the DNS domain search list addresses via DHCP (option 119), via NDP Router Advertisement (option type 31) and DHCPv6 (option 24). (in the manual page but not in --help)man
-I, --ns-ifname nameName of tap interface to be created in target namespace. (in the manual page but not in --help)man
-T, --tcp-ns specConfigure TCP port forwarding from target namespace to init namespace. (in the manual page but not in --help)man
-U, --udp-ns specConfigure UDP port forwarding from target namespace to init namespace. (in the manual page but not in --help)man
--host-lo-to-ns-loIf specified, connections to a host loopback address forwarded with -t or -u will be delivered to the same loopback address in the namespace. (in the manual page but not in --help)man
--userns specTarget user namespace to join, as a path. (in the manual page but not in --help)man
--netns specTarget network namespace to join, as a path or a name. (in the manual page but not in --help)man
--netns-onlyJoin only a target network namespace, not a user namespace, and don't create one for sandboxing purposes either. (in the manual page but not in --help)man
--no-netns-quitDo not exit once the target namespace reference is removed. (in the manual page but not in --help)man
--no-pidnsDon't create a new PID namespace for the spawned command or shell: keep it in the PID namespace pasta itself runs in, and don't mount a new procfs instance on /proc for it. (in the manual page but not in --help)man
--config-netConfigure networking in the namespace: set up addresses and routes as configured or sourced from the host, and bring up the tap interface. (in the manual page but not in --help)man
--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. (in the manual page but not in --help)man
--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. (in the manual page but not in --help)man
--ns-mac-addr addrConfigure MAC address addr on the tap interface in the namespace. (in the manual page but not in --help)man
--no-spliceDisable the bypass path for inbound, local traffic. (in the manual page but not in --help)man
--splice-onlyDo not create a tap device in the namespace. (in the manual page but not in --help)man
Examples (10) from the manual page, untested

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.