FreeBSD virtual environment management and repository

2020-10 upd: we reached the first fundraising goal and rented a server in Hetzner for development! Thank you for donating !

Attention! Current pages describe CBSD version 13.0.x. If you are using an older version, please update first.

Attention! I apologize for the automatic translation of this text. You can improve it by sending me a more correct version of the text or fix html pages via GITHUB repository.

Profiles for jail creation

Command: jcreate

			% 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". For example, let's create two profiles: baserw and lo0:


  • 		% echo 'jail_profile="baserw"' > ~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 '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
    		
  • Please note that the files in the $workdir/etc/defaults can not be edited - as well as in the /etc/defaults. If you want to override the default values, copy the directory $workdir/etc/defaults file with the same name in the directory $workdir/etc and change