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 <avagin@google.com>

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)