ip-tuntap

Show all existing TUN/TAP devices

$ ip [[tunt|tuntap]]

$ sudo ip [[tunt|tuntap]] [[a|add]] [[d|dev]] [tun0] [[m|mode]] [[t|tun]]

$ sudo ip [[tunt|tuntap]] [[a|add]] [[d|dev]] [tap0] [[m|mode]] [[ta|tap]]

$ sudo ip [[tunt|tuntap]] [[d|delete]] [[d|dev]] [tun0|tap0] [[m|mode]] [tun|tap]

$ sudo ip [[tunt|tuntap]] [[a|add]] [[d|dev]] [tun0|tap0] [[m|mode]] [tun|tap] [[u|user]] [username]

$ sudo ip [[tunt|tuntap]] [[a|add]] [[d|dev]] [tun0|tap0] [[m|mode]] [tun|tap] [[u|user]] [username] [[g|group]] [group_name]

ip [ OPTIONS ] tuntap { COMMAND | help }

ip tuntap add [ dev NAME ] mode { tun | tap } [ user USER ] [ group GROUP ] [ persist ] [ pi { on | off } ]

ip tuntap del dev NAME [ mode { tun | tap } ]

ip tuntap show [ mode { tun | tap } ]

dev NAME
    Specifies the name of the TUN/TAP device to create, delete, or show. If creating and no name is provided, the kernel assigns a default (e.g., tun0, tap1).

mode { tun | tap }
    Defines the type of virtual network device. tun for Layer 3 (IP packets), or tap for Layer 2 (Ethernet frames). This option is mandatory for creation.

user USER
    Sets the owner (username or UID) of the device file (/dev/net/tun). This allows non-root processes to open and use the device.

group GROUP
    Sets the group owner (group name or GID) of the device file (/dev/net/tun). This allows processes in a specific group to open and use the device.

persist
    Makes the TUN/TAP device persistent. A persistent device is not destroyed when the last process closes it, remaining active until explicitly deleted. Requires user or group to be set.

pi { on | off }
    Controls the Packet Information (PI) header. When on (default), a 4-byte header (flags + protocol) is prepended to each packet read. When off, raw IP packets or Ethernet frames are read directly.

ip-tuntap is a sub-command of the ip utility, part of the iproute2 suite, used for managing virtual network devices known as TUN (Tunnel) and TAP (Terminal Access Point) interfaces. These virtual devices are crucial for various networking applications, including Virtual Private Networks (VPNs), virtualization environments, and network emulation.

A TUN device operates at Layer 3 (the network layer), encapsulating IP packets. When data is written to a TUN device, it's typically an IP packet that the kernel then routes. Conversely, when the kernel sends an IP packet to a TUN device, it can be read by a user-space program. This makes TUN devices ideal for point-to-point connections like those used by VPN clients.

A TAP device, on the other hand, operates at Layer 2 (the data link layer), encapsulating Ethernet frames. It behaves like a real Ethernet network adapter, allowing user-space programs to send and receive raw Ethernet frames. This functionality is essential for bridging, where a virtual machine might need to appear as a physical host on the network, or for creating virtual network segments.

The ip-tuntap command allows administrators to create, delete, and inspect these virtual interfaces, configure their ownership, and control persistence, providing a flexible and powerful tool for building complex network setups.

Using ip-tuntap generally requires root privileges or appropriate capabilities (e.g., CAP_NET_ADMIN). Ensure the 'tun' kernel module is loaded (e.g., via modprobe tun) before attempting to create TUN/TAP devices. If the module is not loaded, device creation will fail. Device names must be unique and adhere to standard network interface naming conventions.

TUN (Tunnel) devices operate at the network layer (Layer 3) and handle IP packets. They are typically used for point-to-point connections where an application wants to send or receive IP packets directly, such as in VPNs. The kernel treats data from a TUN device as regular IP traffic.

TAP (Terminal Access Point) devices operate at the data link layer (Layer 2) and handle Ethernet frames. They emulate an Ethernet adapter, allowing user-space applications to send and receive raw Ethernet frames. This makes them suitable for virtualization and bridging scenarios where a virtual machine or process needs to appear as a physical device on an Ethernet segment.

When creating a TUN/TAP device, by default, only root can interact with its associated character device file (/dev/net/tun). Using the user and group options allows specifying a non-root user or group that can open and operate the device. This is crucial for security and least-privilege principles, enabling applications like VPN clients to manage their own virtual interfaces without requiring global root access.

The TUN/TAP driver has been a fundamental part of the Linux kernel for many years, providing the core functionality for virtual network interfaces. Initially, tools like tunctl were used to manage these devices. However, with the development of the iproute2 suite, the management of TUN/TAP devices was integrated into the versatile ip command as the ip-tuntap sub-command. This integration streamlined network configuration, allowing administrators to manage most aspects of networking from a single, consistent command-line interface, aligning with the broader philosophy of iproute2 to replace older, less flexible tools like ifconfig and route.

ip(8), ip-link(8), tunctl(8), brctl(8), openvpn(8), qemu(1)