Mirrors/hackacad
2
0
Fork 0
mirror of https://github.com/hackacad/bastille.git synced 2025-12-19 16:51:00 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc: reformat and reflow documentation for consistent 80-column text

Browse Source
This commit is contained in:
Juan David Hurtado G
2025-07-08 22:40:28 -05:00
parent f1c2e80f42
commit 3fb721b296
14 changed files with 280 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
docs/chapters/centralized-assets.rst
View File

@@ -1,20 +1,21 @@
Centralized Assets Centralized Assets
================== ==================
Sometimes it is preferable to share applications, libraries, packages or even directories Sometimes it is preferable to share applications, libraries, packages or even
and files across multiple jails. directories and files across multiple jails.
Or perhaps we just want to avoid all the time it takes to create a jail, and manully configure Or perhaps we just want to avoid all the time it takes to create a jail, and
it with the packages we normally use. manually configure it with the packages we normally use.
Bastille offers a number of ways to do the above. Bastille offers a number of ways to do the above.
Templates Templates
--------- ---------
A template is a predefined file containing instructions to execute on a targeted jail. This A template is a predefined file containing instructions to execute on a targeted
is one of the easiest ways to create a repeatable environment for your Bastille jails. Simply jail. This is one of the easiest ways to create a repeatable environment for your
create your template, the execute it on as many jails as you prefer. Bastille jails. Simply create your template, the execute it on as many jails as
you prefer.
.. code-block:: shell .. code-block:: shell
@@ -25,12 +26,12 @@ See the chapter on templates for details on how to create your own templates.
Mounting Mounting
-------- --------
On of the fastest ways to share directories and files across multiple jails is with On of the fastest ways to share directories and files across multiple jails is
the ``bastille mount`` command. with the ``bastille mount`` command.
The following command will mount ``/my/host/directory`` into ``jail1`` and ``jail2`` The following command will mount ``/my/host/directory`` into ``jail1`` and ``jail2``
at ``/my/jail/directory`` with read and write access. To mount with read only access, at ``/my/jail/directory`` with read and write access. To mount with read only
simply use ``ro`` instead of ``rw`` as the option. access, simply use ``ro`` instead of ``rw`` as the option.
.. code-block:: shell .. code-block:: shell
@@ -39,8 +40,8 @@ simply use ``ro`` instead of ``rw`` as the option.
Cloning Cloning
------- -------
Bastille allows you to create a full duplicate of your jail using ``bastille clone``. To clone Bastille allows you to create duplicate of your jail using ``bastille clone``.
your jail, use the following command. To clone your jail, use the following command.
.. code-block:: shell .. code-block:: shell
@@ -51,29 +52,30 @@ This will create an exact duplicate of ``myjail`` at ``mynewjail``.
Custom Releases Custom Releases
--------------- ---------------
Bastille allows creating custom releases from jails, then using those releases to create Bastille allows creating custom releases from jails, then using those releases to
more jails. create more jails.
To start, we must first create our jail. Make sure it is a thick jail, as this process will To start, we must first create our jail. Make sure it is a thick jail, as this
not work with any other jail types. process will not work with any other jail types.
.. code-block:: shell .. code-block:: shell
ishmael ~ # bastille create -T myjail 14.2-RELEASE 10.0.0.1 ishmael ~ # bastille create -T myjail 14.2-RELEASE 10.0.0.1
Once the jail is up and running, configure it to your liking, then run the following commmand Once the jail is up and running, configure it to your liking, then run the
to create a custom release based on your jail. following commmand to create a custom release based on your jail.
.. code-block:: shell .. code-block:: shell
ishmael ~ # bastille convert myjail myrelease ishmael ~ # bastille convert myjail myrelease
Once this process completes, you will be able to run the following command to create a jail Once this process completes, you will be able to run the following command to
based off your newly created release. create a jail based off your newly created release.
Please note that using this approach is experimental. It will be up to the end user to keep Please note that using this approach is experimental. It will be up to the end
track of which official FreeBSD release their custom release is based on. The ``osrelease`` user to keep track of which official FreeBSD release their custom release is
config variable will be set to your custom release name inside the ``jail.conf`` file. based on. The ``osrelease`` config variable will be set to your custom release
name inside the ``jail.conf`` file.
.. code-block:: shell .. code-block:: shell

10
docs/chapters/comparing.rst
View File

@@ -112,11 +112,13 @@ as a list of popular managers and their status on each option.
| Support | | | | | | | Support | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+ +--------------+-------------+--------------+-----------+-----------+-----------+
We do our best to stay true and honest as to what other jail managers do and don't do. We do our best to stay true and honest as to what other jail managers do and
don't do.
If you see an error, you can open a PR on the BastillBSD github repo. If you see an error, you can open a PR on the BastillBSD github repo.
We also realize that each jail manger does certain things better than other, and perhaps We also realize that each jail manger does certain things better than other, and
certain things worse. Some do this, others do that. They are all different, and each user perhaps certain things worse. Some do this, others do that. They are all
should choose the one they want to use based on their needs. different, and each user should choose the one they want to use based on their
needs.
Thanks for using BastilleBSD! Thanks for using BastilleBSD!

10
docs/chapters/gettingstarted.rst
View File

@@ -12,10 +12,11 @@ will attempt to configure the networking, storage, and firewall on your system
for use with Bastille. for use with Bastille.
By default the setup command will configure a loopback interface, storage (ZFS if By default the setup command will configure a loopback interface, storage (ZFS if
enabled, otherwise UFS) and the pf firewall if you run it as below without any options. enabled, otherwise UFS) and the pf firewall if you run it as below without any
options.
Alternatively, you can run the ``setup`` command with any of the supported options to Alternatively, you can run the ``setup`` command with any of the supported
configure the selected option by itself. options to configure the selected option by itself.
To see a list of available options and switches, see the ``setup`` subcommand. To see a list of available options and switches, see the ``setup`` subcommand.
@@ -103,7 +104,8 @@ Linux Jail
^^^^^^^^^^ ^^^^^^^^^^
Linux jails are still considered experimental, but they seem to work. First we Linux jails are still considered experimental, but they seem to work. First we
must bootstrap a linux distro (Linux distros are bootstrapped with the Debian tool debootstrap). must bootstrap a linux distro (Linux distros are bootstrapped with the Debian
tool debootstrap).
.. code-block:: shell .. code-block:: shell

82
docs/chapters/jail-startup-configuration.rst
View File

@@ -1,33 +1,39 @@
Jail Startup Configuration Jail Startup Configuration
========================== ==========================
Bastille can start jails on system startup, and stop them on system shutdown. To enable this functionality, we Bastille can start jails on system startup, and stop them on system shutdown.
must first enable Bastille as a service using ``sysrc bastille_enable=YES``. Once you reboot your host, all jails To enable this functionality, we must first enable Bastille as a service using
with ``boot=on`` will be started when the host boots. ``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 If you have certain jails that must be started before other jails, you can use
in order starting at the lowest value, and will stop in order starting at the highest value. So, jails with a priority the priority option. Jails will start in order starting at the lowest value, and
value of 1 will start first, and stop last. will stop in order starting at the highest value. So, jails with a priority value
of 1 will start first, and stop last.
See the chapter on targeting for more info. See the chapter on targeting for more info.
Boot Boot
---- ----
The boot setting controls whether a jail will be started on system startup. If you have enabled bastille The boot setting controls whether a jail will be started on system startup. If
with ``sysrc bastille_enable=YES``, all jails with ``boot=on`` will start on system startup. Any jail(s) you have enabled bastille with ``sysrc bastille_enable=YES``, all jails with
with ``boot=off`` will not be started on system startup. ``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 By default, when jails are created with Bastille, the boot setting is set to ``on``
the ``--no-boot`` flag. See ``bastille create --no-boot TARGET...``. 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 You can also use ``bastille start --boot TARGET`` to make Bastille respect the
used, the targeted jail(s) will start, regardless of the boot setting. 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. 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 The ``-b|--boot`` can also be used with the ``stop`` command. Any jails with
not be touched if ``stop`` is called with ``-b|--boot``. Same goes for the ``restart`` command. ``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 can be changed using ``bastille config TARGET set boot [on|off]``.
@@ -36,39 +42,49 @@ This value will be shown using ``bastille list all``.
Depend Depend
------ ------
Bastille supports configuring jails to depend on each other when started and stopped. If jail1 "depends" on jail2, then Bastille supports configuring jails to depend on each other when started and
jail2 will be started if it is not running when ``bastille start jail1`` is called. Any jail that jail1 "depends" on will stopped. If jail1 "depends" on jail2, then jail2 will be started if it is not
first be verified running (started if stopped) before jail1 is started. 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 For example, I have 3 jails called nginx, mariadb and nextcloud. I want to
nextcloud is started. 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"``. First we must add both jails to nextcloud's depend property with
Then, when we start nextcloud with ``bastille start nextcloud`` it will verify that nginx and mariadb are running (start if stopped) before ``bastille config nextcloud set depend "mariadb nginx"``.
starting nextcloud. 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 When stopping a jail, any jail that "depends" on it will first be stopped.
nextcloud will first be stopped because it "depends" on nginx. 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. 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 Parallel Startup
---------------- ----------------
Bastille supports starting, stopping and restarting jails in parallel mode using the ``rc`` service script. To enable this functionality, set 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. ``bastille_parallel_limit`` to a numeric value.
For example, if you run ``sysrc bastille_parallel_limit=4``, then Bastille will start 4 For example, if you run ``sysrc bastille_parallel_limit=4``, then Bastille will
jails at a time on system startup, as well as stop or restart 4 jails at a time when ``service bastille...`` is called. 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. This value is set to 1 by default, to only start/stop/restart jails one at a time.
Startup Delay Startup Delay
------------- -------------
Sometimes it is necessary to let a jail start fully before continuing to the next jail. 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 We can do this with another sysrc value called ``bastille_startup_delay``.
tell Bastille to wait 5 seconds between starting each jail. 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. You can also use ``bastille start -d|--delay 5 all`` or
``bastille restart -d|--delay 5 all`` to achieve the same thing.

67
docs/chapters/migration.rst
View File

@@ -9,54 +9,61 @@ Bastille supports migrations to a remote system using the ``migrate`` subcommand
Prerequisites Prerequisites
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
There are a couple of things that need to be in place before running the ``migrate`` command. There are a couple of things that need to be in place before running the
``migrate`` command.
First, you must have bastille configured both locally and remotely to use the same filesystem First, you must have bastille configured both locally and remotely to use the
configuration. ZFS on both, or UFS on both. same filesystem configuration. ZFS on both, or UFS on both.
Second, you must create a user on the remote system that will be used to migrate the jail. The user Second, you must create a user on the remote system that will be used to migrate
must be able to log in via SSH using either key-based authentication, or password based authentication. the jail. The user must be able to log in via SSH using either key-based
The user also needs ``sudo`` permissions on the remote system. This user should then be given as the authentication, or password based authentication.
``USER`` arg in the ``migrate`` command. The user also needs ``sudo`` permissions on the remote system. This user should
then be given as the ``USER`` arg in the ``migrate`` command.
If you don't want to use ``sudo``, we support using ``doas`` as the super-user command. Simply set ``--doas`` as If you don't want to use ``sudo``, we support using ``doas`` as the super-user
one of the options when running the ``migrate`` command. command. Simply set ``--doas`` as one of the options when running the ``migrate`` command.
If you are using key-based auth, the keys should be stored in the default location at ``$HOME/.ssh/id_rsa``, If you are using key-based auth, the keys should be stored in the default
where ``$HOME`` is the users home directory. This is the default location for ssh keys, and where Bastille location at ``$HOME/.ssh/id_rsa``, where ``$HOME`` is the users home directory.
will try to load them from. This is the default location for ssh keys, and where Bastille will try to load
them from.
If you want to use password based authentication, simply run ``bastille migrate -p TARGET USER@HOST``. This If you want to use password based authentication, simply run
will prompt you to enter the password for the remote system, which Bastille will then use during the migration ``bastille migrate -p TARGET USER@HOST``. This will prompt you to enter the
password for the remote system, which Bastille will then use during the migration
process. process.
Migration Migration
^^^^^^^^^ ^^^^^^^^^
To migrate a jail (or multiple jails) we can simply run To migrate a jail (or multiple jails) we can simply run
``bastille migrate TARGET USER@HOST``. This will export the jail(s), send them to the ``bastille migrate TARGET USER@HOST``. This will export the jail(s), send them
remote system, and import them. to the remote system, and import them.
The ``migrate`` sub-command includes the ``-a|--auto`` option, which will auto-stop the old jail, The ``migrate`` sub-command includes the ``-a|--auto`` option, which will
migrate it, and attempt to start the migrated jail on the remote system after importing it. See the auto-stop the old jail, migrate it, and attempt to start the migrated jail on
warning below about auto-starting the migrated jail. the remote system after importing it. See the warning below about auto-starting
the migrated jail.
WARNING: Every system is unique, has different interfaces, bridges, and network configurations. WARNING: Every system is unique, has different interfaces, bridges, and network
It is possible, with the right configuration, for jails to start and work normally. But for some configurations. It is possible, with the right configuration, for jails to start
systems, it will be necessary to edit the ``jail.conf`` file of the migrated jail to get it working and work normally. But for some systems, it will be necessary to edit the
properly. ``jail.conf`` file of the migrated jail to get it working properly.
Using ``-l|--live`` mode (ZFS only) will leave the local jail running, and the remote jail stopped. Using ``-l|--live`` mode (ZFS only) will leave the local jail running, and the
remote jail stopped.
Using ``-a|--auto`` mode will stop the local jail, and start the remote jail. Using ``-a|--auto`` mode will stop the local jail, and start the remote jail.
Using the ``-l|--live`` and ``-a|--auto`` options together will migrate the jail while it is running, Using the ``-l|--live`` and ``-a|--auto`` options together will migrate the jail
then stop the local jail, and start the remote jail. while it is running, then stop the local jail, and start the remote jail.
You can optionally set ``-d|--destroy`` to have Bastille destroy the old jail on completion. You can optionally set ``-d|--destroy`` to have Bastille destroy the old jail on
completion.
You can also set ``-b|--backup`` to retain the archives remotely. They will be copied into You can also set ``-b|--backup`` to retain the archives remotely. They will be
``${bastille_backupsdir}``. copied into ``${bastille_backupsdir}``.
iocage iocage
------ ------
@@ -89,7 +96,7 @@ Import the iocage backup file (use zip file name)
bastille import jailname_$(date +%F).zip bastille import jailname_$(date +%F).zip
Bastille will attempt to configure your interface and IP from the Bastille will attempt to configure your interface and IP from the
``config.json`` file, but if you have issues you can configure it manully. ``config.json`` file, but if you have issues you can configure it manually.
.. code-block:: shell .. code-block:: shell

90
docs/chapters/networking.rst
View File

@@ -13,10 +13,10 @@ different types of jail network configurations.
whatever your interface is called. This will be used for the host/jail epairs. whatever your interface is called. This will be used for the host/jail epairs.
Bastille will create/destroy these epairs as the jail is started/stopped. Bastille will create/destroy these epairs as the jail is started/stopped.
* Bridged VNET mode: For bridged VNET jails (``-B``) you must manually create a bridge * Bridged VNET mode: For bridged VNET jails (``-B``) you must manually create a
interface to attach your jail to. Bastille will then create and attach the bridge interface to attach your jail to. Bastille will then create and attach
host/jail epairs to this interface when the jail starts, and remove them when the host/jail epairs to this interface when the jail starts, and remove them\
it stops. when it stops.
* Alias mode: For classic/standard jails that use an IP that is accessible * Alias mode: For classic/standard jails that use an IP that is accessible
within your local subnet (alias mode) Bastille will add the IP to the within your local subnet (alias mode) Bastille will add the IP to the
@@ -24,10 +24,10 @@ different types of jail network configurations.
* NAT mode: For classic/standard jails that use an IP not reachable in your local * NAT mode: For classic/standard jails that use an IP not reachable in your local
subnet, Bastille will add the IP to the specified interface as an alias, and subnet, Bastille will add the IP to the specified interface as an alias, and
additionally, add it to the pf firewall table (if available) to allow the jail outbound additionally, add it to the pf firewall table (if available) to allow the jail
access. If you do not specify an interface, Bastille will assume you have run outbound access. If you do not specify an interface, Bastille will assume you
the ``bastille setup`` command and will attempt to use ``bastille0`` (which have run the ``bastille setup`` command and will attempt to use ``bastille0``
is created using the setup command) as its interface. If you have not run (which is created using the setup command) as its interface. If you have not run
``bastille setup`` and do not specify an interface, Bastille will error. ``bastille setup`` and do not specify an interface, Bastille will error.
* Inherit mode: For classic/standard jails that are set to ``inherit`` or * Inherit mode: For classic/standard jails that are set to ``inherit`` or
@@ -38,9 +38,9 @@ different types of jail network configurations.
bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config.
The jail will then function according the jail(8) documentation. The jail will then function according the jail(8) documentation.
You cannot use ``-V|--vnet`` with any interface that is already a member of another You cannot use ``-V|--vnet`` with any interface that is already a member of
bridge. For example, if you create a bridge, and assign ``vtnet0`` as a member, you another bridge. For example, if you create a bridge, and assign ``vtnet0`` as a
will not be able to use ``vtnet0`` with ``-V|--vnet``. member, you will not be able to use ``vtnet0`` with ``-V|--vnet``.
IP Address Options IP Address Options
------------------ ------------------
@@ -95,8 +95,9 @@ For the ``inherit`` and ``ip_hostname`` options, you can also specify
Shared Interface Shared Interface
---------------- ----------------
This scenario works best when you have just one computer, or a home or small office network This scenario works best when you have just one computer, or a home or small
that is separated from the rest of the internet by a router. So you are free to use office network that is separated from the rest of the internet by a router. So
you are free to use
`private IP addresses `private IP addresses
<https://www.lifewire.com/what-is-a-private-ip-address-2625970>`_. <https://www.lifewire.com/what-is-a-private-ip-address-2625970>`_.
@@ -118,9 +119,10 @@ reach services at that address.
This method is the simplest. All you need to know is the name of your network This method is the simplest. All you need to know is the name of your network
interface and a free IP on your local network. interface and a free IP on your local network.
We can also run ``bastille setup shared`` to configure our primary interface as a default We can also run ``bastille setup shared`` to configure our primary interface as
interface for Bastille to use. Once we have run the command and chosen our interface, it will a default interface for Bastille to use. Once we have run the command and chosen
not be necessary to specify an interface in our create command. our interface, it will not be necessary to specify an interface in our create
command.
.. code-block:: shell .. code-block:: shell
@@ -128,8 +130,8 @@ not be necessary to specify an interface in our create command.
This will automatically use the interface we selected during the setup command. This will automatically use the interface we selected during the setup command.
Note that we cannot use the ``shared`` option together with the ``loopback`` option. Configuring Note that we cannot use the ``shared`` option together with the ``loopback``
one using the ``bastille setup`` command will disable the other. option. Configuring one using the ``bastille setup`` command will disable the other.
Shared Interface on IPV6 network (vultr.com) Shared Interface on IPV6 network (vultr.com)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -259,8 +261,8 @@ bridge, use the ``-B`` option, an IP/netmask and external bridge.
bastille create -B azkaban 13.2-RELEASE 192.168.1.50/24 bridge0 bastille create -B azkaban 13.2-RELEASE 192.168.1.50/24 bridge0
Bastille will automagically create the needed interface(s), attach it to the specified Bastille will automagically create the needed interface(s), attach it to the
bridge and connect/disconnect containers as they are started and stopped. specified bridge and connect/disconnect containers as they are started and stopped.
The bridge needs to be created/enabled before creating and starting the jail. The bridge needs to be created/enabled before creating and starting the jail.
Below are the steps to creating a bridge for this purpose. Below are the steps to creating a bridge for this purpose.
@@ -309,21 +311,23 @@ on your system is.
VLAN Configuration VLAN Configuration
------------------ ------------------
Bastille supports VLANs to some extent when creating jails. When creating a jail, use Bastille supports VLANs to some extent when creating jails. When creating a jail,
the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set the proper use the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set
variables inside the jails `rc.conf` to add the jail to the specified VLAN. When using this method, the proper variables inside the jails `rc.conf` to add the jail to the specified
the interface being assigned must carry tagged VLAN packets, e.g. you can bridge a VLAN trunk to VLAN. When using this method, the interface being assigned must carry tagged VLAN
the jail and in the jail you then can access all VLANs. But be careful: This may have packets, e.g. you can bridge a VLAN trunk to the jail and in the jail you then can
security implications. access all VLANs. But be careful: This may have security implications.
You cannot use the ``-V|--vnet`` options with interfaces that have dots (.) in the name, which is the You cannot use the ``-V|--vnet`` options with interfaces that have dots (.) in the
standard way of naming a VLAN interface. This is due to the limitations name, which is the standard way of naming a VLAN interface. This is due to the
of the JIB script that Bastille uses to manage VNET jails. limitations of the JIB script that Bastille uses to manage VNET jails.
You can however use ``-B|--bridge`` with VLAN interfaces (even with dots in the name). You can however use ``-B|--bridge`` with VLAN interfaces (even with dots in the
Using this method you create bridge interfaces in ``rc.conf`` and only add VLANs that are needed name). Using this method you create bridge interfaces in ``rc.conf`` and only
for the jail. The jail only has access to these VLANs and not to the whole trunk. add VLANs that are needed for the jail. The jail only has access to these VLANs
Below is an ``rc.conf`` snippet that was provided by a user who has such a configuration. and not to the whole trunk.
Below is an ``rc.conf`` snippet that was provided by a user who has such a
configuration.
.. code-block:: shell .. code-block:: shell
@@ -397,11 +401,13 @@ To enable netgraph, run `bastille setup netgraph`. This will load and persist th
required kernel modules. Once netgraph is configured, any VNET jails required kernel modules. Once netgraph is configured, any VNET jails
you create will be managed with netgraph. you create will be managed with netgraph.
Note that you should only enable netgraph on a new system. Bastille is set up to use either Note that you should only enable netgraph on a new system. Bastille is set up to
`netgraph` or `if_bridge` as the VNET management, and uses `if_bridge` as the default, as it use either `netgraph` or `if_bridge` as the VNET management, and uses `if_bridge`
always has. The `netgraph` option is new, and should only be used with new systems. as the default, as it always has. The `netgraph` option is new, and should only
be used with new systems.
This value is set with the `bastille_network_vnet_type` option inside the config file. This value is set with the `bastille_network_vnet_type` option inside the config
file.
loopback (bastille0) loopback (bastille0)
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
@@ -423,9 +429,9 @@ traffic out of containers and can selectively redirect traffic into containers
based on connection ports (ie; 80, 443, etc.) based on connection ports (ie; 80, 443, etc.)
To set up the loopback address automatically, we can simply run ``bastille setup``. To set up the loopback address automatically, we can simply run ``bastille setup``.
This will configure the storage, pf firewall, and loopback addresses for us. To set This will configure the storage, pf firewall, and loopback addresses for us.
these up individually, we can run ``bastille setup storage``, ``bastille setup firewall``, To set these up individually, we can run ``bastille setup storage``,
and ``bastille setup loopback`` respectively. ``bastille setup firewall``, and ``bastille setup loopback`` respectively.
Alternatively, you can do it all manually, as shown below. Alternatively, you can do it all manually, as shown below.
@@ -512,8 +518,8 @@ ssh session and continue.
This step only needs to be done once in order to prepare the host. This step only needs to be done once in order to prepare the host.
Note that we cannot use the ``loopback`` option together with the ``shared`` option. Configuring Note that we cannot use the ``loopback`` option together with the ``shared``
one using the ``bastille setup`` command will disable the other. option. Configuring one using the ``bastille setup`` command will disable the other.
local_unbound local_unbound
------------- -------------

5
docs/chapters/subcommands/convert.rst
View File

@@ -18,7 +18,8 @@ RELEASE as args.
ishmael ~ # bastille convert azkaban myrelease ishmael ~ # bastille convert azkaban myrelease
This release can then be used to create a thick jail using the ``--no-validate`` flag. This release can then be used to create a thick jail using the ``--no-validate``
flag.
.. code-block:: shell .. code-block:: shell
@@ -33,4 +34,4 @@ This release can then be used to create a thick jail using the ``--no-validate``
-a | --auto Auto mode. Start/stop jail(s) if required. -a | --auto Auto mode. Start/stop jail(s) if required.
-y | --yes Do not prompt. Just convert. -y | --yes Do not prompt. Just convert.
-x | --debug Enable debug mode. -x | --debug Enable debug mode.

27
docs/chapters/subcommands/limits.rst
View File

@@ -11,29 +11,30 @@ To add a limit, use ``bastille limits TARGET add OPTION VALUE``.
To clear the limits from the system, use ``bastille limits TARGET clear``. To clear the limits from the system, use ``bastille limits TARGET clear``.
To clear the limits, and remove the rctl.conf, so that limits will not be loaded To clear the limits, and remove the rctl.conf, so that limits will not be loaded
on a restart, use ``bastille limits TARGET reset``. This removes the ``rctl.conf`` file, on a restart, use ``bastille limits TARGET reset``. This removes the ``rctl.conf``
and removes any active limits from the system. file, and removes any active limits from the system.
To remove a limit, use ``bastille limits TARGET remove OPTION``. To remove a limit, use ``bastille limits TARGET remove OPTION``.
This file can be edited manually using ``bastille edit TARGET rctl.conf``. This file can be edited manually using ``bastille edit TARGET rctl.conf``.
Supported actions are ``add``, ``remove``, ``clear``, ``reset``, ``list``, ``show``, and Supported actions are ``add``, ``remove``, ``clear``, ``reset``, ``list``,
``stats``. ``show``, and ``stats``.
cpuset cpuset
------ ------
Bastille supports limiting CPUs using ``cpuset``. To limit a jail to a specific CPU, use Bastille supports limiting CPUs using ``cpuset``. To limit a jail to a specific
``bastille limits TARGET cpu 2,3,4``` where the value (2,3,4) is a comma-separated list of CPUs on CPU, use ``bastille limits TARGET cpu 2,3,4``` where the value (2,3,4) is a
your system. Bastille will validate the CPUs, and error if they are not available to be used. comma-separated list of CPUs on your system. Bastille will validate the CPUs, and
error if they are not available to be used.
To adjust the CPU limits, run ``bastille limits TARGET cpu 1,2,3`` again with a new set of CPU To adjust the CPU limits, run ``bastille limits TARGET cpu 1,2,3`` again with a
values. This will overwrite the ``cpuset.conf`` file. This will restrict the targetted jail(s) to new set of CPU values. This will overwrite the ``cpuset.conf`` file. This will
the specified CPUs. restrict the targetted jail(s) to the specified CPUs.
CPU limits are cleared when the jail is stopped, and loaded again on jail start, providing the CPU CPU limits are cleared when the jail is stopped, and loaded again on jail start,
values are present in ``cpuset.conf`` inside the jail directory. providing the CPU values are present in ``cpuset.conf`` inside the jail directory.
Supported actions are ``add``, ``remove``, ``reset``, ``list`` and ``show``. Supported actions are ``add``, ``remove``, ``reset``, ``list`` and ``show``.
@@ -51,4 +52,4 @@ This file can be edited manually using ``bastille edit TARGET cpuset.conf``.
-a | --auto Auto mode. Start/stop jail(s) if required. -a | --auto Auto mode. Start/stop jail(s) if required.
-l | --log Enable logging for the specified rule (rctl only). -l | --log Enable logging for the specified rule (rctl only).
-x | --debug Enable debug mode. -x | --debug Enable debug mode.

13
docs/chapters/subcommands/list.rst
View File

@@ -1,13 +1,14 @@
list list
==== ====
List jails, ports, releases, templates, logs, limits, exports and imports and much more List jails, ports, releases, templates, logs, limits, exports and imports and
managed by bastille. See the ``help`` output below. much more managed by bastille. See the ``help`` output below.
Using `bastille list` without args will print all jails with the info we feel is most important. Using `bastille list` without args will print all jails with the info we feel is
most important.
Most options can be printed in JSON format by including the ``-j|--json`` flag. Use ``-p|--pretty`` Most options can be printed in JSON format by including the ``-j|--json`` flag.
to print in columns instead of rows. Use ``-p|--pretty`` to print in columns instead of rows.
.. code-block:: shell .. code-block:: shell
@@ -21,4 +22,4 @@ to print in columns instead of rows.
-p | --pretty Print JSON in columns. -p | --pretty Print JSON in columns.
-s | --sort VALUE Print info in VALUE order. -s | --sort VALUE Print info in VALUE order.
-u | --up List running jails only. -u | --up List running jails only.
-x | --debug Enable debug mode. -x | --debug Enable debug mode.

4
docs/chapters/subcommands/rdr.rst
View File

@@ -68,8 +68,8 @@ The options can be used together, as seen above.
If you have multiple interfaces assigned to your jail, ``bastille rdr`` will If you have multiple interfaces assigned to your jail, ``bastille rdr`` will
only redirect using the default one. only redirect using the default one.
It is also possible to specify a pf table as the source, providing it exists. Simply use the table It is also possible to specify a pf table as the source, providing it exists.
name instead of an IP address or subnet. Simply use the table name instead of an IP address or subnet.
.. code-block:: shell .. code-block:: shell

47
docs/chapters/subcommands/setup.rst
View File

@@ -25,38 +25,41 @@ Below is a list of available options that can be used with the ``setup`` command
-y | --yes Assume always yes on prompts. -y | --yes Assume always yes on prompts.
-x | --debug Enable debug mode. -x | --debug Enable debug mode.
The ``loopback`` option will configure a loopback interface called ``bastille0`` that The ``loopback`` option will configure a loopback interface called ``bastille0``
will be used as a default when not specifying an interface with the ``create`` command. that will be used as a default when not specifying an interface with the
``create`` command.
The ``shared`` option will configure the interface you choose to also be used as the default The ``shared`` option will configure the interface you choose to also be used as
when not specifying an interface with the ``create`` command. the default when not specifying an interface with the ``create`` command.
Please note. You CANNOT run both a loopback and a shared interface with Bastille. Only one Please note. You CANNOT run both a loopback and a shared interface with Bastille.
should be configured. If you configure one, it will disable the other. Only one should be configured. If you configure one, it will disable the other.
The ``loopback`` option is the default, and is enough for most use cases. It is simply an ``lo`` interface The ``loopback`` option is the default, and is enough for most use cases. It is
that jails will get linked to on creation. It is not attached to any specific interface. This is the simplest simply an ``lo`` interface that jails will get linked to on creation. It is not
networking option. The ``loopback`` and ``shared`` options are only for cases where the ``interface`` attached to any specific interface. This is the simplest networking option. The
is not specified during the ``create`` command. If an interface is specified, these options have no effect. ``loopback`` and ``shared`` options are only for cases where the ``interface``
Instead, the specified interface will be used. is not specified during the ``create`` command. If an interface is specified,
these options have no effect. Instead, the specified interface will be used.
The ``shared`` option is for cases where you want an actual interface to use with bastille as The ``shared`` option is for cases where you want an actual interface to use with
opposed to a loopback. Jails will be linked to the shared interface on creation. Bastille as opposed to a loopback. Jails will be linked to the shared interface
on creation.
The ``pf|firewall`` option will configure the pf firewall by enabling the service and creating the The ``pf|firewall`` option will configure the pf firewall by enabling the service
default ``pf.conf`` file. Once this is done, you can use the ``rdr`` command to forward traffic into and creating the default ``pf.conf`` file. Once this is done, you can use the
a jail. ``rdr`` command to forward traffic into a jail.
The ``storage`` option will attempt to configure a pool and dataset for Bastille, but only The ``storage`` option will attempt to configure a pool and dataset for Bastille,
if ZFS in enabled on your system. Otherwise it will use UFS. but only if ZFS in enabled on your system. Otherwise it will use UFS.
The ``vnet`` option will configure your system for use with VNET ``-V`` jails. The ``vnet`` option will configure your system for use with VNET ``-V`` jails.
The ``bridge`` options will attempt to configure a bridge interface for use with bridged VNET The ``bridge`` options will attempt to configure a bridge interface for use with
``-B`` jails. bridged VNET ``-B`` jails.
Running ``bastille setup`` without any options will attempt to auto-configure the ``filesystem``, ``loopback``, ``firewall`` and Running ``bastille setup`` without any options will attempt to auto-configure the
``storage`` options. ``filesystem``, ``loopback``, ``firewall`` and ``storage`` options.
.. code-block:: shell .. code-block:: shell

25
docs/chapters/targeting.rst
View File

@@ -22,14 +22,18 @@ quotes, as seen below.
Priority Priority
-------- --------
The priority value determines in what order commands are executed if multiple jails are targetted, including the ALL target. The priority value determines in what order commands are executed if multiple
jails are targetted, including the ALL target.
It also controls in what order jails are started and stopped on system startup and shutdown. This requires Bastille to be enabled It also controls in what order jails are started and stopped on system startup
with ``sysrc bastille_enable=YES``. Jails will start in order starting at the lowest value, and will stop in order starting and shutdown. This requires Bastille to be enabled with ``sysrc bastille_enable=YES``.
at the highest value. So, jails with a priority value of 1 will start first, and stop last. 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.
When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on When jails are created with Bastille, this value defaults to ``99``, but can be
creation. See ``bastille create --priority 90 TARGET...``. overridden with ``-p|--priority VALUE`` on creation.
See ``bastille create --priority 90 TARGET...``.
This value can be changed using ``bastille config TARGET set priority VALUE``. This value can be changed using ``bastille config TARGET set priority VALUE``.
@@ -38,14 +42,15 @@ This value will be shown using ``bastille list all``.
Parallel Mode Parallel Mode
------------- -------------
Any command that supports multiple targets, also supports parallel mode. This means that Any command that supports multiple targets, also supports parallel mode. This
Bastille will run the command on multiple jails at a single time, depending on the value means that Bastille will run the command on multiple jails at a single time,
given. depending on the value given.
To use parallel mode, run ``bastille -p 4 pkg ALL update``, for example, to start To use parallel mode, run ``bastille -p 4 pkg ALL update``, for example, to start
updating packages in all jails, 4 processes at a time. updating packages in all jails, 4 processes at a time.
Note that the ``-p`` option should follow the main ``bastille`` command, and not the sub-command. Note that the ``-p`` option should follow the main ``bastille`` command, and not
the sub-command.
Examples: Containers Examples: Containers
-------------------- --------------------

23
docs/chapters/template.rst
View File

@@ -65,15 +65,15 @@ Template Hook Descriptions
ARGS will default to the value set inside the template, but can be changed by ARGS will default to the value set inside the template, but can be changed by
including ``--arg ARG=VALUE`` when running the template. including ``--arg ARG=VALUE`` when running the template.
Multiple ARGS can also be specified as seen below. If no ARG value is given, Bastille Multiple ARGS can also be specified as seen below. If no ARG value is given,
will show a warning, but continue on with the rest of the template. Bastille will show a warning, but continue on with the rest of the template.
.. code-block:: shell .. code-block:: shell
ishmael ~ # bastille template azkaban sample/template --arg ARG=VALUE --arg ARG1=VALUE ishmael ~ # bastille template azkaban sample/template --arg ARG=VALUE --arg ARG1=VALUE
The ``ARG`` hook has a wide range of functionality, including passing KEY=VALUE pairs The ``ARG`` hook has a wide range of functionality, including passing KEY=VALUE
to any templates called with the ``INCLUDE`` hook. See the following example... pairs to any templates called with the ``INCLUDE`` hook. See the following example...
.. code-block:: shell .. code-block:: shell
@@ -82,14 +82,15 @@ to any templates called with the ``INCLUDE`` hook. See the following example...
INCLUDE other/template --arg JAIL=${JAIL} --arg IP=${IP} INCLUDE other/template --arg JAIL=${JAIL} --arg IP=${IP}
If the above template is called with ``--arg JAIL=myjail --arg IP=10.3.3.3``, these values will If the above template is called with ``--arg JAIL=myjail --arg IP=10.3.3.3``,
be passed along to ``other/template`` as well, with the matching variable. So ``${JAIL}`` will be these values will be passed along to ``other/template`` as well, with the
``myjail`` and ``${IP}`` will be ``10.3.3.3``. matching variable. So ``${JAIL}`` will be ``myjail`` and ``${IP}`` will be
``10.3.3.3``.
The ARG hook has three values that are built in, and will differ for every jail. The values The ARG hook has three values that are built in, and will differ for every jail.
are ``JAIL_NAME``, ``JAIL_IP``, and ``JAIL_IP6``. These can be used inside any template without The values are ``JAIL_NAME``, ``JAIL_IP``, and ``JAIL_IP6``. These can be used
setting the values at the top of the Bastillefile. The values are automatically retrieved from inside any template without setting the values at the top of the Bastillefile.
the targeted jails configuration. The values are automatically retrieved from the targeted jails configuration.
``CMD`` - run the specified command ``CMD`` - run the specified command

51
docs/chapters/zfs-support.rst
View File

@@ -63,46 +63,55 @@ If this is not desirable, you can change it at the top of the config file.
Altroot Altroot
------- -------
If a ZFS pool has been imported using ``-R`` (altroot), your system will automatically add whatever the ``altroot`` is to If a ZFS pool has been imported using ``-R`` (altroot), your system will
any ``zfs mount`` commands. Bastille supports using an ``altroot``, and there should be no issues using this feature. automatically add whatever the ``altroot`` is to any ``zfs mount`` commands.
Bastille supports using an ``altroot``, and there should be no issues using this feature.
One thing to note though, is that you MUST NOT include your ``altroot`` path in the ``bastille_prefix``. For example, if One thing to note though, is that you MUST NOT include your ``altroot`` path in
you imported your pool with ``zpool import -R /mnt poolname``, and you wish for your jails to live at ``/mnt/poolname/bastille`` the ``bastille_prefix``. For example, if you imported your pool with
then ``bastille_prefix`` should be set to ``/poolname/bastille`` without the ``/mnt`` part. ``zpool import -R /mnt poolname``, and you wish for your jails to live at
``/mnt/poolname/bastille`` then ``bastille_prefix`` should be set to
``/poolname/bastille`` without the ``/mnt`` part.
If you do accidentally add the ``/mnt`` part, your datasets will be mounted at ``/mnt/mnt/poolname/bastille`` and Bastille will If you do accidentally add the ``/mnt`` part, your datasets will be mounted at
throw all kinds of errors due to not finding the proper paths. ``/mnt/mnt/poolname/bastille`` and Bastille will throw all kinds of errors due
to not finding the proper paths.
Jailing a Dataset Jailing a Dataset
----------------- -----------------
It is possible to "jail" a dataset. This means mounting a datset into a jail, and being It is possible to "jail" a dataset. This means mounting a datset into a jail,
able to fully manage it from within the jail. and being able to fully manage it from within the jail.
To add a dataset to a jail, we can run ``bastille zfs TARGET jail pool/dataset /path/inside/jail``. To add a dataset to a jail, we can run
This will mount ``pool/dataset`` into the jail at ``/path/inside/jail`` when the jail is started, and ``bastille zfs TARGET jail pool/dataset /path/inside/jail``.
unmount and unjail it when the jail is stopped. This will mount ``pool/dataset`` into the jail at ``/path/inside/jail`` when the
jail is started, and unmount and unjail it when the jail is stopped.
You can manually change the path where the dataset will be mounted by ``bastille edit TARGET zfs.conf`` and You can manually change the path where the dataset will be mounted by
adjusting the path after you have added it, bearing in mind the warning below. ``bastille edit TARGET zfs.conf`` and adjusting the path after you have added it,
bearing in mind the warning below.
WARNING: Adding or removing datasets to the ``zfs.conf`` file can result in permission errors with your jail. It is WARNING: Adding or removing datasets to the ``zfs.conf`` file can result in
important that the jail is first stopped before attempting to manually configure this file. The format inside permission errors with your jail. It is important that the jail is first stopped
the file is simple. before attempting to manually configure this file. The format inside the file is
simple.
.. code-block:: shell .. code-block:: shell
pool/dataset /path/in/jail pool/dataset /path/in/jail
pool/other/dataset /other/path/in/jail pool/other/dataset /other/path/in/jail
To remove a dataset from being jailed, we can run ``bastille zfs TARGET unjail pool/dataset``. To remove a dataset from being jailed, we can run
``bastille zfs TARGET unjail pool/dataset``.
Template Approach Template Approach
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
While it is possible to "jail" a dataset using a template, it is a bit more "hacky" than the above apporach. While it is possible to "jail" a dataset using a template, it is a bit more
Below is a template that you can use that will add the necessary bits to the ``jail.conf`` file to "jail" a "hacky" than the above apporach.
dataset. Below is a template that you can use that will add the necessary bits to the
``jail.conf`` file to "jail" a dataset.
.. code-block:: shell .. code-block:: shell