Blackship
A FreeBSD jail orchestrator with TOML configuration, dependency management, state machine lifecycle control, and ZFS integration.
Features
- Declarative Configuration: Define jails in TOML with dependencies, networking, and hooks
- Dependency Management: Automatically start/stop jails in correct order using dependency graph
- State Machine Lifecycle: Clean state transitions (stopped → starting → running → stopping)
- VNET Networking: Bridge-based networking with epair interfaces, static IPs, and MAC addresses
- ZFS Integration: Automatic dataset creation, snapshots, clones, and efficient export/import
- Jailfile Templates: Docker-like build system for reproducible jail creation
- Health Checks: HTTP, TCP, and command-based health monitoring
- Lifecycle Hooks: Run scripts at start/stop with configurable failure handling
- Port Forwarding: PF-based port exposure with source IP binding
- Shell Completion: Bash, Zsh, and Fish completions
Requirements
- FreeBSD 15.0+ with jail support
- ZFS (optional, for snapshots/clones)
- PF (optional, for port forwarding)
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.). Usesudo blackship bootstrap <release>for extraction.
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.0-RELEASE"
= "web.local"
[]
= true
= "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)
# Dry run to see what would be downloaded
# List available releases
4. Create Network
# Create bridge with gateway
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
Configuration Reference
Global Config
[]
# 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
Jail Definition
[[]]
= "myapp" # Jail name (required)
= "15.0-RELEASE" # Base release
= "/jails/myapp" # Custom path (optional)
= "myapp.local" # Hostname
= ["database"] # Dependencies
[]
= true # Enable VNET
= "blackship0" # Bridge interface
= "10.0.1.10" # Static IP
= "10.0.1.1" # Default gateway
= "02:00:00:00:00:01" # Static MAC (optional)
[]
= ["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"
[[]]
= "post_start"
= "jail"
= "/etc/rc.d/nginx start"
= "abort" # abort or continue
[[]]
= "pre_stop"
= "jail"
= "/etc/rc.d/nginx stop"
= "continue"
Commands
Lifecycle
| Command | Description |
|---|---|
blackship up [jail] [--all] [--dry-run] |
Start jail(s) with dependencies |
blackship down [jail] [--all] [--dry-run] |
Stop jail(s) in reverse order |
blackship restart [jail] [--all] [--dry-run] |
Restart jail(s) |
blackship ps [--json] |
List jail status |
blackship check |
Validate configuration |
blackship setup |
Initialize PF firewall anchor |
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] -- <cmd> |
Execute command in jail |
blackship run --name <n> --release <r> [-d] -- <cmd> |
Run ephemeral jail (auto-cleanup unless -d) |
File Operations
| Command | Description |
|---|---|
blackship cp <src> <dest> |
Copy files (use jail:path for jail paths) |
blackship rm <jails...> [-f] [--volumes] |
Remove/destroy jails |
Bootstrap & Releases
| Command | Description |
|---|---|
blackship bootstrap <release> [-f] [-a archives] |
Download FreeBSD release |
blackship releases [list|delete|verify] [--json] |
Manage releases |
Networking
| Command | Description |
|---|---|
blackship network create <name> -s <subnet> [-g gw] [-b bridge] |
Create network |
blackship network destroy <name> [--force] |
Destroy network |
blackship network list |
List 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 |
Export & Import
| Command | Description |
|---|---|
blackship export <jail> [-o file] [--zfs-send] |
Export to archive |
blackship import <file> [-n name] [--force] |
Import from archive |
Build System
| Command | Description |
|---|---|
blackship build [-f Jailfile] [-n name] [--build-arg K=V] [--dry-run] |
Build from Jailfile |
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 supervise |
Start Warden supervisor for auto-restart |
blackship logs <jail> [-f] [-n lines] |
Tail jail logs |
Armada (Multi-Jail Orchestration)
| Command | Description |
|---|---|
blackship armada init [-f file] |
Create a new blackship.toml |
blackship armada up [-d] [jails...] |
Start all jails |
blackship armada down [jails...] |
Stop all jails |
blackship armada build [jails...] |
Build jails from Jailfiles |
blackship armada ps [--json] |
Show status of all jails |
blackship armada config [--show] |
Validate and show configuration |
Config File Merging
Armada supports merging multiple config files (later files override earlier):
# 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 |
Jailfile Format
Jailfiles define reproducible jail builds, similar to Dockerfiles:
# Jailfile
FROM 15.0-RELEASE
# Metadata
METADATA name=nginx-jail version=1.0
# Build arguments
ARG NGINX_VERSION=1.24
# Environment variables
ENV NGINX_VERSION=${NGINX_VERSION}
# Run commands (executed via jexec)
RUN pkg install -y 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;'
TOML Format (Alternative)
# Jailfile.toml
[]
= "nginx-jail"
= "1.0"
= "15.0-RELEASE"
[[]]
= "NGINX_VERSION"
= "1.24"
[[]]
= "run"
= "pkg install -y nginx"
[[]]
= "copy"
= "nginx.conf"
= "/usr/local/etc/nginx/nginx.conf"
[[]]
= 80
= "tcp"
= "/usr/local/sbin/nginx -g 'daemon off;'"
Build Commands
# Basic build
# With build arguments
# Dry run
ZFS Integration
When zfs_enabled = true, Blackship:
- Creates datasets automatically:
zpool/blackship/jails/<name> - Enables snapshots and clones
- Supports ZFS send/receive for fast export/import
Snapshot Workflow
# 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
# Import (auto-detects format)
Networking
VNET Setup
Blackship uses VNET jails with epair interfaces connected to a bridge:
Host Bridge (blackship0)
├── epair0a ←→ epair0b (jail: web, 10.0.1.10)
├── epair1a ←→ epair1b (jail: db, 10.0.1.11)
└── gateway: 10.0.1.1
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:
rdr-anchor "blackship"
anchor "blackship"
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"
Monitoring
# One-time check
# Watch mode (updates every 5 seconds)
# JSON output for scripting
Dependencies
Jails start in dependency order and stop in reverse:
[[]]
= "app"
= ["cache", "database"]
[[]]
= "cache"
[[]]
= "database"
# Starts: database → cache → app
# Stops: app → cache → database
Examples
Web Application Stack
[]
# data_dir defaults to ~/.local/share/blackship
= true
= "zroot"
= "blackship"
[[]]
= "postgres"
= "15.0-RELEASE"
= "db.local"
[]
= true
= "blackship0"
= "10.0.1.10"
= "10.0.1.1"
[[]]
= "redis"
= "15.0-RELEASE"
= "cache.local"
[]
= true
= "blackship0"
= "10.0.1.11"
= "10.0.1.1"
[[]]
= "webapp"
= "15.0-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.0-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.
Troubleshooting
Jail won't start
# Check configuration
# Try dry run
# Clean up failed resources
Network issues
# List bridges
# Check jail IP
# Verify routing
ZFS issues
# Verify dataset exists
|
# Check snapshots
# Manual cleanup
License
BSD-3-Clause - See LICENSE file for details.
Author
Abdelkader Boudih oss@seuros.com