Define Linux Network Devices

The proposed "netdevices" field provides a declarative way to specify which host network devices should be moved into a container's network namespace. This approach is similar than the existing "devices" field used for block devices but uses a dictionary keyed by the interface name instead. The proposed scheme is based on the existing representation of network device by the `struct net_device` https://docs.kernel.org/networking/netdevices.html. This proposal focuses solely on moving existing network devices into the container namespace. It does not cover the complexities of network configuration or network interface creation, emphasizing the separation of device management and network configuration. Signed-off-by: Antonio Ojea <[email protected]>
opencontainers · Nov 7, 2024 · d63b59f · d63b59f
1 parent 9505701
commit d63b59f
Show file tree

Hide file tree

Showing 6 changed files with 122 additions and 2 deletions.
diff --git a/config-linux.md b/config-linux.md
@@ -189,6 +189,55 @@ In addition to any devices configured with this setting, the runtime MUST also s
 * [`/dev/ptmx`][pts.4].
   A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
 
+## <a name="configLinuxNetworkDevices" />Network Devices
+
+Linux network devices are entities that send and receive data packets.
+They are not represented as files in the /dev directory, unlike block devices, network devices are represented with the [`net_device`][net_device] data structure in the Linux kernel.
+Network devices have their own network namespace and a set of operations distinct from regular file operations. Examples of network devices include Ethernet cards, loopback devices, and virtual devices like bridges, VLANs, and MACVLANs.
+
+This schema focuses solely on moving existing network devices identified by name into the container namespace. It does not cover the complexities of network device creation or network configuration, such as IP address assignment, routing, and DNS setup.
+
+**`netdevices`** (object, OPTIONAL) set of network devices that MUST be available in the container. The runtime MAY supply them however it likes.
+
+The name of the network device is the entry key.
+Entry values are objects with the following properties:
+
+* **`name`** *(string, OPTIONAL)* - the name of the network device inside the container namespace. If not specified, the host name is used.
+* **`address`** *(string, OPTIONAL)* - the IP address of the device within the container.
+* **`mask`** *(string, OPTIONAL)* - the network mask for the IP address.
+* **`mtu`** *(uint32, OPTIONAL)* - the MTU (Maximum Transmission Unit) size for the device.
+
+### Example
+
+#### Moving a device with a renamed interface inside the container:
+
+```json
+
+"netdevices": [
+  {
+    "eth0" : {
+      "name": "container_eth0"
+    }
+  }
+]
+```
+
+This configuration will move the device named "eth0" from the host into the container's network namespace. Inside the container, the device will be named "container_eth0".
+
+#### Moving a device with a specific IP address and MTU inside the container:
+
+```json
+"netdevices": [
+  {
+    "ens4": {
+      "address": "10.0.0.10",
+      "mask": "255.255.255.0",
+      "mtu": 9000
+    }
+  }
+]
+```
+
 ## <a name="configLinuxControlGroups" />Control groups
 
 Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
@@ -960,6 +1009,7 @@ subset of the available options.
 [devices]: https://www.kernel.org/doc/Documentation/admin-guide/devices.txt
 [devpts]: https://www.kernel.org/doc/Documentation/filesystems/devpts.txt
 [file]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_164
+[ifreq]: https://man7.org/linux/man-pages/man7/netdevice.7.html
 [libseccomp]: https://github.com/seccomp/libseccomp
 [proc]: https://www.kernel.org/doc/Documentation/filesystems/proc.txt
 [seccomp]: https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt
@@ -971,6 +1021,7 @@ subset of the available options.
 [mknod.1]: https://man7.org/linux/man-pages/man1/mknod.1.html
 [mknod.2]: https://man7.org/linux/man-pages/man2/mknod.2.html
 [namespaces.7_2]: https://man7.org/linux/man-pages/man7/namespaces.7.html
+[net_device]: https://docs.kernel.org/networking/netdevices.html
 [null.4]: https://man7.org/linux/man-pages/man4/null.4.html
 [personality.2]: https://man7.org/linux/man-pages/man2/personality.2.html
 [pts.4]: https://man7.org/linux/man-pages/man4/pts.4.html

diff --git a/schema/config-linux.json b/schema/config-linux.json
@@ -9,6 +9,12 @@
                     "$ref": "defs-linux.json#/definitions/Device"
                 }
             },
+            "netdevices": {
+                "type": "object",
+                "additionalProperties": {
+                    "$ref": "defs-linux.json#/definitions/NetDevice"
+                }
+            },
             "uidMappings": {
                 "type": "array",
                 "items": {
@@ -294,4 +300,4 @@
             }
         }
     }
-}
+}
diff --git a/schema/defs-linux.json b/schema/defs-linux.json
@@ -185,6 +185,23 @@
                 }
             }
         },
+        "NetDevice": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string"
+                },
+                "address": {
+                    "type": "string"
+                },
+                "mask": {
+                    "type": "string"
+                },
+                "mtu": {
+                    "$ref": "defs.json#/definitions/uint32"
+                }
+            }
+        },
         "weight": {
             "$ref": "defs.json#/definitions/uint16"
         },
@@ -349,4 +366,4 @@
             ]
         }
     }
-}
+}
diff --git a/schema/test/config/bad/linux-netdevice.json b/schema/test/config/bad/linux-netdevice.json
@@ -0,0 +1,14 @@
+{
+    "ociVersion": "1.0.0",
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "netdevices": {
+            "eth0": {
+                "name": "container_eth0",
+                "mtu": "not_an_int"
+            }
+        }
+    }
+}
diff --git a/schema/test/config/good/linux-netdevice.json b/schema/test/config/good/linux-netdevice.json
@@ -0,0 +1,18 @@
+{
+    "ociVersion": "1.0.0",
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "netdevices": {
+            "eth0": {
+                "name": "container_eth0"
+            },
+            "ens4": {
+                "address": "10.0.0.10",
+                "mask": "255.255.255.0",
+                "mtu": 9000
+            }
+        }
+    }
+}
diff --git a/specs-go/config.go b/specs-go/config.go
@@ -236,6 +236,8 @@ type Linux struct {
 	Namespaces []LinuxNamespace `json:"namespaces,omitempty"`
 	// Devices are a list of device nodes that are created for the container
 	Devices []LinuxDevice `json:"devices,omitempty"`
+	// NetDevices are key-value pairs, keyed by network device name, moved to the container's network namespace.
+	NetDevices map[string]LinuxNetDevice `json:"netdevices,omitempty"`
 	// Seccomp specifies the seccomp security settings for the container.
 	Seccomp *LinuxSeccomp `json:"seccomp,omitempty"`
 	// RootfsPropagation is the rootfs mount propagation mode for the container.
@@ -491,6 +493,18 @@ type LinuxDevice struct {
 	GID *uint32 `json:"gid,omitempty"`
 }
 
+// LinuxNetDevice represents a single network device to be added to the container's network namespace
+type LinuxNetDevice struct {
+	// Name of the device in the container namespace
+	Name string `json:"name,omitempty"`
+	// Address is the IP address in the container namespace
+	Address string `json:"address,omitempty"`
+	// Mask is the network mask in the container namespace
+	Mask string `json:"mask,omitempty"`
+	// MTU Maximum Transfer Unit of the network device in the container namespace
+	MTU uint32 `json:"mtu,omitempty"`
+}
+
 // LinuxDeviceCgroup represents a device rule for the devices specified to
 // the device controller
 type LinuxDeviceCgroup struct {