Command Examples

# Resolve an image reference without touching the network
$ ocifbsd pull docker.io/library/freebsd:15.1 --dry-run
reference=docker.io/library/freebsd:15.1
registry=docker.io
repository=library/freebsd
tag=15.1
store_path=/var/lib/ocifbsd/docker.io/library/freebsd/15.1

# Import a local OCI image archive into the store
$ ocifbsd load --name freebsd:15.1 FreeBSD-15.1-RELEASE-amd64-container-image.txz

# List images in the local store
$ ocifbsd images
REPOSITORY                   TAG    PATH
docker.io/library/freebsd    15.1   /var/lib/ocifbsd/docker.io/library/freebsd/15.1

# Create and start a container from the image in one step
$ ocifbsd run --name web --image docker.io/library/freebsd:15.1
9db0fb6dc0870e46ca47f6926c4744715939bc6531199246543edb1a75ed1c94

# The container is a native jail sharing the host kernel
$ ocifbsd exec 9db0fb6dc087 /usr/bin/uname -a
FreeBSD  15.1-STABLE FreeBSD 15.1-STABLE stable/15 GENERIC amd64
$ ocifbsd exec 9db0fb6dc087 /usr/bin/id
uid=0(root) gid=0(wheel) groups=0(wheel),5(operator)
$ ocifbsd exec --cwd /tmp 9db0fb6dc087 /bin/pwd
/tmp

# With no hostname in the image config, the container takes its name
$ ocifbsd exec 9db0fb6dc087 /bin/hostname
web

# Inspect full metadata as JSON
$ ocifbsd inspect 9db0fb6dc087
{"id": "9db0fb6d...","name": "web","state": "running","created": 1788079471,
 "started": 1788079471,"finished": 0,"exit_code": 0,
 "bundle": "/var/lib/ocifbsd/docker.io/library/freebsd/15.1",
 "rootfs": "/var/lib/ocifbsd/docker.io/library/freebsd/15.1/rootfs"}

# state/list report actual jail liveness: a container whose jail is
# gone (host reboot, external jail -r) is reported stopped, not running

# Two-step: create (persist) then start
$ ocifbsd create --name build --image docker.io/library/freebsd:15.1
0031b99442b3483338a1ae562d885292d3029dc16774cb87c98033b6a57ec52b
$ ocifbsd state 0031b99442b3
{"id":"0031b99442b3...","status":"created"}
$ ocifbsd start 0031b99442b3

# Pause and resume freeze/thaw every process in the jail
$ ocifbsd pause 0031b99442b3
{"id":"0031b99442b3...","status":"paused"}
$ ocifbsd resume 0031b99442b3
{"id":"0031b99442b3...","status":"running"}

# Graceful stop (SIGTERM, then SIGKILL after the timeout), then delete
$ ocifbsd stop --timeout 5 0031b99442b3
{"id":"0031b99442b3...","status":"stopped"}
$ ocifbsd delete 0031b99442b3

# Remove an image from the store
$ ocifbsd rmi scratch:1.0
deleted=/var/lib/ocifbsd/docker.io/library/scratch/1.0

# View a container's network configuration
$ ocifbsd network list web
CONTAINER: web (id 3dbca749f8ec)
  vnet:      enabled
  ip4:       10.0.0.5/24, 10.0.0.6/24
  ip6:       2001:db8::5/64
  gateway4:  10.0.0.1
  dns:       1.1.1.1

# Modify it; every address is validated before being stored
$ ocifbsd network set web --vnet on --ip4 10.0.0.7/24 --gateway4 10.0.0.1
updated network configuration for web

# An invalid address is rejected and nothing is changed
$ ocifbsd network set web --ip4 999.0.0.1/24
error: invalid value: 999.0.0.1/24

# Only root or the 'ocifbsd' group may view or modify it
$ ocifbsd network list web
error: permission denied: viewing container network configuration
       requires root or the ocifbsd group

# Usage
$ ocifbsd-gc -h
Usage: ocifbsd-gc [-fvh]
  -f  Run in foreground
  -v  Verbose output
  -h  Show this help

# Run a single collection pass in the foreground, verbose
# (scans container, image, volume and network state and reclaims
#  orphaned or TTL-expired resources)
$ ocifbsd-gc -fv

# Enable and start the periodic collector at boot
$ sysrc ocifbsd_gc_enable=YES
ocifbsd_gc_enable:  -> YES
$ service ocifbsd-gc start
Starting ocifbsd_gc.

# Run in the foreground at info level with an explicit config
$ ocifbsd-logd -f -l info -c /etc/ocifbsd/logd.conf
logd: ring buffer 65536 entries, rotate to /var/log/ocifbsd/
logd: forwarding 0 endpoints, 0 alert rules loaded

# Enable the aggregation daemon at boot
$ sysrc ocifbsd_logd_enable=YES
$ service ocifbsd-logd start
Starting ocifbsd_logd.

# List managed certificates (none issued yet -> empty JSON array)
$ ocifbsd-cert list
[]

# Verify certificate health / expiry
$ ocifbsd-cert check

# Rotate the runtime's EC P-256 key material and re-issue
$ ocifbsd-cert rotate
{"rotated":1,"algorithm":"ec-p256","not_after":"2027-08-30T00:00:00Z"}

# Back up the certificate store
$ ocifbsd-cert backup
backup=/var/db/ocifbsd/cert/backup-20260830.tar

# Subcommands
$ ocifbsd-export
Usage: ocifbsd-export <command> [args]
Commands: export, import, list, status

# Export statistics so far
$ ocifbsd-export list
{"total":0,"successful":0,"failed":0,"bytes_exported":0,
 "bytes_uploaded":0,"last_export":0}

# Export a container image as a cloud machine image (AWS/GCP/Azure)
$ ocifbsd-export export --format aws --image freebsd:15.1
{"format":"aws","image":"freebsd:15.1","artifact":"ami-builder.raw",
 "bytes_exported":1181116006,"status":"uploaded"}

# Reference the module from a service's PAM configuration.
# It authenticates against the ocifbsd user registry and enforces
# RBAC role bindings and per-user rate limits.
auth       required     pam_ocifbsd.so
account    required     pam_ocifbsd.so
session    optional     pam_ocifbsd.so

# A login that maps to an RBAC role binding
$ ocifbsd login --user operator
Password:
authenticated: user=operator role=container-operator (rate 60/min)

/* Pull and unpack an OCI image, then verify layer digests. */
#include <ocifbsd/image/pull.h>
#include <ocifbsd/image/unpack.h>

struct pull_ctx *ctx = pull_new("docker.io/library/freebsd:15.1");
if (pull_fetch(ctx, "/var/lib/ocifbsd") != 0)
        return (-1);
unpack_layer(layer_tgz, rootfs, /*whiteouts=*/NULL);

# The same library backs the pull/load/images/rmi verbs
$ ocifbsd pull docker.io/library/freebsd:15.1 --dry-run
store_path=/var/lib/ocifbsd/docker.io/library/freebsd/15.1

/* Attach a VNET jail to a bridge for isolated networking. */
#include <ocifbsd/network.h>

network_init();
bridge_create("ocibr0");
vnet_setup(jid, "epair0b");   /* move epair into the jail's VNET */
cni_invoke(container_id, netns); /* optional CNI plugin */

/* Declare a pod, deploy it, and scale replicas. */
#include <ocifbsd/orchestration.h>

struct orch_config cfg = { .max_pods = 64 };
orch_init(&cfg);
pod_create(&spec);
pod_scale("web", 3);    /* 3 replicas */
health_check_pod("web");
rolling_update(&new_spec); /* zero-downtime roll */

/* Apply RCTL resource limits and a MAC label to a jail. */
#include <ocifbsd/security/rctl.h>
#include <ocifbsd/security/mac.h>

rctl_apply(jid, "memoryuse:deny=512M");
rctl_apply(jid, "pcpu:deny=50");
mac_label_set(jid, "biba/low");

# Resource limits enforced by RCTL show up on the host
$ rctl -h jail:ocifbsd_web
jail:ocifbsd_web:memoryuse:deny=512M
jail:ocifbsd_web:pcpu:deny=50