How to Automate Jail Management with ezjail on FreeBSD Operating System

Learn how to automate jail management with ezjail on FreeBSD, simplifying the creation, management, and maintenance of FreeBSD jails.

by İbrahim Korucuoğlu ( @siberoloji) | Thursday, March 20, 2025

Introduction

FreeBSD jails provide a powerful, lightweight approach to virtualization and system compartmentalization. First introduced in FreeBSD 4.0, jails offer a way to partition a FreeBSD system into multiple independent mini-systems with their own files, processes, users, and network resources. While the base FreeBSD system includes native jail management tools, these require significant manual configuration and maintenance.

Enter ezjail – a collection of scripts designed to simplify and automate the creation, management, and maintenance of FreeBSD jails. This article will guide you through setting up and automating jail management with ezjail, allowing you to efficiently deploy, manage, and maintain multiple jails with minimal effort.

Why Use ezjail for Automation?

Before diving into the technical details, it’s worth understanding the advantages ezjail offers over manual jail management:

Simplified Creation: Create new jails with a single command
Centralized Management: Manage all jails from a central location
Template System: Deploy new jails based on templates
Efficient Storage: Use a single read-only base system for all jails
Automated Updates: Update all jails simultaneously
Backup & Restore: Built-in functionality for backing up and restoring jails
Boot-Time Control: Configure jails to start automatically at system boot

These features make ezjail an excellent choice for environments that require multiple jails, consistent configuration, and streamlined management.

Prerequisites

A FreeBSD system (version 12.0 or newer recommended)
Root access or sudo privileges
Basic understanding of FreeBSD system administration
At least 2GB of free disk space for the base jail system

Setting Up ezjail

1. Installing ezjail

Begin by installing ezjail from the FreeBSD ports collection or packages:

# Using pkg
pkg install ezjail

# Or using ports
cd /usr/ports/sysutils/ezjail
make install clean

2. Basic Configuration

After installation, you should configure ezjail to match your system requirements. The main configuration file is located at /usr/local/etc/ezjail.conf. Open it with your preferred text editor:

ee /usr/local/etc/ezjail.conf

Key configuration options include:

ezjail_jaildir: The directory where jails will be stored (default: /usr/jails)
ezjail_ftphost: The FTP server from which FreeBSD base files are downloaded
ezjail_use_zfs: Whether to use ZFS for jail storage
ezjail_zfs_properties: ZFS dataset properties for jails

For example, to enable ZFS support with compression:

ezjail_use_zfs="YES"
ezjail_zfs_properties="-o compression=lz4"

3. Setting Up the Host System

Configure the host system to properly handle jails:

Enable IP aliasing in /etc/rc.conf:

echo 'cloned_interfaces="lo1"' >> /etc/rc.conf
echo 'ifconfig_lo1="up"' >> /etc/rc.conf

Enable packet forwarding and firewall if needed:

echo 'net.inet.ip.forwarding=1' >> /etc/sysctl.conf
sysctl net.inet.ip.forwarding=1

Start the ezjail service at boot:

echo 'ezjail_enable="YES"' >> /etc/rc.conf

4. Creating the Base Jail

Initialize the base jail system that will be shared by all your jails:

ezjail-admin install -p

This command downloads and installs the FreeBSD base system files. The -p flag includes the ports collection. For specific FreeBSD versions, use the -r flag:

ezjail-admin install -p -r 13.2-RELEASE

Automating Jail Management with ezjail

1. Creating and Starting Jails

Create a new jail with a single command:

ezjail-admin create example.jail 192.168.1.50

This creates a jail named “example.jail” with the IP address 192.168.1.50. Start the jail:

ezjail-admin start example.jail

To automate the creation of multiple jails, you can use a shell script:

#!/bin/sh
# create-jails.sh

JAILS="web.jail db.jail mail.jail dns.jail"
BASE_IP="192.168.1"
START_IP=50

ip=$START_IP

for jail in $JAILS; do
    ezjail-admin create $jail ${BASE_IP}.${ip}
    ezjail-admin start $jail
    ip=$((ip+1))
done

Make the script executable and run it:

chmod +x create-jails.sh
./create-jails.sh

2. Jail Templates for Consistent Deployment

Create a template jail that you’ll use as a base for other jails:

ezjail-admin create -f template template.jail 192.168.1.100

Customize the template jail:

ezjail-admin console template.jail

Inside the jail, update the system, install common packages, and configure settings:

pkg install -y vim-console bash git-lite
echo 'export EDITOR=vim' >> /root/.profile

Exit the jail and archive it as a template:

ezjail-admin stop template.jail
ezjail-admin archive template.jail

Now use this template to create new jails:

ezjail-admin create -a template.jail.tar.gz new-jail.example 192.168.1.101

3. Automating Updates Across All Jails

One of ezjail’s powerful features is the ability to update all jails simultaneously. First, update the base jail:

ezjail-admin update -u

Then update all jails based on this updated base jail:

ezjail-admin update -i

Create a script to automate regular updates:

#!/bin/sh
# update-jails.sh

# Update host system
freebsd-update fetch install

# Update base jail
ezjail-admin update -u

# Update all jails
ezjail-admin update -i

# Update packages in all jails
for jail in $(ezjail-admin list | grep -v "STA" | awk '{print $4}'); do
    echo "Updating packages in $jail"
    pkg -j $jail update
    pkg -j $jail upgrade -y
done

Schedule this script using cron to run monthly:

echo "0 3 1 * * root /path/to/update-jails.sh > /var/log/jail-updates.log 2>&1" >> /etc/crontab

4. Jail Configuration Automation

Create a configuration script that can be applied to multiple jails:

#!/bin/sh
# configure-jail.sh
# Usage: ./configure-jail.sh jailname

JAIL=$1

if [ -z "$JAIL" ]; then
    echo "Usage: $0 jailname"
    exit 1
fi

# Check if jail exists
ezjail-admin list | grep -q $JAIL
if [ $? -ne 0 ]; then
    echo "Jail $JAIL not found"
    exit 1
fi

# Configure jail parameters
echo "Configuring $JAIL..."

# Apply resource limits
ezjail-admin config -c jailname=$JAIL cpuset=0-1 osrelease=13.1-RELEASE

# Create standard user account
ezjail-admin console $JAIL pw useradd -n admin -m -G wheel -s /bin/sh

# Install basic packages
ezjail-admin console $JAIL pkg install -y sudo bash vim-console htop

# Configure sudo
ezjail-admin console $JAIL sh -c 'echo "%wheel ALL=(ALL) ALL" > /usr/local/etc/sudoers.d/wheel'

# Set timezone
ezjail-admin console $JAIL ln -sf /usr/share/zoneinfo/UTC /etc/localtime

echo "Jail $JAIL configured successfully"

5. Automated Backup and Restoration

Set up automated backups of your jails:

#!/bin/sh
# backup-jails.sh

BACKUP_DIR="/backups/jails"
DATE=$(date +%Y-%m-%d)

# Ensure backup directory exists
mkdir -p $BACKUP_DIR

# Backup each running jail
for jail in $(ezjail-admin list | grep -v "STA" | awk '{print $4}'); do
    echo "Backing up $jail"
    ezjail-admin stop $jail
    ezjail-admin archive $jail
    mv /usr/jails/$jail.tar.gz $BACKUP_DIR/$jail-$DATE.tar.gz
    ezjail-admin start $jail
done

# Keep only last 7 backups
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

Schedule this script to run daily:

echo "0 2 * * * root /path/to/backup-jails.sh > /var/log/jail-backups.log 2>&1" >> /etc/crontab

To restore a jail from backup:

ezjail-admin delete -w restored.jail # If this jail name already exists
ezjail-admin create -a /backups/jails/example.jail-2023-03-15.tar.gz restored.jail 192.168.1.200
ezjail-admin start restored.jail

6. Monitoring Jails and Automated Responses

Create a monitoring script that checks jail status and restarts failed jails:

#!/bin/sh
# monitor-jails.sh

# Get list of jails that should be running
JAILS=$(grep '^jail_' /etc/rc.conf | grep '_enable="YES"' | sed 's/jail_\(.*\)_enable.*/\1/')

for jail in $JAILS; do
    # Check if jail is running
    jls -j $jail > /dev/null 2>&1
    if [ $? -ne 0 ]; then
        echo "Jail $jail is not running. Attempting to start..."
        service jail restart $jail
        
        # Verify restart was successful
        jls -j $jail > /dev/null 2>&1
        if [ $? -ne 0 ]; then
            echo "Failed to restart jail $jail. Sending alert..."
            echo "Jail $jail failed to restart" | mail -s "Jail Alert: $jail" admin@example.com
        else
            echo "Jail $jail successfully restarted"
        fi
    fi
done

Run this script every 15 minutes:

echo "*/15 * * * * root /path/to/monitor-jails.sh > /var/log/jail-monitor.log 2>&1" >> /etc/crontab

Advanced Automation Techniques

1. Configuration Management with Ansible

For larger deployments, consider using Ansible for jail configuration management:

Install Ansible on the host system:

pkg install ansible

Create an inventory file for your jails:

# /etc/ansible/hosts
[webjails]
web1.jail ansible_connection=jail
web2.jail ansible_connection=jail

[dbjails]
db1.jail ansible_connection=jail
db2.jail ansible_connection=jail

Create playbooks for common tasks:

# web-setup.yml
---
- hosts: webjails
  tasks:
    - name: Install web server packages
      pkgng:
        name:
          - nginx
          - php82
          - php82-extensions
        state: present

    - name: Enable and start nginx
      service:
        name: nginx
        enabled: yes
        state: started

Run the playbook:

ansible-playbook web-setup.yml

2. ZFS Snapshots for Jail Rollback

If using ZFS, automate snapshot creation and management:

#!/bin/sh
# jail-snapshots.sh

# Create daily snapshots
for jail in $(ezjail-admin list | grep -v "STA" | awk '{print $4}'); do
    # Get the ZFS dataset for this jail
    dataset="zroot/jails/$jail"
    
    # Create snapshot with timestamp
    snapshot="${dataset}@$(date +%Y-%m-%d)"
    zfs snapshot $snapshot
    echo "Created snapshot $snapshot"
done

# Keep only last 30 daily snapshots
for jail in $(ezjail-admin list | grep -v "STA" | awk '{print $4}'); do
    dataset="zroot/jails/$jail"
    count=$(zfs list -t snapshot -o name -H $dataset | wc -l)
    
    if [ $count -gt 30 ]; then
        oldest=$(zfs list -t snapshot -o name -H $dataset | head -1)
        zfs destroy $oldest
        echo "Removed oldest snapshot $oldest"
    fi
done

3. Automated Jail Provisioning API

For advanced environments, create a simple API to provision jails:

Install the necessary packages:

pkg install nginx python3 py38-flask

Create a simple Flask application:

# app.py
from flask import Flask, request, jsonify
import subprocess
import os

app = Flask(__name__)

@app.route('/api/jails', methods=['GET'])
def list_jails():
    result = subprocess.run(['ezjail-admin', 'list'], capture_output=True, text=True)
    jails = []
    for line in result.stdout.splitlines()[1:]:
        if line.strip():
            parts = line.split()
            jails.append({
                'name': parts[3],
                'status': 'Running' if parts[1] == 'R' else 'Stopped',
                'ip': parts[2]
            })
    return jsonify(jails)

@app.route('/api/jails', methods=['POST'])
def create_jail():
    data = request.json
    name = data.get('name')
    ip = data.get('ip')
    
    if not name or not ip:
        return jsonify({'error': 'Name and IP required'}), 400
    
    result = subprocess.run(
        ['ezjail-admin', 'create', name, ip],
        capture_output=True, text=True
    )
    
    if result.returncode == 0:
        return jsonify({'status': 'created', 'name': name, 'ip': ip})
    else:
        return jsonify({'error': result.stderr}), 500

if __name__ == '__main__':
    app.run(host='127.0.0.1', port=5000)

Configure Nginx as a reverse proxy:

server {
    listen 80;
    server_name jailapi.local;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Conclusion

ezjail transforms FreeBSD jail management from a manual, command-heavy process into a streamlined, automated system. By leveraging these automation techniques, system administrators can manage large numbers of jails efficiently, ensuring consistent configuration, regular updates, and reliable backups.

The scripts and techniques presented in this article provide a foundation for building a comprehensive jail automation system. As your environment grows, consider expanding these tools with more sophisticated configuration management systems, monitoring solutions, and custom automation scripts tailored to your specific needs.

With ezjail’s powerful features and the automation techniques described, FreeBSD jails become an even more compelling solution for service isolation, security enhancement, and resource management in both development and production environments.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

< Setting Up a Virtual Machine with bhyve on FreeBSD Configure Jails with VNET Networking on FreeBSD >