CBSDfile advanced features

Volume environments

For applications with persistent data, system directories can be moved to separate ZFS datasets. This simplifies backup and migration.

Enabling volumes

In CBSDfile:

jail_app1()
{
    sysdir_volume=1
    ip4_addr="10.0.0.30"
}

When sysdir_volume=1, the directory ~cbsd/jails-system/<jname> is moved to ~cbsd/VOLUMES/<jname>-system.

Direct mounts via fstab.local

Create a jails-system/fstab.local file in the CBSDfile directory to define additional nullfs mounts:

/data/jails/app1/data    /usr/local/www/nginx    nullfs    ro    0    0
/data/shared/logs        /var/log/myapp          nullfs    rw    0    0

These mounts are automatically applied to the jail upon creation.

Skeleton directories (skel)

The skel/ directory next to the CBSDfile allows automatically copying files into the jail upon creation. The directory structure inside skel/ is replicated in the jail's filesystem.

Structure

my-jail/
├── CBSDfile
└── skel/
    ├── etc/
    │   ├── rc.conf
    │   └── ssh/
    │       └── sshd_config
    └── usr/
        └── local/
            └── etc/
                └── pkg/
                    └── FreeBSD.conf

Files are copied into the jail during creation. The skel/ directory is processed automatically; explicit specification in CBSDfile is not required.

Disabling skel

jail_test1()
{
    applytpl=0
}

Lab environments and hierarchy

For complex configurations, it is recommended to use a hierarchical directory structure. One directory = one set of environments (lab).

cbsdfile-recipes/
├── jail/
│   ├── app1/
│   │   └── CBSDfile
│   └── web/
│       └── CBSDfile
├── bhyve/
│   ├── db/
│   │   └── CBSDfile
│   └── api/
│       └── CBSDfile
└── labs/    
    └── lab1/        
        ├── config              # Common variables (IP addresses, etc.)        
        ├── redisro            
        │   └── CBSDfile        
        └── redisrw            
            └── CBSDfile

Lab Configuration

In each lab's CBSDfile, include shared variables:

preup()
{
    . ../config
}

The config file contains shared variables:

REDIS_RO_IP="10.0.0.20"
REDIS_RW_IP="10.0.0.21"
REDIS_DOMAIN="lab1.example.com"

Starting the Lab

# Option 1: change to the directory containing the CBSDfile
cd cbsdfile-recipes/labs/lab1/redisro/ && cbsd up

# Option 2: specify the path to the CBSDfile directly
cbsd up cbsdfile=/full-path/to/cbsdfile-recipes/labs/lab1/redisrw/CBSDfile

Hierarchical Categories

CBSDfile supports nested categories. A function named like labs_<name>() will be created via jcreate. The category derived from the function name determines the operation type:

# Creates a jail via jcreate
jail_web1() { ... }

# Creates a bhyve VM via bcreate
bhyve_db1() { ... }

# Creates a jail (the labs category uses jcreate by default)
labs_test1() { ... }

Recommendations

  1. One directory per environment/lab — group related environments into subdirectories.
  2. Use globals() for common parameters — domain, network, VNC binds.
  3. CLI overrides — keep CBSDfile as a template and modify values via command-line arguments.
  4. Volumes for persistent data — sysdir_volume=1 for applications with persistent data.
  5. skel/ for static files — configuration files, scripts, templates.
  6. Laboratories for complex sets — subdirectories with shared configuration via preup().