diff --git a/config-linux.md b/config-linux.md index 7d47da748..8f7963e8d 100644 --- a/config-linux.md +++ b/config-linux.md @@ -197,14 +197,22 @@ Network devices have their own network namespace and a set of operations distinc 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. +Only one IP address is allowed for initial network device setup. This restriction is intended to reduce complexity during the container creation and to mitigate the risk during container start of IP address duplication. Adding additional IP addresses to the interface can be handled through post-configuration or by the container application itself. + **`netDevices`** (object, OPTIONAL) set of network devices that MUST be available in the container. The runtime is responsible for providing these devices; the underlying mechanism is implementation-defined. +Only privileged containers with a dedicated network namespace can have network devices directly assigned to them. This is required because moving network devices requires CAP_NET_ADMIN capabilities, not present on rootless containers, and to ensure security and avoid conflicts manipulate interfaces in the runtime network namespace. +The runtime MUST check that is possible to move the network interface to the container namespace and MUST [generate an error](runtime.md#errors) if the check fails. + +Notice that after deleting a network namespace, all its migratable network devices are moved to the default network namespace, unmoveable devices (NETIF_F_NETNS_LOCAL) and virtual devices (veth, macvlan, ...) are destroyed. +The runtime MAY decide to move back or destroy the network device before the network namespace is deleted. If the network device is moved back, the runtime MUST set its state to "down" to ensure that the interface is no longer active and won't interfere with other network operations or cause IP address conflicts. + 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. All IPv4 addresses must be expressed in their decimal format, consisting of four decimal numbers separated by periods. Each number ranges from 0 to 255 and represents an octet of the address. IPv6 addresses must be represented in their canonical form as defined in RFC 5952. -* **`mask`** *(string, OPTIONAL)* - the network mask for the IP address. +* **`name`** *(string, OPTIONAL)* - the name of the network device inside the container namespace. If not specified, the host name is used. The network device name is unique per network namespace, if an existing network with the same name exist that rename operation will fail. The runtime MAY check that the name is unique before the rename operation. +* **`address`** *(string, OPTIONAL)* - the IP address of the device within the container in CIDR format (IP address / Prefix). All IPv4 addresses must be expressed in their decimal format, consisting of four decimal numbers separated by periods. Each number ranges from 0 to 255 and represents an octet of the address. IPv6 addresses must be represented in their canonical form as defined in RFC 5952. +* **`hardwareAddress`** *(string, OPTIONAL)* - represents the hardware address (e.g. MAC Address) of the device's network interface. * **`mtu`** *(uint32, OPTIONAL)* - the MTU (Maximum Transmission Unit) size for the device. ### Example @@ -212,30 +220,39 @@ Entry values are objects with the following properties: #### Moving a device with a renamed interface inside the container: ```json - -"netDevices": [ - { +"netDevices": { "eth0" : { - "name": "container_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: +IPv4 address + ```json -"netDevices": [ - { +"netDevices": { "ens4": { - "address": "10.0.0.10", - "mask": "255.255.255.0", - "mtu": 9000 + "address": "10.0.0.10/24", + "hardwareAddress": "32:ba:1c:b1:eb:63", + "mtu": 9000 } - } -] +} +``` + +IPv6 address + +```json +"netDevices": { + "ens4": { + "address": "2001:db8:1:2::a/64", + "hardwareAddress": "32:ba:1c:b1:eb:63", + "mtu": 9000 + } +} ``` ## Control groups diff --git a/schema/config-linux.json b/schema/config-linux.json index af2884c21..add4cf0e4 100644 --- a/schema/config-linux.json +++ b/schema/config-linux.json @@ -300,4 +300,4 @@ } } } -} \ No newline at end of file +} diff --git a/schema/defs-linux.json b/schema/defs-linux.json index e31275e23..2602f9a01 100644 --- a/schema/defs-linux.json +++ b/schema/defs-linux.json @@ -194,7 +194,7 @@ "address": { "type": "string" }, - "mask": { + "hardwareAddress": { "type": "string" }, "mtu": { @@ -366,4 +366,4 @@ ] } } -} \ No newline at end of file +} diff --git a/schema/test/config/bad/linux-netdevice.json b/schema/test/config/bad/linux-netdevice.json index 336554ba9..9a6ebfe04 100644 --- a/schema/test/config/bad/linux-netdevice.json +++ b/schema/test/config/bad/linux-netdevice.json @@ -11,4 +11,4 @@ } } } -} \ No newline at end of file +} diff --git a/schema/test/config/good/linux-netdevice.json b/schema/test/config/good/linux-netdevice.json index 56f2901df..3e0384986 100644 --- a/schema/test/config/good/linux-netdevice.json +++ b/schema/test/config/good/linux-netdevice.json @@ -9,10 +9,14 @@ "name": "container_eth0" }, "ens4": { - "address": "10.0.0.10", - "mask": "255.255.255.0", + "address": "10.0.0.10/24", + "hardwareAddress": "32:ba:1c:b1:eb:63", "mtu": 9000 + }, + "ens5": { + "address": "2001:db8:1:2::4/64", + "mtu": 1500 } } } -} \ No newline at end of file +} diff --git a/specs-go/config.go b/specs-go/config.go index 3d55fd24b..2d0dd21fc 100644 --- a/specs-go/config.go +++ b/specs-go/config.go @@ -497,10 +497,10 @@ type LinuxDevice struct { 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 is the IP address in CIDR format in the container namespace Address string `json:"address,omitempty"` - // Mask is the network mask in the container namespace - Mask string `json:"mask,omitempty"` + // HardwareAddress represents the hardware address (e.g. MAC Address) of the device's network interface + HardwareAddress string `json:"hardwareAddress,omitempty"` // MTU Maximum Transfer Unit of the network device in the container namespace MTU uint32 `json:"mtu,omitempty"` }