.. -*- coding: utf-8; indent-tabs-mode: nil; -*-

ftjail
======

Synopsis
--------

**ftjail -hV**

**ftjail subcommand**


Description
-----------

Management tool for Thin Jails: creation of base and skeleton ZFS datasets,
mount and population helpers.

The following global options are implemented:

.. program:: ftjail

.. option:: -h

   Print a short usage message to stdout and exit.

.. option:: -V

   Print the program name and version number to stdout and exit.


Subcommands
-----------

:manpage:`ftjail-build-etcupdate-current-tmpl(8)`

    Build a "current" tree suitable for the default and extract mode
    of \"etcupdate\"

:manpage:`ftjail-check-freebsd-update(8)`

    Check for preconditions to run :manpage:`ftjail-freebsd-update(8)`
    for a Thin Jail successfully

:manpage:`ftjail-copy-skel(8)`

    Recursively copy template skeleton contents into jail-specific datasets

:manpage:`ftjail-datasets-tmpl(8)`

    Create ZFS template datasets for new Thin Jails using base and skeleton

:manpage:`ftjail-freebsd-update(8)`

    A :manpage:`freebsd-update(8)` implementation for Thin Jails

:manpage:`ftjail-mount-tmpl(8)`

    Canonically mount the RO base and the RW skeleton of a Thin Jail

:manpage:`ftjail-umount-tmpl(8)`

    Unmount mounted Thin Jail template datasets

:manpage:`ftjail-interlink-tmpl(8)`

    Create proper symlinks for "skeleton" style Thin Jails

:manpage:`ftjail-populate-tmpl(8)`

    Populate a prepared directory structure with the contents of a
    FreeBSD base system

:manpage:`ftjail-snapshot-tmpl(8)`

    Recursively create ZFS snapshots of the RO base datasets and the RW
    skeleton datasets


Implementation Notes
--------------------

All commands with the exception of :command:`ftjail populate-tmpl` and
:command:`ftjail interlink-tmpl` require ZFS as filesystem.


Environment
-----------

All environment variables that affect :command:`zfs` are effective also.


Examples
--------

Prepare the containers for the template datasets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Container for templates::

   zfs create -o canmount=off -o mountpoint=/jail/ttmpl zpool/jail/ttmpl

Sub-container for all read-only bases::

  zfs create -o canmount=off zpool/jail/ttmpl/base-ro

Sub-container for all read-write volumes::

   zfs create -o canmount=off zpool/jail/ttmpl/skel-rw


Create a new complete template for a FreeBSD distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create new template datasets and populate them from a distribution archive.
The example is for FreeBSD 13.3-RELEASE::

  # prepare empty datasets
  ftjail datasets-tmpl -P zpool/jail/ttmpl/base-ro zpool/jail/ttmpl/skel-rw 13.3-RELEASE

  #
  # Here you can adjust some properties (``canmount``) or create some additional
  # datasets manually.
  #

  # mount at a temporary mountpoint
  mkdir /var/tmp/13.3
  ftjail mount-tmpl -P zpool/jail/ttmpl/base-ro/13.3-RELEASE zpool/jail/ttmpl/skel-rw/13.3-RELEASE /var/tmp/13.3

  # populate the contents from the distribution archive
  ftjail populate-tmpl -P /var/tmp/13.3 base-13.3-RELEASE.txz

  # If the kernel is wanted also then extract it like this
  ftjail populate-tmpl -P -b /var/tmp/13.3 base-13.3-RELEASE.txt kernel-13.3-RELEASE.txz

Make a named snapshot named "base" for the original::

  ftjail snapshot-tmpl zpool/jail/ttmpl/base-ro/13.3-RELEASE zpool/jail/ttmpl/skel-rw/13.3-RELEASE base

Also prepare the :command:`etcupdate`::

  ftjail build-etcupdate-current-tmpl /var/tmp/13.3 etcupdate-current-13.3@base.tbz

Update to the current patch level and tag accordingly (e.g. "p5")::

  # Update
  freebsd-update -b /var/tmp/13.3 -d /var/tmp/13.3/var/db/freebsd-update/ --currently-running 13.3-RELEASE fetch
  freebsd-update -b /var/tmp/13.3 -d /var/tmp/13.3/var/db/freebsd-update/ --currently-running 13.3-RELEASE install

  # Snapshot
  ftjail snapshot-tmpl zpool/jail/ttmpl/base-ro/13.3-RELEASE zpool/jail/ttmpl/skel-rw/13.3-RELEASE p5

  # Do not forget to prepare for etcupdate
  ftjail build-etcupdate-current-tmpl /var/tmp/13.3 etcupdate-current-13.3@p5.tbz

Unmount::

  ftjail umount-tmpl zpool/jail/ttmpl/base-ro/13.3-RELEASE zpool/jail/ttmpl/skel-rw/13.3-RELEASE


Container and Common Location for instantiated Thin Jails
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All thin jails are located at :file:`/jail/TROOT`::

  zfs create -o mountpoint=/jail/TROOT zpool/jail/TROOT

Create the variable datasets (read-write) with the same mountpoint as above::

  zfs create -o canmount=off -o mountpoint=/jail/TROOT zpool/jail/TVAR


Creation of a real Thin Jail
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clone the read-only root filesystem base::

  zfs clone -o readonly=on zpool/jail/ttmpl/base-ro/13.3-RELEASE@p5 zpool/jail/TROOT/build13

If you want some additional directory (e.g. for :file:`/srv` et al.) do this
instead::

  zfs clone -o readonly=off zpool/jail/ttmpl/base-ro/13.3-RELEASE@p5 zpool/jail/TROOT/build13
  # change before making it read-only
  mkdir /jail/TROOT/build13/srv
  zfs set readonly=on zpool/jail/TROOT/build13

Copy -- not clone -- the variable parts::

  ftjail copy-skel -P  zpool/jail/ttmpl/skel-rw/13.3-RELEASE p5 zpool/jail/TVAR/build13

Configure some important parts (as in "normal" jails)::

  mount -t devfs devfs /jail/TROOT/build13/dev
  fjail configure /jail/TROOT/build13
  umount /jail/TROOT/build13/dev