mirror of
https://github.com/BastilleBSD/bastille.git
synced 2025-12-12 01:49:51 +01:00
433 lines
18 KiB
ReStructuredText
433 lines
18 KiB
ReStructuredText
Configuration
|
|
=============
|
|
|
|
Bastille is configured using a default config file located at
|
|
``/usr/local/etc/bastille/bastille.conf``. When first installing bastille, you
|
|
should run ``bastille setup``. This will ask if you want to copy the sample
|
|
config file to the above location. The defaults are sensible for UFS, but
|
|
if you use ZFS, ``bastille setup`` will configure it for you. If you have
|
|
multiple zpools, Bastille will ask which one you want to use. See also
|
|
:doc:`/chapters/zfs-support`.
|
|
|
|
This is the default `bastille.conf` file.
|
|
|
|
.. code-block:: shell
|
|
|
|
#####################
|
|
## [ BastilleBSD ] ##
|
|
#####################
|
|
|
|
## Default paths
|
|
bastille_prefix="/usr/local/bastille" ## default: "/usr/local/bastille"
|
|
bastille_backupsdir="${bastille_prefix}/backups" ## default: "${bastille_prefix}/backups"
|
|
bastille_cachedir="${bastille_prefix}/cache" ## default: "${bastille_prefix}/cache"
|
|
bastille_jailsdir="${bastille_prefix}/jails" ## default: "${bastille_prefix}/jails"
|
|
bastille_releasesdir="${bastille_prefix}/releases" ## default: "${bastille_prefix}/releases"
|
|
bastille_templatesdir="${bastille_prefix}/templates" ## default: "${bastille_prefix}/templates"
|
|
bastille_logsdir="/var/log/bastille" ## default: "/var/log/bastille"
|
|
|
|
## pf configuration path
|
|
bastille_pf_conf="/etc/pf.conf" ## default: "/etc/pf.conf"
|
|
|
|
## Bastille commands directory (assumed by bastille pkg)
|
|
bastille_sharedir="/usr/local/share/bastille" ## default: "/usr/local/share/bastille"
|
|
|
|
## Bootstrap archives, which components of the OS to install.
|
|
## base - The base OS, kernel + userland
|
|
## lib32 - Libraries for compatibility with 32 bit binaries
|
|
## ports - The FreeBSD ports (3rd party applications) tree
|
|
## src - The source code to the kernel + userland
|
|
## test - The FreeBSD test suite
|
|
## Whitespace separated list:
|
|
## bastille_bootstrap_archives="base lib32 ports src test"
|
|
bastille_bootstrap_archives="base" ## default: "base"
|
|
|
|
## Pkgbase package sets
|
|
## Any set with [-dbg] can be installed with debugging
|
|
## symbols by adding '-dbg' to the package set
|
|
## base[-dbg] - Base system
|
|
## base-jail[-dbg] - Base system for jails
|
|
## devel[-dbg] - Development tools
|
|
## kernels[-dbg] - Base system kernels
|
|
## lib32[-dbg] - 32-bit compatability libraries
|
|
## minimal[-dbg] - Basic multi-user system
|
|
## minimal-jail[-dbg] - Basic multi-user jail system
|
|
## optional[-dbg] - Optional base system software
|
|
## optional-jail[-dbg] - Optional base system software for jails
|
|
## src - System source code
|
|
## tests - System test suite
|
|
## Whitespace separated list:
|
|
## bastille_pkgbase_packages="base-jail lib32-dbg src"
|
|
bastille_pkgbase_packages="base-jail" ## default: "base-jail"
|
|
|
|
## Default timezone
|
|
bastille_tzdata="" ## default: empty to use host's time zone
|
|
|
|
## Default jail resolv.conf
|
|
bastille_resolv_conf="/etc/resolv.conf" ## default: "/etc/resolv.conf"
|
|
|
|
## Bootstrap URLs
|
|
bastille_url_freebsd="http://ftp.freebsd.org/pub/FreeBSD/releases/" ## default: "http://ftp.freebsd.org/pub/FreeBSD/releases/"
|
|
bastille_url_hardenedbsd="https://installers.hardenedbsd.org/pub/" ## default: "https://installer.hardenedbsd.org/pub/HardenedBSD/releases/"
|
|
bastille_url_midnightbsd="https://www.midnightbsd.org/ftp/MidnightBSD/releases/" ## default: "https://www.midnightbsd.org/pub/MidnightBSD/releases/"
|
|
|
|
## ZFS options
|
|
bastille_zfs_enable="NO" ## default: "NO"
|
|
bastille_zfs_zpool="" ## default: ""
|
|
bastille_zfs_prefix="bastille" ## default: "bastille"
|
|
bastille_zfs_options="-o compress=on -o atime=off" ## default: "-o compress=on -o atime=off"
|
|
|
|
## Export/Import options
|
|
bastille_compress_xz_options="-0 -v" ## default "-0 -v"
|
|
bastille_decompress_xz_options="-c -d -v" ## default "-c -d -v"
|
|
bastille_compress_gz_options="-1 -v" ## default "-1 -v"
|
|
bastille_decompress_gz_options="-k -d -c -v" ## default "-k -d -c -v"
|
|
bastille_compress_zst_options="-3 -v" ## default "-3 -v"
|
|
bastille_decompress_zst_options="-k -d -c -v" ## default "-k -d -c -v"
|
|
bastille_export_options="" ## default "" predefined export options, e.g. "--live --gz"
|
|
|
|
## Networking
|
|
bastille_network_vnet_type="if_bridge" ## default: "if_bridge"
|
|
bastille_network_loopback="bastille0" ## default: "bastille0"
|
|
bastille_network_pf_ext_if="ext_if" ## default: "ext_if"
|
|
bastille_network_pf_table="jails" ## default: "jails"
|
|
bastille_network_shared="" ## default: ""
|
|
bastille_network_gateway="" ## default: ""
|
|
bastille_network_gateway6="" ## default: ""
|
|
|
|
## Default Templates
|
|
bastille_template_base="default/base" ## default: "default/base"
|
|
bastille_template_empty="" ## default: "default/empty"
|
|
bastille_template_thick="default/thick" ## default: "default/thick"
|
|
bastille_template_clone="default/clone" ## default: "default/clone"
|
|
bastille_template_thin="default/thin" ## default: "default/thin"
|
|
bastille_template_vnet="default/vnet" ## default: "default/vnet"
|
|
bastille_template_vlan="default/vlan" ## default: "default/vlan"
|
|
|
|
Custom Configuration
|
|
--------------------
|
|
|
|
Bastille supports using a custom config in addition to the default one. This
|
|
is nice if you have multiple users, or want to store different
|
|
jails at different locations based on your needs.
|
|
|
|
The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at
|
|
``/usr/local/etc/bastille`` or it will not work.
|
|
|
|
Simply copy the default config file and edit it according to your new
|
|
environment or user. Then, it can be used in a couple of ways.
|
|
|
|
1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE``
|
|
to bootstrap the release using the new config.
|
|
|
|
2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export
|
|
BASTILLE_CONFIG=config.conf``. This config will then always be used when
|
|
running Bastille with that user. See notes below...
|
|
|
|
- Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current session. If you want to persist the export, see documentation for the shell that you use.
|
|
|
|
- If you use sudo, you will need to run it with ``sudo -E bastille bootstrap...`` to preserve your users environment. This can also be persisted by editing the sudoers file.
|
|
|
|
- If you do set the ``BASTILLE_CONFIG`` variable, you do not need to specify the config file when running Bastille as that specified user.
|
|
|
|
Note: FreeBSD introduced container technology twenty years ago, long before the
|
|
industry standardized on the term "container". Internally, FreeBSD refers to
|
|
these containers as "jails".
|
|
|
|
Jail Startup Configuration
|
|
--------------------------
|
|
|
|
Bastille can start jails on system startup, and stop them on system shutdown.
|
|
To enable this functionality, we must first enable Bastille as a service using
|
|
``sysrc bastille_enable=YES``. Once you reboot your host, all jails with
|
|
``boot=on`` will be started when the host boots.
|
|
|
|
If you have certain jails that must be started before other jails, you can use
|
|
the priority option. Jails will start in order starting at the lowest value, and
|
|
will stop in order starting at the highest value. So, jails with a priority value
|
|
of 1 will start first, and stop last.
|
|
|
|
See :doc:`/chapters/targeting` for more info.
|
|
|
|
Boot
|
|
^^^^
|
|
|
|
The boot setting controls whether a jail will be started on system startup. If
|
|
you have enabled bastille with ``sysrc bastille_enable=YES``, all jails with
|
|
``boot=on`` will start on system startup. Any jail(s) with ``boot=off`` will not
|
|
be started on system startup.
|
|
|
|
By default, when jails are created with Bastille, the boot setting is set to ``on``
|
|
by default. This can be overridden using the ``--no-boot`` flag.
|
|
See ``bastille create --no-boot TARGET...``.
|
|
|
|
You can also use ``bastille start --boot TARGET`` to make Bastille respect the
|
|
boot setting. If ``-b|--boot`` is not used, the targeted jail(s) will start,
|
|
regardless of the boot setting.
|
|
|
|
Jails will still shut down on system shutdown, regardless of this setting.
|
|
|
|
The ``-b|--boot`` can also be used with the ``stop`` command. Any jails with
|
|
``boot=off`` will not be touched if ``stop`` is called with ``-b|--boot``. Same
|
|
goes for the ``restart`` command.
|
|
|
|
This value can be changed using ``bastille config TARGET set boot [on|off]``.
|
|
|
|
This value will be shown using ``bastille list all``.
|
|
|
|
Depend
|
|
^^^^^^
|
|
|
|
Bastille supports configuring jails to depend on each other when started and
|
|
stopped. If jail1 "depends" on jail2, then jail2 will be started if it is not
|
|
running when ``bastille start jail1`` is called. Any jail that jail1 "depends"
|
|
on will first be verified running (started if stopped) before jail1 is started.
|
|
|
|
For example, I have 3 jails called nginx, mariadb and nextcloud. I want to
|
|
ensure that nginx and mariadb are running before nextcloud is started.
|
|
|
|
First we must add both jails to nextcloud's depend property with
|
|
``bastille config nextcloud set depend "mariadb nginx"``.
|
|
Then, when we start nextcloud with ``bastille start nextcloud`` it will verify
|
|
that nginx and mariadb are running (start if stopped) before starting nextcloud.
|
|
|
|
When stopping a jail, any jail that "depends" on it will first be stopped.
|
|
For example, if we run ``bastille stop nginx``, then nextcloud will first be
|
|
stopped because it "depends" on nginx.
|
|
|
|
Note that if we do a ``bastille restart nginx``, however, nextcloud will be
|
|
stopped, because it "depends" on nginx, but will not be started again, because
|
|
the jail we just restarted, nginx, does not depend on nextcloud.
|
|
|
|
Parallel Startup
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Bastille supports starting, stopping and restarting jails in parallel mode using
|
|
the ``rc`` service script. To enable this functionality, set
|
|
``bastille_parallel_limit`` to a numeric value.
|
|
|
|
For example, if you run ``sysrc bastille_parallel_limit=4``, then Bastille will
|
|
start 4 jails at a time on system startup, as well as stop or restart 4 jails at
|
|
a time when ``service bastille...`` is called.
|
|
|
|
This value is set to 1 by default, to only start/stop/restart jails one at a time.
|
|
|
|
Startup Delay
|
|
^^^^^^^^^^^^^
|
|
|
|
Sometimes it is necessary to let a jail start fully before continuing to the
|
|
next jail.
|
|
|
|
We can do this with another sysrc value called ``bastille_startup_delay``.
|
|
Setting ``bastille_startup_delay=5`` will tell Bastille to wait 5 seconds between
|
|
starting each jail.
|
|
|
|
You can also use ``bastille start -d|--delay 5 all`` or
|
|
``bastille restart -d|--delay 5 all`` to achieve the same thing.
|
|
|
|
jail.conf
|
|
---------
|
|
|
|
In this section we'll look at the default config for a new container. The
|
|
defaults are sane for most applications, but if you want to tweak the settings
|
|
here they are.
|
|
|
|
A ``jail.conf`` template is used each time a new container is created. This
|
|
template looks like this:
|
|
|
|
.. code-block:: shell
|
|
|
|
{name} {
|
|
devfs_ruleset = 4;
|
|
enforce_statfs = 2;
|
|
exec.clean;
|
|
exec.consolelog = /var/log/bastille/{name}_console.log;
|
|
exec.start = '/bin/sh /etc/rc';
|
|
exec.stop = '/bin/sh /etc/rc.shutdown';
|
|
host.hostname = {name};
|
|
interface = {interface};
|
|
mount.devfs;
|
|
mount.fstab = /usr/local/bastille/jails/{name}/fstab;
|
|
path = /usr/local/bastille/jails/{name}/root;
|
|
securelevel = 2;
|
|
|
|
ip4.addr = interface|x.x.x.x;
|
|
ip6 = disable;
|
|
}
|
|
|
|
|
|
devfs_ruleset
|
|
^^^^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
devfs_ruleset
|
|
The number of the devfs ruleset that is enforced for mounting
|
|
devfs in this jail. A value of zero (default) means no ruleset
|
|
is enforced. Descendant jails inherit the parent jail's devfs
|
|
ruleset enforcement. Mounting devfs inside a jail is possible
|
|
only if the allow.mount and allow.mount.devfs permissions are
|
|
effective and enforce_statfs is set to a value lower than 2.
|
|
Devfs rules and rulesets cannot be viewed or modified from inside
|
|
a jail.
|
|
|
|
NOTE: It is important that only appropriate device nodes in devfs
|
|
be exposed to a jail; access to disk devices in the jail may
|
|
permit processes in the jail to bypass the jail sandboxing by
|
|
modifying files outside of the jail. See devfs(8) for
|
|
information on how to use devfs rules to limit access to entries
|
|
in the per-jail devfs. A simple devfs ruleset for jails is
|
|
available as ruleset #4 in /etc/defaults/devfs.rules.
|
|
|
|
|
|
enforce_statfs
|
|
^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
enforce_statfs
|
|
This determines what information processes in a jail are able to
|
|
get about mount points. It affects the behaviour of the
|
|
following syscalls: statfs(2), fstatfs(2), getfsstat(2), and
|
|
fhstatfs(2) (as well as similar compatibility syscalls). When
|
|
set to 0, all mount points are available without any
|
|
restrictions. When set to 1, only mount points below the jail's
|
|
chroot directory are visible. In addition to that, the path to
|
|
the jail's chroot directory is removed from the front of their
|
|
pathnames. When set to 2 (default), above syscalls can operate
|
|
only on a mount-point where the jail's chroot directory is
|
|
located.
|
|
|
|
|
|
exec.clean
|
|
^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
exec.clean
|
|
Run commands in a clean environment. The environment is
|
|
discarded except for HOME, SHELL, TERM and USER. HOME and SHELL
|
|
are set to the target login's default values. USER is set to the
|
|
target login. TERM is imported from the current environment.
|
|
The environment variables from the login class capability
|
|
database for the target login are also set.
|
|
|
|
|
|
exec.consolelog
|
|
^^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
exec.consolelog
|
|
A file to direct command output (stdout and stderr) to.
|
|
|
|
|
|
exec.start
|
|
^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
exec.start
|
|
Command(s) to run in the jail environment when a jail is created.
|
|
A typical command to run is "sh /etc/rc".
|
|
|
|
|
|
exec.stop
|
|
^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
exec.stop
|
|
Command(s) to run in the jail environment before a jail is
|
|
removed, and after any exec.prestop commands have completed. A
|
|
typical command to run is "sh /etc/rc.shutdown".
|
|
|
|
|
|
host.hostname
|
|
^^^^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
host.hostname
|
|
The hostname of the jail. Other similar parameters are
|
|
host.domainname, host.hostuuid and host.hostid.
|
|
|
|
|
|
mount.devfs
|
|
^^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
mount.devfs
|
|
Mount a devfs(5) filesystem on the chrooted /dev directory, and
|
|
apply the ruleset in the devfs_ruleset parameter (or a default of
|
|
ruleset 4: devfsrules_jail) to restrict the devices visible
|
|
inside the jail.
|
|
|
|
|
|
mount.fstab
|
|
^^^^^^^^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
mount.fstab
|
|
An fstab(5) format file containing filesystems to mount before
|
|
creating a jail.
|
|
|
|
|
|
path
|
|
^^^^
|
|
|
|
.. code-block:: shell
|
|
|
|
path
|
|
The directory which is to be the root of the jail. Any commands
|
|
run inside the jail, either by jail or from jexec(8), are run
|
|
from this directory.
|
|
|
|
|
|
securelevel
|
|
^^^^^^^^^^^
|
|
|
|
By default, Bastille containers run at ``securelevel = 2;``. See below for the
|
|
implications of kernel security levels and when they might be altered.
|
|
|
|
Note: Bastille does not currently have any mechanism to automagically change
|
|
securelevel settings. My recommendation is this only be altered manually on a
|
|
case-by-case basis and that "Highly secure mode" is a sane default for most use
|
|
cases.
|
|
|
|
.. code-block:: shell
|
|
|
|
The kernel runs with five different security levels. Any super-user
|
|
process can raise the level, but no process can lower it. The security
|
|
levels are:
|
|
|
|
-1 Permanently insecure mode - always run the system in insecure mode.
|
|
This is the default initial value.
|
|
|
|
0 Insecure mode - immutable and append-only flags may be turned off.
|
|
All devices may be read or written subject to their permissions.
|
|
|
|
1 Secure mode - the system immutable and system append-only flags may
|
|
not be turned off; disks for mounted file systems, /dev/mem and
|
|
/dev/kmem may not be opened for writing; /dev/io (if your platform
|
|
has it) may not be opened at all; kernel modules (see kld(4)) may
|
|
not be loaded or unloaded. The kernel debugger may not be entered
|
|
using the debug.kdb.enter sysctl. A panic or trap cannot be forced
|
|
using the debug.kdb.panic and other sysctl's.
|
|
|
|
2 Highly secure mode - same as secure mode, plus disks may not be
|
|
opened for writing (except by mount(2)) whether mounted or not.
|
|
This level precludes tampering with file systems by unmounting
|
|
them, but also inhibits running newfs(8) while the system is multi-
|
|
user.
|
|
|
|
In addition, kernel time changes are restricted to less than or
|
|
equal to one second. Attempts to change the time by more than this
|
|
will log the message "Time adjustment clamped to +1 second".
|
|
|
|
3 Network secure mode - same as highly secure mode, plus IP packet
|
|
filter rules (see ipfw(8), ipfirewall(4) and pfctl(8)) cannot be
|
|
changed and dummynet(4) or pf(4) configuration cannot be adjusted.
|