Mirrors/criu
1
0
Fork 0
mirror of https://github.com/checkpoint-restore/criu.git synced 2026-07-18 00:58:31 +00:00
Code Issues Projects Releases Wiki Activity

docs: update TUN/TAP documentation

Browse source 
- Detail the capture of device attributes (TUN vs TAP, Flags)
- Explain index preservation using TUNSETIFINDEX
- Document multi-queue support and re-attachment via TUNSETQUEUE
- Clarify current limitations (BPF filters, in-flight packets)
- Explain persistency management during restoration

Signed-off-by: Andrei Vagin <avagin@google.com>
This commit is contained in:
Andrei Vagin 2026-03-07 22:51:25 +00:00
parent f218dfbb22
commit 0a9a673a67
1 changed files with 29 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

35
Documentation/under-the-hood/tun-tap.md
View file

@ -1,9 +1,32 @@
# Tun-Tap
# TUN/TAP Interface Support
Tun-Tap devices, often used by software like OpenVPN, are supported by CRIU.
CRIU supports checkpointing and restoring Linux TUN/TAP virtual network interfaces. These devices are frequently used in VPN clients, virtualization platforms (like QEMU), and container networking.
## Devices
The network device entry is stored in the `netdev-ID.img` image file and includes an optional `tun` field.
## How CRIU Handles TUN/TAP
## Files
For every TUN device, there is a corresponding `reg-file` entry in the [images](images.md). Additionally, an entry is created in the `tunfile` image. CRIU performs device-to-file mapping based on the device name.
CRIU manages TUN/TAP as a combination of a **Network Interface** (the link visible to the kernel) and a **File Descriptor** (the handle used by the application to send and receive packets).
### 1. Checkpointing (Dumping)
During a dump, CRIU identifies TUN/TAP descriptors and collects their full kernel state:
* **Device Attributes**: The interface name, type (TUN for L3 or TAP for L2), and operational flags (e.g., `IFF_NO_PI`, `IFF_VNET_HDR`).
* **Persistency**: Whether the device is persistent (`IFF_PERSIST`), meaning it survives even when no process has it open.
* **Buffer Sizes**: Captures the send buffer size (`TUNGETSNDBUF`) and the virtual network header size (`TUNGETVNETHDRSZ`).
* **Multi-Queue State**: CRIU identifies if multiple file descriptors are attached to different queues of the same TUN/TAP device, allowing for parallel I/O.
* **Ownership**: Captures the UID and GID associated with the TUN/TAP device.
### 2. Restoration
To recreate the TUN/TAP environment exactly as it was, CRIU performs the following:
* **Interface Creation**: Recreates the virtual link or attaches to an existing persistent one using `TUNSETIFF`.
* **Index Preservation**: Uses the `TUNSETIFINDEX` ioctl to ensure the restored interface has the exact same numeric index as the original. This is critical for applications that have cached the interface index.
* **Queue Re-attachment**: For multi-queue devices, CRIU uses `TUNSETIFF` in combination with `TUNSETQUEUE` to correctly re-link each restored file descriptor to its original queue.
* **State Application**: Restores the original buffer sizes, ownership, and persistent status. If a device was not originally persistent, CRIU explicitly drops the persistency after the application has attached to it.
## Current Limitations
* **Packet Filters (BPF)**: Capturing a TAP interface with a complex BPF filter attached is currently **not supported**. The kernel does not provide a robust way to extract the filter program and re-attach it during restoration without the original application context.
* **In-flight Packets**: Data currently residing in the kernel's internal TUN/TAP queues (packets sent by the application but not yet processed by the virtual device, or vice versa) is not preserved across a checkpoint.
## See also
* [Network Sockets](sockets.md)
* [Checkpoint/Restore Architecture](checkpointrestore.md)
* [Kerndat Feature Detection](kerndat.md)