Barring access control concerns, the entity using a runtime to create a container MUST be able to use the operations defined in this specification against that same container. Whether other entities using the same, or other, instance of the runtime can see that container is out of scope of this specification.^¶

{
    "ociVersion": "0.2.0",
    "id": "oci-container1",
    "status": "running",
    "pid": 4422,
    "bundlePath": "/containers/redis",
    "annotations": {
        "myKey": "myValue"
    }
}

The lifecycle describes the timeline of events that happen from when a container is created to when it ceases to exist.^¶

In cases where the specified operation generates an error, this specification does not mandate how, or even if, that error is returned or exposed to the user of an implementation. Unless otherwise stated, generating an error MUST leave the state of the environment as if the operation were never attempted - modulo any possible trivial ancillary changes such as logging.^¶

OCI compliant runtimes MUST support the following operations, unless the operation is not supported by the base operating system.^¶

By default, only the stdin, stdout and stderr file descriptors are kept open for the application by the runtime. The runtime MAY pass additional file descriptors to the application to support features such as socket activation. Some of the file descriptors MAY be redirected to /dev/null even though they are open.^¶

After the container has /proc mounted, the following standard symlinks MUST be setup within /dev/ for the IO.^¶

The user for the process is a platform-specific structure that allows specific control over which user the process runs as.^¶

{
  "process": {
    "terminal": true,
    "consoleSize": {
      "height": 25,
      "width": 80
    },
    "user": {
      "uid": 1,
      "gid": 1,
      "additionalGids": [5, 6]
    },
    "env": [
      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
      "TERM=xterm"
    ],
    "cwd": "/root",
    "args": [
      "sh"
    ],
    "apparmorProfile": "acme_secure_profile",
    "selinuxLabel": "system_u:system_r:svirt_lxc_net_t:s0:c124,c675",
    "noNewPrivileges": true,
    "capabilities": [
      "CAP_AUDIT_WRITE",
      "CAP_KILL",
      "CAP_NET_BIND_SERVICE"
    ],
    "rlimits": [
      {
        "type": "RLIMIT_NOFILE",
        "hard": 1024,
        "soft": 1024
      }
    ]
  },
  …
}

{
  "process": {
    "terminal": true,
    "consoleSize": {
      "height": 25,
      "width": 80
    },
    "user": {
      "uid": 1,
      "gid": 1,
      "additionalGids": [2, 8]
    },
    "env": [
      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
      "TERM=xterm"
    ],
    "cwd": "/root",
    "args": [
      "/usr/bin/bash"
    ]
  },
  …
}

{
  "process": {
    "terminal": true,
    "user": {
      "username": "containeradministrator"
    },
    "env": [
      "VARIABLE=1"
    ],
    "cwd": "c:\\foo",
    "args": [
      "someapp.exe",
    ]
  },
  …
}

The Linux ABI includes both syscalls and several special file paths. Applications expecting a Linux environment will very likely expect these file paths to be setup correctly.^¶

The following filesystems MUST be made available in each application’s filesystem:^¶

A namespace wraps a global system resource in an abstraction that makes it appear to the processes within the namespace that they have their own isolated instance of the global resource. Changes to the global resource are visible to other processes that are members of the namespace, but are invisible to other processes. For more information, see the man page.^¶

Entries have the following properties:^¶

If a path is specified, that particular file is used to join that type of namespace. If a namespace type is not specified in the namespaces array, the container MUST inherit the runtime namespace of that type. If a new namespace is not created (because the namespace type is not listed, or because it is listed with a path), runtimes MUST assume that the setup for that namespace has already been done and error out if the config specifies anything else related to that namespace. If a namespaces field contains duplicated namespaces with same type, the runtime MUST error out.^¶

Example. 

{
  "linux": {
    "namespaces": [
      {
        "type": "pid",
        "path": "/proc/1234/ns/pid"
      },
      {
        "type": "network",
        "path": "/var/run/netns/neta"
      },
      {
        "type": "mount"
      },
      {
        "type": "ipc"
      },
      {
        "type": "uts"
      },
      {
        "type": "user"
      },
      {
        "type": "cgroup"
      }
    ],
  },
  …
}

Each entry has the following structure:^¶

The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping. There is a limit of 5 mappings which is the Linux kernel hard limit.^¶

Example. 

{
  "linux": {
    "namespaces": [
      {
        "type": "user"
      }
    ],
    "uidMappings": [
      {
        "hostID": 1000,
        "containerID": 0,
        "size": 32000
      }
    ],
    "gidMappings": [
      {
        "hostID": 1000,
        "containerID": 0,
        "size": 32000
      }
    ]
  },
  …
}

Each entry has the following structure:^¶

Example. 

{
  "linux": {
    "namespaces": [
      {
        "type": "mount"
      },
    ],
    "devices": [
      {
        "path": "/dev/fuse",
        "type": "c",
        "major": 10,
        "minor": 229,
        "fileMode": 438,
        "uid": 0,
        "gid": 0
      },
      {
        "path": "/dev/sda",
        "type": "b",
        "major": 8,
        "minor": 0,
        "fileMode": 432,
        "uid": 0,
        "gid": 0
      }
    ],
  }
  …
}

Also known as cgroups, they are used to restrict resource usage for a container and handle device access. cgroups provide controls (through controllers) to restrict cpu, memory, IO, pids and network for the container. For more information, see the kernel cgroups documentation.^¶

The path to the cgroups can be specified in the Spec via cgroupsPath. cgroupsPath can be used to either control the cgroup hierarchy for containers or to run a new process in an existing container. If cgroupsPath is:^¶

Runtimes MAY consider certain cgroupsPath values to be invalid, and MUST generate an error if this is the case. If a cgroupsPath value is specified, the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of cgroupsPath.^¶

Implementations of the Spec can choose to name cgroups in any manner. The Spec does not include naming schema for cgroups. The Spec does not support per-controller paths for the reasons discussed in the cgroupv2 documentation. The cgroups will be created if they don’t exist.^¶

You can configure a container’s cgroups via the resources field of the Linux configuration. Do not specify resources unless limits have to be updated. For example, to run a new process in an existing container without updating limits, resources need not be specified.^¶

A runtime MUST at least use the minimum set of cgroup controllers required to fulfill the resources settings. However, a runtime MAY attach the container process to additional cgroup controllers supported by the system.^¶

Example. 

{
  "linux": {
    "cgroupsPath": "/myRuntime/myContainer",
    "resources": {
      "memory": {
        "limit": 100000,
        "reservation": 200000
      },
      "devices": [
        {
          "allow": false,
          "access": "rwm"
        }
      ]
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "devices": [
        {
          "allow": false,
          "access": "rwm"
        },
        {
          "allow": true,
          "type": "c",
          "major": 10,
          "minor": 229,
          "access": "rw"
        },
        {
          "allow": true,
          "type": "b",
          "major": 8,
          "minor": 0,
          "access": "r"
        }
      ]
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "disableOOMKiller": false
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "oomScoreAdj": 100
    },
  },
  …
}

{
  "linux": {
    "resources": {
      "memory": {
        "limit": 536870912,
        "reservation": 536870912,
        "swap": 536870912,
        "kernel": 0,
        "kernelTCP": 0,
        "swappiness": 0
      }
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "cpu": {
        "shares": 1024,
        "quota": 1000000,
        "period": 500000,
        "realtimeRuntime": 950000,
        "realtimePeriod": 1000000,
        "cpus": "2-3",
        "mems": "0-7"
      }
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "blockIO": {
        "blkioWeight": 10,
        "blkioLeafWeight": 10,
        "blkioWeightDevice": [
          {
            "major": 8,
            "minor": 0,
            "weight": 500,
            "leafWeight": 300
          },
          {
            "major": 8,
            "minor": 16,
            "weight": 500
          }
        ],
        "blkioThrottleReadBpsDevice": [
          {
            "major": 8,
            "minor": 0,
            "rate": 600
          }
        ],
        "blkioThrottleWriteIOPSDevice": [
          {
            "major": 8,
            "minor": 16,
            "rate": 300
          }
        ]
      }
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "hugepageLimits": [
        {
          "pageSize": "2MB",
          "limit": 9223372036854771712
        }
      ]
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "network": {
        "classID": 1048577,
        "priorities": [
          {
            "name": "eth0",
            "priority": 500
          },
          {
            "name": "eth1",
            "priority": 1000
          }
        ]
      }
    }
  },
  …
}

{
  "linux": {
    "resources": {
      "pids": {
        "limit": 32771
      }
    }
  },
  …
}

Example. 

{
  "linux": {
    "sysctl": {
      "net.ipv4.ip_forward": "1",
      "net.core.somaxconn": "256"
    }
  },
  …
}

Seccomp provides application sandboxing mechanism in the Linux kernel. Seccomp configuration allows one to configure actions to take for matched syscalls and furthermore also allows matching on values passed as arguments to syscalls. For more information about Seccomp, see Seccomp kernel documentation. The actions, architectures, and operators are strings that match the definitions in seccomp.h from libseccomp and are translated to corresponding values. A valid list of constants as of libseccomp v2.3.0 is shown below.^¶

Architecture Constants:^¶

Action Constants:^¶

Operator Constants:^¶

Example. 

{
  "linux": {
    "seccomp": {
      "defaultAction": "SCMP_ACT_ALLOW",
      "architectures": [
        "SCMP_ARCH_X86"
      ],
      "syscalls": [
        {
          "name": "getcwd",
          "action": "SCMP_ACT_ERRNO"
        }
      ]
    }
  },
  …
}

Example. 

{
  "linux": {
    "rootfsPropagation": "slave"
  },
  …
}

Example. 

{
  "linux": {
    "maskedPaths": [
      "/proc/kcore"
    ]
  },
  …
}

Example. 

{
  "linux": {
    "readonlyPaths": [
      "/proc/sys"
    ]
  },
  …
}

Example. 

{
  "linux": {
    "mountLabel": "system_u:object_r:svirt_sandbox_file_t:s0:c715,c811"
  },
  …
}

The SMF(Service Management Facility) FMRI which should go to "online" state before we start the desired process within the container.^¶

Example. 

{
  "solaris": {
    "milestone": "svc:/milestone/container:default"
  },
  …
}

The maximum set of privileges any process in this container can obtain. The property should consist of a comma-separated privilege set specification as described in priv_str_to_set(3C) man page for the respective release of Solaris.^¶

Example. 

{
  "solaris": {
    "limitpriv": "default"
  },
  …
}

The maximum amount of shared memory allowed for this application container. A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte). Mapped to max-shm-memory in zonecfg(8) man page.^¶

Example. 

{
  "solaris": {
    "maxShmMemory": "512m"
  },
  …
}

Sets a limit on the amount of CPU time that can be used by a container. The unit used translates to the percentage of a single CPU that can be used by all user threads in a container, expressed as a fraction (for example, .75) or a mixed number (whole number and fraction, for example, 1.25). An ncpu value of 1 means 100% of a CPU, a value of 1.25 means 125%, .75 mean 75%, and so forth. When projects within a capped container have their own caps, the minimum value takes precedence. cappedCPU is mapped to capped-cpu in zonecfg(8) man page.^¶

Example. 

{
  "solaris": {
    "cappedCPU": {
      "ncpus": "8"
    }
  },
  …
}

The physical and swap caps on the memory that can be used by this application container. A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte). cappedMemory is mapped to capped-memory in zonecfg(8) man page.^¶

Example. 

{
  "solaris": {
    "cappedMemory": {
      "physical": "512m",
      "swap": "512m"
    }
  },
  …
}

You can configure a container’s resource limits via the OPTIONAL resources field of the Windows configuration.^¶

{
  "windows": {
    "resources": {
      "memory": {
        "limit": 2097152,
        "reservation": 524288
      }
    }
  },
  …
}

{
  "windows": {
    "resources": {
      "cpu": {
        "percent": 50
      }
    }
  },
  …
}

{
  "windows": {
    "resources": {
      "storage": {
        "iops": 50
      }
    }
  },
  …
}

{
  "windows": {
    "resources": {
      "network": {
        "egressBandwidth": 1048577
      }
    }
  },
  …
}

The pre-start hooks are called after the container process is spawned, but before the user supplied command is executed. They are called after the container namespaces are created on Linux, so they provide an opportunity to customize the container. In Linux, for e.g., the network namespace could be configured in this hook.^¶

If a hook returns a non-zero exit code, then an error including the exit code and the stderr is returned to the caller and the container is torn down.^¶

The post-start hooks are called after the user process is started. For example this hook can notify user that real process is spawned.^¶

If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.^¶

The post-stop hooks are called after the container process is stopped. Cleanup or debugging could be performed in such a hook. If a hook returns a non-zero exit code, then an error is logged and the remaining hooks are executed.^¶

Example. 

{
  "hooks": {
    "prestart": [
      {
        "path": "/usr/bin/fix-mounts",
        "args": ["fix-mounts", "arg1", "arg2"],
        "env":  [ "key1=value1"]
      },
      {
        "path": "/usr/bin/setup-network"
      }
    ],
    "poststart": [
      {
        "path": "/usr/bin/notify-start",
        "timeout": 5
      }
    ],
    "poststop": [
      {
        "path": "/usr/sbin/cleanup.sh",
        "args": ["cleanup.sh", "-f"]
      }
    ]
  },
  …
}

path is REQUIRED for a hook. args and env are OPTIONAL. timeout is the number of seconds before aborting the hook. The semantics are the same as Path, Args and Env in golang Cmd.^¶