blackship-0.1.1 is not a library.
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 14.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)
Quick Start
1. Initialize Configuration
Create blackship.toml:
[]
= "/var/blackship"
= "/var/blackship/releases"
= "/var/blackship/cache"
= true
= "zroot"
= "blackship"
[[]]
= "web"
= "15.0-RELEASE"
= "web.local"
[]
= true
= "blackship0"
= "10.0.1.10"
= "10.0.1.1"
2. Bootstrap a Release
# Download and extract FreeBSD base
# List available releases
3. Create Network
# Create bridge with gateway
4. Start Jails
# Start a specific jail
# Start all jails
# Dry run (show what would happen)
5. Interact with Jails
# Open console
# Execute command
# Check status
Configuration Reference
Global Config
[]
= "/var/blackship" # Base data directory
= "/var/blackship/releases" # FreeBSD releases
= "/var/blackship/cache" # Download cache
= "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 init |
Initialize ZFS datasets |
blackship cleanup <jail> [--force] |
Clean up failed jail resources |
Console & Execution
| Command | Description |
|---|---|
blackship console <jail> [-u user] |
Open interactive shell |
blackship exec <jail> [-u user] -- <cmd> |
Execute command in jail |
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 |
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
[]
= "/var/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
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
MIT - See LICENSE file for details.
Author
Abdelkader Boudih oss@seuros.com