Cells for NetBSD – Kernel-enforced, jail-like Isolation with User-friendly Operations

This section demonstrates a minimal, reproducible workflow with the current
cellmgr command surface.

The example bootstraps the host, creates a desired cell manifest for a simple
HTTP service, adds a declarative apply plan, converges runtime state, and
checks that the cell is running.

1. Bootstrap Host Integration

Initialize host integration, prepare base layers, and verify that required
kernel/runtime prerequisites are present.

vhost# cellmgr system bootstrap 

2. Create Desired Cell Manifest

Create the desired-state manifest for one HTTP workload. This writes
configuration into /etc/cellmgr only (--scope desired) and does not yet
start the service.

vhost# cellmgr cell create mysite-edge-httpd \
  --autostart YES \
  --profile medium \
  --reserved-ports 8080 \
  --log-facility local1 \
  --stdout-level info \
  --stderr-level err \
  --log-tag cell-mysite-edge-httpd \
  --cmd '/usr/libexec/httpd -I 8080 -X -f -s /var/www/mysite-edge-httpd' \
  --healthcheck 'test -f /var/www/mysite-edge-httpd/index.html' \
  --scope desired
Created manifest /etc/cellmgr/mysite-edge-httpd.cell

3. Add Declarative Apply Plan

Define a small apply plan that creates the initial web content inside the cell.
Plans are declarative, versionable, and executed by cellmgr apply during
reconciliation.

vhost# vi /etc/cellmgr/mysite-edge-httpd.apply

Plan content:

FILE_BEGIN /var/www/mysite-edge-httpd/index.html

        Hello NetBSD

FILE_END

4. Converge Desired to Runtime

Run reconciliation to render runtime state from manifests, execute the apply
plan, start supervised service processes, and run the configured healthcheck.

vhost# cellmgr apply
apply: dry-run=NO reapply=NO restart-changed=NO verbose=NO
cell mysite-edge-httpd
  CREATE       render runtime cell state
  APPLY        run /etc/cellmgr/mysite-edge-httpd.apply
  START        supervised service after apply
  HEALTHCHECK  test -f /var/www/mysite-edge-httpd/index.html
  RESULT       changed

summary: cells=1 changed=1 failed=0 dry-run=NO

5. Verify Runtime State

Inspect the live cell view and confirm that the instance is running with an
assigned CID and increasing age.

vhost# cellmgr cell list -o name,running,cid,age
NAME               RUNNING  CID  AGE
mysite-edge-httpd  YES      1    31s

6. Open the Service

Confirm the HTTP endpoint from your client or browser:

http://vhost.local:8080/

7. Export Prometheus-Compatible Metrics

cellctl stats -P -h emits Prometheus text format with a minimal HTTP header.
This can be wired into inetd for a very lightweight metrics endpoint without
additional exporter software.

vhost# cellctl stats -P -h
HTTP/1.1 200 OK
Content-Type: text/plain

# TYPE cell_cpu_ticks_1s gauge
# TYPE cell_cpu_ticks_10s_avg gauge
# TYPE cell_processes_current gauge
# TYPE cell_references_current gauge
# TYPE cell_memory_vmsize_bytes gauge
# TYPE cell_age_seconds gauge
cell_cpu_ticks_1s⚡ 0
cell_cpu_ticks_10s_avg⚡ 0
cell_processes_current⚡ 1
cell_references_current💬 1
cell_memory_vmsize_bytes{cid="2",name="mysite-edge-httpd",root="/var/cellmgr/cells/mysite-edge-httpd/root"} 137601024
cell_age_seconds{cid="2",name="mysite-edge-httpd",root="/var/cellmgr/cells/mysite-edge-httpd/root"} 596

Next Steps

For deeper operational guides and reference material, continue in the
documentation.

The docs are still being built out, but they already include polished end-to-end
recipes, including a
MantisBT 3-tier setup (three cells, multiple volumes)
and a
Luanti gameserver example.