diff -pruN 1.2.1-1/.codespellrc 1.3.0-1/.codespellrc --- 1.2.1-1/.codespellrc 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/.codespellrc 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,3 @@ +[codespell] +# Those should always be in lowercase! +ignore-words-list = clos diff -pruN 1.2.1-1/.github/workflows/build.yml 1.3.0-1/.github/workflows/build.yml --- 1.2.1-1/.github/workflows/build.yml 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/.github/workflows/build.yml 2025-11-02 07:35:43.000000000 +0000 @@ -14,7 +14,12 @@ jobs: strategy: matrix: - go: [1.21.x, 1.22.x] + # our oldest (officially) supported version and the two upstream-supported versions + go: [1.21.x, oldstable, stable] + + env: + # avoid downloading any alternate toolchains (https://go.dev/doc/toolchain) + GOTOOLCHAIN: local steps: - name: checkout source code @@ -33,10 +38,9 @@ jobs: go get -d ./schema/... - name: run golangci-lint - uses: golangci/golangci-lint-action@v4 + uses: golangci/golangci-lint-action@v8 with: - version: v1.56.1 - args: --verbose + version: v2.5 - name: run tests run: | diff -pruN 1.2.1-1/.github/workflows/lint.yml 1.3.0-1/.github/workflows/lint.yml --- 1.2.1-1/.github/workflows/lint.yml 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/.github/workflows/lint.yml 2025-11-02 07:35:43.000000000 +0000 @@ -12,3 +12,12 @@ jobs: run: make -C schema fmt - name: Check for changes run: git diff --exit-code + + codespell: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 + - name: install deps + run: pip install --break-system-packages codespell==v2.4.1 + - name: run codespell + run: codespell diff -pruN 1.2.1-1/ChangeLog 1.3.0-1/ChangeLog --- 1.2.1-1/ChangeLog 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/ChangeLog 2025-11-02 07:35:43.000000000 +0000 @@ -1,5 +1,39 @@ OpenContainers Specifications +Changes with v1.3.0: + + Additions: + + * config-vm: add hwConfig object (#1209) + * config-linux: add intelRdt.schemata field (#1230) + * config-linux: add netDevices object (#1271) + * config-linux: add memoryPolicy object (#1282) + * config-freebsd: add the spec for FreeBSD (#1286) + * config-linux: add intelRdt.enableMonitoring field (#1287) + + Minor fixes: + + * config-linux: clarify intelRdt configuration (#1196) + * runtime: fail when a poststart hook fails (#1262) + * config-linux: clarify pids cgroup settings (#1279) + * config-linux: define default clos for intelRdt (#1289) + * features-linux: add intelRdt.enableMonitoring field (#1290) + * features-linux: add intelRdt.schemata field (#1291) + * config-linux: fix and elaborate memoryPolicy.nodes field (#1294) + * config-linux, schema: fix FileMode description (#1298) + + Documentation, CI & Governance: + + * add systemd-nspawn to implementations.md (#1272) + * CI: add codespell, bump golangci-lint (#1281) + * docs: add missing backticks for code formatting (#1284) + * docs: fix typo (#1285) + * principles: fix typo (#1288) + * schema: fix json (#1297) + * ci: use supported Go versions (#1300) + * Add minimum supported Go version to CI (#1303) + * Mention FreeBSD platform (#1304) + Changes with v1.2.1: Additions: @@ -230,7 +264,7 @@ Changes with v1.0.1: * config-linux: More specific documentation for weightDevice and throttle* (#825) * config-linux: Modify procfs to proc (#905) - * config-linux: Fix "psuedo" -> "pseudo" typo (#921) + * config-linux: Fix a typo (#921) * config-windows: Make maximum a uint16 (was a uint) (#891) * runtime: Change "process in the container" -> "container process" (#907) @@ -490,7 +524,7 @@ Changes with v1.0.0-rc3: * spec: Separate the spec from project scaffolding (#626) * README: Define "unspecified", "undefined", and "implementation-defined" (#575) - * config: Clarify absolue and relative values for root.path (#558) + * config: Clarify absolute and relative values for root.path (#558) * config: Clarify ociVersion covering the configuration <-> runtime API (#523) * config-linux: Forbid duplicated namespaces with same `type` @@ -551,7 +585,7 @@ Changes with v1.0.0-rc1: * runtime: Split create and start, #384, #450, #463, #464, #467, #468 * runtime: Remove exec, #388 - * runtime: Enviroment MUST match the configuration, #397 + * runtime: Environment MUST match the configuration, #397 * config: Runtime MUST generate errors for unsupported platforms, #441 * config: Windows mount destinations MUST NOT be nested, #437 @@ -567,7 +601,7 @@ Changes with v1.0.0-rc1: * config: Allow absolute paths for root.path (which previously required relative paths), #394 * config-linux: Add linux.mountLabel, #393 - * config-linux: Add suport for cgroup namespace, #397 + * config-linux: Add support for cgroup namespace, #397 * config-linux: Runtime SHOULD NOT modify ownership of any referenced filesystem (previously the restriction only applied to the root filesystem), #452 @@ -576,7 +610,7 @@ Changes with v1.0.0-rc1: Minor fixes and documentation: * README: Add project.md to the Table of Contents, #376 - * README: Consistenly indent the Table of Contents, #400 + * README: Consistently indent the Table of Contents, #400 * README: Link to LICENSE, #442 * README: Weekly call is OCI-wide, #378 * config: Explicit runtime namespace for hooks, #415 @@ -642,8 +676,7 @@ Changes with v0.5.0: * style: Move one-sentence-per-line rule from the README, #369 * style: Remove dangling parenthesis, #359 * README: Add a link to the IRC logs, #358 - * Fix "manadate", "exmaple", "paramters", and "preferrably" typos, - #353, #354 + * Fix typos, #353, #354 Changes with v0.4.0: Breaking changes: @@ -729,7 +762,7 @@ Changes with v0.2.0: * bundle.md: fix off-by-one error * bundle.md: various updates to latest spec * bundle: Move 'Linux sysctl' header to its own line - * Change commiter to committer + * Fix a typo * Change Device field order in spec_linux.go, 'Path' should be top of the 'Type' field, according to the different of the config-linux.md, 'Path' field is the unique key. * Change layout of mountpoints and mounts * Change the rlimit type to string instead of int @@ -854,7 +887,7 @@ Changes with v0.1.0: * implementations: Link to mrunalp/ocitools * lifecycle: Don't require /run/opencontainer//containers * lifecycle: Mention runtime.json - * lifecycle: no hypens + * lifecycle: no hyphens * MAINTAINERS: add tianon per the charter * MAINTAINERS: correct Vish's github account * Makefile: Add glossary to DOC_FILES diff -pruN 1.2.1-1/config-freebsd.md 1.3.0-1/config-freebsd.md --- 1.2.1-1/config-freebsd.md 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/config-freebsd.md 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,137 @@ +# FreeBSD Container Configuration + +This document describes the schema for the [FreeBSD-specific section](config.md#platform-specific-configuration) of the [container configuration](config.md). + +## Devices + +Devices in FreeBSD are accessed via the `devfs` filesystem. Each container SHOULD have a `devfs` filesystem mounted into its `/dev` directory. Often, a minimal set of devices is exposed to the container using ruleset 4 from `/etc/defaults/devfs.rules` - the ruleset is specified as a mount option. + +Optionally, additional devices can be exposed to the container using an array of entries inside the `devices` root field: + +* **`path`** _(string, REQUIRED)_ - the device path relative to `/dev` +* **`mode`** _(uint32, OPTIONAL)_ - file mode for the device. + +Note that JSON numbers must be represented in decimal. The value `448` below is the decimal representation of octal `0700` and this is used to request file mode `rwx------` for the device. + +### Example +```json +"devices": [ + { + "path": "pf", + "mode": 448 + } +] +``` + +## Jail + +On FreeBSD, containers are implemented using the platform's jail subsystem. +Each jail is configured using a set of name/value pairs passed to the kernel using the `jail(2)` system calls. +The `jail` root field contains values which are passed to the kernel when the container is created. + +* **`parent`** _(string, OPTIONAL)_ - parent jail. + If set, the value is the name of a jail which should be this container's parent, otherwise the container's parent is the host. This can be used to share namespaces such as `vnet` with another container. +* **`host`** _(string, OPTIONAL)_ - allow overriding hostname, domainname, hostuuid and hostid. + The value can be "new" which allows these values to be overridden in the container or "inherit" to use the host values (or parent container values). If set to "new", the values for hostname and domainname are taken from the base config, if present. +* **`ip4`** _(string, OPTIONAL)_ - control the availability of IPv4 addresses. + Set to "inherit" to allow access to host (or parent container) addresses or set to "disable" to stop use of IPv4 entirely. This is typically left unset when **`vnet`** is used (see below). +* **`ip4Addr`** _(array of strings, OPTIONAL)_ - restrict the set of IPv4 addresses which the container can use. These addresses should be in numeric form (e.g. `"10.11.12.13"`). This can be used to allow restricted use of the host network. A common pattern with FreeBSD jails is to add alias addresses to a loopback interface and restrict each jail to a subset of addresses. +* **`ip6`** _(string, OPTIONAL)_ - control the availability of IPv6 addresses. + Set to "inherit" to allow access to host (or parent container) addresses or set to "disable" to stop use of IPv6 entirely. This is typically left unset when **`vnet`** is used (see below). +* **`ip6Addr`** _(array of strings, OPTIONAL)_ - restrict the set of IPv6 addresses which the container can use. These addresses should be in numeric form (e.g. `"fd10::11:12:13"`). This can be used to allow restricted use of the host network. A common pattern with FreeBSD jails is to add alias addresses to a loopback interface and restrict each jail to a subset of addresses. +* **`vnet`** _(string, OPTIONAL)_ - control the vnet used for this container. + The value can be "new" which causes a new vnet to be created for the container or "inherit" which shares the vnet for the parent container (or host if there is no parent). +* **`interface`** _(string, OPTIONAL)_ A network interface to add the container's IP addresses (**`ip4Addr`** and **`ip6Addr`**) to. An alias for each address will be added to the interface when the container is created, and will be removed from the interface after the container is stopped. This is typically used when **`vnet`** is not set. +* **`vnetInterfaces`** _(array of strings, OPTIONAL)_ - a set of network interfaces which are added to the container's vnet during its lifetime. +* **`sysvmsg`** _(string, OPTIONAL)_ - allow access to SYSV IPC message primitives. + If set to "inherit", all IPC objects in the host (or parent container) are visible to this container, whether they were created by the container itself, the base system, or other containers. If set to "new", the container will have its own key namespace, and can only see the objects that it has created; the system (or parent container) has access to the container's objects, but not to its keys. If set to "disable", the container cannot perform any sysvmsg-related system calls. Defaults to "new". +* **`sysvsem`** _(string, OPTIONAL)_ - allow access to SYSV IPC semaphore primitives, in the same manner as sysvmsg. Defaults to "new". +* **`sysvshm`** _(string, OPTIONAL)_ - allow access to SYSV IPC shared memory primitives, in the same manner as sysvmsg. Defaults to "new". +* **`enforceStatfs`** _(integer, OPTIONAL)_ - control visibility of mounts in the container. + A value of 0 allows visibility of all host mounts, 1 allows visibility of mounts nested under the container's root and 2 only allows the container root to be visible. If unset, the default value is 2. +* **`allow`** _(object, OPTIONAL)_ - Some restrictions of the container environment may be set on a per-container basis. With the exception of **`setHostname`** and **`reservedPorts`**, these boolean parameters are off by default. + - **`setHostname`** _(bool, OPTIONAL)_ - Allow the container's hostname to be changed. Defaults to `false`. + - **`rawSockets`** _(bool, OPTIONAL)_ - Allow the container to use raw sockets to support network utilities such as ping and traceroute. Defaults to `false`. + - **`chflags`** _(bool, OPTIONAL)_ - Allow the system file flags to be changed. Defaults to `false`. + - **`mount`** _(array of strings, OPTIONAL)_ - Allow the listed filesystem types to be mounted and unmounted in the container. + - **`quotas`** _(bool, OPTIONAL)_ - Allow the filesystem quotas to be changed in the container. Defaults to `false`. + - **`socketAf`** _(bool, OPTIONAL)_ - Allow socket types other than IPv4, IPv6 and unix. Defaults to `false`. + - **`mlock`** _(bool, OPTIONAL)_ - Allow the container to use `mlock(2)` and `munlock(2)` system calls. Defaults to `false`. + - **`reservedPorts`** _(bool, OPTIONAL)_ - Allow the jail to bind to ports lower than 1024. Defaults to `false`. + - **`suser`** _(bool, OPTIONAL)_ - The value of the jail's security.bsd.suser_enabled sysctl. The super-user will be disabled automatically if its parent system has it disabled. The super-user is enabled by default. + +These fields SHOULD be mapped to a corresponding set of `jail(8)` parameters which can be used to create the container jail. +A typical jail-based OCI implementation on FreeBSD MAY use the following mapping: + +| Jail parameter | JSON equivalent | +| -------------- | -------------------- | +| `jid` | - | +| `name` | see below | +| `path` | `root.path` | +| `ip4.addr` | `freebsd.jail.ip4Addr` | +| `ip4.saddrsel` | - | +| `ip4` | `freebsd.jail.ip4` | +| `ip6.addr` | `freebsd.jail.ip6Addr` | +| `ip6.saddrsel` | - | +| `ip6` | `freebsd.jail.ip6` | +| `vnet` | `freebsd.jail.vnet` | +| `interface` | `freebsd.jail.interface` | +| `vnet.interface` | see below | +| `host.hostname` | `hostname` | +| `host` | `freebsd.jail.host` | +| `sysvmsg` | `freebsd.jail.sysvmsg` | +| `sysvsem` | `freebsd.jail.sysvsem` | +| `sysvshm` | `freebsd.jail.sysvshm` | +| `securelevel` | - | +| `devfs_ruleset` | see below | +| `children.max` | see below | +| `enforce_statfs` | `freebsd.jail.enforceStatfs` | +| `persist` | - | +| `parent` | `freebsd.jail.parent` | +| `osrelease` | - | +| `osreldate` | - | +| `allow.set_hostname` | `freebsd.jail.allow.setHostname` | +| `allow.sysvipc` | `freebsd.jail.allow.sysvipc` | +| `allow.raw_sockets` | `freebsd.jail.allow.rawSockets` | +| `allow.chflags` | `freebsd.jail.allow.chflags` | +| `allow.mount` | `freebsd.jail.allow.mount` | +| `allow.quotas` | `freebsd.jail.allow.quotas` | +| `allow.read_msgbuf` | - | +| `allow.socket_af` | `freebsd.jail.allow.socketAf` | +| `allow.mlock` | `freebsd.jail.allow.mlock` | +| `allow.nfsd` | - | +| `allow.reserved_ports` | `freebsd.jail.allow.reservedPorts` | +| `allow.unprivileged_proc_debug` | - | +| `allow.suser` | `freebsd.jail.allow.suser` | +| `allow.mount.*` | see below | + +The jail name SHOULD be set to the create command's `container-id` argument. + +The `vnet.interface` jail pseudo parameter is not handled in the kernel but rather is implemented in user space (e.g. in `jail(8)`). In traditional jail configs, this parameter can be repeated several times and each instance specifies a network interface which is moved into the jail's vnet during the lifetime of the jail using the `ifconfig(8)` utility on the host. For OCI containers, this is managed using the `freebsd.jail.vnetInterfaces` field which is an array of interface names. + +A container which needs its own network namespace SHOULD set `"vnet"` to `"new"` and leave `"ip4"` and `"ip6"` unchanged. +A container which shares the parent/host vnet SHOULD leave `"vnet"` unchanged and set `"ip4"` and `"ip6"` to `"inherit"`. + +The `devfs_ruleset` parameter is only required for jails which create new `devfs` mounts - typically OCI runtimes will mount `devfs` on the host. The value is a rule set number - these rule sets are defined on the host, typically via `/etc/defaults/devfs.rules` or using the `devfs` command line utility. + +The `children.max` parameter SHOULD be managed by the OCI runtime e.g. when a new container shares namespaces with an existing container. + +The `allow.mount.*` parameter set is extensible - allowed mount types are listed as an array. As with `devfs`, typically the OCI runtime will manage mounts for the container by performing mount operations on the host. + +Jail parameters not supported by this runtime extension are marked with "-". These parameters will have their default values - see the `jail(8)` man page for details. + +### Example +```json +"jail": { + "host": "new", + "vnet": "new", + "enforceStatfs": 1, + "allow": { + "rawSockets": true, + "chflags": true, + "mount": [ + "tmpfs" + ] + } +} +``` diff -pruN 1.2.1-1/config-linux.md 1.3.0-1/config-linux.md --- 1.2.1-1/config-linux.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/config-linux.md 2025-11-02 07:35:43.000000000 +0000 @@ -135,7 +135,7 @@ Each entry has the following structure: If a [file][] already exists at `path` that does not match the requested device, the runtime MUST generate an error. The path MAY be anywhere in the container filesystem, notably outside of `/dev`. * **`major, minor`** *(int64, REQUIRED unless `type` is `p`)* - [major, minor numbers][devices] for the device. -* **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device. +* **`fileMode`** *(uint32, OPTIONAL)* - file mode for the device. Note it is a decimal (not an octal) number. You can also control access to devices [with cgroups](#configLinuxDeviceAllowedlist). * **`uid`** *(uint32, OPTIONAL)* - id of device owner in the [container namespace](glossary.md#container-namespace). * **`gid`** *(uint32, OPTIONAL)* - id of device group in the [container namespace](glossary.md#container-namespace). @@ -189,6 +189,108 @@ In addition to any devices configured wi * [`/dev/ptmx`][pts.4]. A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts]. +## Network Devices + +Linux network devices are entities that send and receive data packets. They are +not represented as files in the `/dev` directory. Instead, they are represented +by the [`net_device`][net_device] data structure in the Linux kernel. Network +devices can belong to only one network namespace and use a set of operations +distinct from regular file operations. Network devices can be categorized as +**physical** or **virtual**: + +* **Physical network devices** correspond to hardware interfaces, such as + Ethernet cards (e.g., `eth0`, `enp0s3`). They are directly associated with + physical network hardware. +* **Virtual network devices** are software-defined interfaces, such as loopback + devices (`lo`), virtual Ethernet pairs (`veth`), bridges (`br0`), VLANs, and + MACVLANs. They are created and managed by the kernel and do not correspond + to physical hardware. + +This schema focuses solely on moving existing network devices identified by name +from the host network namespace into the container network 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) - A set of network devices that MUST be made +available in the container. The runtime is responsible for moving these devices; +the underlying mechanism is implementation-defined. + +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. + +The runtime MUST check if moving the network interface to the container +namespace is possible. If a network device with the specified name already +exists in the container namespace, the runtime MUST [generate an error](runtime.md#errors), +unless the user has provided a template by appending +`%d` to the new name. In that case, the runtime MUST allow the move, and the +kernel will generate a unique name for the interface within the container's +network namespace. + +The runtime MUST preserve existing network interface attributes, including all +permanent IP addresses (IFA_F_PERMANENT flag) of any family with global scope +(RT_SCOPE_UNIVERSE value) as defined in [`RFC 3549 Section 2.3.3.2`][rfc3549]. +This ensures that only addresses intended for persistent, external communication +are transferred. + +The runtime MUST set the network device state to "up" after moving it to the +network namespace to allow the container to send and receive network traffic +through that device. + +### Namespace Lifecycle and Container Termination + +The runtime MUST NOT actively manage the interface's lifecycle and configuration +*within* the container's network namespace. This is because network interfaces +are inherently tied to the network namespace itself, and their lifecycle is +therefore managed by the owner of the network namespace. Typically, this +ownership and management are handled by higher-level container runtime +orchestrators, rather than the processes running directly within the container. + +The runtime **MUST NOT** attempt to move the interface out of the namespace +before deletion. This design decision is based on the following: + +* **Namespace Ownership:** Network interfaces are tied to the network namespace, + which may not always be directly managed by the runtime. +* **Abrupt Termination:** Even when the runtime manages the namespace, it cannot + reliably participate in its deletion if the container's processes terminate + abruptly (e.g., due to a crash) or run until completion. + +During the network namespace deletion the kernel's built-in namespace cleanup +mechanisms take over, as described in [network_namespaces(7)][net_namespaces.7]: +"When a network namespace is freed (i.e., when the last process in the namespace +terminates), its physical network devices are moved back to the initial network +namespace." All the network namespace migratable physical network devices are +moved to the default network namespace, while virtual devices (veth, macvlan, +...) are destroyed. + +If users require custom handling of interface lifecycle during namespace +deletion, they can utilize existing features within the namespace orchestrator +or employ post-stop hooks. + +**Physical Interface Renaming and Systemd** + +When a physical interface is renamed within a container and the container's +network namespace is later deleted, the kernel will move the interface back to +the root namespace with its renamed name. In case of a name conflict in the root +namespace, the kernel will rename it to `dev%d`. To ensure predictable interface +names in the root namespace, users can utilize systemd's `udevd` and `networkd` +rules. Refer to [systemd Predictable Network Interface Names][predictable-network-interfaces-names] +for more information on configuring predictable names. + +### Example + +#### Moving a device with a renamed interface inside the container: + +```json +"netDevices": { + "eth0" : { + "name": "container_eth0" + } +} +``` + ## Control groups Also known as cgroups, they are used to restrict resource usage for a container and handle device access. @@ -564,7 +666,9 @@ For more information, see the kernel cgr The following parameters can be specified to set up the controller: -* **`limit`** *(int64, REQUIRED)* - specifies the maximum number of tasks in the cgroup +* **`limit`** *(int64, OPTIONAL)* - specifies the maximum number of tasks in the cgroup, with `-1` indicating no limit (`max`). + +> Note: Even though it may superficially seem redundant, `0` is a valid limit value for the `pids` cgroup controller from the kernel's perspective and SHOULD be treated as such by runtimes. #### Example @@ -640,52 +744,115 @@ If `intelRdt` is not set, the runtime MU The following parameters can be specified for the container: * **`closID`** *(string, OPTIONAL)* - specifies the identity for RDT Class of Service (CLOS). + As a special case, value `/` means that the container MUST be assigned to the default CLOS (the + root of the resctrl filesystem). * **`l3CacheSchema`** *(string, OPTIONAL)* - specifies the schema for L3 cache id and capacity bitmask (CBM). The value SHOULD start with `L3:` and SHOULD NOT contain newlines. * **`memBwSchema`** *(string, OPTIONAL)* - specifies the schema of memory bandwidth per L3 cache id. The value MUST start with `MB:` and MUST NOT contain newlines. +* **`schemata`** *(array of strings, OPTIONAL)* - specifies the schemata to be written to the `schemata` file in resctrlfs. Each element represents one line in the `schemata` file. The value MUST NOT contain newlines. +* **`enableMonitoring`** *(boolean, OPTIONAL)* - enables resctrl monitoring for the container. The following rules on parameters MUST be applied: -* If both `l3CacheSchema` and `memBwSchema` are set, runtimes MUST write the combined value to the `schemata` file in that sub-directory discussed in `closID`. - -* If `l3CacheSchema` contains a line beginning with `MB:`, the value written to `schemata` file MUST be the non-`MB:` line(s) from `l3CacheSchema` and the line from `memBWSchema`. +* If both `l3CacheSchema` and `memBwSchema` are set, runtimes MUST write the values to the `schemata` file in that sub-directory discussed in `closID`. The runtimes MUST write `l3CacheSchema` first and `memBwSchema` last. * If either `l3CacheSchema` or `memBwSchema` is set, runtimes MUST write the value to the `schemata` file in the that sub-directory discussed in `closID`. -* If neither `l3CacheSchema` nor `memBwSchema` is set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems. +* If `schemata` field is set, runtimes MUST write the value to the `schemata` file in the that sub-directory discussed in `closID`. If also `l3CacheSchema` or `memBwSchema` is set the value of `schemata` field must be written last, after the values from `l3CacheSchema` and `memBwSchema` has been written. + +* If none of `l3CacheSchema`, `memBwSchema` or `schemata` is set, runtimes MUST NOT write to `schemata` files in any `resctrl` pseudo-filesystems. * If `closID` is not set, runtimes MUST use the container ID from [`start`](runtime.md#start) and create the `` directory. -* If `closID` is set, `l3CacheSchema` and/or `memBwSchema` is set +* If `closID` is set, `l3CacheSchema` and/or `memBwSchema` and/or `schemata` is set * if `closID` directory in a mounted `resctrl` pseudo-filesystem doesn't exist, the runtimes MUST create it. * if `closID` directory in a mounted `resctrl` pseudo-filesystem exists, runtimes MUST compare `l3CacheSchema` and/or `memBwSchema` value with `schemata` file, and [generate an error](runtime.md#errors) if doesn't match. -* If `closID` is set, and neither of `l3CacheSchema` and `memBwSchema` are set, runtime MUST check if corresponding pre-configured directory `closID` is present in mounted `resctrl`. If such pre-configured directory `closID` exists, runtime MUST assign container to this `closID` and [generate an error](runtime.md#errors) if directory does not exist. +* If `closID` is set, and none of `l3CacheSchema`, `memBwSchema` or `schemata` are set, runtime MUST check if corresponding pre-configured directory `closID` is present in mounted `resctrl`. If such pre-configured directory `closID` exists, runtime MUST assign container to this `closID` and [generate an error](runtime.md#errors) if directory does not exist. + +* If `closID` is not set and the runtime has created the sub-directory, the runtime MUST remove the sub-directory when the container is deleted. -* **`enableCMT`** *(boolean, OPTIONAL)* - specifies if Intel RDT CMT should be enabled: - * CMT (Cache Monitoring Technology) supports monitoring of the last-level cache (LLC) occupancy - for the container. +* If `closID` is set or the runtime has not created the sub-directory, the runtime MUST NOT remove the sub-directory when the container is deleted. -* **`enableMBM`** *(boolean, OPTIONAL)* - specifies if Intel RDT MBM should be enabled: - * MBM (Memory Bandwidth Monitoring) supports monitoring of total and local memory bandwidth - for the container. +* If `enableMonitoring` is set, the runtime MUST create a dedicated MON group + for the container. The runtime MUST use the container ID from + [`start`](runtime.md#start) as the name of the MON group, i.e. create + `mon_groups//` subdirectory under the top-level CTRL_MON group + (named after `closID` or ``, see above). The runtime MUST + delete the MON group after the container is deleted. If creation of the MON + group fails (e.g. the maximum number of MON groups is reached) the runtime MUST + return an error. + +> **NOTE:** The `enableCMT` and `enableMBM` parameters, available in runtime-spec versions v1.1.0 through v1.2.1, were +> replaced with a unified `enableMonitoring` parameter in v1.3.0. Their semantics were loosely defined and there were +> no known implementations. More critically, these parameters were problematic as hardware does not support selective +> enabling of individual monitoring features. This scheme also made it unnecessarily complex to add support for new +> monitoring features, without providing any recognized benefits. ### Example -Consider a two-socket machine with two L3 caches where the default CBM is 0x7ff and the max CBM length is 11 bits, -and minimum memory bandwidth of 10% with a memory bandwidth granularity of 10%. +Consider a two-socket machine with: -Tasks inside the container only have access to the "upper" 7/11 of L3 cache on socket 0 and the "lower" 5/11 L3 cache on socket 1, -and may use a maximum memory bandwidth of 20% on socket 0 and 70% on socket 1. +- two L3 caches where the default CBM is 0x7ff (11 bits) +- eight L2 caches where the default CBM is 0xFF (8 bits) +- minimum memory bandwidth of 10% with a memory bandwidth granularity of 10% + +Tasks inside the container: + +- have access to the "upper" 7/11 of L3 cache on socket 0 and the "lower" 5/11 L3 cache on socket 1 +- have access to the "lower" 4/8 of L2 cache on socket 0 (socket 1 is left out from this example) +- may use a maximum memory bandwidth of 20% on socket 0 and 70% on socket 1. ```json "linux": { "intelRdt": { "closID": "guaranteed_group", - "l3CacheSchema": "L3:0=7f0;1=1f", - "memBwSchema": "MB:0=20;1=70" + "schemata": [ + "L3:0=7f0;1=1f", + "L2:0=f;1=f;2=f;3=f", + "MB:0=20;1=70" + ] + } +} +``` + +## Memory policy + +**`memoryPolicy`** (object, OPTIONAL) sets the NUMA memory policy for the container. +For more information see the [set_mempolicy(2)][set_mempolicy.2] man page. + +* **`mode`** *(string, REQUIRED)* - + + A valid list of constants is shown below. + + * `MPOL_DEFAULT` + * `MPOL_BIND` + * `MPOL_INTERLEAVE` + * `MPOL_WEIGHTED_INTERLEAVE` + * `MPOL_PREFERRED` + * `MPOL_PREFERRED_MANY` + * `MPOL_LOCAL` + +* **`nodes`** *(string, OPTIONAL)* - list of memory nodes from which nodemask is constructed to set_mempolicy(2). This is a comma-separated list, with dashes to represent ranges. For example, `0-3,7` represents memory nodes 0,1,2,3, and 7. Some modes require that there are no nodes, e.g. `MPOL_DEFAULT` and `MPOL_LOCAL`. Others that there is at least one node, e.g. `MPOL_BIND` and `MPOL_INTERLEAVE`. See set_mempolicy(2) for details. + +* **`flags`** *(array of strings, OPTIONAL)* - list of flags to use with set_mempolicy(2). + + A valid list of constants is shown below. + + * `MPOL_F_NUMA_BALANCING` + * `MPOL_F_RELATIVE_NODES` + * `MPOL_F_STATIC_NODES` + +### Example + +```json +"linux": { + "memoryPolicy": { + "mode": "MPOL_INTERLEAVE", + "nodes": "2-3" + "flags": ["MPOL_F_STATIC_NODES"], } } ``` @@ -972,9 +1139,14 @@ subset of the available options. [tmpfs]: https://www.kernel.org/doc/Documentation/filesystems/tmpfs.txt [full.4]: https://man7.org/linux/man-pages/man4/full.4.html +[set_mempolicy.2]: https://man7.org/linux/man-pages/man2/set_mempolicy.2.html [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 +[net_namespaces.7]: https://man7.org/linux/man-pages/man7/network_namespaces.7.html +[predictable-network-interfaces-names]: https://systemd.io/PREDICTABLE_INTERFACE_NAMES +[rfc3549]: https://www.ietf.org/rfc/rfc3549.txt [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 -pruN 1.2.1-1/config-vm.md 1.3.0-1/config-vm.md --- 1.2.1-1/config-vm.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/config-vm.md 2025-11-02 07:35:43.000000000 +0000 @@ -61,8 +61,54 @@ This image contains the root filesystem } ``` +## HWConfig Object + +**`hwConfig`** (object OPTIONAL) Specifies the hardware configuration that should be passed to the VM. +* **`deviceTree`** (string OPTIONAL) Path to the container device-tree file that should be passed to the VM. +* **`vcpus`** (int OPTIONAL) Number of virtual cpus for the VM. +* **`memory`** (int OPTIONAL) Maximum memory in bytes allocated to the VM. +* **`dtdevs`** (array OPTIONAL) Host device tree nodes to passthrough to the VM, see [Xen Config][xl-config-format] for the details. +* **`iomems`** (array OPTIONAL) Allow auto-translated domains to access specific hardware I/O memory pages, see [Xen Config][xl-config-format]. + * **`firstGFN`** (int OPTIONAL) Guest Frame Number to map the iomem range. + If GFN is not specified, the mapping will be done to the same Frame Number as was provided in firstMFN, see [Xen Config][xl-config-format] for the details. + * **`firstMFN`** (int REQUIRED) Physical page number of iomem regions, see [Xen Config][xl-config-format] for the details. + * **`nrMFNs`** (int REQUIRED) Number of pages to be mapped, see [Xen Config][xl-config-format] for the details. +* **`irqs`** (array OPTIONAL) Allows VM to access specific physical IRQs, see [Xen Config][xl-config-format] for the details. + +This hwConfig object contains the description of the hardware that can be safely passed through to the VM. Where **`deviceTree`** is the path to the device-tree blob, which contains description of the isolated hardware and paravirtualized hardware that should be used by VM. **`dtdevs`**, **`iomems`** and **`irqs`** parameters describing the minimal set of the parameters, needed for VM to access the hardware. + +### Example + +```json + "hwConfig": { + "deviceTree": "/path/to/vm/devicetree.dtb", + "vcpus": 1, + "memory": 4194304, + "dtdevs": [ + "path/to/dev1_node", + "path/to/dev2_node" + ], + "iomems": [ + { + "firstMFN": 12288, + "nrMFNs": 1 + }, + { + "firstGFN": 12544, + "firstMFN": 33024, + "nrMFNs": 2 + } + ], + "irqs": [ + 11, + 22 + ] + } +``` + [raw-image-format]: https://en.wikipedia.org/wiki/IMG_(file_format) [qcow2-image-format]: https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qcow2.txt;hb=HEAD [vdi-image-format]: https://forensicswiki.org/wiki/Virtual_Disk_Image_(VDI) [vmdk-image-format]: http://www.vmware.com/app/vmdk/?src=vmdk [vhd-image-format]: https://github.com/libyal/libvhdi/blob/master/documentation/Virtual%20Hard%20Disk%20(VHD)%20image%20format.asciidoc +[xl-config-format]: https://xenbits.xen.org/docs/4.10-testing/man/xl.cfg.5.html diff -pruN 1.2.1-1/config.md 1.3.0-1/config.md --- 1.2.1-1/config.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/config.md 2025-11-02 07:35:43.000000000 +0000 @@ -304,7 +304,7 @@ For Linux-based systems, the `process` o If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`. This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#memory) is scoped for a memory cgroup. - For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2]. + For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Control][cgroup-v1-memory_2]. * **`scheduler`** (object, OPTIONAL) is an object describing the scheduler properties for the process. The `scheduler` contains the following properties: * **`policy`** (string, REQUIRED) represents the scheduling policy. A valid list of values is: @@ -518,14 +518,16 @@ For Windows based systems the user struc ## Platform-specific configuration +* **`freebsd`** (object, OPTIONAL) [FreeBSD-specific configuration](config-freebsd.md). + This MAY be set if the target platform of this spec is `freebsd`. * **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md). This MAY be set if the target platform of this spec is `linux`. -* **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md). - This MUST be set if the target platform of this spec is `windows`. * **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md). This MAY be set if the target platform of this spec is `solaris`. * **`vm`** (object, OPTIONAL) [Virtual-machine-specific configuration](config-vm.md). This MAY be set if the target platform and architecture of this spec support hardware virtualization. +* **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md). + This MUST be set if the target platform of this spec is `windows`. * **`zos`** (object, OPTIONAL) [z/OS-specific configuration](config-zos.md). This MAY be set if the target platform of this spec is `zos`. diff -pruN 1.2.1-1/debian/changelog 1.3.0-1/debian/changelog --- 1.2.1-1/debian/changelog 2025-08-11 00:06:54.000000000 +0000 +++ 1.3.0-1/debian/changelog 2025-11-05 12:15:51.000000000 +0000 @@ -1,3 +1,21 @@ +golang-github-opencontainers-specs (1.3.0-1) experimental; urgency=medium + + * New upstream release + - FreeBSD support added (new config-freebsd section) + - Virtual machine hardware configuration (hwConfig object) + - Intel RDT: schemata and enableMonitoring fields + - Network device passthrough (netDevices object) + - NUMA-aware memory policy (memoryPolicy.nodes) + - Hooks: post-start hooks now fail the container on error + - Clarified Intel RDT, PID limits, and memory policy behaviour + - Default CLOS defined for Intel RDT + * Documentation: systemd-nspawn listed as implementation + * debian/control: + - Replace Tim with myself as maintainer + - Drop redundant "Rules-Requires-Root" + + -- Reinhard Tartler Wed, 05 Nov 2025 07:15:51 -0500 + golang-github-opencontainers-specs (1.2.1-1) unstable; urgency=medium * Team upload diff -pruN 1.2.1-1/debian/control 1.3.0-1/debian/control --- 1.2.1-1/debian/control 2025-08-11 00:06:54.000000000 +0000 +++ 1.3.0-1/debian/control 2025-11-05 12:15:51.000000000 +0000 @@ -5,7 +5,7 @@ Standards-Version: 4.7.2 Maintainer: Debian Go Packaging Team Uploaders: Dmitry Smirnov , - Tim Potter , + Reinhard Tartler , Build-Depends: debhelper-compat (= 13), dh-golang, @@ -13,7 +13,6 @@ Build-Depends: Homepage: https://github.com/opencontainers/runtime-spec Vcs-Browser: https://salsa.debian.org/go-team/packages/golang-github-opencontainers-specs Vcs-Git: https://salsa.debian.org/go-team/packages/golang-github-opencontainers-specs.git -Rules-Requires-Root: no Testsuite: autopkgtest-pkg-go XS-Go-Import-Path: github.com/opencontainers/runtime-spec diff -pruN 1.2.1-1/debian/gitlab-ci.yml 1.3.0-1/debian/gitlab-ci.yml --- 1.2.1-1/debian/gitlab-ci.yml 2025-08-11 00:06:54.000000000 +0000 +++ 1.3.0-1/debian/gitlab-ci.yml 2025-11-05 12:15:51.000000000 +0000 @@ -1,47 +1,11 @@ -# DO NOT MODIFY -# This file was automatically generated from the authoritative copy at: -# https://salsa.debian.org/go-team/infra/pkg-go-tools/blob/master/config/gitlabciyml.go +# cf. https://salsa.debian.org/salsa-ci-team/pipeline/ --- -stages: - - test - - package - include: - - project: go-team/infra/pkg-go-tools - ref: master - file: pipeline/test-archive.yml - # Run the Go team CI only in the go-team project that has access to GitLab - # CI runners tagged 'go-ci' - rules: - - if: $CI_PROJECT_ROOT_NAMESPACE == "go-team" - -Salsa CI: - stage: package - trigger: - include: - - project: salsa-ci-team/pipeline - ref: master - file: recipes/debian.yml - strategy: depend - rules: - # Do not create a pipeline for tags unless SALSA_CI_ENABLE_PIPELINE_ON_TAGS is set - - if: $CI_COMMIT_TAG != null && $SALSA_CI_ENABLE_PIPELINE_ON_TAGS !~ /^(1|yes|true)$/ - when: never - # Avoid duplicated pipelines, do not run detached pipelines - - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - when: never - # Run Salsa CI only if the Play button is pressed on the pipeline - - if: $CI_PIPELINE_SOURCE == "push" - when: manual - variables: - SALSA_CI_DISABLE_REPROTEST: 1 # Disable to save CI runner resources + - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/salsa-ci.yml + - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/pipeline-jobs.yml + - https://salsa.debian.org/newgateway-team/pipelines/raw/main/pipeline-jobs.yml +# - https://salsa.debian.org/go-team/infra/pkg-go-tools/-/raw/master/pipeline/test-archive.yml -# If Salsa CI is not running at -# https://salsa.debian.org/%{project_path}/-/pipelines, ensure that -# https://salsa.debian.org/%{project_path}/-/settings/ci_cd has in field "CI/CD -# configuration file" the same filename as this file. -# -# If Salsa CI is running, but first job is stuck because the project doesn't -# have any runners online assigned to it, ensure that -# https://salsa.debian.org/%{project_path}/-/settings/ci_cd has under "Runners" -# the setting for "Enable instance runners for this project" enabled. +variables: + SALSA_CI_DISABLE_APTLY: 0 + SALSA_CI_DISABLE_LICENSERECON: 0 diff -pruN 1.2.1-1/debian/watch 1.3.0-1/debian/watch --- 1.2.1-1/debian/watch 2025-08-11 00:06:54.000000000 +0000 +++ 1.3.0-1/debian/watch 2025-11-05 12:15:51.000000000 +0000 @@ -1,9 +1,5 @@ -version=4 +Version: 5 -#opts=uversionmangle=s{\-rc}{~rc},\ -# https://github.com/opencontainers/runtime-spec/releases \ -# .*/archive/v?(\d[\d\.\-rc]+)\.tar\.gz - -opts="mode=git, pgpmode=none, pretty=describe, uversionmangle=s/^v//;s/-rc\./~rc/" \ - https://github.com/opencontainers/runtime-spec/ \ - refs/tags/v@ANY_VERSION@ +Template: Github +Owner: opencontainers +Project: runtime-spec diff -pruN 1.2.1-1/features-linux.md 1.3.0-1/features-linux.md --- 1.2.1-1/features-linux.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/features-linux.md 2025-11-02 07:35:43.000000000 +0000 @@ -195,18 +195,55 @@ Irrelevant to the availability of SELinu } ``` +## MemoryPolicy + +**`memoryPolicy`** (object, OPTIONAL) represents the runtime's implementation status of memoryPolicy. + +* **`modes`** (array of strings, OPTIONAL). Recognized memory policies. Includes policies that may not be supported by the host operating system. + The runtime MUST recognize the elements in this array as the [`mode` of `linux.memoryPolicy` objects in `config.json`](config-linux.md#memory-policy). + +* **`flags`** (array of strings, OPTIONAL). Recognized flags for memory policies. Includes flags that may not be supported by the host operating system. + The runtime MUST recognize the elements in this in the [`flags` property of the `linux.memoryPolicy` object in `config.json`](config-linux.md#memory-policy) + +### Example + +```json +"memoryPolicy": { + "modes": [ + "MPOL_DEFAULT", + "MPOL_BIND", + "MPOL_INTERLEAVE", + "MPOL_WEIGHTED_INTERLEAVE", + "MPOL_PREFERRED", + "MPOL_PREFERRED_MANY", + "MPOL_LOCAL" + ], + "flags": [ + "MPOL_F_NUMA_BALANCING", + "MPOL_F_RELATIVE_NODES", + "MPOL_F_STATIC_NODES" + ] +} +``` + ## Intel RDT **`intelRdt`** (object, OPTIONAL) represents the runtime's implementation status of Intel RDT. Irrelevant to the availability of Intel RDT on the host operating system. * **`enabled`** (bool, OPTIONAL) represents whether the runtime supports Intel RDT. +* **`schemata`** (bool, OPTIONAL) represents whether the + (`schemata` field of `linux.intelRdt` in `config.json`)[config-linux.md#intelrdt] is supported. +* **`monitoring`** (bool, OPTIONAL) represents whether the + (`enableMonitoring` field of `linux.intelRdt` in `config.json`)[config-linux.md#intelrdt] is supported. ### Example ```json "intelRdt": { - "enabled": true + "enabled": true, + "schemata": true, + "monitoring": true } ``` @@ -228,3 +265,17 @@ Irrelevant to the availability of Intel } } ``` + +## NetDevices + +**`netDevices`** (object, OPTIONAL) represents the runtime's implementation status of Linux network devices. + +* **`enabled`** (bool, OPTIONAL) represents whether the runtime supports the capability to move Linux network devices into the container's network namespace. + +### Example + +```json +"netDevices": { + "enabled": true +} +``` diff -pruN 1.2.1-1/features.md 1.3.0-1/features.md --- 1.2.1-1/features.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/features.md 2025-11-02 07:35:43.000000000 +0000 @@ -354,8 +354,26 @@ Here is a full example for reference. "selinux": { "enabled": true }, + "memoryPolicy": { + "modes": [ + "MPOL_DEFAULT", + "MPOL_BIND", + "MPOL_INTERLEAVE", + "MPOL_WEIGHTED_INTERLEAVE", + "MPOL_PREFERRED", + "MPOL_PREFERRED_MANY", + "MPOL_LOCAL" + ], + "flags": [ + "MPOL_F_NUMA_BALANCING", + "MPOL_F_RELATIVE_NODES", + "MPOL_F_STATIC_NODES" + ] + }, "intelRdt": { - "enabled": true + "enabled": true, + "schemata": true, + "monitoring": true } }, "annotations": { diff -pruN 1.2.1-1/implementations.md 1.3.0-1/implementations.md --- 1.2.1-1/implementations.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/implementations.md 2025-11-02 07:35:43.000000000 +0000 @@ -10,6 +10,7 @@ If you know of any associated projects t * [containers/youki][youki] - Runtime implementation in Rust * [opencontainers/runc][runc] - Reference implementation of OCI runtime * [projectatomic/bwrap-oci][bwrap-oci] - Convert the OCI spec file to a command line for [bubblewrap][bubblewrap] +* [systemd/systemd][systemd] - Contains [systemd-nspawn][nspawn], runtime implementation in C (via `--oci-bundle` option since systemd v242) ## Runtime (Virtual Machine) @@ -30,11 +31,13 @@ If you know of any associated projects t [crun]: https://github.com/containers/crun [gvisor]: https://github.com/google/gvisor [kata-runtime]: https://github.com/kata-containers/runtime +[nspawn]: https://www.freedesktop.org/software/systemd/man/latest/systemd-nspawn.html [oct]: https://github.com/huawei-openlab/oct [octool]: https://github.com/kunalkushwaha/octool [runc]: https://github.com/opencontainers/runc [rune]: https://github.com/alibaba/inclavare-containers [runtime-tools]: https://github.com/opencontainers/runtime-tools [runv]: https://github.com/hyperhq/runv +[systemd]: https://github.com/systemd/systemd [virtcontainers]: https://github.com/containers/virtcontainers -[youki]: https://github.com/containers/youki \ No newline at end of file +[youki]: https://github.com/containers/youki diff -pruN 1.2.1-1/principles.md 1.3.0-1/principles.md --- 1.2.1-1/principles.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/principles.md 2025-11-02 07:35:43.000000000 +0000 @@ -43,4 +43,4 @@ The process was slow, inefficient and co Standard Containers make INDUSTRIAL-GRADE DELIVERY of software a reality. Leveraging all of the properties listed above, Standard Containers are enabling large and small enterprises to streamline and automate their software delivery pipelines. -Whether it is in-house devOps flows, or external customer-based software delivery mechanisms, Standard Containers are changing the way the community thinks about software packaging and delivery. +Whether it is in-house DevOps flows, or external customer-based software delivery mechanisms, Standard Containers are changing the way the community thinks about software packaging and delivery. diff -pruN 1.2.1-1/runtime.md 1.3.0-1/runtime.md --- 1.2.1-1/runtime.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/runtime.md 2025-11-02 07:35:43.000000000 +0000 @@ -70,7 +70,7 @@ The lifecycle describes the timeline of If any `startContainer` hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 12. 8. The runtime MUST run the user-specified program, as specified by [`process`](config.md#process). 9. The [`poststart` hooks](config.md#poststart) MUST be invoked by the runtime. - If any `poststart` hook fails, the runtime MUST [log a warning](#warnings), but the remaining hooks and lifecycle continue as if the hook had succeeded. + If any `poststart` hook fails, the runtime MUST [generate an error](#errors), stop the container, and continue the lifecycle at step 12. 10. The container process exits. This MAY happen due to erroring out, exiting, crashing or the runtime's [`kill`](runtime.md#kill) operation being invoked. 11. Runtime's [`delete`](runtime.md#delete) command is invoked with the unique identifier of the container. diff -pruN 1.2.1-1/schema/README.md 1.3.0-1/schema/README.md --- 1.2.1-1/schema/README.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/README.md 2025-11-02 07:35:43.000000000 +0000 @@ -10,6 +10,7 @@ The layout of the files is as follows: * [config-linux.json](config-linux.json) - the [Linux-specific configuration sub-structure](../config-linux.md) * [config-solaris.json](config-solaris.json) - the [Solaris-specific configuration sub-structure](../config-solaris.md) * [config-windows.json](config-windows.json) - the [Windows-specific configuration sub-structure](../config-windows.md) +* [config-freebsd.json](config-freebsd.json) - the [FreeBSD-specific configuration sub-structure](../config-freebsd.md) * [state-schema.json](state-schema.json) - the primary entrypoint for the [state JSON](../runtime.md#state) schema * [defs.json](defs.json) - definitions for general types * [defs-linux.json](defs-linux.json) - definitions for Linux-specific types diff -pruN 1.2.1-1/schema/config-freebsd.json 1.3.0-1/schema/config-freebsd.json --- 1.2.1-1/schema/config-freebsd.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/config-freebsd.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,90 @@ +{ + "freebsd": { + "description": "FreeBSD platform-specific configurations", + "type": "object", + "properties": { + "devices": { + "type": "array", + "items": { + "$ref": "defs-freebsd.json#/definitions/Device" + } + }, + "jail": { + "type": "object", + "properties": { + "parent": { + "type": "string" + }, + "host": { + "$ref": "defs-freebsd.json#/definitions/SharingModeNoDisable" + }, + "ip4": { + "$ref": "defs-freebsd.json#/definitions/SharingMode" + }, + "ip4Addr": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, + "ip6": { + "$ref": "defs-freebsd.json#/definitions/SharingMode" + }, + "ip6Addr": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, + "vnet": { + "$ref": "defs-freebsd.json#/definitions/SharingModeNoDisable" + }, + "interface": { + "type": "string" + }, + "vnetInterfaces": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, + "sysvmsg": { + "$ref": "defs-freebsd.json#/definitions/SharingMode" + }, + "sysvsem": { + "$ref": "defs-freebsd.json#/definitions/SharingMode" + }, + "sysvshm": { + "$ref": "defs-freebsd.json#/definitions/SharingMode" + }, + "enforceStatfs": { + "$ref": "defs.json#/definitions/uint8" + }, + "allow": { + "type": "object", + "properties": { + "setHostname": { + "type": "boolean" + }, + "rawSockets": { + "type": "boolean" + }, + "chflags": { + "type": "boolean" + }, + "mount": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, + "quotas": { + "type": "boolean" + }, + "socketAf": { + "type": "boolean" + }, + "mlock": { + "type": "boolean" + }, + "reservedPorts": { + "type": "boolean" + }, + "suser": { + "type": "boolean" + } + } + } + } + } + } + } +} diff -pruN 1.2.1-1/schema/config-linux.json 1.3.0-1/schema/config-linux.json --- 1.2.1-1/schema/config-linux.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/config-linux.json 2025-11-02 07:35:43.000000000 +0000 @@ -9,6 +9,12 @@ "$ref": "defs-linux.json#/definitions/Device" } }, + "netDevices": { + "type": "object", + "additionalProperties": { + "$ref": "defs-linux.json#/definitions/NetDevice" + } + }, "uidMappings": { "type": "array", "items": { @@ -262,6 +268,9 @@ "closID": { "type": "string" }, + "schemata": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, "l3CacheSchema": { "type": "string" }, @@ -269,11 +278,25 @@ "type": "string", "pattern": "^MB:[^\\n]*$" }, - "enableCMT": { + "enableMonitoring": { "type": "boolean" + } + } + }, + "memoryPolicy": { + "type": "object", + "properties": { + "mode": { + "$ref": "defs-linux.json#/definitions/MemoryPolicyMode" }, - "enableMBM": { - "type": "boolean" + "nodes": { + "type": "string" + }, + "flags": { + "type": "array", + "items": { + "$ref": "defs-linux.json#/definitions/MemoryPolicyFlag" + } } } }, diff -pruN 1.2.1-1/schema/config-schema.json 1.3.0-1/schema/config-schema.json --- 1.2.1-1/schema/config-schema.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/config-schema.json 2025-11-02 07:35:43.000000000 +0000 @@ -250,6 +250,9 @@ }, "zos": { "$ref": "config-zos.json#/zos" + }, + "freebsd": { + "$ref": "config-freebsd.json#/freebsd" } }, "required": [ diff -pruN 1.2.1-1/schema/config-vm.json 1.3.0-1/schema/config-vm.json --- 1.2.1-1/schema/config-vm.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/config-vm.json 2025-11-02 07:35:43.000000000 +0000 @@ -54,6 +54,35 @@ "$ref": "defs-vm.json#/definitions/RootImageFormat" } } + }, + "hwConfig": { + "description": "hardware configuration for the VM image", + "type": "object", + "properties": { + "deviceTree": { + "$ref": "defs.json#/definitions/FilePath" + }, + "vcpus": { + "$ref": "defs.json#/definitions/uint32" + }, + "memory": { + "$ref": "defs.json#/definitions/uint64" + }, + "dtdevs": { + "$ref": "defs.json#/definitions/ArrayOfStrings" + }, + "iomems": { + "type": "array", + "items": [ + { + "$ref": "defs-vm.json#/definitions/IOMemEntryFormat" + } + ] + }, + "irqs": { + "$ref": "defs.json#/definitions/ArrayOfUint32" + } + } } } } diff -pruN 1.2.1-1/schema/defs-freebsd.json 1.3.0-1/schema/defs-freebsd.json --- 1.2.1-1/schema/defs-freebsd.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/defs-freebsd.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,30 @@ +{ + "definitions": { + "Device": { + "type": "object", + "properties": { + "path": { + "type": "string" + }, + "mode": { + "$ref": "defs.json#/definitions/FileMode" + } + } + }, + "SharingMode": { + "type": "string", + "enum": [ + "disable", + "new", + "inherit" + ] + }, + "SharingModeNoDisable": { + "type": "string", + "enum": [ + "new", + "inherit" + ] + } + } +} diff -pruN 1.2.1-1/schema/defs-linux.json 1.3.0-1/schema/defs-linux.json --- 1.2.1-1/schema/defs-linux.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/defs-linux.json 2025-11-02 07:35:43.000000000 +0000 @@ -148,12 +148,6 @@ "description": "minor device number", "$ref": "defs.json#/definitions/int64" }, - "FileMode": { - "description": "File permissions mode (typically an octal value)", - "type": "integer", - "minimum": 0, - "maximum": 512 - }, "FileType": { "description": "Type of a block or special character device", "type": "string", @@ -173,7 +167,7 @@ "$ref": "defs.json#/definitions/FilePath" }, "fileMode": { - "$ref": "#/definitions/FileMode" + "$ref": "defs.json#/definitions/FileMode" }, "major": { "$ref": "#/definitions/Major" @@ -189,6 +183,14 @@ } } }, + "NetDevice": { + "type": "object", + "properties": { + "name": { + "type": "string" + } + } + }, "weight": { "$ref": "defs.json#/definitions/uint16" }, @@ -264,6 +266,26 @@ "allow" ] }, + "MemoryPolicyMode": { + "type": "string", + "enum": [ + "MPOL_DEFAULT", + "MPOL_BIND", + "MPOL_INTERLEAVE", + "MPOL_WEIGHTED_INTERLEAVE", + "MPOL_PREFERRED", + "MPOL_PREFERRED_MANY", + "MPOL_LOCAL" + ] + }, + "MemoryPolicyFlag": { + "type": "string", + "enum": [ + "MPOL_F_NUMA_BALANCING", + "MPOL_F_RELATIVE_NODES", + "MPOL_F_STATIC_NODES" + ] + }, "NetworkInterfacePriority": { "type": "object", "properties": { diff -pruN 1.2.1-1/schema/defs-vm.json 1.3.0-1/schema/defs-vm.json --- 1.2.1-1/schema/defs-vm.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/defs-vm.json 2025-11-02 07:35:43.000000000 +0000 @@ -9,6 +9,24 @@ "vmdk", "vhd" ] + }, + "IOMemEntryFormat": { + "type": "object", + "properties": { + "firstGFN": { + "$ref": "defs.json#/definitions/uint64" + }, + "firstMFN": { + "$ref": "defs.json#/definitions/uint64" + }, + "nrMFNs": { + "$ref": "defs.json#/definitions/uint64" + } + }, + "required": [ + "firstMFN", + "nrMFNs" + ] } } } diff -pruN 1.2.1-1/schema/defs.json 1.3.0-1/schema/defs.json --- 1.2.1-1/schema/defs.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/defs.json 2025-11-02 07:35:43.000000000 +0000 @@ -75,6 +75,18 @@ "type": "string" } }, + "ArrayOfUint32": { + "type": "array", + "items": { + "$ref": "#definitions/uint32" + } + }, + "FileMode": { + "description": "File permissions mode (in decimal, not octal)", + "type": "integer", + "minimum": 0, + "maximum": 511 + }, "FilePath": { "type": "string" }, diff -pruN 1.2.1-1/schema/features-linux.json 1.3.0-1/schema/features-linux.json --- 1.2.1-1/schema/features-linux.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/features-linux.json 2025-11-02 07:35:43.000000000 +0000 @@ -110,6 +110,14 @@ } } } + }, + "netDevices": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + } } } } diff -pruN 1.2.1-1/schema/test/config/bad/freebsd-vnet-disable.json 1.3.0-1/schema/test/config/bad/freebsd-vnet-disable.json --- 1.2.1-1/schema/test/config/bad/freebsd-vnet-disable.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/test/config/bad/freebsd-vnet-disable.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,11 @@ +{ + "ociVersion": "1.3.0", + "root": { + "path": "rootfs" + }, + "freebsd": { + "jail": { + "vnet": "disable" + } + } +} diff -pruN 1.2.1-1/schema/test/config/bad/linux-netdevice.json 1.3.0-1/schema/test/config/bad/linux-netdevice.json --- 1.2.1-1/schema/test/config/bad/linux-netdevice.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/test/config/bad/linux-netdevice.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,13 @@ +{ + "ociVersion": "1.0.0", + "root": { + "path": "rootfs" + }, + "linux": { + "netDevices": { + "eth0": { + "name": 23 + } + } + } +} diff -pruN 1.2.1-1/schema/test/config/good/freebsd-example.json 1.3.0-1/schema/test/config/good/freebsd-example.json --- 1.2.1-1/schema/test/config/good/freebsd-example.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/test/config/good/freebsd-example.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,54 @@ +{ + "ociVersion": "1.3.0", + "process": { + "terminal": true, + "args": [ + "sh" + ], + "env": [ + "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "TERM=xterm" + ], + "cwd": "/" + }, + "root": { + "path": "rootfs" + }, + "hostname": "slartibartfast", + "mounts": [ + { + "destination": "/dev", + "type": "devfs", + "source": "devfs", + "options": [ + "ruleset=4" + ] + }, + { + "destination": "/dev/fd", + "type": "fdescfs", + "source": "fdescfs", + "options": [] + } + ], + "freebsd": { + "devices": [ + { + "path": "pf", + "mode": 448 + } + ], + "jail": { + "host": "new", + "vnet": "new", + "enforceStatfs": 1, + "allow": { + "rawSockets": true, + "chflags": true, + "mount": [ + "tmpfs" + ] + } + } + } +} diff -pruN 1.2.1-1/schema/test/config/good/freebsd-minimal.json 1.3.0-1/schema/test/config/good/freebsd-minimal.json --- 1.2.1-1/schema/test/config/good/freebsd-minimal.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/test/config/good/freebsd-minimal.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,7 @@ +{ + "ociVersion": "1.3.0", + "root": { + "path": "rootfs" + }, + "freebsd": {} +} diff -pruN 1.2.1-1/schema/test/config/good/linux-netdevice.json 1.3.0-1/schema/test/config/good/linux-netdevice.json --- 1.2.1-1/schema/test/config/good/linux-netdevice.json 1970-01-01 00:00:00.000000000 +0000 +++ 1.3.0-1/schema/test/config/good/linux-netdevice.json 2025-11-02 07:35:43.000000000 +0000 @@ -0,0 +1,15 @@ +{ + "ociVersion": "1.0.0", + "root": { + "path": "rootfs" + }, + "linux": { + "netDevices": { + "eth0": { + "name": "container_eth0" + }, + "ens4": {}, + "ens5": {} + } + } +} diff -pruN 1.2.1-1/schema/test/features/good/runc.json 1.3.0-1/schema/test/features/good/runc.json --- 1.2.1-1/schema/test/features/good/runc.json 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/schema/test/features/good/runc.json 2025-11-02 07:35:43.000000000 +0000 @@ -182,6 +182,9 @@ }, "selinux": { "enabled": true + }, + "netDevices": { + "enabled": true } }, "annotations": { diff -pruN 1.2.1-1/spec.md 1.3.0-1/spec.md --- 1.2.1-1/spec.md 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/spec.md 2025-11-02 07:35:43.000000000 +0000 @@ -13,6 +13,7 @@ The execution environment is specified t Platforms defined by this specification are: +* `freebsd`: [runtime.md](runtime.md), [config.md](config.md), [features.md](features.md), and [config-freebsd.md](config-freebsd.md). * `linux`: [runtime.md](runtime.md), [config.md](config.md), [features.md](features.md), [config-linux.md](config-linux.md), [runtime-linux.md](runtime-linux.md), and [features-linux.md](features-linux.md). * `solaris`: [runtime.md](runtime.md), [config.md](config.md), [features.md](features.md), and [config-solaris.md](config-solaris.md). * `windows`: [runtime.md](runtime.md), [config.md](config.md), [features.md](features.md), and [config-windows.md](config-windows.md). @@ -28,6 +29,7 @@ Platforms defined by this specification - [Runtime and Lifecycle](runtime.md) - [Linux-specific Runtime and Lifecycle](runtime-linux.md) - [Configuration](config.md) + - [FreeBSD-specific Configuration](config-freebsd.md) - [Linux-specific Configuration](config-linux.md) - [Solaris-specific Configuration](config-solaris.md) - [Windows-specific Configuration](config-windows.md) diff -pruN 1.2.1-1/specs-go/config.go 1.3.0-1/specs-go/config.go --- 1.2.1-1/specs-go/config.go 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/specs-go/config.go 2025-11-02 07:35:43.000000000 +0000 @@ -31,6 +31,8 @@ type Spec struct { VM *VM `json:"vm,omitempty" platform:"vm"` // ZOS is platform-specific configuration for z/OS based containers. ZOS *ZOS `json:"zos,omitempty" platform:"zos"` + // FreeBSD is platform-specific configuration for FreeBSD based containers. + FreeBSD *FreeBSD `json:"freebsd,omitempty" platform:"freebsd"` } // Scheduler represents the scheduling attributes for a process. It is based on @@ -170,7 +172,7 @@ type Mount struct { // Destination is the absolute path where the mount will be placed in the container. Destination string `json:"destination"` // Type specifies the mount kind. - Type string `json:"type,omitempty" platform:"linux,solaris,zos"` + Type string `json:"type,omitempty" platform:"linux,solaris,zos,freebsd"` // Source specifies the source path of the mount. Source string `json:"source,omitempty"` // Options are fstab style mount options. @@ -236,6 +238,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 on the host, 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. @@ -249,6 +253,8 @@ type Linux struct { // IntelRdt contains Intel Resource Director Technology (RDT) information for // handling resource constraints and monitoring metrics (e.g., L3 cache, memory bandwidth) for the container IntelRdt *LinuxIntelRdt `json:"intelRdt,omitempty"` + // MemoryPolicy contains NUMA memory policy for the container. + MemoryPolicy *LinuxMemoryPolicy `json:"memoryPolicy,omitempty"` // Personality contains configuration for the Linux personality syscall Personality *LinuxPersonality `json:"personality,omitempty"` // TimeOffsets specifies the offset for supporting time namespaces. @@ -430,7 +436,7 @@ type LinuxCPU struct { // LinuxPids for Linux cgroup 'pids' resource management (Linux 4.3) type LinuxPids struct { // Maximum number of PIDs. Default is "no limit". - Limit int64 `json:"limit"` + Limit *int64 `json:"limit,omitempty"` } // LinuxNetwork identification and priority configuration @@ -491,6 +497,12 @@ 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"` +} + // LinuxDeviceCgroup represents a device rule for the devices specified to // the device controller type LinuxDeviceCgroup struct { @@ -678,6 +690,32 @@ type WindowsHyperV struct { UtilityVMPath string `json:"utilityVMPath,omitempty"` } +// IOMems contains information about iomem addresses that should be passed to the VM. +type IOMems struct { + // Guest Frame Number to map the iomem range. If GFN is not specified, the mapping will be done to the same Frame Number as was provided in FirstMFN. + FirstGFN *uint64 `json:"firstGFN,omitempty"` + // Physical page number of iomem regions. + FirstMFN *uint64 `json:"firstMFN"` + // Number of pages to be mapped. + NrMFNs *uint64 `json:"nrMFNs"` +} + +// Hardware configuration for the VM image +type HWConfig struct { + // Path to the container device-tree file that should be passed to the VM configuration. + DeviceTree string `json:"deviceTree,omitempty"` + // Number of virtual cpus for the VM. + VCPUs *uint32 `json:"vcpus,omitempty"` + // Maximum memory in bytes allocated to the VM. + Memory *uint64 `json:"memory,omitempty"` + // Host device tree nodes to passthrough to the VM. + DtDevs []string `json:"dtdevs,omitempty"` + // Allow auto-translated domains to access specific hardware I/O memory pages. + IOMems []IOMems `json:"iomems,omitempty"` + // Allows VM to access specific physical IRQs. + Irqs []uint32 `json:"irqs,omitempty"` +} + // VM contains information for virtual-machine-based containers. type VM struct { // Hypervisor specifies hypervisor-related configuration for virtual-machine-based containers. @@ -686,6 +724,8 @@ type VM struct { Kernel VMKernel `json:"kernel"` // Image specifies guest image related configuration for virtual-machine-based containers. Image VMImage `json:"image,omitempty"` + // Hardware configuration that should be passed to the VM. + HwConfig *HWConfig `json:"hwconfig,omitempty"` } // VMHypervisor contains information about the hypervisor to use for a virtual machine. @@ -828,23 +868,41 @@ type LinuxSyscall struct { type LinuxIntelRdt struct { // The identity for RDT Class of Service ClosID string `json:"closID,omitempty"` + + // Schemata specifies the complete schemata to be written as is to the + // schemata file in resctrl fs. Each element represents a single line in the schemata file. + // NOTE: This will overwrite schemas specified in the L3CacheSchema and/or + // MemBwSchema fields. + Schemata []string `json:"schemata,omitempty"` + // The schema for L3 cache id and capacity bitmask (CBM) // Format: "L3:=;=;..." + // NOTE: Should not be specified if Schemata is non-empty. L3CacheSchema string `json:"l3CacheSchema,omitempty"` // The schema of memory bandwidth per L3 cache id // Format: "MB:=bandwidth0;=bandwidth1;..." // The unit of memory bandwidth is specified in "percentages" by // default, and in "MBps" if MBA Software Controller is enabled. + // NOTE: Should not be specified if Schemata is non-empty. MemBwSchema string `json:"memBwSchema,omitempty"` - // EnableCMT is the flag to indicate if the Intel RDT CMT is enabled. CMT (Cache Monitoring Technology) supports monitoring of - // the last-level cache (LLC) occupancy for the container. - EnableCMT bool `json:"enableCMT,omitempty"` - - // EnableMBM is the flag to indicate if the Intel RDT MBM is enabled. MBM (Memory Bandwidth Monitoring) supports monitoring of - // total and local memory bandwidth for the container. - EnableMBM bool `json:"enableMBM,omitempty"` + // EnableMonitoring enables resctrl monitoring for the container. This will + // create a dedicated resctrl monitoring group for the container. + EnableMonitoring bool `json:"enableMonitoring,omitempty"` +} + +// LinuxMemoryPolicy represents input for the set_mempolicy syscall. +type LinuxMemoryPolicy struct { + // Mode for the set_mempolicy syscall. + Mode MemoryPolicyModeType `json:"mode"` + + // Nodes representing the nodemask for the set_mempolicy syscall in comma separated ranges format. + // Format: "-,,-,..." + Nodes string `json:"nodes"` + + // Flags for the set_mempolicy syscall. + Flags []MemoryPolicyFlagType `json:"flags,omitempty"` } // ZOS contains platform-specific configuration for z/OS based containers. @@ -876,6 +934,26 @@ const ( ZOSUTSNamespace ZOSNamespaceType = "uts" ) +type MemoryPolicyModeType string + +const ( + MpolDefault MemoryPolicyModeType = "MPOL_DEFAULT" + MpolBind MemoryPolicyModeType = "MPOL_BIND" + MpolInterleave MemoryPolicyModeType = "MPOL_INTERLEAVE" + MpolWeightedInterleave MemoryPolicyModeType = "MPOL_WEIGHTED_INTERLEAVE" + MpolPreferred MemoryPolicyModeType = "MPOL_PREFERRED" + MpolPreferredMany MemoryPolicyModeType = "MPOL_PREFERRED_MANY" + MpolLocal MemoryPolicyModeType = "MPOL_LOCAL" +) + +type MemoryPolicyFlagType string + +const ( + MpolFNumaBalancing MemoryPolicyFlagType = "MPOL_F_NUMA_BALANCING" + MpolFRelativeNodes MemoryPolicyFlagType = "MPOL_F_RELATIVE_NODES" + MpolFStaticNodes MemoryPolicyFlagType = "MPOL_F_STATIC_NODES" +) + // LinuxSchedulerPolicy represents different scheduling policies used with the Linux Scheduler type LinuxSchedulerPolicy string @@ -915,3 +993,75 @@ const ( // SchedFlagUtilClampMin represents the utilization clamp maximum scheduling flag SchedFlagUtilClampMax LinuxSchedulerFlag = "SCHED_FLAG_UTIL_CLAMP_MAX" ) + +// FreeBSD contains platform-specific configuration for FreeBSD based containers. +type FreeBSD struct { + // Devices which are accessible in the container + Devices []FreeBSDDevice `json:"devices,omitempty"` + // Jail definition for this container + Jail *FreeBSDJail `json:"jail,omitempty"` +} + +type FreeBSDDevice struct { + // Path to the device, relative to /dev. + Path string `json:"path"` + // FileMode permission bits for the device. + Mode *os.FileMode `json:"mode,omitempty"` +} + +// FreeBSDJail describes how to configure the container's jail +type FreeBSDJail struct { + // Parent jail name - this can be used to share a single vnet + // across several containers + Parent string `json:"parent,omitempty"` + // Whether to use parent UTS names or override in the container + Host FreeBSDSharing `json:"host,omitempty"` + // IPv4 address sharing for the container + Ip4 FreeBSDSharing `json:"ip4,omitempty"` + // IPv4 addresses for the container + Ip4Addr []string `json:"ip4Addr,omitempty"` + // IPv6 address sharing for the container + Ip6 FreeBSDSharing `json:"ip6,omitempty"` + // IPv6 addresses for the container + Ip6Addr []string `json:"ip6Addr,omitempty"` + // Which network stack to use for the container + Vnet FreeBSDSharing `json:"vnet,omitempty"` + // If set, Ip4Addr and Ip6Addr addresses will be added to this interface + Interface string `json:"interface,omitempty"` + // List interfaces to be moved to the container's vnet + VnetInterfaces []string `json:"vnetInterfaces,omitempty"` + // SystemV IPC message sharing for the container + SysVMsg FreeBSDSharing `json:"sysvmsg,omitempty"` + // SystemV semaphore message sharing for the container + SysVSem FreeBSDSharing `json:"sysvsem,omitempty"` + // SystemV memory sharing for the container + SysVShm FreeBSDSharing `json:"sysvshm,omitempty"` + // Mount visibility (see jail(8) for details) + EnforceStatfs *int `json:"enforceStatfs,omitempty"` + // Jail capabilities + Allow *FreeBSDJailAllow `json:"allow,omitempty"` +} + +// These values are used to control access to features in the container, either +// disabling the feature, sharing state with the parent or creating new private +// state in the container. +type FreeBSDSharing string + +const ( + FreeBSDShareDisable FreeBSDSharing = "disable" + FreeBSDShareNew FreeBSDSharing = "new" + FreeBSDShareInherit FreeBSDSharing = "inherit" +) + +// FreeBSDJailAllow describes jail capabilities +type FreeBSDJailAllow struct { + SetHostname bool `json:"setHostname,omitempty"` + RawSockets bool `json:"rawSockets,omitempty"` + Chflags bool `json:"chflags,omitempty"` + Mount []string `json:"mount,omitempty"` + Quotas bool `json:"quotas,omitempty"` + SocketAf bool `json:"socketAf,omitempty"` + Mlock bool `json:"mlock,omitempty"` + ReservedPorts bool `json:"reservedPorts,omitempty"` + Suser bool `json:"suser,omitempty"` +} diff -pruN 1.2.1-1/specs-go/features/features.go 1.3.0-1/specs-go/features/features.go --- 1.2.1-1/specs-go/features/features.go 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/specs-go/features/features.go 2025-11-02 07:35:43.000000000 +0000 @@ -47,7 +47,9 @@ type Linux struct { Apparmor *Apparmor `json:"apparmor,omitempty"` Selinux *Selinux `json:"selinux,omitempty"` IntelRdt *IntelRdt `json:"intelRdt,omitempty"` + MemoryPolicy *MemoryPolicy `json:"memoryPolicy,omitempty"` MountExtensions *MountExtensions `json:"mountExtensions,omitempty"` + NetDevices *NetDevices `json:"netDevices,omitempty"` } // Cgroup represents the "cgroup" field. @@ -129,6 +131,21 @@ type IntelRdt struct { // Unrelated to whether the host supports Intel RDT or not. // Nil value means "unknown", not "false". Enabled *bool `json:"enabled,omitempty"` + // Schemata is true if the "linux.intelRdt.enableMonitoring" field of the + // spec is implemented. + Schemata *bool `json:"schemata,omitempty"` + // Monitoring is true if the "linux.intelRdt.enableMonitoring" field of the + // spec is implemented. + // Nil value means "unknown", not "false". + Monitoring *bool `json:"monitoring,omitempty"` +} + +// MemoryPolicy represents the "memoryPolicy" field. +type MemoryPolicy struct { + // modes is the list of known memory policy modes, e.g., "MPOL_INTERLEAVE". + Modes []string `json:"modes,omitempty"` + // flags is the list of known memory policy mode flags, e.g., "MPOL_F_STATIC_NODES". + Flags []string `json:"flags,omitempty"` } // MountExtensions represents the "mountExtensions" field. @@ -143,3 +160,10 @@ type IDMap struct { // Nil value means "unknown", not "false". Enabled *bool `json:"enabled,omitempty"` } + +// NetDevices represents the "netDevices" field. +type NetDevices struct { + // Enabled is true if network devices support is compiled in. + // Nil value means "unknown", not "false". + Enabled *bool `json:"enabled,omitempty"` +} diff -pruN 1.2.1-1/specs-go/version.go 1.3.0-1/specs-go/version.go --- 1.2.1-1/specs-go/version.go 2025-02-25 22:46:15.000000000 +0000 +++ 1.3.0-1/specs-go/version.go 2025-11-02 07:35:43.000000000 +0000 @@ -6,9 +6,9 @@ const ( // VersionMajor is for an API incompatible changes VersionMajor = 1 // VersionMinor is for functionality in a backwards-compatible manner - VersionMinor = 2 + VersionMinor = 3 // VersionPatch is for backwards-compatible bug fixes - VersionPatch = 1 + VersionPatch = 0 // VersionDev indicates development branch. Releases will be empty string. VersionDev = ""