Jailman: FreeBSD jail management tool for its own jails

Jailman

Jailman is a jail management tool only for jails that are generated by jailman. Jailman enables users to fetch base file, to create, to list, to start, to login, to stop and to remove jails.

Types of jails supported

Jailman deals with only thick jails. About network, vnet is supported. The following schema shows how non-vnet jails and vnet jails are constructed by jailman.

Non-vnet jail

# (e.g.) assuming host's network interfacde is em0
             ----- Jail -----
             |              |
             |              |
             |              |
             |--------------|
Internet -- em0
             |---- Host ----|
             |              |
             |              |
             |              |
             ----------------

vnet jail

(e.g.) assuming host’s network interfacde is em0.

Routing (recommended way)

# 
L2 Level
             ----- Host -----           ---- Jail -----
             |              |           |             |
Internet -- em0            epair0a--epair0b           |
             |              |           |             |
             |              |           |             |
             ----------------           ---------------
L3 Level
    NetworkA --- Routing ----- NetworkB
 203.0.113.11/24     10.10.10.1/24 - 10.10.10.11/24 

Bridging (optional way)

# 
L2 Level
             ----- Host -----           ---- Jail -----
             |              |           |             |
Internet -- em0 ----+----- epair0a--epair0b           |
             |      |       |           |             |
             |   bridge0    |           |             |
             ----------------           ---------------
L3 Level
    NetworkA ----------------- NetworkB
             203.0.113.11/24         203.0.113.21/24 

Prerequisite

• Gauche Scheme (>= 0.9.15)

For vnet jails with routing (recommended)

• Allow ip forwarding on host (gateway_enable)
• Instruct ip forwarding on host (pf)

You need to explicitly allow and instruct packet forwarding from jail internal network to external interface as follows by setting rc.conf and pf.conf.

# /etc/rc.conf
gateway_enable="YES"
pf_enable="YES"

# /etc/pf.conf
ext_if = "em0"
jail_net = "10.10.10.0/24"
nat on $ext_if from $jail_net to any -> ($ext_if)

For vnet jails with bridging (optional)

• Bridge interface on host

# (e.g.)
# assuming host's network interfacde is em0
# prepare new bridge interface and add em0 to it.

# /etc/rc.conf
cloned_interfaces="bridge0"
ifconfig_bridge0="addm em0 up"

• Bridge interface that has IP on host
  • In the following example, em0 is assigned by DHCP.
  • bridge0 uses em0’s IP and remove the IP from em0.
• Bridge host forwards packets at L3 level.

Anyway, it is safe to have only one of the bridge and/or added memeber interfaces has IP address to avoid mltiple ARP reply issue.

# (e.g.)
# assign IP to bridge interface

# /etc/rc.conf
gateway_enable="YES" # allow L3 packet forwarding
cloned_interfaces="bridge0"
ifconfig_bridge0="addm em0 up"
ifconfig_bridge0="addm em0 SYNCDHCP" # use ip assigned to em0 for bridge0
ifconfig_em0="up" # remove ip from em0

Installation

Clone this repository, give executable permission to the file named ‘jailman’. Add the directory to PATH variable.

Directories

The default directory jailman utilizes is /usr/local/jailman. If JAILMAN_BASE_DIR is set, the directory is used as the base directory. The following directories are created when jailman is used.

• <jailman-base-dir>/media/
  • Store downloaded FreeBSD base files
• <jailman-base-dir>/config/
  • Store configurations of each jail
  • The format is Scheme s-expression.
• <jailman-base-dir>/container/
  • Store jail container
• <jailman-base-dir>/running-info/
  • Store information of running jails

Commands

fetch-media

This command fetches FreeBSD base of the version specified. Available versions can be seen at https://download.freebsd.org/ftp/releases/. Files are stored under <jailman-dir>/media/.

• --version <version>
  • This option specifies a version of FreeBSD to fetch

jailman fetch-media --version 14.2-RELEASE

remove-media

This command removes FreeBSD base version downloaded.

• --version <version>
  • This option specifies a version of FreeBSD to remove

list-media

This command lists FreeBSD base files downloaded.

jailman list-media

create

This command creates FreeBSD container with the specified name and its configuration file. The version of FreeBSD is expanded for the jail. Specified configuration is saved in the configuration file.

• Required options
  • --name <name>
    • This name is used for this jail
  • --version <version>
    • This version needs to be one of the downloaded versions, meaning one of the versions listed by jailman list-media
    • (e.g.) 14.2-RELEASE
  • --hostname <hostname>
    • Hostname of the jail
• Optional option
  • --devfs-ruleset <ruleset-num>
    • devfs rulest number needs to be specified in /etc/devfs.rules or /etc/defaults/devfs.rules

Network related options

Non-vnet jails are created when --vnet is not specified. Vnet jails are created with --vnet option.

For non-vnet jails

• --interface-addr-ip4 <interface|addr> or <interface|add/mask> is optinoally specified.
  • format: <interface>|<ipv4> or <interface>|<ipv4>/mask (e.g.) em0|192.168.11.11

For vnet jails without bridge (recommended way for vnet jail)

• --vnet is required
• --vnet-epaira-ip4 <addr/mask> is required.
  • format: <ipv4>/<netmask> (e.g.) 10.10.10.1/24
• --vnet-epairb-ip4 <addr/mask> is required.
  • format: <ipv4>/<netmask> (e.g.) 10.10.10.101/24

For vnet jails using bridge (optional way)

• --vnet is required
• --use-bridge <bridge-interface> is required.
  • format: bridgeN (e.g.) bridge0
• --vnet-epairb-ip4 <addr/mask> is required.
  • format: <ipv4>/<netmask> (e.g.) 203.0.113.21/24
  • this should belong to the same network of brdige interface.

# non-vnet jail
jailman create --name jail01 --version 14.2-RELEASE --hostname jail01

# vnet jail
jailman create --name jailvnet01 --version 14.2-RELEASE --hostname jailvnet01 \
        --vnet --vnet-epaira-ip4 10.10.10.1/24 --vnet-epairb-ip4 10.10.10.11/24

# vnet jail using bridge (optional)
# (please make sure eparib IP belongs to the same network as the bridge's or its member's network
jailman create --name jailvnet02 --version 14.2-RELEASE --hostname jailvnet01 \
        --vnet --use-bridge bridge0 --vnet-epairb-ip4 203.0.113.21/24

start

This command starts the specified container with its configuration.

• --name <name>
  • This option specifies the jail to start.

jailman start --name jail01

stop

This command stops the specified container with its running information.

• --name <name>
  • This option specifies the jail to stop.

jailman stop --name jail01

stopall

This command stops all the running jails managed by jailman

• --yes
  • This option skips confirmation.

jailman stopall --yes

login

This command allows users to log in the specified jail if it is running. Unlike jexec, login shell session is started.

• --name <name>
  • This option specifies the jail to log in.
• --user <user>
  • This option allows login by the specified user.

jailman login --name jail01
jailman login --name jail01 --user admin

list

This command lists jail conditions managed by jailman. If there are jails that are not managed by jailman, they are not listed.

jailman list

remove

This command removes the specified name of container and config.

• --name <name>
  • This option specifies the jail to remove.

jailman remove --name jail01

Contact

Your feedback is welcome.

Maintainer: Toshihiro (Toshi) Umehara toshi@niceume.com