Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Blackship
A FreeBSD jail orchestrator with TOML configuration, dependency management, state machine lifecycle control, and ZFS integration.
Documentation
The README is the quick reference. The manual is built for every release and attached to it: the complete operator guide, architecture, configuration, command reference, integration, security model, and troubleshooting material.
Features
- Declarative Configuration: Define jails in TOML with dependencies, networking, hooks, and resource limits
- Dependency Management: Real dependency-graph traversal for start/stop ordering; target jails by name, unambiguous prefix, tag, or ALL
- State Machine Lifecycle: Clean state transitions, devfs mounted per jail, /etc/rc boot and /etc/rc.shutdown on stop
- Hot Updates (EVA):
blackship evadiffs the config against running jails and applies parameter, rctl, and cpuset changes live via jail_set(JAIL_UPDATE) -- no restart, with drift warnings for changes that need one - VNET Networking: epair (if_bridge) and native netgraph (ng_bridge) backends, named networks with automatic host gateway wiring, deterministic MAC addresses
- Instant Provisioning: releases bootstrap into datasets with a @pristine snapshot; jail roots are zfs clones, created in under a second
- Jailfile Builds with Layer Cache: every RUN/COPY is snapshotted; rebuilds resume from the longest cached prefix like a Docker layer cache
- blackship commit: freeze a configured jail into a reusable release (zero-copy snapshot + clone + promote)
- pkgbase Bootstrap: FreeBSD 16+ userlands from fingerprint-verified base package repos (automatic; --pkgbase opts in earlier)
- Resource Limits: rctl (memory, pcpu, maxproc, openfiles, ...) plus cpuset pinning with least-loaded core allocation
- Health Checks & Supervision: HTTP, TCP, and command checks; warden auto-restart; optional dead-man ping to healthchecks.io/Uptime Kuma
- Migration & Import: zfs send | ssh zfs receive between hosts with the jail definition staged inside the dataset; import from iocage, ezjail, or plain rootfs archives
- Stats: per-jail CPU, RSS, and process counts from jls/ps libxo JSON
- Port Forwarding: PF-based port exposure with source IP binding
- Shell Completion: Bash, Zsh, and Fish completions
- Library API:
Host,Container,Execand friends drive ephemeral jails from your own program (a CI runner, say); the CLI is built on the same calls - MCP Server:
blackship mcp(stdio, or Streamable HTTP with a bearer token) exposes host facts, the real parsers, and operator-approved file creation over MCP, so a model can author ablackship.tomlor Jailfile against this host instead of guessing
Requirements
- FreeBSD 15.0+ with jail support
- ZFS (optional, for snapshots/clones)
- PF (optional, for port forwarding)
Building from source also needs a C compiler and the base system headers:
the ioctl request codes and netgraph message constants are read out of
/usr/include at build time rather than hardcoded. Both ship with a
default FreeBSD install. The crate does not build on other operating
systems.
Installation
# Install from crates.io
# Or download precompiled binary from releases
# Install shell completion (optional)
Default Paths
Blackship uses XDG-compliant user directories by default:
| Path | Default | Environment Override |
|---|---|---|
data_dir |
~/.local/share/blackship |
XDG_DATA_HOME |
releases_dir |
~/.local/share/blackship/releases |
- |
cache_dir |
~/.cache/blackship |
XDG_CACHE_HOME |
These defaults allow running blackship without root for most operations. Override in blackship.toml for system-wide paths:
[]
= "/var/blackship"
= "/var/blackship/releases"
= "/var/blackship/cache"
Note: While paths are user-writable by default,
bootstrapextraction requires root privileges because FreeBSD base archives contain root-owned files with special permissions (setuid binaries, etc.). Blackship will re-exec through FreeBSD'smdowhen the current user has an applicablemac_dorule, then fall back todoasorsudo.
Automatic privilege escalation can be controlled globally:
# Fail instead of re-executing through mdo, doas, or sudo
# Allow escalation, but never prompt for authentication
--non-interactive passes -n to doas and sudo. FreeBSD's mdo is
already non-interactive: authorization comes entirely from mac_do, without a
password prompt. --no-escalate takes precedence when both options are used.
Quick Start
1. Initialize Jailfile
# Create a Jailfile in current directory
# Create with specific FreeBSD release
# TOML format instead of Dockerfile-like
2. Initialize Armada Configuration
Create blackship.toml:
[]
# Paths default to XDG directories (~/.local/share/blackship, ~/.cache/blackship)
# Uncomment to use system-wide paths:
# data_dir = "/var/blackship"
= true
= "zroot"
= "blackship"
[[]]
= "web"
= "15.1-RELEASE"
= "web.local"
[]
= true
= ["default"]
= "blackship0"
= "10.0.1.10"
= "10.0.1.1"
Or use blackship armada init to generate a template.
3. Bootstrap a Release
# Download and extract FreeBSD base (requires root for extraction).
# With ZFS enabled the release lands in its own dataset with a @pristine
# snapshot, so jails clone-provision from it instantly.
# FreeBSD 16 has no dist sets, so pkgbase is used automatically
# (16.0 is still -CURRENT; --pkgbase opts in on older branches)
# List available releases
4. Create Network
# if_bridge network with gateway on the bridge (requires root)
# netgraph network: ng_bridge plus a host-side gateway eiface, wired
# automatically; jails attached to it inherit the netgraph backend
Networks persist across reboots: blackship setup (run by the warden rc
script at boot) recreates missing bridges and gateway interfaces. If PF is
not running yet, blackship setup --enable-pf writes a minimal pf.conf with
the blackship anchors, sets pf_enable=YES, and starts it. Jails reach
beyond the host only through a NAT rule you add; see
Outbound traffic.
Named networks created this way can be referenced from blackship.toml with
[jails.network] networks = ["default"], and the same network can be used by
ephemeral jails with blackship run --network default. Those get the
host's /etc/resolv.conf, minus nameservers on the host's loopback that a
VNET stack cannot reach; when that leaves nothing (a host on
local_unbound), run refuses and asks for --dns <ip>.
5. Start Jails
# Start a specific jail
# Start all jails
# Dry run (show what would happen)
6. Interact with Jails
# Open console
# Execute command
# Check status
Using Blackship as a Library
Everything blackship run, cp, rm, bootstrap, build and commit
do is a library call first; the CLI is a thin coat of paint over it. A CI
runner (or anything else that wants throwaway jails) can depend on the crate
and skip the binary, the argument parser, the MCP server and the OTLP
exporter:
[]
= { = "0.3", = false }
use ;
use Duration;
let host = new.with_zfs;
// Whatever a crashed run left behind goes first.
host.reap_orphans?;
host.ensure_release?;
let job = host.create?;
let step = job.exec?;
println!;
job.copy_out?;
job.destroy?;
The rules of the road:
Hostis a description, not a connection: where releases, containers and state live, and which dataset backs them. Clone it freely; containers carry their own copy, so many can run on many threads with no shared mutable state.- Containers are ephemeral. Dropping a
Containerdestroys it. Callkeep()to let it outlive the handle (that is whatrun --detachdoes),hand_over(pid)to give it to another process (a root helper creating containers for a daemon), anddestroy()when you want to see the errors a drop would swallow. - Networking:
Network::None(the default),Inherit(the host's stack and resolver) orVnet(name)(a leased address on a Blackship network and the host's resolver, minus loopback nameservers it cannot reach).nameserver(ip)overrides the resolver either way. - Mounts are nullfs.
read_writemounts arenosuidunless you callallow_setuid();noexec()andnosuid()apply to either kind. These flags cover the jail-side mount only: the host path is as setuid-capable as its own filesystem, so keep host directories that jobs write to on asetuid=offdataset when other users can reach them. execruns argv orsh -cwith a clean environment, a working directory, and a timeout or deadline. Output is captured, streamed to a callback, or inherited. A non-zero exit is data, not an error. On timeout every process in the container is killed from the host side (pkill -j), so nothing inside can dodge it.- Destroy is idempotent and works from any state: running, half-built,
or left behind by a
kill -9. It removes the jail, unmounts devfs and nullfs (refusing to delete anything while a mount is still live), releases the network lease, and destroys the clone. - Orphans are containers whose creating process is gone. Each one is
claimed with an ownership record before anything is built, so
orphans()/reap_orphans()find them by name prefix or label after a crash. A handed-over container is an orphan once its new owner is gone. Kept containers have no owner and are never reaped. - Releases and images:
releases(),has_release(),bootstrap()andensure_release()(FreeBSD 16 goes through fingerprint-verified pkgbase automatically).build()runs a Jailfile with the layer cache,commit_image()andContainer::commit()freeze a root into a new release, andremove_image()/remove_release()clean up. Baking an image by installing base packages in a container needsContainerSpec::allow_chflags(): pkgbase sets file flags. - Privilege: library calls assume they already run as root and return
Error::NeedsRoototherwise. Only the CLI re-executes throughmdo,doas, orsudo; callers can disable that with--no-escalateor prevent prompts with--non-interactive. - Errors are one typed
blackship::Errorenum. Noanyhowin sight.
examples/ephemeral.rs walks the whole lifecycle:
tests/containers_as_root.rs holds the end-to-end suite (timeouts, mounts,
orphan reaping, concurrency, build and commit); it runs only as root, against
a release you name:
Cargo features
| Feature | Default | What it brings |
|---|---|---|
cli |
yes | The blackship binary and its usage-rs parser; implies telemetry |
mcp |
yes | blackship mcp (mcp-host, schemars, tracing); implies cli |
telemetry |
via cli |
OTLP export through rama; without it [telemetry] still parses and does nothing |
ui |
no | blackship ui, a placeholder web page served by rama (see Web UI); implies cli |
inspect |
no | state machine introspection |
Machine-readable CLI
Automation can opt into a versioned JSON contract with the global
--format json option. As an inherited global, it works before or after the
selected command (blackship --format json capabilities and
blackship capabilities --format json are equivalent). The first contract
version covers the read-only commands most useful to management UIs:
Successful commands write an envelope to standard output:
Failures, including command-line parsing errors, exit non-zero and write a single JSON object to standard error. Error codes are stable identifiers intended for program logic; messages remain for people and diagnostics:
Commands without a complete JSON contract fail with
unsupported_output_format; they never fall back to mixed human-readable
output. Streaming modes such as health --watch are intentionally excluded
from the single-envelope contract. Existing command-local flags such as
blackship ps --json retain their original, unenveloped output for
compatibility.
blackship capabilities requires neither a manifest nor root access. Its JSON
report lets clients discover the Blackship version, output schema, compiled
features, FreeBSD kernel capabilities, host facilities, and installed privilege
escalators before enabling UI actions. The cli.machine_output array lists
each exact command mode that supports the global JSON contract, using a stable
operation identifier plus its privilege and mutation behavior. Clients should
check for the operation instead of inferring support from the Blackship version:
|
A new command mode with a JSON contract must register an operation id in
OPERATION_SPECS (src/commands/capabilities.rs) and in the test's candidate
table; a test fails when a JSON-capable mode has no row or a row has no JSON mode.
Only the --dry-run forms of up, down, restart, eva and autostart have
a JSON contract, so only those appear.
blackship host returns the same best-effort planning profile as the
blackship:///host MCP resource: kernel and facility capabilities, CPU and
memory capacity and claims, ZFS pools, releases, networks and available
addresses, PF state, manifest jails, and unmanaged running jails. Probes that
cannot run unprivileged report null or a local error instead of failing the
whole profile.
blackship ps --host adds running jails outside the selected manifest to the
configured Blackship inventory. Its result identifies each row's manager and
ownership, includes the selected project, the first config path
(config_path) and every merged path (config_paths), and includes a
passive, last-known health summary. ps --host never executes health checks or
recovery actions: health and supervise atomically refresh the summary under
<data_dir>/health. The summary reports why a result is unknown (for example,
stopped, not_checked, stale_jid, or unmanaged) and includes its
checked_at timestamp so clients can judge freshness. A cycle that was shed by
health_concurrency or that errored never refreshes the timestamp, and
supervise --autostart monitors only the autostart jails, so the others report
not_checked. The counts are the last result of each check, not the verdict,
and nothing expires them: judge freshness by checked_at (a paced or slow
supervisor can leave it older than the check interval). A restarted jail reads
stale_jid until the supervisor's checker, which follows the new JID, reports
again. Snapshots are deleted on stop, rm, cleanup and gc, and a one-shot
health inside the start period does not replace a settled result. Stopped unmanaged jails
cannot be discovered without a known manifest and are therefore not reported.
Lifecycle commands support the global JSON format in dry-run mode. Their
data object contains the requested operation and its ordered steps, allowing
management tools to preview dependency-aware changes without parsing terminal
text or modifying the host. Live lifecycle operations remain text-only.
Configuration Reference
Global Config
[]
= "orbital" # Jail name prefix (default: the config file's directory name)
# All paths are optional - defaults to XDG directories
= "~/.local/share/blackship" # Base data directory (default)
= "~/.local/share/blackship/releases" # FreeBSD releases (default)
= "~/.cache/blackship" # Download cache (default)
= "https://download.freebsd.org" # FreeBSD mirror
= true # Enable ZFS features
= "zroot" # ZFS pool name
= "blackship" # Base dataset name
= "https://hc-ping.com/…" # Dead-man ping from the supervisor (optional)
With ZFS enabled the jails dataset is mounted at data_dir/jails, so jail
roots live at the same paths whether or not they are datasets. Blackship sets
that mountpoint only when it creates the dataset; every jail dataset carries
its own mountpoint, so a run with a different data_dir no longer drags the
shared parent along with it.
Running jails are named <project>-<name>: jail web in project orbital
runs as orbital-web, which is what jls and ps show. Commands take
either form. Without project, the name comes from the directory holding
blackship.toml, however you spell its path.
Jail Definition
[[]]
= "myapp" # Jail name (required)
= "15.1-RELEASE" # Base release (clone-provisioned when @pristine exists)
= "/jails/myapp" # Custom path (optional; default data_dir/jails/<name>)
= "myapp.local" # Hostname
= ["database"] # Dependencies
= ["autostart", "web", "prod"] # `autostart` is reserved; others select groups
= 4 # devfs ruleset (default 4; 0 disables devfs)
= true # Run /etc/rc at start, /etc/rc.shutdown at stop (default)
= "service nginx stop" # Run inside the jail before teardown (overrides Jailfile STOP)
[]
# Host directory mounted below the jail root through nullfs. Manifest volumes
# are always read-only, nosuid and noexec; they attach on start and detach on stop.
# The source is checked at start, and targets cannot share or nest.
= ["/home/me/src/myapp:/workspace/myapp:ro"]
[]
= "1g" # rctl memoryuse:deny
= "150" # rctl pcpu:deny (percent)
= 200 # rctl maxproc:deny
= 2 # Pin to N least-loaded CPUs
# cpuset = "0,1" # Or pin to an explicit CPU list
[]
= true # Enable VNET
= ["default"] # Named networks to attach to
= "blackship0" # Optional if runtime network state defines a bridge
= "10.0.1.10" # Static IP, or omit for auto-assignment
= "10.0.1.1" # Optional if resolved from named network
= "02:00:00:00:00:01" # Static MAC (default: deterministic from jail name)
# backend = "netgraph" # Inherited from the named network when omitted
# shared = true # Share the host's network (ip4=inherit); ignored if vnet=true
[]
= ["8.8.8.8", "8.8.4.4"] # DNS servers
= "custom" # custom or inherit
[]
= true
[[]]
= "http"
= "curl -sf http://localhost:80/health"
= "jail"
= 30
= 10
= 3
[[]]
= "process"
= "pgrep nginx"
= "jail"
[[]]
= "pre_start" # pre_create, post_create, pre_start, post_start,
= "host" # pre_stop, post_stop, pre_eva, post_eva
= "/usr/local/bin/fetch-secrets" # A program, not a shell line
= ["${jail_name}"] # also ${jail_path}, ${jail_ip}, ${jid}
= "abort" # abort or continue
[[]]
= "pre_stop"
= "jail"
= "/usr/sbin/service"
= ["nginx", "stop"]
= "continue"
A hook's command is executed directly, with args as its arguments; it is
not passed through a shell, so command = "service nginx stop" looks for a
program by that whole name. Wrap shell syntax yourself:
command = "/bin/sh", args = ["-c", "..."]. post_start hooks run after
the jail is up, so on_failure = "abort" there only warns: the jail keeps
running.
Commands
Lifecycle
| Command | Description |
|---|---|
blackship up [target] [--all] [--dry-run] |
Start jail(s) with dependencies |
blackship down [target] [--all] [--dry-run] |
Stop jail(s) in reverse order |
blackship restart [target] [--all] [--dry-run] |
Restart jail(s) |
blackship eva [target] [--all] [--dry-run] |
Hot-update running jail(s) to match the config, no restart |
blackship autostart [--dry-run] |
Reconcile the project to its autostart tags |
Targets accept a jail name, an unambiguous prefix, a tag (from tags = [...]
in the jail definition), or ALL.
Start at boot
Add the reserved autostart tag to each jail that should run after boot:
[[]]
= "web"
= ["database"]
= ["autostart", "web"]
blackship autostart --dry-run previews the desired project state. Running
blackship autostart stops project jails outside that state, then starts the
tagged jails and their dependencies in dependency order. A dependency such as
database therefore starts at boot without needing its own tag. A jail that
fails to stop is reported at the end and never blocks the start pass. With no
autostart tags it stops every project jail and starts nothing.
blackship supervise --autostart is start-only: it starts the effective set and
never stops anything, so restarting the warden leaves a jail you started by hand
alone. Only the explicit blackship autostart prunes. With no tags it starts
nothing. "Started" means the jail exists and its /etc/rc has been launched
(init = true); services may still be coming up, so judge readiness by health
checks, not by the command returning.
blackship supervise keeps its existing behavior of starting and monitoring
every configured jail. The packaged rc service uses that behavior by default.
Enable its autostart mode to reconcile and monitor only the effective boot set:
The rc service runs blackship setup first, then launches
blackship supervise --autostart; it does not briefly start the entire fleet.
With no autostart tags, that mode starts no project jails. Leave
blackship_warden_autostart at its default NO to retain the all-jails
behavior. ps JSON reports both the raw tags and the effective autostart
value (including dependencies).
eva recomputes each jail's parameters from the config, diffs them against
the live values from jls, and applies only the changes in one
jail_set(JAIL_UPDATE) call. rctl rules are replaced only when they differ from
what the kernel holds (sizes compared in bytes), and the cpuset is re-pinned.
path, vnet, and IP addresses cannot change live: drift on those, including
a VNET jail's address read from inside its stack, is reported as a
restart-required warning and skipped. Not-running jails are skipped.
--dry-run prints the diff without touching anything; run unprivileged, it
cannot read a VNET address or the kernel's rctl rules and lists them as
"could not be read, not verified".
| Command | Description |
|---|---|
blackship ps [--host] [--json] |
List manifest jail status; --host also includes other running host jails |
blackship check |
Validate configuration; warn on jail releases not bootstrapped |
blackship capabilities |
Report binary and host capabilities |
blackship host |
Report the comprehensive host planning profile as JSON |
blackship setup [--enable-pf] |
Reapply networks and PF anchors; --enable-pf turns PF on |
blackship cleanup <jail> [--force] |
Clean up failed jail resources |
blackship init [-f file] [--release] [--toml] |
Create a new Jailfile |
Console & Execution
| Command | Description |
|---|---|
blackship console <jail> [-u user] |
Open interactive shell |
blackship exec <jail> [-u user] [-w dir] [-e K=V] [--clear-env] -- <cmd> |
Execute command in jail (--clear-env starts from an empty environment, keeping only -e values) |
blackship run --name <n> --release <r> [--network <net>] [--dns <ip>] -- <cmd> |
Run a command in an ephemeral jail, removed when it exits |
blackship run --name <n> --release <r> [--network <net>] [--dns <ip>] -d |
Start an ephemeral jail and leave it running (no command; use exec, then rm) |
File Operations
| Command | Description |
|---|---|
blackship cp <src> <dest> |
Copy files (jail:path for jail paths; short or full jail name) |
blackship rm <jails...> [-f] [--volumes] |
Remove/destroy jails; exits non-zero if any was not removed (missing, or running without -f) |
Bootstrap & Releases
| Command | Description |
|---|---|
blackship bootstrap <release> [-f] [-a archives] [--pkgbase] |
Download FreeBSD release (pkgbase automatic for 16+) |
blackship releases [list|delete|verify] [--json] |
Manage releases |
Networking
| Command | Description |
|---|---|
blackship network create <name> -s <subnet> [-g gw] [-b bridge] [--backend epair|netgraph] |
Create network (requires root) |
blackship network destroy <name> [--force] |
Destroy network (requires root) |
blackship network list |
List Blackship-managed networks |
blackship expose <jail> -p <port> [-I bind-ip] [--proto tcp|udp] |
Expose port |
blackship ports [jail] |
List exposed ports |
Snapshots & Clones (requires ZFS)
| Command | Description |
|---|---|
blackship snapshot create <jail> [name] |
Create snapshot |
blackship snapshot list <jail> [--json] |
List snapshots |
blackship snapshot rollback <jail> <snap> [--force] |
Rollback to snapshot |
blackship snapshot delete <jail> <snap> |
Delete snapshot |
blackship clone <jail>@<snap> <newname> |
Clone from snapshot |
blackship commit <jail> <release> |
Freeze a jail into a reusable release (zero-copy) |
Snapshots (and commits) stage the jail definition at .blackship/ inside
the dataset, so zfs send carries everything needed to rebuild the jail.
Export & Import
| Command | Description |
|---|---|
blackship export <jail> [-o file] [--zfs-send] |
Export to archive |
blackship import <file> [-n name] [--force] |
Import from archive |
blackship import <file> --from iocage|ezjail|rootfs|auto [-n name] |
Import from another jail manager |
blackship migrate <jail> user@host [--remote-dataset ds] [--keep] |
Move a jail to another host over ssh; fences the source |
blackship migrate --resume <jail> |
Finish a migration a kill or crash interrupted |
blackship migrate --abort <jail> |
Roll an interrupted migration back: remove the partial destination and the snapshot |
blackship unfence <jail> |
Lift the fence a migration left on a jail, so it can start here again |
Build System
| Command | Description |
|---|---|
blackship build [-f Jailfile] [-n name] [--build-arg K=V] [--dry-run] |
Build from Jailfile (ZFS layer cache: unchanged steps print CACHED) |
blackship template list |
List templates |
blackship template inspect <file> |
Show Jailfile details |
blackship template validate <file> |
Validate Jailfile |
Health & Monitoring
| Command | Description |
|---|---|
blackship health [jail] [-w] [-i interval] [--json] |
Health check status |
blackship stats [jail] [--json] |
Per-jail CPU, RSS, and process counts |
blackship supervise [--autostart] |
Supervise all jails; with --autostart, reconcile and supervise only the boot set |
blackship logs <jail> [-f] [-n lines] |
Tail jail logs |
blackship audit <jail> [--json] |
Durable lifecycle history, peak usage, exit reason |
blackship qos <jail> [--show|--steady|--startup] |
Inspect or switch the QoS profile |
blackship gc [jail] [--dry-run] [--force] [--json] |
Reclaim orphaned jail resources |
Armada (Multi-Jail Orchestration)
| Command | Description |
|---|---|
blackship armada init [-f file] |
Create a new blackship.toml |
blackship armada up [-d] [jails...] |
Start all jails (builds a missing root through the same ZFS-aware path as blackship build) |
blackship armada down [jails...] |
Stop all jails |
blackship armada build [jails...] |
Build jails from Jailfiles, through the same ZFS-aware path and layer cache as blackship build |
blackship armada ps [--json] |
Show status of all jails |
blackship armada config [--show] |
Validate and show configuration |
armada config --show prints, and returns in JSON, only the project, data_dir,
ZFS settings and each jail's name, path, release, build and dependencies. It
never echoes secrets such as [telemetry] headers.
Every Armada action supports the global --format json contract. The result is
wrapped in the versioned JSON envelope used by other Blackship commands. For
actions that normally print progress, those lines are returned in
data.messages so stdout remains one valid JSON document:
Config File Merging
Every manifest-aware command accepts repeated global -c/--config files.
Later files override earlier files, tables merge recursively, and named
[[jails]] and [[networks]] entries merge by name. This makes it possible
to keep project settings and individual jails in separate files:
blackship/
├── project.toml
└── jails/
├── database.toml
└── web.toml
The first path supplies the project name when [config].project is omitted.
With one path, -c blackship.toml behaves exactly as before. Arrays other than
[[jails]] and [[networks]] replace the earlier value, a name may appear only
once per file, and errors name the offending file. Relative paths (build,
jailfile) resolve against the working directory, not the file that wrote them.
mcp reads only the first file; armada uses its own -f list.
Armada continues to support its command-local -f/--file spelling:
# Merge base config with production overrides
# Merge multiple files
Jailfile References
Jails in blackship.toml can reference Jailfiles for building:
[[]]
= "web"
= "./web" # Directory containing Jailfile
= ["db"]
[[]]
= "api"
= "./custom/Api.jailfile" # Explicit Jailfile path
Shell Completion
| Command | Description |
|---|---|
blackship completion bash|zsh|fish |
Generate shell completion |
MCP Server
| Command | Description |
|---|---|
blackship mcp [--listen addr:port] |
Serve MCP on stdio, or Streamable HTTP with --listen (see MCP Server) |
blackship ui [--listen addr:port] |
Placeholder web page, --features ui (see Web UI) |
Jailfile Format
Jailfiles define reproducible jail builds, similar to Dockerfiles:
# Jailfile
FROM 15.1-RELEASE
# Labels (metadata)
LABEL name=nginx-jail version=1.0
# Build arguments
ARG NGINX_VERSION=1.30
# Environment variables
ENV NGINX_VERSION=${NGINX_VERSION}
# Run commands (executed via jexec)
RUN pkg install -y -g "nginx-${NGINX_VERSION}*"
RUN sysrc nginx_enable=YES
# Copy files from build context
COPY nginx.conf /usr/local/etc/nginx/nginx.conf
COPY html/ /usr/local/www/html/
# Set working directory
WORKDIR /usr/local/www
# Expose ports (documentation)
EXPOSE 80/tcp
EXPOSE 443/tcp
# Default command
CMD /usr/local/sbin/nginx -g 'daemon off;'
# Run inside the jail before teardown
STOP /usr/local/sbin/nginx -s quit
STOP runs before /etc/rc.shutdown when the jail is stopped. A stop = key on
the jail in blackship.toml overrides it.
TOML Format (Alternative)
# Jailfile.toml
[]
= "nginx-jail"
= "1.0"
[]
= "15.1-RELEASE"
[[]]
= "NGINX_VERSION"
= "1.30"
[[]]
= 'pkg install -y -g "nginx-${NGINX_VERSION}*"'
[[]]
= "nginx.conf"
= "/usr/local/etc/nginx/nginx.conf"
= "root:wheel"
= 0o644
[[]]
= 80
= "tcp"
[]
= "/usr/local/sbin/nginx -g 'daemon off;'"
[]
= "/usr/local/sbin/nginx -s quit"
The TOML format runs its steps in a fixed order, whatever order the tables
appear in: from, workdir, args, env, every run, every copy, then
expose. No run can act on a copied file, so set ownership and permissions on
the copy entry itself (owner, mode); when a command must follow a copy,
use the line format, which keeps the order as written. Unknown keys are
rejected rather than ignored.
Build Commands
# Basic build
# With build arguments
# Dry run
ZFS Integration
ZFS is what makes jails cheap. With zfs_enabled = true:
- Releases bootstrap into their own dataset and get a
@pristinesnapshot - Jail roots are
zfs clones of that snapshot, so creation is near-instant and jails share the base blocks instead of copying them - Jailfile builds snapshot each step, giving rebuilds a layer cache
blackship commitfreezes a jail back into a reusable release- Snapshots carry the jail's own definition, and send/receive moves jails between hosts
The jails dataset is mounted at data_dir/jails, so a jail root is at the
same path whether or not it is a dataset. Without ZFS everything still works,
but each jail is a full copy of the release (Blackship refuses the copy if the
filesystem cannot take it).
Instant provisioning and commit
# Bootstrap once: extracts to a dataset, snapshots it @pristine
# Jails clone from it: sub-second, and nearly free on disk
# Configure a jail, then freeze it into a reusable release
# Everything cloned from it starts pre-configured
commit promotes the new release so it no longer depends on the jail. A side
effect of zfs promote: snapshots the jail took before the commit move to
the release, and the jail can no longer roll back to them.
Build layer cache
Every RUN and COPY is snapshotted as bs-layer-<n>-<hash>, keyed by a
rolling hash of the instructions before it, the build arguments, the base
release, and the contents of anything copied in. A rebuild rolls back to the
longest cached prefix and continues from there:
$ blackship build -f runner/Jailfile -n runner
CACHED steps 1-5 (layer bs-layer-4-a1aadc5d826c)
Build complete! Jail root: /var/blackship/jails/armada-runner
Change a line in the Jailfile and only that step and everything after it re-runs, exactly like a Docker layer cache.
Snapshot Workflow
Snapshots stage the jail's definition (and its Jailfile, when known) at
.blackship/ inside the dataset first, so a zfs send of the snapshot
carries everything needed to rebuild the jail elsewhere.
# Create snapshot before changes
# Make changes
# If something breaks, rollback
# Clone for testing
Export/Import with ZFS
# Fast export using ZFS send
# Standard tar.zst export (bsdtar: hardlinks and file flags kept, sockets
# skipped, devfs and other mounts left out; a failed export leaves no file)
# Import (auto-detects format)
# Import from another jail manager
# Move a stopped jail to another host over ssh
migrate runs as root, so the ssh connection uses root's keys and
known_hosts, not yours: set those up for the target first.
A migration that succeeds fences the source so the jail cannot quietly run on
two hosts: its dataset goes read-only, gets a blackship:migrated property
(<host>/<dataset>@<unix time>), and up refuses to start it, naming where it
went. blackship unfence web lifts the fence if you change your mind. A
transfer that fails fences nothing, and blackship removes the partial dataset
it left on the target. A jail cloned from a release is sent as a full copy of
its current state, without its older snapshots (the target does not have the
release to clone from). The source is never removed: --keep only silences the
hint about removing it yourself (blackship rm web --volumes). The dataset
arrives on the target with the mountpoint it had here; a target with a different
data_dir moves it with zfs set mountpoint=<data_dir>/jails/<name> (the
command prints the real source path). gc follows its usual rules for a fenced
dataset, so it is only reclaimed with --force, and its report says the dataset
was migrated and to where.
A migration is recorded at <data_dir>/migrations/<jail>.json from before its
first effect until it settles, so a kill -9 (or a power cut) between the
receive and the fence leaves a trace instead of a jail that is runnable on both
hosts. While a record exists, migrate refuses to start the same jail again and
names the record. Then pick one:
Both look at the real state first (does the destination dataset or the snapshot
exist, is the source fenced) rather than trusting the record, and neither
sends the stream twice. --resume also needs the jail stopped, and the source is only fenced if it has not been written to since the snapshot (otherwise the stale copy is removed and the migration rolls back). If undoing a step
fails twice (the target is down, a snapshot is held), the migration is parked: the
record stays, the error says what is left, and the attempt count is kept in the
record. Fix the cause and run --resume (or --abort) again: the parked step is
retried with a fresh run of attempts, after looking at what is really left, and the
rollback carries on in reverse until the record settles. --resume and --abort exit 0 when they settle the record (completed, or rolled back with nothing left; JSON outcome is completed, rolled_back or aborted) and nonzero when the migration is still parked, refused, or failed again. A record that does not read back as one blackship wrote is
refused and left alone. Both accept --format json.
Networking
Every VNET jail gets its own network stack and one interface plugged into a host bridge. Blackship implements that two ways, and a named network picks which one:
epair (default) |
netgraph |
|
|---|---|---|
| Host bridge | if_bridge |
ng_bridge node |
| Jail interface | if_epair pair (epair0a/epair0b) |
ng_eiface (ngethN) |
| Gateway lives on | the bridge interface | a host-side ng_eiface |
| VLAN tagging | supported | not supported |
Named networks
A named network is a persisted record (subnet, gateway, bridge, backend), not
a live interface. Creating one realizes it on the host; blackship setup
re-realizes it after a reboot, when bridges and eifaces are gone but the
record remains:
Created network 'default' on bridge 'ngbridge0' (netgraph)
Subnet: 10.0.1.0/24
Gateway: 10.0.1.1
Host gateway interface: ngeth0
Jails attach by name and inherit the backend, so nothing in the jail definition needs to know which dataplane is in use:
[]
= true
= ["default"]
= "10.0.1.10"
How the netgraph backend is wired
ng_bridge is a kernel graph node with numbered linkN hooks. Blackship
hangs one ng_eiface off a hook per jail, plus one for the host itself,
which is where the gateway address lives:
ng_bridge (ngbridge0)
├── link0 ── ng_eiface ngeth0 [host] 10.0.1.1
├── link1 ── ng_eiface ngeth1 [jail web] 10.0.1.10
└── link2 ── ng_eiface ngeth2 [jail db] 10.0.1.11
host NIC (em0) ── PF NAT ── routing ── ngeth0
There is no epair pair and no if_bridge: the jail interface is moved into
the jail's vnet with SIOCSIFVNET, and traffic reaches the outside through
normal host routing plus a NAT rule (see Outbound traffic).
Outbound traffic
Both backends route jail traffic through the host gateway, and Blackship
does not install NAT. Blackship sets net.inet.ip.forwarding=1 when it
realizes a gateway; reaching anything beyond the host takes a NAT rule per
subnet in pf.conf, on the interface that carries the default route:
nat on $ext_if inet from 10.0.1.0/24 to any -> ($ext_if)
Without it, jails reach the gateway and each other, and nothing else.
Concurrent jail creation is safe: two creators racing for the same free
linkN retry the next index, and IP claims are arbitrated by the lease store
under a lock rather than by whoever wrote last.
Interface ownership
Host-side interfaces are tagged into the blackship interface group
(ifconfig -g blackship lists them). Cleanup checks that tag before
destroying an interface it found by name, so a recycled name belonging to
something else is never torn down. Only the host end is tagged, because
moving an interface into a vnet strips its groups.
Jail interfaces also get a deterministic MAC by default: the FreeBSD OUI
58:9c:fc plus a hash of the jail name and bridge, so an address survives
restarts and differs between clones. Set mac_address to override.
Gotcha: one namespace, two bridge types
Loading ng_ether gives every ethernet interface a netgraph node named after
itself, and that includes if_bridge interfaces. A named network created
with the epair backend on blackship0 therefore occupies the name
blackship0 in the netgraph namespace too, and a netgraph bridge cannot then
use it:
Error: Network error: NgNameNode(.:bridge_tmp, blackship0) failed: Address already in use
Give the two backends distinct bridge names (blackship0 and ngbridge0).
Port Forwarding
Uses PF anchors to avoid modifying /etc/pf.conf:
# Expose nginx on port 80
# Expose on specific host IP
# Different internal port
Add to /etc/pf.conf (blackship setup --enable-pf writes a minimal one
with these lines when none exists):
rdr-anchor "blackship"
anchor "blackship"
The blackship anchor also references the per-jail drain anchors, so these
two lines cover [jails.drain] and cascade = "isolate" as well.
Port forwards are persisted under Blackship's data directory. After a PF
restart or host reboot, run blackship setup to recreate the anchor and
reapply the saved rules.
Health Checks
All health checks are command-based (exit 0 = healthy).
HTTP Check
[[]]
= "api"
= "curl -sf http://localhost:8080/health"
= "jail"
= 30
= 10
TCP Check
[[]]
= "postgres"
= "nc -z localhost 5432"
= "jail"
Command Check
[[]]
= "nginx-running"
= "service nginx status"
= "jail"
Suspicion instead of retry counting
By default a check is Failing after retries consecutive failures. For flaky
probes you can opt in to a phi-accrual detector per check:
[[]]
= "api"
= "curl -sf http://localhost:8080/health"
= "jail"
= 5
[]
= 8 # passing checks before phi is reported (default 8, at most 64)
= 3.0 # a failed check reports unhealthy at this phi (default 3.0)
= 8.0 # ... and failing at this one (default 8.0)
# min_std_dev_ms = 1250 # deviation floor; default is a quarter of `interval`
A passing check is a heartbeat; a failing check is silence. The detector
measures how long the check has been silent relative to how regular its passes
were, and a failed check is only reported once that silence is unusual. Below
unhealthy_phi a failed check stays healthy, between the two it is
unhealthy, and at failing_phi it is failing. Until min_samples passes
have been seen, the check falls back to plain retry counting. Only a failing
verdict can trigger the check's recovery action; suspicion reports a level
and never restarts anything by itself. Rate limits are unchanged.
Leave the table out and nothing changes. unhealthy_phi and failing_phi
must be positive and unhealthy_phi <= failing_phi; bad values are rejected
at load.
Bounding concurrent checks
Under supervise, every jail's monitor runs its checks on its own. To keep a
slow host from being buried by its own probes, cap them:
[]
= 4 # runs allowed in flight at the start (default 4)
= 1 # the limit never drops below this (default 1)
= 1000 # never grows above this (default 1000)
The limit moves by additive-increase, multiplicative-decrease: it grows by one
when a run completes while the limit is saturated, and drops to three quarters
when a run errors or takes at least half of its check timeout. A cycle that
finds the limit full is shed, not queued: the monitor skips it and tries again
on its next interval. Unset means unbounded, exactly as before. This applies
to supervise health monitors only; up and down start and stop jails one
at a time.
Monitoring
health runs checks inside the jail, so it escalates to root like exec.
start_period (default 60s) counts from when the jail started, so a one-time
check on a jail that has been up for a while reports real results; within the
start period it reports starting, and a jail that is not running reports
unknown. Every completed pass saves an atomic last-known summary which
ps --host can read without running checks. A saved result is accepted only
when its JID matches the current jail instance.
# One-time check
# Watch mode (updates every 5 seconds)
# JSON output for scripting
Lifecycle state, reclamation, and telemetry
Every host mutation up performs is checkpointed to a scope record at
<data_dir>/scope/<jail>.toml before it happens, and every transition is
appended to <data_dir>/audit/<jail>.jsonl. The scope record is the reclamation
work-list; the audit log outlives it.
Reclaiming orphans
A jail killed out of band (jail -r, a panic, a hard reset) leaves its epair,
rctl rules, lease, mounts, and dataset behind. gc finds them by diffing scope
records against what is actually running:
Datasets blackship did not create, and jails marked ephemeral = false, are
reported but never destroyed without --force. up and supervise run the
report-and-reap-orphans half automatically.
Blackship tags every jail dataset it creates with the ZFS property
blackship:ephemeral. A jail that is stopped and started again reuses its
dataset, and the tag lets the new scope record claim it again, so a supervisor
that dies after a restart is still cleaned up by gc. A dataset without the
tag (say, one from build) is never claimed that way.
gc also reclaims a bridge that blackship created for a VNET jail once nothing
uses it, no --force needed. It must be tagged into the blackship interface
group (blackship tags a bridge only when it creates it), have no members, and
be named by no network record, no live jail's VNET record and no
[config.bridge]. Bridges that predate the tag, bridges you made yourself,
and the [config.bridge] one are never touched, and ng_bridge is not
handled.
Jail state as a chart
Lifecycle and health live in one statechart, so the order things are left and entered is resolved by the chart, not by hand:
stateDiagram-v2
state Jail {
[*] --> Down
state Down {
[*] --> Stopped
Failed --> Stopped: recover
}
state Up {
[*] --> Starting
Starting --> Running: started
state Running {
[*] --> Healthy
Unhealthy
Failing
Suspended
}
Running --> Draining: drain
Running --> Stopping: stop
Draining --> Stopping: stop
}
Down --> Up: start (Stopped to Starting)
Up --> Down: stopped (Stopping to Stopped)
Up --> Down: fail (to Failed)
}
The arrows are the state-machines events. fail leaves any Up state for
Failed, and start and stopped are the Stopped-to-Starting and
Stopping-to-Stopped moves between the two groups. Supervisor health verdicts
move the leaf among the four Running states in any direction.
Events and guards stay in the state-machines jail machine; the chart answers
which states a move exits and enters. fail from a healthy running jail exits
Healthy, Running and Up, then enters Down and Failed. Health verdicts from
supervise move the leaf inside Running, and stop releases what leaving Up
held (VNET, then the address lease) in the order the chart reports.
Two-phase QoS
A jail usually needs headroom while it warms caches and forks workers, and a
tighter cap once it settles. [jails.qos] gives it both:
[]
= "healthy" # "healthy" | "timer" | "manual"
= 120
[]
= "4g"
= "400"
[]
= "2g"
= "200"
The healthy transition fires on the first passing healthcheck and therefore
needs blackship supervise; max_startup_secs is its fallback deadline. For
one-shot blackship up there is no warden, so shift by hand:
Only the resources a profile names are swapped — custom rules entries survive
the shift, and eva reconciles against the recorded phase rather than
reverting it.
Draining and cascade policy
[jails.drain] blocks new TCP connections through a per-jail PF sub-anchor
(blackship/drain/<jail>) and waits for established states to close before
teardown, up to timeout_secs. cascade decides what happens to dependents on
down: strict stops them (default), detach stops only the target, isolate
leaves them running but fences them off at the firewall.
Post-mortem
This reads the durable JSONL, so it still answers after the jail, its scope
record, and a reboot are gone — including peak racct usage sampled by the
supervisor and the recorded termination reason. Peaks are bounded by
usage_sample_secs (default 30s); they are sampled maxima, not exact kernel
counters.
OTLP export
Adding a [telemetry] block sends the same event stream to a collector over
OTLP/HTTP, alongside racct gauges:
[]
= "http://127.0.0.1:4318"
= "blackship"
= 30
[]
= "Bearer <token>"
Omitting the table costs nothing: no exporter is built, no runtime is started, no socket is opened. A collector that is down, slow, or misconfigured warns once and never fails a jail operation.
Dependencies
up starts a jail after everything it depends on; down stops a jail after
everything that depends on it (with the default cascade = "strict"). Jails
already in the target state are skipped, and restart brings back the
dependents its stop took down:
[[]]
= "app"
= ["cache", "database"]
[[]]
= "cache"
[[]]
= "database"
# Starts: cache → database → app (siblings in depends_on order)
# Stops: app → database (app depends on it)
# Stops only app: nothing depends on it
Examples
Web Application Stack
[]
# data_dir defaults to ~/.local/share/blackship
= true
= "zroot"
= "blackship"
[[]]
= "postgres"
= "15.1-RELEASE"
= "db.local"
[]
= true
= "blackship0"
= "10.0.1.10"
= "10.0.1.1"
[[]]
= "redis"
= "15.1-RELEASE"
= "cache.local"
[]
= true
= "blackship0"
= "10.0.1.11"
= "10.0.1.1"
[[]]
= "webapp"
= "15.1-RELEASE"
= "app.local"
= ["postgres", "redis"]
[]
= true
= "blackship0"
= "10.0.1.20"
= "10.0.1.1"
[]
= ["8.8.8.8"]
= "custom"
[]
= true
[[]]
= "http"
= "curl -sf http://localhost:3000/health"
= "jail"
= 30
Backup and Migration
# Create snapshot
# Export for migration
# On new host
# Edit blackship.toml to add jail config
CI/CD Integration (Example)
This is an example of how Blackship could be used as a backend for CI/CD systems. This is not a built-in integration - it demonstrates how the run, exec, cp, and rm commands can be combined for CI/CD workflows.
Example: Gitea Actions with act_runner
Blackship could be used as a backend for Gitea Actions via act_runner.
Setup
- Bootstrap a release:
- Configure act_runner with jail labels:
runner:
labels:
- "freebsd-15:jail://15.1-RELEASE"
- Workflows targeting
runs-on: freebsd-15would execute in ephemeral jails.
How it Would Work
When act_runner receives a job with a jail:// label, the runner could:
- Create an ephemeral jail via
blackship run --name gitea-runner-<id> --release <release> --detach - Clone the repository into the jail using
blackship cp - Execute each step via
blackship exec <jail> --workdir /workspace -- <command> - Clean up via
blackship rm <jail> --force
Note: This requires custom act_runner configuration or a wrapper script - it is not built into act_runner by default.
Web UI (placeholder)
Not a real UI yet, just the hook. Build with --features ui (off by default),
then:
It serves one page and one Datastar SSE stream
(/stream) that patches the blackship version and the running jail count
every two seconds. It is read-only and has no authentication, so
--listen refuses anything that is not a loopback address. Datastar comes
from rama itself (rama::http::sse::datastar), no extra crate.
MCP Server
blackship mcp speaks the Model Context Protocol
over stdin/stdout, or over Streamable HTTP with --listen, so an MCP-capable assistant can author jail configuration
for this host. Writing a blackship.toml or a Jailfile by hand means knowing
two schemas and knowing what the host can actually do; the server supplies both,
plus the real parsers, so a draft is checked before it reaches disk.
It is built by default. Compile without it using --no-default-features.
Running it
It needs no root, and it does not require a blackship.toml to exist --
creating one is the point. Register it with a client:
Pass --config <path> before mcp to change the manifest path the tools
default to. Stdout carries the JSON-RPC frame stream, so diagnostics go to
$XDG_DATA_HOME/blackship/mcp.log (by default
~/.local/share/blackship/mcp.log) instead; set RUST_LOG to raise the level.
Over HTTP
--listen serves the same tools, prompts and resources as Streamable HTTP at
/mcp, so an assistant on another machine can author configuration for this
host:
# Loopback: no token needed; Host/Origin checks guard against DNS rebinding
# Any other address requires a bearer token
BLACKSHIP_MCP_TOKEN=
The token comes from the environment, never from argv, so it does not show up
in ps. Without it, --listen on a non-loopback address refuses to start.
blackship:///host describes the host and the creating tools write files on
it, so treat the token like a login. The write gate works the same over HTTP: the
approval prompt reaches the client on the session's stream, and a client that
does not declare elicitation gets a refusal and no file. The server speaks
plain HTTP; put TLS in front of it (a reverse proxy, or an ssh tunnel to the
loopback listener) when the network between you and the host is not trusted.
Tools
Read-only, no approval needed:
| Tool | Returns |
|---|---|
manifest_inspect |
The parsed manifest as JSON |
manifest_validate |
Every diagnostic, staged read -> parse -> validate |
jailfile_inspect |
The parsed Jailfile as JSON |
jailfile_validate |
Every bad line with line and column, in one call |
File-producing, and approval is not optional:
| Tool | Writes |
|---|---|
manifest_create |
A blackship.toml rendered from a project name and a list of jails |
jailfile_create |
A Jailfile in the TOML format |
Facts about the host are a resource, blackship:///host, not a tool: one
source, read before planning. Output is compact JSON; the reader is a model.
Writes are gated on the operator
Neither creating tool can write a file on its own authority. Both render the
text, validate it through the same code blackship up and blackship build
use, and then ask you through an MCP
elicitation.
Nothing lands on disk unless you set confirm, and replacing an existing file
additionally needs overwrite, which is only ever offered when the file really
exists. The prompt names the absolute path.
The gate fails closed. A declined or cancelled request, a form returned without
confirm, a client that does not support elicitation, a prompt left unanswered
for two minutes, a target directory that does not exist, and a draft that does
not validate all produce the same result on disk: nothing. A refusal comes back
as a payload with "written": false and a reason, so the model can tell a
rejection from an error.
Writes themselves go through a temp file in the target directory followed by a rename, so an interrupted write cannot truncate an existing manifest. That is also why the target's directory has to exist: it is checked before you are asked, so an approval is never spent on a write that cannot land. blackship does not create directories on your behalf.
Prompts
The prompts carry the workflow -- they tell the model which tools to call and in what order, rather than leaving it to infer that.
| Prompt | Purpose |
|---|---|
new_project |
Author a blackship.toml: gather host facts, draft, validate, then create |
new_jailfile |
The same arc, ending at jailfile_create |
diagnose_config |
Explain why an existing file is rejected, in terms of the schema |
Resources
| URI | Contents |
|---|---|
blackship:///host |
The live host: FreeBSD version and kernel features, CPU, memory (physical, free, ARC, swap) and what manifest jails claim, ZFS pools and free space, networks with used and free addresses, PF state and the NAT egress interface, releases, manifest and unmanaged jails |
blackship:///man |
The CLI manual, generated from the live command spec (stdio only) |
blackship:///man.kdl |
The full command tree as KDL (stdio only) |
blackship:///schema/manifest |
JSON Schema for what manifest_create accepts |
blackship:///schema/jailfile |
JSON Schema for what jailfile_create accepts |
blackship:///reference/jailfile |
The line-format keywords, including which Dockerfile constructs do not exist here |
blackship:///reference/jail-params |
The reserved jail_set(2) parameters blackship manages itself |
The manual and the schemas are generated, not hand-written, so a new subcommand
or a new parameter shows up the day it is added and cannot drift out of date.
Over HTTP the client is remote and cannot run the CLI, so the manual is not
served there. A value the server cannot read unprivileged, such as PF state,
is null, never a guess.
Troubleshooting
Jail won't start
# Check configuration
# Try dry run
# Clean up failed resources
Network issues
# List Blackship-managed networks
# Check jail IP
# Verify routing
ZFS issues
# Verify dataset exists
|
# Check snapshots
# Manual cleanup
Built files are missing after armada up
On ZFS, 0.4.2 and earlier built a manifest jail's build= Jailfile into a
plain directory at the jail root, without creating the dataset. Starting the
jail mounted the dataset over it, hiding the build. 0.5.0 and later build
through the dataset but do not repair an old root. Remove the jail twice (the
first rm destroys the dataset, the second clears the directory left under
it, schg files included), then rebuild:
blackship up aborts where it used to warn
Resource-limit and VNET-attach failures are fatal: the jail is removed and
its resources are rolled back rather than left running in a half-configured
state. A jail with [jails.resources] set will now fail on a host without
RCTL instead of quietly ignoring its limits.
kern.racct.enable is a read-only tunable, so it cannot be set at runtime.
Add it to /boot/loader.conf and reboot:
kern.racct.enable="1"
Rejected params entries
Manifest params cannot override the keys Blackship uses to establish jail
identity and isolation — vnet, path, name, securelevel,
devfs_ruleset, enforce_statfs, allow.* and similar. Those are reported
and ignored rather than applied. Set the supported options ([jails.network],
[jails.resources]) instead.
Raw sockets and chflags inside blackship run
Ephemeral run jails are not granted allow.raw_sockets, allow.socket_af
or allow.chflags. Use a managed jail defined in the manifest for workloads
that need raw sockets or chflags.
License
BSD-3-Clause - See LICENSE file for details.
Author
Abdelkader Boudih oss@seuros.com