NAME

cbsd —

FreeBSD jail management tool

SYNOPSIS

cbsd [cmd]

cbsd [cmd] [param=val]

cbsd [--help]

DESCRIPTION

cbsd is a jail and VM management tool. It builds upon and extends standard tools used for jails and bhyve manipulation.

List of some of the programs and functions involved in cbsd :

vnet (VIMAGE)
zfs
racct/rctl
pf/ipfw/ipfilter
carp
hastd
bhyve
Xen

Many of these subsystems are not directly related to jails, however allow cbsd (being the connecting link between these components) to provide the system administrator with a more advanced and integrated system for problem solving.

The information provided below could be useful to the system administrator and describes the cbsd architecture in more detail. It is also recommended to read through the official articles about FreeBSD Jails for better understanding of the jails basics.

You can get a description for each command via: cbsd <command> --help or cbsd help <command> , for example, start with:

% cbsd help --help

Naming conventions

Let us agree on some names and values that will be used throughout the documentation:

node

physical server / resource unit

jail

isolated environment with its own set of software/services.

farm

cluster of interconnected nodes, a full-fledged peer network (each node can do other tasks)

basejail

in the CBSD context - a copy of FreeBSD base system.

cbsd

an entity that has control over the particular node(s) and certain subsystems of FreeBSD, is able to provide a simplified and unified action (API) on the nodes or jails and provides ACL and setting permissions for CBSD customers

$jname

jail name

All working data of CBSD is placed in the $workdir directory (e.g. /usr/jails), it is also the home directory for the cbsd user. You can quickly change to this directory by issuing:

% cd ~cbsd

The most important data are located in $workdir/jails-data/$jname, as it is directly the root of the jail's filesystem called $jname, if jail is created with the flag baserw=1. Or contains the data of jail, which are superimposed on the standard $workdir/basejail/$basename system mounted in the ${workdir}/jails directory.

The base system can always be built from source code, or downloaded from the repository.

cbsd allows jails creation, backups, snapshotting, cloning and changing different jails options. It also allows to control the order in which the jails should be started. When using more than one node running cbsd it allows to clone jails between nodes and even allows to control the remote node(s) from the "master" of the farm.

All commands begin with cbsd prefix.

The cbsd commands can accept arguments which are written in a "param=value" form. cbsd commands can have both obligatory arguments and arguments which are optional. To receive list of all available commands type: cbsd --help

Each subcommand has a short usage help available when typing cbsd <subcommand> --help and an extended manual page accessible by typing "man cbsd-subcommand". The subcommands are as follows:

alljails=1

ENVIRONMENT

By default, CBSD displays text in color (using escape sequences ANSII). If for some reason the color is unpleasant, or you want to use output from CBSD utilities in your scripts, you can disable the color through the environment variable NOCOLOR=1. For example:

% env NOCOLOR=1 cbsd jls

In addition, you can create your own COLOR schemes via ~cbsd/etc/color.conf config file. For example for white color schema you can copy sample profile:

% cp /usr/local/cbsd/etc/defaults/color-white.conf \
  ~cbsd/etc/color.conf

FILES

${workdir}: Working directory on CBSD node (usually /usr/jails). It is initialized through cbsd initenv
${workdir}/.rssh/: Directory to store private keys of remote nodes. The files are added and removed via the cbsd node
${workdir}/.ssh: This location serves as a storage for private and a public keys of the node itself. Formed during the initialization with the cbsd initenv command. The public keys of remote hosts when adding them as node using the cbsd node mode=add will be taken from here. Key filename is the MD5 sum of the node name.
${workdir}/basejail: Here are the FreeBSD base system and kernels kept ready for use (the result of cbsd buildworld/buildkernel, cbsd installworld/installkernel or cbsd repo action=get sources=base/kernel )
${workdir}/etc: Configuration files needed to run CBSD
${workdir}/export: Default directory for jails exported to a file (using the cbsd jexport jname=$jname, the file will be stored under $jname.img)
${workdir}/import: Default directory from which jails are imported (using cbsd jimport jname=$jname, jail will be deployed as $jname)
${workdir}/jails: This directory contains the mount point for the jails' root, those that use baserw=0.
${workdir}/jails-data: This directory has the jails data. These are the directories that you need to backup (including fstab and rc.conf files). Also, if the jail uses baserw=1, these directories contain the jail's root when it starts
${workdir}/jails-fstab: fstab file for the jails. The syntax is like for regular FreeBSD fstab with the only exception, that the path to the mount point is written relative to the jail's root (record
/usr/ports /usr/ports nullfs rw 0 0
in the file fstab.$jname means, that the master node directory /usr/ports will be mounted at startup in ${workdir}/jails/$jname/usr/ports)
${workdir}/jails-rcconf: rc.conf files for jail creation. These parameters can be changed with your editor, or via the command cbsd jset $jname param=val (eg cbsd jset jname=$jname ip="192.168.0.2/24"). To change these settings the jail should be turned off.
${workdir}/jails-system: This directory may contain some helper scripts related to the jail (e.g. configuration wizards, etc) as well as the preserved jail traffic information, when using ipfw and its description. This directory participates in jimport/jexport operations and migration of jail
${workdir}/var: directory that contains system information for CBSD. For example, in ${workdir}/var/db is an inventory of local and remote nodes that were added
/usr/local/cbsd: A copy of the original files installed by CBSD port. Also contains the working scripts in sudoexec

EXIT STATUS

The cbsd utility exits 0 on success, and >0 if an error occurs. The codes are usually described in the --help section for the command/subcommand.

EXAMPLES

Show list of jails:

cbsd jls

Show help for jlogin command:

cbsd jlogin --help

Run DIALOG-based jail configuration tools:

cbsd jconstruct-tui

EXIT STATUS

cbsd returns a zero exit status if it succeeds. Non-zero is returned in case of a failure or non-standard conclusion. The codes are usually described in the --help parameter to a command/subcommand.

AUTHORS

Oleg Ginzburg <olevole@olevole.ru>