Mirrors/BastilleBSD_bastille
1
0
Fork 1
mirror of https://github.com/BastilleBSD/bastille.git synced 2025-12-11 09:29:55 +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
==================
Sometimes it is preferable to share applications, libraries, packages or even directories
and files across multiple jails.
Sometimes it is preferable to share applications, libraries, packages or even
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
it with the packages we normally use.
Or perhaps we just want to avoid all the time it takes to create a jail, and
manually configure it with the packages we normally use.
Bastille offers a number of ways to do the above.
Templates
---------
A template is a predefined file containing instructions to execute on a targeted jail. This
is one of the easiest ways to create a repeatable environment for your Bastille jails. Simply
create your template, the execute it on as many jails as you prefer.
A template is a predefined file containing instructions to execute on a targeted
jail. This is one of the easiest ways to create a repeatable environment for your
Bastille jails. Simply create your template, the execute it on as many jails as
you prefer.
.. code-block:: shell
@@ -25,12 +26,12 @@ See the chapter on templates for details on how to create your own templates.
Mounting
--------
On of the fastest ways to share directories and files across multiple jails is with
the ``bastille mount`` command.
On of the fastest ways to share directories and files across multiple jails is
with the ``bastille mount`` command.
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,
simply use ``ro`` instead of ``rw`` as the option.
at ``/my/jail/directory`` with read and write access. To mount with read only
access, simply use ``ro`` instead of ``rw`` as the option.
.. code-block:: shell
@@ -39,8 +40,8 @@ simply use ``ro`` instead of ``rw`` as the option.
Cloning
-------
Bastille allows you to create a full duplicate of your jail using ``bastille clone``. To clone
your jail, use the following command.
Bastille allows you to create duplicate of your jail using ``bastille clone``.
To clone your jail, use the following command.
.. code-block:: shell
@@ -51,29 +52,30 @@ This will create an exact duplicate of ``myjail`` at ``mynewjail``.
Custom Releases
---------------
Bastille allows creating custom releases from jails, then using those releases to create
more jails.
Bastille allows creating custom releases from jails, then using those releases to
create more jails.
To start, we must first create our jail. Make sure it is a thick jail, as this process will
not work with any other jail types.
To start, we must first create our jail. Make sure it is a thick jail, as this
process will not work with any other jail types.
.. code-block:: shell
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
to create a custom release based on your jail.
Once the jail is up and running, configure it to your liking, then run the
following commmand to create a custom release based on your jail.
.. code-block:: shell
ishmael ~ # bastille convert myjail myrelease
Once this process completes, you will be able to run the following command to create a jail
based off your newly created release.
Once this process completes, you will be able to run the following command to
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
track of which official FreeBSD release their custom release is based on. The ``osrelease``
config variable will be set to your custom release name inside the ``jail.conf`` file.
Please note that using this approach is experimental. It will be up to the end
user to keep track of which official FreeBSD release their custom release is
based on. The ``osrelease`` config variable will be set to your custom release
name inside the ``jail.conf`` file.
.. 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 | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
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.
We also realize that each jail manger does certain things better than other, and perhaps
certain things worse. Some do this, others do that. They are all different, and each user
should choose the one they want to use based on their needs.
We also realize that each jail manger does certain things better than other, and
perhaps certain things worse. Some do this, others do that. They are all
different, and each user should choose the one they want to use based on their
needs.
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.
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
configure the selected option by itself.
Alternatively, you can run the ``setup`` command with any of the supported
options to configure the selected option by itself.
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
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

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

@@ -1,33 +1,39 @@
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.
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.
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 the chapter on 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.
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...``.
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.
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.
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]``.
@@ -36,39 +42,49 @@ 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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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
^^^^^^^^^^^^^
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
configuration. ZFS on both, or UFS on both.
First, you must have bastille configured both locally and remotely to use the
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
must be able to log in via SSH using either key-based authentication, or password based authentication.
The user also needs ``sudo`` permissions on the remote system. This user should then be given as the
``USER`` arg in the ``migrate`` command.
Second, you must create a user on the remote system that will be used to migrate
the jail. The user must be able to log in via SSH using either key-based
authentication, or password based authentication.
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
one of the options when running the ``migrate`` command.
If you don't want to use ``sudo``, we support using ``doas`` as the super-user
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``,
where ``$HOME`` is the users home directory. This is the default location for ssh keys, and where Bastille
will try to load them from.
If you are using key-based auth, the keys should be stored in the default
location at ``$HOME/.ssh/id_rsa``, where ``$HOME`` is the users home directory.
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
will prompt you to enter the password for the remote system, which Bastille will then use during the migration
If you want to use password based authentication, simply run
``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.
Migration
^^^^^^^^^
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
remote system, and import them.
``bastille migrate TARGET USER@HOST``. This will export the jail(s), send them
to the remote system, and import them.
The ``migrate`` sub-command includes the ``-a|--auto`` option, which will auto-stop the old jail,
migrate it, and attempt to start the migrated jail on the remote system after importing it. See the
warning below about auto-starting the migrated jail.
The ``migrate`` sub-command includes the ``-a|--auto`` option, which will
auto-stop the old jail, migrate it, and attempt to start the migrated jail on
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.
It is possible, with the right configuration, for jails to start and work normally. But for some
systems, it will be necessary to edit the ``jail.conf`` file of the migrated jail to get it working
properly.
WARNING: Every system is unique, has different interfaces, bridges, and network
configurations. It is possible, with the right configuration, for jails to start
and work normally. But for some systems, it will be necessary to edit the
``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 the ``-l|--live`` and ``-a|--auto`` options together will migrate the jail while it is running,
then 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, 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
``${bastille_backupsdir}``.
You can also set ``-b|--backup`` to retain the archives remotely. They will be
copied into ``${bastille_backupsdir}``.
iocage
------
@@ -89,7 +96,7 @@ Import the iocage backup file (use zip file name)
bastille import jailname_$(date +%F).zip
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

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.
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
interface to attach your jail to. Bastille will then create and attach the
host/jail epairs to this interface when the jail starts, and remove them when
it stops.
* Bridged VNET mode: For bridged VNET jails (``-B``) you must manually create a
bridge interface to attach your jail to. Bastille will then create and attach
the host/jail epairs to this interface when the jail starts, and remove them\
when it stops.
* 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
@@ -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
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
access. If you do not specify an interface, Bastille will assume you have run
the ``bastille setup`` command and will attempt to use ``bastille0`` (which
is created using the setup command) as its interface. If you have not run
additionally, add it to the pf firewall table (if available) to allow the jail
outbound access. If you do not specify an interface, Bastille will assume you
have run the ``bastille setup`` command and will attempt to use ``bastille0``
(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.
* 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.
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
bridge. For example, if you create a bridge, and assign ``vtnet0`` as a member, you
will not be able to use ``vtnet0`` with ``-V|--vnet``.
You cannot use ``-V|--vnet`` with any interface that is already a member of
another bridge. For example, if you create a bridge, and assign ``vtnet0`` as a
member, you will not be able to use ``vtnet0`` with ``-V|--vnet``.
IP Address Options
------------------
@@ -95,8 +95,9 @@ For the ``inherit`` and ``ip_hostname`` options, you can also specify
Shared Interface
----------------
This scenario works best when you have just one computer, or a home or small office network
that is separated from the rest of the internet by a router. So you are free to use
This scenario works best when you have just one computer, or a home or small
office network that is separated from the rest of the internet by a router. So
you are free to use
`private IP addresses
<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
interface and a free IP on your local network.
We can also run ``bastille setup shared`` to configure our primary interface as a default
interface for Bastille to use. Once we have run the command and chosen our interface, it will
not be necessary to specify an interface in our create command.
We can also run ``bastille setup shared`` to configure our primary interface as
a default interface for Bastille to use. Once we have run the command and chosen
our interface, it will not be necessary to specify an interface in our create
command.
.. 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.
Note that we cannot use the ``shared`` option together with the ``loopback`` option. Configuring
one using the ``bastille setup`` command will disable the other.
Note that we cannot use the ``shared`` option together with the ``loopback``
option. Configuring one using the ``bastille setup`` command will disable the other.
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 will automagically create the needed interface(s), attach it to the specified
bridge and connect/disconnect containers as they are started and stopped.
Bastille will automagically create the needed interface(s), attach it to the
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.
Below are the steps to creating a bridge for this purpose.
@@ -309,21 +311,23 @@ on your system is.
VLAN Configuration
------------------
Bastille supports VLANs to some extent when creating jails. When creating a jail, use
the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set the proper
variables inside the jails `rc.conf` to add the jail to the specified VLAN. When using this method,
the interface being assigned must carry tagged VLAN packets, e.g. you can bridge a VLAN trunk to
the jail and in the jail you then can access all VLANs. But be careful: This may have
security implications.
Bastille supports VLANs to some extent when creating jails. When creating a jail,
use the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set
the proper variables inside the jails `rc.conf` to add the jail to the specified
VLAN. When using this method, the interface being assigned must carry tagged VLAN
packets, e.g. you can bridge a VLAN trunk to the jail and in the jail you then can
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
standard way of naming a VLAN interface. This is due to the limitations
of the JIB script that Bastille uses to manage VNET jails.
You cannot use the ``-V|--vnet`` options with interfaces that have dots (.) in the
name, which is the standard way of naming a VLAN interface. This is due to the
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).
Using this method you create bridge interfaces in ``rc.conf`` and only add VLANs that are needed
for the jail. The jail only has access to these VLANs and not to the whole trunk.
Below is an ``rc.conf`` snippet that was provided by a user who has such a configuration.
You can however use ``-B|--bridge`` with VLAN interfaces (even with dots in the
name). Using this method you create bridge interfaces in ``rc.conf`` and only
add VLANs that are needed for the jail. The jail only has access to these VLANs
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
@@ -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
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
`netgraph` or `if_bridge` as the VNET management, and uses `if_bridge` as the default, as it
always has. The `netgraph` option is new, and should only be used with new systems.
Note that you should only enable netgraph on a new system. Bastille is set up to
use either `netgraph` or `if_bridge` as the VNET management, and uses `if_bridge`
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)
^^^^^^^^^^^^^^^^^^^^
@@ -423,9 +429,9 @@ traffic out of containers and can selectively redirect traffic into containers
based on connection ports (ie; 80, 443, etc.)
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
these up individually, we can run ``bastille setup storage``, ``bastille setup firewall``,
and ``bastille setup loopback`` respectively.
This will configure the storage, pf firewall, and loopback addresses for us.
To set these up individually, we can run ``bastille setup storage``,
``bastille setup firewall``, and ``bastille setup loopback`` respectively.
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.
Note that we cannot use the ``loopback`` option together with the ``shared`` option. Configuring
one using the ``bastille setup`` command will disable the other.
Note that we cannot use the ``loopback`` option together with the ``shared``
option. Configuring one using the ``bastille setup`` command will disable the other.
local_unbound
-------------

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

@@ -18,7 +18,8 @@ RELEASE as args.
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
@@ -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.
-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, 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,
and removes any active limits from the system.
on a restart, use ``bastille limits TARGET reset``. This removes the ``rctl.conf``
file, and removes any active limits from the system.
To remove a limit, use ``bastille limits TARGET remove OPTION``.
This file can be edited manually using ``bastille edit TARGET rctl.conf``.
Supported actions are ``add``, ``remove``, ``clear``, ``reset``, ``list``, ``show``, and
``stats``.
Supported actions are ``add``, ``remove``, ``clear``, ``reset``, ``list``,
``show``, and ``stats``.
cpuset
------
Bastille supports limiting CPUs using ``cpuset``. To limit a jail to a specific CPU, use
``bastille limits TARGET cpu 2,3,4``` where the value (2,3,4) is a comma-separated list of CPUs on
your system. Bastille will validate the CPUs, and error if they are not available to be used.
Bastille supports limiting CPUs using ``cpuset``. To limit a jail to a specific
CPU, use ``bastille limits TARGET cpu 2,3,4``` where the value (2,3,4) is a
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
values. This will overwrite the ``cpuset.conf`` file. This will restrict the targetted jail(s) to
the specified CPUs.
To adjust the CPU limits, run ``bastille limits TARGET cpu 1,2,3`` again with a
new set of CPU values. This will overwrite the ``cpuset.conf`` file. This will
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
values are present in ``cpuset.conf`` inside the jail directory.
CPU limits are cleared when the jail is stopped, and loaded again on jail start,
providing the CPU values are present in ``cpuset.conf`` inside the jail directory.
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.
-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 jails, ports, releases, templates, logs, limits, exports and imports and much more
managed by bastille. See the ``help`` output below.
List jails, ports, releases, templates, logs, limits, exports and imports and
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``
to print in columns instead of rows.
Most options can be printed in JSON format by including the ``-j|--json`` flag.
Use ``-p|--pretty`` to print in columns instead of rows.
.. code-block:: shell
@@ -21,4 +22,4 @@ to print in columns instead of rows.
-p | --pretty Print JSON in columns.
-s | --sort VALUE Print info in VALUE order.
-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
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
name instead of an IP address or subnet.
It is also possible to specify a pf table as the source, providing it exists.
Simply use the table name instead of an IP address or subnet.
.. 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.
-x | --debug Enable debug mode.
The ``loopback`` option will configure a loopback interface called ``bastille0`` that
will be used as a default when not specifying an interface with the ``create`` command.
The ``loopback`` option will configure a loopback interface called ``bastille0``
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
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 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
should be configured. If you configure one, it will disable the other.
Please note. You CANNOT run both a loopback and a shared interface with Bastille.
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
that jails will get linked to on creation. It is not attached to any specific interface. This is the simplest
networking option. The ``loopback`` and ``shared`` options are only for cases where the ``interface``
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 ``loopback`` option is the default, and is enough for most use cases. It is
simply an ``lo`` interface that jails will get linked to on creation. It is not
attached to any specific interface. This is the simplest networking option. The
``loopback`` and ``shared`` options are only for cases where the ``interface``
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
opposed to a loopback. Jails will be linked to the shared interface on creation.
The ``shared`` option is for cases where you want an actual interface to use with
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
default ``pf.conf`` file. Once this is done, you can use the ``rdr`` command to forward traffic into
a jail.
The ``pf|firewall`` option will configure the pf firewall by enabling the service
and creating the default ``pf.conf`` file. Once this is done, you can use the
``rdr`` command to forward traffic into a jail.
The ``storage`` option will attempt to configure a pool and dataset for Bastille, but only
if ZFS in enabled on your system. Otherwise it will use UFS.
The ``storage`` option will attempt to configure a pool and dataset for Bastille,
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 ``bridge`` options will attempt to configure a bridge interface for use with bridged VNET
``-B`` jails.
The ``bridge`` options will attempt to configure a bridge interface for use with
bridged VNET ``-B`` jails.
Running ``bastille setup`` without any options will attempt to auto-configure the ``filesystem``, ``loopback``, ``firewall`` and
``storage`` options.
Running ``bastille setup`` without any options will attempt to auto-configure the
``filesystem``, ``loopback``, ``firewall`` and ``storage`` options.
.. code-block:: shell

25
docs/chapters/targeting.rst
View File

@@ -22,14 +22,18 @@ quotes, as seen below.
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
with ``sysrc bastille_enable=YES``. 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.
It also controls in what order jails are started and stopped on system startup
and shutdown. This requires Bastille to be enabled with ``sysrc bastille_enable=YES``.
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
creation. See ``bastille create --priority 90 TARGET...``.
When jails are created with Bastille, this value defaults to ``99``, but can be
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``.
@@ -38,14 +42,15 @@ This value will be shown using ``bastille list all``.
Parallel Mode
-------------
Any command that supports multiple targets, also supports parallel mode. This means that
Bastille will run the command on multiple jails at a single time, depending on the value
given.
Any command that supports multiple targets, also supports parallel mode. This
means that Bastille will run the command on multiple jails at a single time,
depending on the value given.
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.
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
--------------------

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
including ``--arg ARG=VALUE`` when running the template.
Multiple ARGS can also be specified as seen below. If no ARG value is given, Bastille
will show a warning, but continue on with the rest of the template.
Multiple ARGS can also be specified as seen below. If no ARG value is given,
Bastille will show a warning, but continue on with the rest of the template.
.. code-block:: shell
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
to any templates called with the ``INCLUDE`` hook. See the following example...
The ``ARG`` hook has a wide range of functionality, including passing KEY=VALUE
pairs to any templates called with the ``INCLUDE`` hook. See the following example...
.. 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}
If the above template is called with ``--arg JAIL=myjail --arg IP=10.3.3.3``, these values will
be passed along to ``other/template`` as well, with the matching variable. So ``${JAIL}`` will be
``myjail`` and ``${IP}`` will be ``10.3.3.3``.
If the above template is called with ``--arg JAIL=myjail --arg IP=10.3.3.3``,
these values will be passed along to ``other/template`` as well, with the
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
are ``JAIL_NAME``, ``JAIL_IP``, and ``JAIL_IP6``. These can be used inside any template without
setting the values at the top of the Bastillefile. The values are automatically retrieved from
the targeted jails configuration.
The ARG hook has three values that are built in, and will differ for every jail.
The values are ``JAIL_NAME``, ``JAIL_IP``, and ``JAIL_IP6``. These can be used
inside any template without setting the values at the top of the Bastillefile.
The values are automatically retrieved from the targeted jails configuration.
``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
-------
If a ZFS pool has been imported using ``-R`` (altroot), your system will 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.
If a ZFS pool has been imported using ``-R`` (altroot), your system will
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
you imported your pool with ``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.
One thing to note though, is that you MUST NOT include your ``altroot`` path in
the ``bastille_prefix``. For example, if you imported your pool with
``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
throw all kinds of errors due to not finding the proper paths.
If you do accidentally add the ``/mnt`` part, your datasets will be mounted at
``/mnt/mnt/poolname/bastille`` and Bastille will throw all kinds of errors due
to not finding the proper paths.
Jailing a Dataset
-----------------
It is possible to "jail" a dataset. This means mounting a datset into a jail, and being
able to fully manage it from within the jail.
It is possible to "jail" a dataset. This means mounting a datset into a 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``.
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.
To add a dataset to a jail, we can run
``bastille zfs TARGET jail pool/dataset /path/inside/jail``.
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
adjusting the path after you have added it, bearing in mind the warning below.
You can manually change the path where the dataset will be mounted by
``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
important that the jail is first stopped before attempting to manually configure this file. The format inside
the file is simple.
WARNING: Adding or removing datasets to the ``zfs.conf`` file can result in
permission errors with your jail. It is important that the jail is first stopped
before attempting to manually configure this file. The format inside the file is
simple.
.. code-block:: shell
pool/dataset /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
^^^^^^^^^^^^^^^^^
While it is possible to "jail" a dataset using a template, it is a bit more "hacky" than the above apporach.
Below is a template that you can use that will add the necessary bits to the ``jail.conf`` file to "jail" a
dataset.
While it is possible to "jail" a dataset using a template, it is a bit more
"hacky" than the above apporach.
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