From 85e6c3306ddc2ff70107ba9046d5eac185fa21ab Mon Sep 17 00:00:00 2001 From: Andrei Vagin Date: Sat, 7 Mar 2026 22:37:54 +0000 Subject: [PATCH] docs: update Mac-VLAN documentation - Explain attribute extraction during checkpointing (Mode, Flags, Parent) - Detail index preservation using IFLA_NEW_IFINDEX - Document the --external macvlan[IFNAME]:OUTNAME option - Improve overall structure and clarity Signed-off-by: Andrei Vagin --- Documentation/under-the-hood/mac-vlan.md | 36 ++++++++++++++++-------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/Documentation/under-the-hood/mac-vlan.md b/Documentation/under-the-hood/mac-vlan.md index dfe5121c2..8bd59ea22 100644 --- a/Documentation/under-the-hood/mac-vlan.md +++ b/Documentation/under-the-hood/mac-vlan.md @@ -1,21 +1,35 @@ -# Mac-Vlan +# Mac-VLAN -CRIU supports checkpointing and restoring network namespaces that use `macvlan` devices. +Mac-VLAN is a Linux network driver that allows creating multiple virtual interfaces with unique MAC addresses on top of a single physical interface. These virtual interfaces act as standalone devices on the network, each with its own IP and MAC address. -## Dump +## Checkpoint and Restore of Mac-VLAN -During a dump, CRIU automatically detects these devices; no additional arguments are required. The name of the `macvlan` device within the checkpointed namespace is saved in the [images](images.md). +CRIU identifies Mac-VLAN interfaces by monitoring netlink messages (specifically `RTM_NEWLINK`) and inspecting their attributes. -## Restore +### 1. Checkpointing +During a dump, CRIU extracts the following attributes for each Mac-VLAN device: +- **Parent Interface**: The physical device (or "upper" link) that the Mac-VLAN is built upon (identified via `IFLA_LINK`). +- **Mode**: The specific Mac-VLAN operational mode (e.g., `bridge`, `private`, `vepa`, `passthru`), extracted from `IFLA_MACVLAN_MODE`. +- **Flags**: Any additional configuration flags associated with the interface (`IFLA_MACVLAN_FLAGS`). +- **MAC Address**: The unique hardware address of the virtual interface. -During restoration, users *must* specify the master device in the host network namespace using the following syntax: +### 2. Restoration +To recreate a Mac-VLAN interface exactly as it was, CRIU performs the following: +- **Link Creation**: It sends an `RTM_NEWLINK` netlink message with the kind set to `"macvlan"`, specifying the original mode and the link to the parent device. +- **Index Preservation**: To ensure that any application sockets bound to the interface index remain valid, CRIU uses the `IFLA_NEW_IFINDEX` attribute. This allows CRIU to request the exact same interface index that the device possessed before the checkpoint. (This kernel feature was originally developed specifically to support CRIU). +- **Namespace Migration**: Once created, the interface is moved into the target network namespace for the restored process. -`--external macvlan[*inner_dev*]:*outer_dev*` +## External Interface Mapping -Where `*inner_dev*` is the device name within the restored namespace, and `*outer_dev*` is the corresponding network device in CRIU's namespace. +Since the parent physical interface may have a different name or index on the destination host during migration, CRIU provides the `--external` option to map these dependencies: -## Implementation Details +```bash +# Example mapping of an internal macvlan interface to a host physical interface +criu restore --external macvlan[eth0]:phys0 ... +``` -Restoring `macvlan` interfaces is complex because the interface itself resides within the target network namespace, while its master device resides outside. CRIU uses `IFLA_NET_NS_ID` to specify the master link's namespace and `IFLA_NET_NS_FD` to specify the namespace where the slave link should be created. +This tells CRIU that the Mac-VLAN interface which was originally attached to `eth0` should now be attached to the physical interface `phys0` on the current host. -In cases involving user namespaces, the `netlink` call is made from `usernsd`, as the caller must have `CAP_NET_ADMIN` in both network namespaces. In non-usernamespace cases, CRIU uses `setns` to create a `netlink` socket within the target namespace and then uses that socket to create the `macvlan` link. +## See also +* [Checkpoint/Restore Architecture](checkpointrestore.md) +* [Networking](networking.md)