% cbsd jconstruct-tui
                

                % cbsd jcreate jconf=/path/to/conf.jconf
                

The jail is created according to configuration file generated by cbsd jcreate jconf=path_to_cfg. For create configuration, use a command cbsd jconstruct (question-answer dialog mode), or dialog(1)-based interface: cbsd jconstruct-tui, or via WEB interface. When pkg.conf and repository configured properly, you can preset to new jail some packages mark them through pkglist menu. For safety reason recommended to use the official FreeBSD pkg repo or build your own package repository.

Please note: when repo unavailable, item pkglist in cbsd jconstruct-tui did not show anything.

Please note: multi-repo and and the ability to choose a specific repository from the list at the moment is missing, and will be used repository prescribed in pkg.conf of master host.

If you do not use automation (Puppet, Ansible, own implementation for generation of jconf) to create environments and you have to create a container with different parameters, use the ability to create your own profile to override the default values. You can override any parameter - the proposed template for jail name, version, binding to a specific interface instead of 'auto', etc..

for creating config via dialog:

                        % cbsd jconstruct-tui
                

The same menu is available to create a jail when configuring CBSD via bsdconfig

If jconstruct-tui work correctly, on the exit the question for jail create will be asked. In a case positively answer, jcreate it will be executed on a new configuration automatically. Otherwise, the script will save configuration file (in $workdir/ftmp), on which it is possible to create a jail by hand.

You can override the jailskeldir="$workdir/share/jail-skel", parameters which is stored in $workdir/etc/defaults/jail-freebsd-default.conf to specify an alternate template directory, which will overwrite the files in the original base files when creating jail. To do this, create a file jail-freebsd-XXXXX.conf in $workdir/etc and enter the value.:

See for details: Profiles for jail creation

• profile - profile in which the parameters are set by default. Described above
• pkglist - Select package list for new jail
• jname - Short (one word) name of the jail
• host_hostname - FQDN for the jail environment
• ip4_addr - specify IP addresses (separated by commas if more than one) or 0 for vnet/bhyve environments
• ver - FreeBSD version for the base (10.1, 11.0 for RELEASE or 10, 11 for STABLE)
• baserw - mount copy of base via nullfs in read only (baserw=no) or populate own copy (baserw=yes) with write access
• mount_ports - mount /usr/ports dir from base system to jail (read only). To the environment can build ports (and not interfere with each other vorkdir) - reassigned WRKDIRPREFIX parameters to alternate location. Or, make sure that applytpl params is set to 1 - then CBSD does this automatically via WRKDIRPREFIX=/tmp in /etc/make.conf of the jail
• astart - Automatic start jail on the system boot
• interface - Specify uplink for jail (on what interface create/remove IP) or prohibit.
• applytpl - Automatically adjust the same settings of the jail (create /etc/hosts, change WRKDIRPREFIX, etc..)
• floatresolv - Automatically adjust /etc/resolv.conf from jnameserver IP (settings from initenv/initenv-tui)
• arch - Specify architecture of jail environment
• vnet - Enable or disable VIMAGE feature

                % cbsd jconstruct
                

                % cbsd jcreate jconf=/path/to/conf.jconf
                

If DIALOG-based script jconstruct-tui for some reason did not come for create configuration of the new jails, you can use the script, dialogue like "question and answer" jconstruct

                        % cbsd jconstruct
                

Which specifies the same question as the tui-version. Also, the configuration can avoid the formation without additional interactive utilities, for example building systems that automatically create the necessary jails.

Example of a standard configuration for jcreate might look like:

                jname="jail1";
                path="/usr/jails/jails/jail1";
                host_hostname="jail1.my.domain";
                ip4_addr="10.0.0.24/24";
                mount_devfs="1";
                allow_mount="1";
                allow_devfs="0";
                allow_nullfs="0";
                mount_fstab="/usr/jails/jails-fstab/fstab.jail1";
                arch="amd64";
                mkhostsfile="1";
                devfs_ruleset="4";
                ver="10.0";
                basename="";
                slavenode="0";
                baserw="0";
                basename="";
                mount_src="0";
                mount_obj="";
                mount_kernel="0";
                mount_ports="1";
                astart="1";
                data="/usr/jails/jails-data/jail1-data";
                vnet="0";
                applytpl="1";
                mdsize="0";
                rcconf="/usr/jails/jails-rcconf/rc.conf_jail1";
                floatresolv="1";
                exec_start="/bin/sh /etc/rc";
                exec_stop="/bin/sh /etc/rc.shutdown";
                
                exec_poststart="0";
                exec_poststop="0";
                exec_prestart="0";
                exec_prestop="0";
                
                exec_master_poststart="0";
                exec_master_poststop="0";
                exec_master_prestart="0";
                exec_master_prestop="0";
                interface="auto";
                jailskeldir="${sharedir}/jail-skel"
        

If you want to create jail with installed some packages from pkg repository, in this configuration must have an pkglist pointing to a file with a list of packages, for example:

                pkglist="/tmp/newjail.txt";
        

The /tmp/newjail.txt file might look like:

        mc
        lynx
        nginx-devel
        lsof
        

cbsd jcreate remove file pointed by pkglist variables after jail create

By default, the directory specified by jailskeldir will be used as source files that will be added (or they will be overwritten with standard files) into a jail automatically when applytpl=1. Accordingly, you can create any configuration templates and content environments that will be copied when creating a new jail.

                        % cbsd jcreate
                

Profile for jail settings

Description

For example, you do not work with a huge number of nodes and environments, when such tools as Puppet, Ansible, SaltStack, Chef or your own implementation for generating .jconf file for jcreate can be useful. However, you often have to create environments and at the same time do not accept a number of default options. In this case we recommend that you use profiles to override the default values, or create your own profile

Take a look on content of $workdir/etc/defaults/jail-freebsd-default.conf file. It represents the settings that are used in jconstruct-tui by default.

Let's say you want to create a container always in baserw=1 mode (instead of baserw=0 by default), on interface lo0 (instead of auto, which selects the interface depending on the subnet jail) and you prefer a name cell instead of jail wih domain example.com and at the same time, container must be launched instantly after creation ( runasap="1" ) ( do not confuse with astart="1" for lauch on boot)

To do this, create in the directory (or copy from $workdir/etc/defaults) $workdir/etc/ file with same name, in which we can reassign the settings:

                % echo 'baserw="1"' > ~cbsd/etc/jail-freebsd-default.conf
                % echo 'interface="lo0"' >> ~cbsd/etc/jail-freebsd-default.conf
                % echo 'default_jailname="cell"' >> ~cbsd/etc/jail-freebsd-default.conf
                % echo 'default_domain="example.com"' >> ~cbsd/etc/jail-freebsd-default.conf
                % echo 'runasap="1"' >> ~cbsd/etc/jail-freebsd-default.conf
                

So we got file $workdir/etc/jail-freebsd-default.conf with follow content:

                baserw="1"
                interface="lo0"
                default_jailname="cell"
                default_domain="example.com"
                runasap="1"
                

It's all! Now we can run cbsd jconstruct-tui, where you need to do even fewer settings to create an environment!

You may want to create several profiles of your own. To do this, also create the files in the directory ~cbsd/etc/ by using in the name of file prefix: jail-freebsd-YOUR_PROFILE.conf

In this case, as the _invariant_ parameter within each profile, there must be a name for this profile in the variable jail_profile="default" and jail_active set to 1 (active profile). For example, let's create two profiles: baserw and lo0:

• 
  

                  % echo 'jail_profile="baserw"' > ~cbsd/etc/jail-freebsd-baserw.conf
                  % echo 'jail_active="1"' >> ~cbsd/etc/jail-freebsd-baserw.conf
                  % echo 'baserw="1"' >> ~cbsd/etc/jail-freebsd-default.conf
                  

• 
  

                  % echo 'jail_profile="lo"' > ~cbsd/etc/jail-freebsd-lo0.conf
                  % echo 'jail_active="1"' >> ~cbsd/etc/jail-freebsd-lo0.conf
                  % echo 'interface="lo0"' >> ~cbsd/etc/jail-freebsd-lo0.conf
                  

  Now you will see the profiles in the choice of possible options for the 'profile' menu at startup of cbsd jconstruct-tui

  Perhaps you want the profile lo0 to be the default, since you use it most often. You can override in $workdir/etc/jail-freebsd-default.conf profile by default via params default_profile:

                  % echo 'default_profile="lo"' > ~cbsd/etc/jail-freebsd-default.conf
                  

  The contents of the file ~cbsd/etc/jail-freebsd-default.conf will be:

                  default_profile="lo"
                  

  In this case, when you execute cbsd jconstruct-tui, you do not even need to choose a profile. There are very few actions to run a new environment.

  Profile for jail content

  Description

  Suppose you need to create a series of alike jails which all require a certain set of software and configuration,for example an environment with running an nginx http server with a custom index.html. One way to achieve this is to create a jail (eg jail1), perform all necessary adjustments and do a jexport. Afterwards whenever you need a new instance, run the command:

     % cbsd jimport jname=jail1 newjname=jail2
                  

  This creates an image on the basis of jail1 called jail2. Another way to get similar results is making use of jclone. However, it is not always convenient (especially in terms of keeping software up to date in the original jail). Another way is to to apply profiles and alternative skel-directories for applications we need to change on the fly when creating fresh jails.

  Example:

  1) Write jconf:

  If you want to create a non-interactive scripts, create a template from which to create new a jail. To do this, run cbsd jconstruct-tui and when asked if you want to create the jail immediately select not to. In this case, the command to be withdrawn for jcreate and the path to jconf - this is the configuration for which you are creating the jail. Alternatively, it is possible to write manually, for example:

  % mkdir /root/share
  % cat > /root/share/nginx.jconf << EOF
  # DO NOT EDIT THIS FILE. PLEASE USE INSTEAD:
  # cbsd jconfig jname=jail1
  relative_path="1";
  jname="jail1";
  path="/usr/jails/jails/jail1";
  host_hostname="jail1.my.domain";
  ip4_addr="DHCP";
  mount_devfs="1";
  allow_mount="1";
  allow_devfs="1";
  allow_nullfs="1";
  mount_fstab="/usr/jails/jails-fstab/fstab.jail1";
  arch="native";
  mkhostsfile="1";
  devfs_ruleset="4";
  ver="native";
  basename="";
  baserw="0";
  mount_src="0";
  mount_obj="0";
  mount_kernel="0";
  mount_ports="1";
  astart="1";
  data="/usr/jails/jails-data/jail1-data";
  vnet="0";
  applytpl="1";
  mdsize="0";
  rcconf="/usr/jails/jails-rcconf/rc.conf_jail1";
  floatresolv="1";
  zfs_snapsrc="";
  
  exec_poststart="0";
  exec_poststop="";
  exec_prestart="0";
  exec_prestop="0";
  
  exec_master_poststart="0";
  exec_master_poststop="0";
  exec_master_prestart="0";
  exec_master_prestop="0";
  pkg_bootstrap="1";
  pkglist="/root/share/pkglist.txt";
  
  with_img_helpers="";
  runasap="0";
  interface="auto";
  jailskeldir="/root/share/nginx-jail"
  jail_profile="default";
  # root password
  user_pw_root='rootpw'
  exec_start="/bin/sh /etc/rc"
  exec_stop="/bin/sh /etc/rc.shutdown"
  emulator="jail"
  EOF
                  

  Where the most important for us:

  • jail1 - jail name
  • user_pw_root - parameter sets the appropriate root password (you can generate password file instead in skel-dir)
  • ip4_addr="DHCP" - causes CBSD take the first free IP range of nodepool
  • jailskeldir="/root/share/nginx-jail" - alternative path to skel-dir, applied after the jail creation
  • pkglist="/root/share/pkglist.txt" - path to a file that defines a set of software in the cell when it is created
  • arch="native" - use/inherit 'hoster' architecture. Or specify: i386, amd64
  • ver="native" -use/inherit 'hoster' version. Or specify: 10.3, 11.1, 12

  2) Write pkglist.txt

  Just listed origin or packagename of software that want to get in the jail:

  % cat > /root/share/pkglist.txt << EOF
  www/nginx
  shells/bash
  EOF
                  

  3) skel-directories

  Custimize directories of additional files that are copied to the jail. Namely - prescribe nginx in rc.conf inside the jail and push into /usr/local/www/nginx/index.html some text to output:

  % cp -a /usr/local/cbsd/share/jail-skel /root/share/nginx-jail
  % mkdir -p /root/share/nginx-jail/usr/local/www/nginx
  % cat > /root/share/nginx-jail/usr/local/www/nginx/index.html << EOF
  <html>
     <body>
        <pre>
        It's been a hard day's night
        And I've been working like a dog
        It's been a hard day's night
        I should be sleeping like a log
        </pre>
     </body>
  </html>
  EOF
  % sysrc -f /root/share/nginx-jail/etc/rc.conf nginx_enable="YES"
                  

  4) the creation and launch

  Create a environment, run and check:

  % cbsd jcreate jconf=/root/share/nginx.jconf
  % cbsd jstart jail1
  % curl http://X.Y.N.M
        It's been a hard day's night
        And I've been working like a dog
        It's been a hard day's night
        I should be sleeping like a log
                  

  Profiles for jconstruct-tui

  If you want to manually create these jails, choosing when it should be necessary skel-directories or the default settings, create the directory $workdir/etc file named jail-freebsd-XXXX.conf with minimum content:

  jail_profile="XXX"
                  

  where XXX - name of the profile. Profile vnet in CBSD is created as an example, you see it in $workdir/etc/defaults/jail-freebsd-vnet.conf

  In turn, it overwrites the default values from the profile defaults: jail-freebsd-default.conf

  If you rarely use the default profile and want to CBSD default offered at your profile, change the value default_profile putting it in the name of your profile:

  echo 'default_profile="XXX"' > ~cbsd/etc/jail-freebsd-default.conf
                  

                        % cbsd jconfig
                        % cbsd jset
                

Descriptions:

Cconfiguration parameters jail

Each CBSD jail stores the settings in SQLite3 database. In addition, $workdir/jails-fstab/ may have fstab files (see below). To change the settings of jail can serve cbsd jconfig command, which is runs the TUI menu to change basic settings:

IP addresses that are bound to the jail sets in ip4_addr parameter. As an IP may serve as IPv4, and the IPv6 address. When starting and stopping jail, working with IP may take place in two modes:

• automatic on-the-fly creation of IP addresses for the jail at the time of launch + automatic removal from the interface IP when stopping
• the use of previously initialized IP addresses.

When for jails assigned to more than one address, they should be listed separated by commas without spaces. IP can include network prefix specified through IP/prefix. By default, aliases created with the prefix /32, that may not be appropriate if the jail uses a separate subnet from the network server — in this case, the correct /prefix is needed.

The parameter that controls this behavior pointed by interface parameter. When interface=0, jstart and jstop will not be called ifconfig alias and ifconfig -alias, respectively. If its value is auto or name of network nics, this command will be executed:

                                % ifconfig interface ips alias
                        

and when jail stop:

                                % ifconfig interface ips -alias
                

Be careful with this option, if you have only one IP for server that is used and this IP is assigned to the same jail, when stopping jail, ip address of the server will be removed automatically that will make the server unavailable. In this case, you need to use:

                        interface=0
                

For example, to run the configuration tool for the jail1, run:

                        % cbsd jconfig jname=jail1
                

Each jail can have your fstab file, which lists the file systems that are mounted jail is startup. System records (they are managed by CBSD and edit this file inappropriately) are located in the file $workdir/jails-fstab/fstab and the same syntax to format the file system /etc/fstab with the exception that as a mount point is the path relative to the root jail, not the master system.

For user entries, you can use the file in the same directory with the extension .local. For example, if you want to make between jail1 and jail2 a shared directory (via nullfs), which physically located in the master node (e.g.: /home/sharefs), the files $workdir/jails-fstab/jail1/fstab.local and $workdir/jails-fstab/jail2/fstab.local should have:

                        /home/sharefs /home/sharefs nullfs rw 0 0
                

If you want to mount tmpfs to /tmp dir in jail1 (those actually in /usr/jails/jails/jail1/tmp), then the entry in the $workdir/jails-fstab/jail1/fstab.local should have:

                        tmpfs /tmp tmpfs rw 0 0
                

both entries perform the same action as commands:

                        mount -t nullfs -o rw /home/sharefs /jailroot/home/sharefs
                        mount -t tmpfs -o rw tmpfs /jailroot/tmp
                

If you want to mount into jail2 a directory from jail1, jail1 path should point to the directory containing the data jail1 (and their mount points ${workdir}/jails/jail1). For example entry $workdir/jails-fstab/jail2/fstab.local:

                        /usr/jails/jails-data/jail1-data/usr/local/www /usr/local/www nullfs ro 0 0
                

Make the shared directory /usr/local/www between jail1 and jail2, but it will jail2 in read-only mode

There are flaws when mounting via mount -t /type/ does not work or mounting must be done in a non-standard way. In this case, use the 'external' reserved word, where the 'source' field will point to your external script, the output of which should be a mounted directory.

An example of such an entry in fstab.local:

                /root/ntfs-3g.sh        /home/web/downloads external rw 0 0
                

and an example working script /root/ntfs-3g.sh for this entry: ntfs-3g.sh, which mounts an external USB drive directly into the container.

If you want to attach separate ZFS filesystems in jail (ie, want to be able to perform in jail zfs mount), ZFS dataset must list in $workdir/jails-fstab/$jname/fstab.local file with specifying the keyword zfs in FStype field. For example, if you want to present the file system ZFS: zroot/jail1_webfs for jail jail1 $workdir/jails-fstab/jail1/fstab.local must have:

                        zroot/jail1_webfs /home/web zfs rw 0 0
                

Note: mount point (/home/web in this example) is not important

Note: jail must have allow_zfs paramaters set to 1, what can be done via cbsd jconfig jname=$jname

In fact, it makes CBSD execute commands:

                        % zfs set jailed=on $FS
                        % zfs jail $jname $FS
                

when jail started and

                        % zfs set jailed=off $FS
                        % zfs unjail $jname $FS
                

when stoped.

Another possibility is to change certain parameters of the jail — use the command cbsd jset. Full list of possible arguments can be accessed through --help:

                        % cbsd jget --help
                

For example, to change ip of jail1:

                        % cbsd jset jname=jail1 ip4_addr="10.0.0.20/24,192.168.0.20/24" 
                

cbsd jconfig jname=jail2

cbsd jset

You can write your own scripts to be executed within the jail and in the master host on startup and shutdown of the environment. For this, the system directory of jail ( $workdir/jails-system/$jname/ ) have the following directories:

• master_poststart.d - scripts for executing in the master host after jail starts (Be careful, because the scripts are is not jailed)
• master_poststop.d - scripts for executiong in the master host after jail stops (Be careful, because the scripts are is not jailed)
• master_prestart.d - scripts for executing in master host before jail starts (Be careful, because the scripts are is not jailed)
• master_prestop.d - scripts for execution in master host after jail stops (Be careful, because the scripts are is not jailed)
• start.d - scripts for execution within jail when jail is starts. Analog of parameter exec.start from original jail.conf
• stop.d - scripts for execution within jail when jail is starts. Analog of parameter exec.stop from original jail.conf
• remove.d - (since CBSD 11.0.10) scripts for execution on remove command

Write scripts to the master_\* directories can be useful if at the start-stop jail you need to perform some action is not associated with content of environment - for example, create a ZFS snapshot, put rules in IPFW and etc.

In scripts, you can use CBSD variables, such as $jname, $path, $data, $ip4_addr, for example, by placing a script (with execute permission) in /usr/jails/jails-system/jail1/master_poststart.d/notify.sh:

                #!/bin/sh
                echo "Jail $jname started with $ip4_addr IP and placed on $path path" | mail -s "$jname started" [email protected]
                

You will receive notification upon startup cells by email: [email protected]

The functionality of execution custom scripts and the availability of variables in environments can play a big role in the integration of CBSD and external applications, such as Consul

As an example of use, see the article Example of using CBSD/bhyve and ISC-DHCPD (Serve IP address in bhyve through pre/post hooks)

As an example of use, see the article Example of using CBSD/jail and Consul (Register/unregister jail's via pre/post hooks, in Consul)

                        % cbsd jstart jname=jail1 jail2
                        % cbsd jstart jail1 jail2 ... jailX

                        % cbsd jstop jname=jail1 jail2
                        % cbsd jstop jail1 jail2 ... jailX

                        % cbsd jrestart
                        % cbsd jorder
                

Running jails occurs at startup CBSD/server automatically if parameter astart (auto-start) corresponding jail set to 1. You can change this setting through cbsd jconfig or cbsd jset. When you stop the server or service cbsdd, all running jails will be stopped automatically.

Starting the jail manually by the command:

                        % cbsd jstart jname=jail1
                

or

                        % cbsd jstart jail1
                

or

                        % cbsd jstart jail1 jail2 jail3 ..
                

(to launch multiple jails by one command)

When ( You can change this behavior in cbsd initenv-tui ) parallel=0 and you try to launch/stoping a few jails, start/stop will be held consecutively. It is not always good, as any error triggered inside jails in the rc-scripts, which leads to a pause, can block start/stop next jails. In the case when parallel have a non-zero value, each next jails will be launched/stopped in N seconds after the previous one, where N — parallel value. After this timeout, no matter whether the previous jail o start fully and next jail will be started.

To stoping jail jstop must be used, with the same syntax and behavior:

                        % cbsd jstop jname=jail1
                

or

                        % cbsd jstop jail1
                

or

                        % cbsd jstop jail1 jail2 jail3 ..
                

(to stopping multiple jails by one command)

If the argument of the jstart/jstop/jrestart command is missing, will displays the corresponding list of all running or stopped jail for interactive selection

When the jail is started, it creates a lock file, a sign that the jail working via file ${jailsysdir}/${jname}/locked which records the name of the node. This feature is used when this jail presented several nodes, these jail are in the DFS (NFS, glusterfs, etc.) and any node is able to run it. This lock ensures that the presence of the same jail at the second node, it will not be launched.

With a large number of jails (particularly databases, with services such as MySQL, redis, cassandra, etc.), it should be borne in mind that the low value parallel (for example, less than 5 seconds) can generate a very intensive storage I/O load that can increase the amount of start-up time of all jails, than if they were run sequentially or higher timeout.

Additionally, when a shutdown command is running on the server with lots of jails/services that should be taken into consideration low timeout that defaults to perform rc.shutdown sequence. In this regard, the process init(8) can interrupt the rc-scripts on this timeout, resulting in abnormal shutdown jails. In this case, the database can lead to nonconservation or damage data. To avoid this, /etc/rc.conf master system should be adjusted parameter rcshutdown_timeout to a more reasonable value (default: 90 seconds)

In the absence of rcshutdown_timeout in the system /etc/rc.conf, cbsd initenv will put this option in its sole discretion automatically.

Also, keep in mind that when using the zfs features ($workdir/nc.inventory, the parameter zfsfeat=1), and the file system ZFS, at jstop, file system of jails will be unmounted and those catalog $workdir/jails-data/jail1-data will be empty. If in such a case when jail data is requires without running it, by the command zfs list You can see the name appropriate file system and run zfs mount fs.

Please read details on the Jail config

% cbsd jls display=jname,b_order
                

% cbsd jls display=jname,b_order
JNAME    B_ORDER
firefly  3
jail1    10
kde4     1
kdeold   9
spicy2   2
test     2
        

% cbsd jorder
        

                        % cbsd jremove
                

                        % cbsd jremove jail1
                

                        % cbsd jrename
                

                        % cbsd jrename old=jail1 new=jail50 host_hostname=jail50.my.domain ip4_addr=192.168.0.5/24
                

                        % cbsd jsnapshot mode=create jname=jail1 snapname=before_update
                

                        % cbsd jsnapshot mode=destroy jname=jail1 snapname=before_update
                

                        % cbsd jexport jname=jail1
                

jupgrade command

                        % cbsd jupgrade
                        % cbsd jconfig