OCIFBSD(8) FreeBSD System Manager's Manual OCIFBSD(8)

ocifbsd — FreeBSD native OCI runtime

ocifbsd [-vhV] command [arguments]

ocifbsd is a FreeBSD-native OCI (Open Container Initiative) runtime. It maps OCI bundles to jail(8) parameters, manages container lifecycle state under /var/run/ocifbsd, and applies host-side mounts (nullfs, devfs, procfs, tmpfs, fdescfs) into the container rootfs on start.

The following commands are available:

[-n name] bundle
Create a container from an OCI bundle. The jail is created with persist so it remains until start or delete. Prints the 64-hex container id on stdout. If the bundle or image configuration does not specify a hostname, the container's hostname defaults to its name (or, absent a name, its id) so sysctl(8) kern.hostname inside the jail is never empty.
container-id
Start a created container (attach init process, apply mounts).
container-id [-s signal]
Send a signal to the container init process. Default is SIGTERM. Idempotent for already-stopped or never-started containers.
container-id [-f]
Delete a container and unmount applied mounts. Use -f to force deletion of a running container.
container-id
Show the current state of a container. The reported state is reconciled against the live jail: a container recorded as running or paused whose jail no longer exists (for example after a host reboot or an external jail(8) removal) is reported as stopped.
List known containers from the state directory. As with state, each container's status reflects actual jail liveness rather than only the last value written to the state file.
container-id
Show detailed container metadata as JSON.
[-n name] bundle
Create and start a container in one command.
[-n | --dry-run] reference
Parse an OCI image reference and print registry, repository, tag, and store path (default /var/lib/ocifbsd, overridable with OCIFBSD_DATA_DIR). With -n only resolve and print. Without -n, fetch the manifest and layers via the OCI Distribution API into that path.
[-n reference] archive
Import a local OCI image into the image store. archive may be a directory in OCI image-layout form (oci-layout, index.json, blobs/) or a .tar, .tar.gz, or .tar.xz archive of that layout, such as the container images published at https://download.freebsd.org/releases/OCI-IMAGES/. The image layers are verified against their manifest digests and unpacked into a rootfs, and a runtime config.json is generated from the image configuration, so the result can be run with create --image or run --image. With -n the store entry is named by the given reference instead of the archive's org.opencontainers.image.ref.name annotation.
List top-level entries under the local image store (/var/lib/ocifbsd). An empty or missing store is not an error.
[-f] reference
Remove the local image store for reference. By default this is refused if a container was created from that image (its bundle still points at the store), so that removing the image cannot delete a running container's root filesystem; the error names the container. -f (--force) removes the image anyway.
list [container]
Show the network configuration (VNET, IPv4/IPv6 addresses, gateways, and DNS servers) of one container, or of every container when no argument is given. Requires view privilege (root or the ocifbsd group).
set container [options]
Modify a container's persisted network configuration. Options accumulate onto the existing configuration:
on|off
Enable or disable VNET (network stack isolation).
cidr, --ip6 cidr
Add an IPv4 or IPv6 address in CIDR form (addr/prefix); may be repeated.
addr, --gateway6 addr
Set the default IPv4 or IPv6 gateway.
addr
Add a DNS nameserver; may be repeated.
, --clear-ip4, --clear-ip6, --clear-dns
Remove all, or a specific class of, address/DNS entries.
Every value is validated before being stored; an invalid address is rejected and the configuration is left unchanged. The configuration is written to /var/lib/ocifbsd/networks/⟨id⟩.json with mode 0640, group-owned by the ocifbsd group. Requires modify privilege (root or the ocifbsd group).

Runtime state under /var/run/ocifbsd and generated config.json files are created mode 0750/0640 and group-owned by the ocifbsd administrative group when it exists, so that only root and members of that group can view or modify container configuration. When the group does not exist, access is restricted to root only. The network subcommands additionally enforce this policy in-process: viewing requires membership in that set, and modifying requires it as well.

Global options (before the command):

, --verbose
Enable verbose output.
, --pretty
Pretty-print JSON output with indentation for the commands that emit JSON (inspect, state). This is the default; the flag is accepted for explicitness.
, --compact
Print JSON as a single compact line instead of the pretty-printed default, for scripts and pipelines.
, --help
Show help message and exit.
, --version
Show version information and exit.

Subcommand options:

name, -name name
Human-readable name for create and run (also used in jail naming).
signal, -signal signal
Signal for kill (number or name).
, --force
Force delete of a running container.

Override the image and volume data directory (default /var/lib/ocifbsd).
Override the runtime state directory (default /var/run/ocifbsd), useful for tests or an unprivileged, self-contained instance.
Override the path to the registry alias table (see FILES).

Beyond the standard OCI runtime fields, the bundle config.json recognizes a freebsd object and honors a subset of linux.resources. All are opt-in: an absent field leaves the corresponding behavior at its open default.

Boolean. When true the container runs in its own network stack (vnet(9)). The runtime creates an epair(4) pair, moves one end into the jail, and destroys it again on delete.
, ip6
Array of CIDR addresses assigned to the container interface inside the jail (the first is configured automatically when ifconfig(8) is present in the image).
, defaultGateway6
Array; the first entry becomes the container's default route.
Name of a host if_bridge(4) to which the host side of the epair is added, giving the container external reachability. The bridge is created if it does not exist and is left in place on delete (it may be shared).
A mac(4) label (for example “biba/high”) applied to the container's init process via mac_set_proc(3). It takes effect only when the matching labeling policy is loaded (policies load at boot, e.g. mac_biba_load=YES); otherwise start warns that the label will not be enforced.

When present, the runtime maps these onto rctl(8) rules on the jail, applied at start and removed at delete. This requires kern.racct.enable=1; without it start warns and proceeds unbounded.

Bytes; mapped to the jail memoryuse limit.
, cpu.period
Microseconds; the quotient (quota / period × 100) becomes the jail pcpu percentage (a value over 100 spans multiple cores).
Process count; mapped to the jail nproc limit.

/var/run/ocifbsd/
Runtime state directory (per-container JSON)
/var/lib/ocifbsd/
Image and volume data directory (future image store)
/var/lib/ocifbsd/networks/
Per-container network configuration (network set)
/etc/ocifbsd/
Configuration directory
/usr/local/etc/ocifbsd/registries.conf, /etc/ocifbsd/registries.conf
Registry alias table: maps a registry reference name to its API host and token endpoint, selects the transport (TLS by default; plain HTTP for registries marked insecure and for localhost), and sets the default registry for unqualified image references via a default-registry directive (default docker.io). Built-in defaults cover the default public registry, so this file is optional. See the shipped example for the format.

Create a container from an OCI bundle:

ocifbsd create --name my-container /path/to/bundle

Start, inspect state, signal, and delete:

ocifbsd start <id>
ocifbsd state <id>
ocifbsd kill <id>
ocifbsd delete --force <id>

Create and run in one command:

ocifbsd run --name web /path/to/bundle

jail(3), mac_set_proc(3), epair(4), if_bridge(4), mac(4), ocifbsd.conf(5), ifconfig(8), jail(8), mount(8), rctl(8)

ocifbsd was developed to provide native OCI runtime support for FreeBSD. Phase 1 acceptance covers create/start/state/kill/delete with ATF unit and root integration tests on FreeBSD lab hosts.

ocifbsd was developed by REVYTECH, Inc., including the lifecycle and test work on the feature/oci-bootstrap branch.

FreeBSD 16.0-CURRENT July 22, 2026 OCIFBSD(8)