mirror of
https://github.com/BastilleBSD/bastille.git
synced 2025-12-11 09:29:55 +01:00
139 lines
5.5 KiB
ReStructuredText
139 lines
5.5 KiB
ReStructuredText
========
|
|
Template
|
|
========
|
|
|
|
Bastille supports a templating system allowing you to apply files, pkgs and
|
|
execute commands inside the containers automatically.
|
|
|
|
Currently supported template hooks are: `PRE`, `OVERLAY`, `PKG`, `SYSRC`, `CMD`.
|
|
Planned template hooks include: `FSTAB`, `PF`, `LOG`.
|
|
|
|
Templates are created in `${bastille_prefix}/templates` and can leverage any of
|
|
the template hooks. Simply create a new directory named after the template. eg;
|
|
|
|
.. code-block:: shell
|
|
|
|
mkdir -p /usr/local/bastille/templates/username/base
|
|
|
|
To leverage a template hook, create an UPPERCASE file in the root of the
|
|
template directory named after the hook you want to execute. eg;
|
|
|
|
.. code-block:: shell
|
|
|
|
echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/username/base/PKG
|
|
echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/username/base/CMD
|
|
echo "etc\nrootjn usr" > /usr/local/bastille/templates/username/base/OVERLAY
|
|
|
|
Template hooks are executed in specific order and require specific syntax to
|
|
work as expected. This table outlines those requirements:
|
|
|
|
|
|
+---------+------------------+--------------------------------------+
|
|
| HOOK | format | example |
|
|
+=========+==================+======================================+
|
|
| PRE | /bin/sh command | mkdir -p /usr/local/my_app/html |
|
|
+---------+------------------+--------------------------------------+
|
|
| OVERLAY | path(s) | etc root usr (one per line) |
|
|
+---------+------------------+--------------------------------------+
|
|
| PKG | port/pkg name(s) | vim-console zsh git-lite tree htop |
|
|
+---------+------------------+--------------------------------------+
|
|
| SYSRC | sysrc command(s) | nginx_enable=YES |
|
|
+---------+------------------+--------------------------------------+
|
|
| SERVICE | service command | 'nginx start' OR 'postfix reload' |
|
|
+---------+------------------+--------------------------------------+
|
|
| CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh |
|
|
+---------+------------------+--------------------------------------+
|
|
|
|
Note: SYSRC requires that NO quotes be used or that quotes (`"`) be escaped
|
|
ie; (`\\"`)
|
|
|
|
In addition to supporting template hooks, Bastille supports overlaying
|
|
files into the container. This is done by placing the files in their full path,
|
|
using the template directory as "/".
|
|
|
|
An example here may help. Think of `bastille/templates/username/base`, our
|
|
example template, as the root of our filesystem overlay. If you create an
|
|
`etc/hosts` or `etc/resolv.conf` *inside* the base template directory, these
|
|
can be overlayed into your container.
|
|
|
|
Note: due to the way FreeBSD segregates user-space, the majority of your
|
|
overlayed template files will be in `usr/local`. The few general
|
|
exceptions are the `etc/hosts`, `etc/resolv.conf`, and
|
|
`etc/rc.conf.local`.
|
|
|
|
After populating `usr/local/` with custom config files that your container will
|
|
use, be sure to include `usr` in the template OVERLAY definition. eg;
|
|
|
|
.. code-block:: shell
|
|
|
|
echo "etc\nusr" > /usr/local/bastille/templates/username/base/OVERLAY
|
|
|
|
The above example "etc usr" will include anything under "etc" and "usr"
|
|
inside the template. You do not need to list individual files. Just
|
|
include the top-level directory name. List these top-level directories one per
|
|
line.
|
|
|
|
Applying Templates
|
|
------------------
|
|
|
|
Containers must be running to apply templates.
|
|
|
|
Bastille includes a `template` command. This command requires a target and a
|
|
template name. As covered in the previous section, template names correspond to
|
|
directory names in the `bastille/templates` directory.
|
|
|
|
.. code-block:: shell
|
|
|
|
ishmael ~ # bastille template ALL username/base
|
|
[proxy01]:
|
|
Copying files...
|
|
Copy complete.
|
|
Installing packages.
|
|
pkg already bootstrapped at /usr/local/sbin/pkg
|
|
vulnxml file up-to-date
|
|
0 problem(s) in the installed packages found.
|
|
Updating bastillebsd.org repository catalogue...
|
|
[cdn] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
|
|
[cdn] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01
|
|
Processing entries: 100%
|
|
bastillebsd.org repository update completed. 499 packages processed.
|
|
All repositories are up to date.
|
|
Checking integrity... done (0 conflicting)
|
|
The most recent version of packages are already installed
|
|
Updating services.
|
|
cron_flags: -J 60 -> -J 60
|
|
sendmail_enable: NONE -> NONE
|
|
syslogd_flags: -ss -> -ss
|
|
Executing final command(s).
|
|
chsh: user information updated
|
|
Template Complete.
|
|
|
|
[web01]:
|
|
Copying files...
|
|
Copy complete.
|
|
Installing packages.
|
|
pkg already bootstrapped at /usr/local/sbin/pkg
|
|
vulnxml file up-to-date
|
|
0 problem(s) in the installed packages found.
|
|
Updating pkg.bastillebsd.org repository catalogue...
|
|
[poudriere] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
|
|
[poudriere] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01
|
|
Processing entries: 100%
|
|
pkg.bastillebsd.org repository update completed. 499 packages processed.
|
|
Updating bastillebsd.org repository catalogue...
|
|
[poudriere] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
|
|
[poudriere] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01
|
|
Processing entries: 100%
|
|
bastillebsd.org repository update completed. 499 packages processed.
|
|
All repositories are up to date.
|
|
Checking integrity... done (0 conflicting)
|
|
The most recent version of packages are already installed
|
|
Updating services.
|
|
cron_flags: -J 60 -> -J 60
|
|
sendmail_enable: NONE -> NONE
|
|
syslogd_flags: -ss -> -ss
|
|
Executing final command(s).
|
|
chsh: user information updated
|
|
Template Complete.
|
|
|