33.2 Debian Jail

This section configures a Jail based on Debian 12.

Prepare the Base System

Using Debian 12 (bookworm) as an example, build an Ubuntu/Debian base system.

Install the tools for building a Debian/Ubuntu base system.

# pkg install debootstrap

Create the Jail path:

# mkdir -p /usr/jails/debian

Bootstrap the Debian 12 system from the USTC Open Source Mirror:

# debootstrap bookworm /usr/jails/debian https://mirrors.ustc.edu.cn/debian/

Example output is as follows:

I: Retrieving InRelease
I: Retrieving Packages
I: Validating Packages
I: Resolving dependencies of required packages...
I: Resolving dependencies of base packages...
I: Checking component main on https://mirrors.ustc.edu.cn/debian...
I: Retrieving adduser 3.130
I: Validating adduser 3.130
...
I: Extracting usr-is-merged...
I: Extracting util-linux-extra...
I: Extracting zlib1g...

Configuration-related messages may appear at the end of the output. This is normal when debootstrap runs service configuration scripts in a chroot environment and does not affect the base system.

Create a Jail instance using the Debian 12 base system, named debian.

Configure Mount Files

Create the /etc/fstab.debian file. The purpose of each file system is as follows:

devfs      /usr/jails/debian/dev      devfs       rw                      0  0
tmpfs      /usr/jails/debian/dev/shm  tmpfs       rw,size=1g,mode=1777    0  0
fdescfs    /usr/jails/debian/dev/fd   fdescfs     rw,linrdlnk             0  0
linprocfs  /usr/jails/debian/proc     linprocfs   rw                      0  0
linsysfs   /usr/jails/debian/sys      linsysfs    rw                      0  0
/tmp       /usr/jails/debian/tmp      nullfs      rw                      0  0

The purpose of each file system is as follows:

File System	Purpose
devfs	Provides device node access
tmpfs	Provides a temporary file system for shared memory
fdescfs	Provides file descriptor access
linprocfs	Provides a compatible proc file system for Linux applications
linsysfs	Provides a compatible sys file system for Linux applications
nullfs	Mounts the host's tmp directory

Manage the Jail Configuration File

In the /etc/jail.conf file, add the following content (create the file if it does not exist). Key configuration items include: devfs_ruleset defines the ruleset for devfs; enforce_statfs controls the visibility of mount points within the Jail, with values of 0 (no restriction), 1 (visible only under the root directory), or 2 (default, operable only on the mount point where the root directory resides):

debian {                               # Jail name
  host.hostname = "debian";             # Set the Jail's hostname
  mount.fstab = "/etc/fstab.debian";    # fstab file used by the Jail: mount or unmount the corresponding file systems when starting or stopping the Jail
  path = "/usr/jails/debian";           # Jail root directory path
  devfs_ruleset = 4;                     # devfs mount ruleset for the Jail, 0 means no ruleset, the Jail inherits the parent ruleset;
                                        # devfs can only be mounted when allow.mount and allow.mount.devfs are enabled and enforce_statfs is less than 2
  enforce_statfs = 1;                    # Set to 0: all mount points available, no restrictions
                                        # Set to 1: only mount points under the Jail root directory are visible, and the Jail root portion in the path prefix is stripped (e.g., /usr/jails/debian/mnt appears as /mnt inside the Jail)
                                        # Set to 2 (default): can only operate on the mount point where the Jail root directory resides, cannot mount devfs, tmpfs, etc.
  allow.mount;                          # Allow mounting file systems
  allow.mount.devfs;                     # Allow mounting devfs
  exec.start = "/bin/true";              # Command executed when the Jail starts
  exec.stop = "/bin/true";               # Command executed when the Jail stops
  persist;                               # Allow the Jail to persist even without any running processes
  allow.raw_sockets;                      # Allow raw sockets, e.g., ping
  interface = "lo1";                      # Use lo1 as the network interface
  ip4.addr = 192.168.5.1;                 # Specify the IPv4 address
  ip6 = "disable";                        # Disable IPv6
}

exec.start specifies the command to run when starting the Jail. When creating a Jail on FreeBSD, exec.start = 'sh /etc/rc' is typically used to invoke the rc system to start services.

Debian uses systemd as its init system, but Jails lack the necessary cgroup mounts and system privileges to run systemd, so the corresponding commands cannot be executed directly (though the service command still works). Here, /bin/true is used to safely return true (success status) without performing any action.

For example, after enabling the sshd service in the debian Jail (by running service ssh start), the sshd service will not start automatically when the Jail is restarted. In this case, you can set exec.start = 'service ssh start' to ensure that the sshd service starts automatically when the Jail starts.

To enable more services, you can write it as follows:

Start the SSH and D-Bus services in order when the Jail starts:

exec.start += 'service ssh start'
exec.start += 'service dbus start'

exec.stop specifies the command to run when stopping the Jail. FreeBSD Jails typically use sh /etc/rc.shutdown.

Similarly, due to systemd limitations, /bin/true is used here to safely return true.

Manage Firewall Network Access

Add the Jail's address to the jails table in the pf firewall to allow the Jail to access the network:

# pfctl -t jails -T add 192.168.5.1

Start the Instance

Start the Jail:

# jail -c debian

Stop the Jail:

# jail -r debian

Update the Debian System

Update Inside the Jail

Run the following commands to enter the Jail and update the system:

# jexec debian /bin/bash # Currently on FreeBSD
Debian # apt remove rsyslog  # Currently in the Debian Jail
Debian # apt update # Currently in the Debian Jail

Update Outside the Jail

# Execute command inside the debian Jail to remove rsyslog
# jexec -l debian /bin/bash -c "apt remove rsyslog"

# Execute command inside the debian Jail to update the package index
# jexec -l debian /bin/bash -c "apt update"

Using the same method, you can create multiple Jails based on different versions of Debian or Ubuntu.

Jail Service Management

Start the jail service at boot:

# service jail enable

By default, all Jails configured in the /etc/jail.conf file will be started.

You can also specify which Jails to start at boot using the jail_list variable in the /etc/rc.conf file. Edit /etc/rc.conf and add:

jail_list="debian"

Or run:

# sysrc jail_list+=debian

If the jail_list variable is empty, all Jails configured in the /etc/jail.conf file will be started.