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: general reformatting to use 80 columns in the text

Browse Source
This commit is contained in:
Juan David Hurtado G
2025-04-20 11:19:18 -05:00
parent 4c9947689e
commit 2390245a32
32 changed files with 443 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/chapters/boot-and-priority.rst
View File

@@ -4,20 +4,24 @@ Boot and Priority
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.
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.
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...``.
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...``.
This value can be changed using ``bastille config TARGET boot [on|off]``.
@@ -26,13 +30,16 @@ This value will be shown using ``bastille list all``.
Priority
--------
The priority value determines in what order commands are executed if multiple jails are targetted. This 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.
The priority value determines in what order commands are executed if multiple
jails are targetted. This 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 priority VALUE``.

48
docs/chapters/configuration.rst
View File

@@ -1,9 +1,12 @@
Configuration
=============
Bastille is configured using a default config file located at ``/usr/local/etc/bastille/bastille.conf``. When first installing
bastille, you should run ``bastille setup``. This will ask if you want to copy the sample config file to the above location. The defaults are sensible for UFS, but
if you want to use ZFS, you will have to change a few options. See the chapter on ZFS Support.
Bastille is configured using a default config file located at
``/usr/local/etc/bastille/bastille.conf``. When first installing bastille, you
should run ``bastille setup``. This will ask if you want to copy the sample
config file to the above location. The defaults are sensible for UFS, but if you
want to use ZFS, you will have to change a few options. See the chapter on ZFS
Support.
This is the default `bastille.conf` file.
@@ -83,26 +86,45 @@ Notes
The options here are fairly self-explanitory, but there are some things to note.
* If you use ZFS, DO NOT create the bastille dataset. You must only create the parent. Bastille must be allowed to create the ``bastille`` child dataset, or you will have issues. So, if you want bastille to live at ``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and ``bastille_zfs_prefix`` to ``data/bastille`` but you should only create ``zroot/data`` before running bastille for the first time.
* If you use ZFS, DO NOT create the bastille dataset. You must only create the
parent. Bastille must be allowed to create the ``bastille`` child dataset, or
you will have issues. So, if you want bastille to live at
``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and
``bastille_zfs_prefix`` to ``data/bastille`` but you should only create
``zroot/data`` before running bastille for the first time.
* Bastille will mount the dataset it creates at ``bastille_prefix`` which defaults to ``/usr/local/bastille``. So if you want to navigate to your jails, you will use the ``bastille_prefix`` as the location because this is where the will be mounted.
* Bastille will mount the dataset it creates at ``bastille_prefix`` which
defaults to ``/usr/local/bastille``. So if you want to navigate to your jails,
you will use the ``bastille_prefix`` as the location because this is where the
will be mounted.
Custom Configuration
--------------------
Bastille now supports using a custom config in addition to the default one. This is nice if you have multiple users, or want to store different
Bastille now supports using a custom config in addition to the default one. This
is nice if you have multiple users, or want to store different
jails at different locations based on your needs.
The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at ``/usr/local/etc/bastille`` or it will not work.
The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at
``/usr/local/etc/bastille`` or it will not work.
Simply copy the default config file and edit it according to your new environment or user. Then, it can be used in a couple of ways.
Simply copy the default config file and edit it according to your new
environment or user. Then, it can be used in a couple of ways.
1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE`` to bootstrap the release using the new config.
1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE``
to bootstrap the release using the new config.
2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export BASTILLE_CONFIG=config.conf``. This config will then always be used when running Bastille with that user. See notes below...
2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export
BASTILLE_CONFIG=config.conf``. This config will then always be used when
running Bastille with that user. See notes below...
- Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current session. If you want to persist the export, see documentation for the shell that you use.
- Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current
session. If you want to persist the export, see documentation for the shell that
you use.
- If you use sudo, you will need to run it with ``sudo -E bastille bootstrap...`` to preserve your users environment. This can also be persisted by editing the sudoers file.
- If you use sudo, you will need to run it with ``sudo -E bastille
bootstrap...`` to preserve your users environment. This can also be persisted by
editing the sudoers file.
- If you do set the ``BASTILLE_CONFIG`` variable, you do not need to specify the config file when running Bastille as that specified user.
- If you do set the ``BASTILLE_CONFIG`` variable, you do not need to specify the
config file when running Bastille as that specified user.

28
docs/chapters/gcp.rst
View File

@@ -3,16 +3,17 @@ Bastille VNET on GCP
Bastille VNET runs on GCP with a few small tweaks. In summary, they are:
- change MTU setting in jib script
- add an IP address to the bridge interface
- configure host pf to NAT and allow bridge traffic
- set defaultrouter and nameserver in the host
- change MTU setting in jib script - add an IP address to the bridge interface -
configure host pf to NAT and allow bridge traffic - set defaultrouter and
nameserver in the host
## Change MTU in the jib script
GCP uses ``vtnet`` with MTU 1460, which [jib fails on](https://github.com/BastilleBSD/bastille/issues/538).
GCP uses ``vtnet`` with MTU 1460, which [jib fails
on](https://github.com/BastilleBSD/bastille/issues/538).
Apply the below patch to set the correct MTU. You may need to ``cp /usr/share/examples/jails/jib /usr/local/bin/`` first.
Apply the below patch to set the correct MTU. You may need to ``cp
/usr/share/examples/jails/jib /usr/local/bin/`` first.
``patch /usr/local/bin/jib jib.patch``
@@ -39,7 +40,8 @@ Apply the below patch to set the correct MTU. You may need to ``cp /usr/share/ex
## Configure bridge interface
Configure the bridge interface in /etc/rc.conf so it is available in the firewall rules.
Configure the bridge interface in /etc/rc.conf so it is available in the
firewall rules.
.. code-block:: shell
sysrc cloned_interfaces="bridge0"
@@ -49,7 +51,8 @@ Configure the bridge interface in /etc/rc.conf so it is available in the firewal
## Configure host pf
This basic /etc/pf.conf allow incoming packets on the bridge interface, and NATs them through the external interface:
This basic /etc/pf.conf allow incoming packets on the bridge interface, and NATs
them through the external interface:
.. code-block:: text
ext_if="vtnet0"
@@ -68,7 +71,8 @@ This basic /etc/pf.conf allow incoming packets on the bridge interface, and NATs
pass in inet proto icmp icmp-type { echoreq }
pass in on $bridge_if
Restart the host and make sure everything comes up correctly. You should see the following ifconfig:
Restart the host and make sure everything comes up correctly. You should see the
following ifconfig:
.. code-block:: text
vtnet0bridge: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1460
@@ -83,11 +87,13 @@ Restart the host and make sure everything comes up correctly. You should see the
## Configure router and resolver for new jails
Set the default network gateway for new jails as described in the Networking chapter, and configure a default resolver.
Set the default network gateway for new jails as described in the Networking
chapter, and configure a default resolver.
.. code-block:: shell
sysrc -f /usr/local/etc/bastille/bastille.conf bastille_network_gateway="192.168.1.1"
echo "nameserver 8.8.8.8" > /usr/local/etc/bastille/resolv.conf
sysrc -f /usr/local/etc/bastille/bastille.conf bastille_resolv_conf="/usr/local/etc/bastille/resolv.conf"
You can now create a VNET jail with ``bastille create -V myjail 13.2-RELEASE 192.168.1.50/24 vtnet0``
You can now create a VNET jail with ``bastille create -V myjail 13.2-RELEASE
192.168.1.50/24 vtnet0``

51
docs/chapters/gettingstarted.rst
View File

@@ -1,30 +1,38 @@
Getting Started
===============
This guide is meant to get you up and running with bastille, and will show you a number
of different options to create and manage your jails.
This guide is meant to get you up and running with bastille, and will show you
a number of different options to create and manage your jails.
The first step is running ``bastille setup`` to try to configure bastille initially, if you didn't during setup. Setup should only be run once.
The first step is running ``bastille setup`` to try to configure bastille
initially, if you didn't during setup. Setup should only be run once.
.. code-block:: shell
ishmael ~ # bastille setup
Then we need to bootstrap a release for bastille to use. We will use 14.2-RELEASE.
Then we need to bootstrap a release for bastille to use. We will use
14.2-RELEASE.
.. code-block:: shell
ishmael ~ # bastille bootstrap 14.2-RELEASE
Next we can create our first jail. Bastille can create a few different types of jails.
Next we can create our first jail. Bastille can create a few different types of
jails.
* Thin jails are the default, and are called thin because they use symlinks to the bootstrapped release. They are lightweight and are created quickly.
* Thin jails are the default, and are called thin because they use symlinks to
the bootstrapped release. They are lightweight and are created quickly.
* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independent of the release. Created with ``bastille create -T``.
* Thick jails used the entire release, which is copied into the jail. The jail
then acts like a full BSD install, completely independent of the release.
Created with ``bastille create -T``.
* Clone jails are essentially clones of the bootstrapped release. Changes to the release will affect the clone jail. Created with ``bastille create -C``.
* Clone jails are essentially clones of the bootstrapped release. Changes to the
release will affect the clone jail. Created with ``bastille create -C``.
* Empty jails are just that, empty. These should be used only if you know what you are doing. Created with ``bastille create -E``.
* Empty jails are just that, empty. These should be used only if you know what
you are doing. Created with ``bastille create -E``.
* Linux jails are jails that run linux. Created with ``bastille create -L``.
@@ -39,12 +47,13 @@ Classic/Standard Jail
ishmael ~ # bastille create nextcloud 14.2-RELEASE 10.1.1.4/24 vtnet0
This will create a classic jail and add the IP as an alias to the vtnet0 interface. This jail will
use NAT for its outbound traffic. If you want to run a webserver of something similar inside it, you
will have to redirect traffic from the host using ``bastille rdr``
This will create a classic jail and add the IP as an alias to the vtnet0
interface. This jail will use NAT for its outbound traffic. If you want to run
a webserver of something similar inside it, you will have to redirect traffic
from the host using ``bastille rdr``
It the IP is reachable within your local subnet, however, then it is not necessary to redirect the
traffic. It will pass in and out normally.
It the IP is reachable within your local subnet, however, then it is not
necessary to redirect the traffic. It will pass in and out normally.
.. code-block:: shell
@@ -55,26 +64,28 @@ This will forward traffic from port 80 on the host to port 80 inside the jail.
VNET Jail
---------
VNET jails can use either a host interface with ``-V`` or a manually created bridge interface with ``-B``. You can
also optionally set a static MAC for the jail interface with ``-M``.
VNET jails can use either a host interface with ``-V`` or a manually created
bridge interface with ``-B``. You can also optionally set a static MAC for the
jail interface with ``-M``.
.. code-block:: shell
ishmael ~ # bastille create -BM nextcloud 14.2-RELEASE 192.168.1.50/24 bridge0
or
or
.. code-block:: shell
ishmael ~ # bastille create -VM nextcloud 14.2-RELEASE 192.168.1.50/24 vtnet0
The IP used for VNET jails should be an IP reachable inside your local network. You can also specify 0.0.0.0 or DHCP
to use DHCP.
The IP used for VNET jails should be an IP reachable inside your local network.
You can also specify 0.0.0.0 or DHCP to use DHCP.
Linux Jail
----------
Linux jails are still considered experimental, but they seem to work. First we must bootstrap a linux distro.
Linux jails are still considered experimental, but they seem to work. First we
must bootstrap a linux distro.
.. code-block:: shell

9
docs/chapters/migration.rst
View File

@@ -12,7 +12,8 @@ Stop the running jail and export it:
iocage stop jailname
iocage export jailname
Move the backup files (.zip and .sha256) into Bastille backup dir (default: /usr/local/bastille/backups/):
Move the backup files (.zip and .sha256) into Bastille backup dir (default:
/usr/local/bastille/backups/):
.. code-block:: shell
@@ -31,11 +32,13 @@ 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.
Bastille will attempt to configure your interface and IP from the
``config.json`` file, but if you have issues you can configure it manully.
.. code-block:: shell
bastille edit jailname
ip4.addr = bastille0|192.168.0.1/24;
You can use your primary network interface instead of the virtual ``bastille0`` interface as well if you know what you’re doing.
You can use your primary network interface instead of the virtual ``bastille0``
interface as well if you know what you’re doing.

132
docs/chapters/networking.rst
View File

@@ -12,52 +12,88 @@ Bastille includes a number of IP options.
The IP address specified above can be any of the following options.
* An IP in your local subnet should be chosen if you create your jail using ``-V`` or ``-B`` (VNET jail). It is also preferable to add the subnet mask (/24 or whaterver your subnet is) to the IP.
* An IP in your local subnet should be chosen if you create your jail using
``-V`` or ``-B`` (VNET jail). It is also preferable to add the subnet mask
(/24 or whaterver your subnet is) to the IP.
* DHCP, SYNCDHCP, or 0.0.0.0 will configure your jail to use DHCP to obtain an address from your router. This should only be used with ``-V`` and ``-B``.
* DHCP, SYNCDHCP, or 0.0.0.0 will configure your jail to use DHCP to obtain an
address from your router. This should only be used with ``-V`` and ``-B``.
* Any IP address inside the RFC1918 range if you are not using a VNET jail. Bastille will automatically add this IP to the firewall table to allow outbound access. It you want traffic to be forwarded into the jail, you can use the ``bastille rdr`` command.
* Any IP address inside the RFC1918 range if you are not using a VNET jail.
Bastille will automatically add this IP to the firewall table to allow
outbound access. It you want traffic to be forwarded into the jail, you can
use the ``bastille rdr`` command.
* Any IP in your local subnet without the ``-V`` or ``-B`` options will add the IP as an alias to the selected interface, which will simply end up sharing the interface. If the IP is in your local subnet, you will not need the ``bastille rdr`` command. Traffic will pass in and out just as in a VNET jail.
* Any IP in your local subnet without the ``-V`` or ``-B`` options will add the
IP as an alias to the selected interface, which will simply end up sharing the
interface. If the IP is in your local subnet, you will not need the ``bastille
rdr`` command. Traffic will pass in and out just as in a VNET jail.
* Setting the IP to ``inherit`` will make the jail inherit the entire host network stack.
* Setting the IP to ``inherit`` will make the jail inherit the entire host
network stack.
* Setting the IP to ``ip_hostname`` will add all the IPs that the hostname resolves to. This is an advanced option and should only be used if you know what you are doing.
* Setting the IP to ``ip_hostname`` will add all the IPs that the hostname
resolves to. This is an advanced option and should only be used if you know
what you are doing.
Note that jails support specifying an IP without the subnet (/24 or whatever yours is) but we highly recommend setting it, especially
on VNET jails. Not doing so can cause issues in some rare cases.
Note that jails support specifying an IP without the subnet (/24 or whatever
yours is) but we highly recommend setting it, especially on VNET jails. Not
doing so can cause issues in some rare cases.
Bastille also supports IPv6. Instead of an IPv4 address, you can specify and IPv6 address when creating a jail to use IPv6. It is also possible to use both by quoting and IPv4 and IPv6 address together as seen in the following example.
Bastille also supports IPv6. Instead of an IPv4 address, you can specify and
IPv6 address when creating a jail to use IPv6. It is also possible to use both
by quoting and IPv4 and IPv6 address together as seen in the following example.
.. code-block:: shell
bastille create alcatraz 13.2-RELEASE "192.168.1.50/24 2001:19f0:6c01:114c:0:100/64" vtnet0
For the ``inherit`` and ``ip_hostname`` options, you can also specify ``-D|--dual`` to use both IPv4 and IPv6 inside the jail.
For the ``inherit`` and ``ip_hostname`` options, you can also specify
``-D|--dual`` to use both IPv4 and IPv6 inside the jail.
Host Network Configuration
--------------------------
Bastille will automatically add and remove IP addressess to specified interfaces as jails are started and stopped. Below is an outline of how Bastille handles different types of jail network configs.
Bastille will automatically add and remove IP addressess to specified interfaces
as jails are started and stopped. Below is an outline of how Bastille handles
different types of jail network configs.
* VNET mode. For VNET jails (non-bridged) bastille will create a bridge interface and attach your jail to it. It will be called ``em0bridge`` or 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.
* VNET mode. For VNET jails (non-bridged) bastille will create a bridge
interface and attach your jail to it. It will be called ``em0bridge`` or
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, 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, 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 specified interface as an alias.
* 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
specified interface as an alias.
* NAT mode. For classic/standard jails that use an IP not reachable in you local subnet, bastille will add the IP to the specified interface as an alias, and additionally add it the the pf firewall table 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 attemplt to use ``bastille0`` (which is created using the setup command) as it's interface. If you have not run ``bastille setup`` and do not specify an interface, Bastille will error.
* NAT mode. For classic/standard jails that use an IP not reachable in you local
subnet, bastille will add the IP to the specified interface as an alias, and
additionally add it the the pf firewall table 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 attemplt to use ``bastille0`` (which
is created using the setup command) as it's 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 ``ip_hostname``, bastille will simply set ``ip4`` to ``inherit`` inside the jail config. The jail will then function according the jail(8) documentation.
* Inherit mode. For classic/standard jails that are set to ``inherit`` or
``ip_hostname``, bastille will simply set ``ip4`` to ``inherit`` inside the
jail config. The jail will then function according the jail(8) documentation.
* ip_hostname mode. For classic/standard jails that are set to ``ip_hostname``, bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. The jail will then function according the jail(8) documentation.
* ip_hostname mode. For classic/standard jails that are set to ``ip_hostname``,
bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config.
The jail will then function according the jail(8) documentation.
Network Scenarios
-----------------
Here's the scenario. You've installed Bastille at home or in the cloud and want
to get started putting applications in secure little containers, but how do you
get these containers on the network? Bastille tries to be flexible about how to
get these containers on the network? Bastille tries to be flexible about how to
network containerized applications. Four methods are described here.
1. Home or Small Office
@@ -72,12 +108,12 @@ Please choose the option which is most appropriate for your environment.
First a few notes. Bastille tries to verify that the interface name you provide
is a valid interface. In FreeBSD network interfaces have different names, but
look something like ``em0``, ``bge0``, ``re0``, ``vtnet0`` etc. Running the ifconfig
commend will tell you the name of your existing interfaces. Bastille also
checks for a valid syntax IP4 or IP6 address. When you are testing calling out
from your containers, please note that the ping command is disabled within the
containers, because raw socket access are a security hole. Instead, install and
test with ``wget/curl/fetch`` instead.
look something like ``em0``, ``bge0``, ``re0``, ``vtnet0`` etc. Running the
``ifconfig`` command will tell you the name of your existing interfaces.
Bastille also checks for a valid syntax IP4 or IP6 address. When you are testing
calling out from your containers, please note that the ping command is disabled
within the containers, because raw socket access are a security hole. Instead,
install and test with ``wget/curl/fetch`` instead.
Shared Interface on Home or Small Office Network
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -107,7 +143,8 @@ interface and a free IP on your local network.
Shared Interface on IPV6 network (vultr.com)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some ISP's, such as `Vultr <https://vultr.com>`_, give you a single ipv4 address,
Some ISP's, such as `Vultr <https://vultr.com>`_, give you a single ipv4
address,
and a large block of ipv6 addresses. You can then assign a unique ipv6 address
to each Bastille Container.
@@ -131,7 +168,7 @@ The `vultr ipv6 subnet calculator
<https://www.vultr.com/resources/subnet-calculator-ipv6/?prefix_length=64&display=long&ipv6_address=2001%3Adb8%3Aacad%3Ae%3A%3A%2F64>`_
is helpful in making sense of that ipv6 address.
We could have also written that IPV6 address as 2001:19f0:6c01:114c:0:0
We could have also written that IPV6 address as 2001:19f0:6c01:114c:0:0
Where the /64 basicaly means that the first 64 bits of the address (4x4
character hexadecimal) values define the network, and the remaining characters,
@@ -157,9 +194,9 @@ Virtual Network (VNET)
(Added in 0.6.x) VNET is supported on FreeBSD 12+ only.
Virtual Network (VNET) creates a private network interface for a container.
This includes a unique hardware address. This is required for VPN, DHCP, and
similar containers.
Virtual Network (VNET) creates a private network interface for a container. This
includes a unique hardware address. This is required for VPN, DHCP, and similar
containers.
To create a VNET based container use the ``-V`` option, an IP/netmask and
external interface.
@@ -188,7 +225,7 @@ host system:
.. code-block:: shell
## /etc/devfs.rules (NOT .conf)
[bastille_vnet=13]
add include $devfsrules_hide_all
add include $devfsrules_unhide_basic
@@ -224,27 +261,36 @@ Below is the definition of what these three parameters are used for and mean:
Bridged Network (VNET bridged)
------------------------------
To use a bridged VNET setup the first thing you have to do is to create a bridge interface on your system. This is done with the ifconfig command and will create a bridged interface named bridge0:
To use a bridged VNET setup the first thing you have to do is to create a bridge
interface on your system. This is done with the ifconfig command and will
create a bridged interface named bridge0:
.. code-block:: shell
ifconfig bridge create
Then you need to add your system's network interface to the bridge and bring it up (substitute your interface for em0).
Then you need to add your system's network interface to the bridge and bring it
up (substitute your interface for em0).
.. code-block:: shell
ifconfig bridge0 addm em0 up
Optionally you can rename the interface if you wish to make it obvious that it is for bastille:
Optionally you can rename the interface if you wish to make it obvious that it
is for bastille:
.. code-block:: shell
ifconfig bridge0 name bastille0bridge
To create a bridged container you use the ``-B`` option, an IP or DHCP, and the bridge interface.
To create a bridged container you use the ``-B`` option, an IP or DHCP, and the
bridge interface.
.. code-block:: shell
bastille create -B folsom 14.2-RELEASE DHCP bastille0bridge
All the epairs and networking other than the manually created bridge will be created for you automagically. Now if you want this to persist after a reboot then you need to add some lines to your ``/etc/rc.conf`` file. Add the following lines, again, obviously change em0 to whatever your network interface on your system is.
All the epairs and networking other than the manually created bridge will be
created for you automagically. Now if you want this to persist after a reboot
then you need to add some lines to your ``/etc/rc.conf`` file. Add the
following lines, again, obviously change em0 to whatever your network interface
on your system is.
.. code-block:: shell
cloned_interfaces="bridge0"
@@ -293,9 +339,10 @@ Public Network
--------------
In this section we describe how to network containers in a public network
such as a cloud hosting provider who only provides you with a single ip address.
(AWS, Digital Ocean, etc) (The exception is vultr.com, which does
provide you with lots of IPV6 addresses and does a great job supporting FreeBSD!)
such as a cloud hosting provider who only provides you with a single ip address.
(AWS, Digital Ocean, etc) (The exception is vultr.com, which does
provide you with lots of IPV6 addresses and does a great job supporting
FreeBSD!)
So if you only have a single IP address and if you want to create multiple
containers and assign them all unique IP addresses, you'll need to create a new
@@ -356,7 +403,8 @@ Create the firewall rules:
antispoof for $ext_if inet
pass in inet proto tcp from any to any port ssh flags S/SA modulate state
- Make sure to change the ``ext_if`` variable to match your host system interface.
- Make sure to change the ``ext_if`` variable to match your host system
interface.
- Make sure to include the last line (``port ssh``) or you'll end up locked out.
Note: if you have an existing firewall, the key lines for in/out traffic
@@ -405,7 +453,8 @@ This step only needs to be done once in order to prepare the host.
local_unbound
-------------
If you are running "local_unbound" on your server, you will probably have issues with DNS resolution.
If you are running "local_unbound" on your server, you will probably have issues
with DNS resolution.
To resolve this, add the following configuration to local_unbound:
@@ -416,6 +465,7 @@ To resolve this, add the following configuration to local_unbound:
access-control: 192.168.0.0/16 allow
access-control: 10.17.90.0/24 allow
Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf
Also, change the nameserver to the servers IP instead of 127.0.0.1 inside
/etc/rc.conf
Adjust the above "access-control" strings to fit your network.

21
docs/chapters/subcommands/bootstrap.rst
View File

@@ -1,15 +1,14 @@
bootstrap
=========
The bootstrap sub-command is used to download and extract releases and
templates for use with Bastille containers. A valid release is needed before
containers can be created. Templates are optional but are managed in the same
manner.
The bootstrap sub-command is used to download and extract releases and templates
for use with Bastille containers. A valid release is needed before containers
can be created. Templates are optional but are managed in the same manner.
Note: your mileage may vary with unsupported releases and releases newer
than the host system likely will NOT work at all. Bastille tries to filter for
valid release names. If you find it will not bootstrap a valid release, please
let us know.
Note: your mileage may vary with unsupported releases and releases newer than
the host system likely will NOT work at all. Bastille tries to filter for valid
release names. If you find it will not bootstrap a valid release, please let us
know.
In this document we will describe using the ``bootstrap`` sub-command with both
releases and templates. We begin with releases.
@@ -60,8 +59,8 @@ Tips
^^^^
The ``bootstrap`` sub-command can now take (0.5.20191125+) an optional second
argument of ``update``. If this argument is used, ``bastille update`` will be run
immediately after the bootstrap, effectively bootstrapping and applying
argument of ``update``. If this argument is used, ``bastille update`` will be
run immediately after the bootstrap, effectively bootstrapping and applying
security patches and errata in one motion.
Notes
@@ -126,4 +125,4 @@ begin applying your template.
Usage: bastille bootstrap [option(s)] [RELEASE|TEMPLATE] [update|arch]
Options:
-x | --debug Enable debug mode.
-x | --debug Enable debug mode.

2
docs/chapters/subcommands/clone.rst
View File

@@ -2,7 +2,7 @@ clone
=====
To clone a container and make a duplicate, use the ``bastille clone``
sub-command..
sub-command.
.. code-block:: shell

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

@@ -1,7 +1,8 @@
console
=======
This sub-command launches a login shell into the container. Default is password-less root login.
This sub-command launches a login shell into the container. Default is password-
less root login.
.. code-block:: shell
@@ -9,7 +10,7 @@ This sub-command launches a login shell into the container. Default is password-
[folsom]:
root@folsom:~ #
At this point you are logged in to the container and have full shell access. The
At this point you are logged in to the container and have full shell access. The
system is yours to use and/or abuse as you like. Any changes made inside the
container are limited to the container.

40
docs/chapters/subcommands/create.rst
View File

@@ -1,14 +1,11 @@
create
======
Bastille create uses any available bootstrapped release to create a
lightweight container system. To create a container simply provide a name,
bootstrapped release and a private (rfc1918) IP address.
Bastille create uses any available bootstrapped release to create a lightweight
container system. To create a container simply provide a name, bootstrapped
release and a private (rfc1918) IP address.
- name
- release
- ip
- interface (optional)
- name - release - ip - interface (optional)
.. code-block:: shell
@@ -26,31 +23,31 @@ address to the new system.
ishmael ~ # bastille create alcatraz 13.2-RELEASE 10.17.89.113/24
The above code will create a jail with a /24 mask. At the time of this documentation you
can only use CIDR notation, and not use a netmask 255.255.255.0 to accomplish this.
The above code will create a jail with a /24 mask. At the time of this
documentation you can only use CIDR notation, and not use a netmask
255.255.255.0 to accomplish this.
I recommend using private (rfc1918) ip address ranges for your container. These
ranges include:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
- 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16
Bastille does its best to validate the submitted ip is valid. This has not been
thouroughly tested--I generally use the 10/8 range.
A couple of notes about the created jails. First, MOTD has been disabled inside
of the jails because it does not give information about the jail, but about the host
system. This caused confusion for some users, so we implemented the .hushlogin which
silences the MOTD at login.
A couple of notes about the created jails. First, MOTD has been disabled inside
of the jails because it does not give information about the jail, but about the
host system. This caused confusion for some users, so we implemented the
.hushlogin which silences the MOTD at login.
Also, uname does not work from within a jail. Much like MOTD, it gives you the version
information about the host system instead of the jail. If you need to check the version
of freebsd running on the jail use the freebsd-version command to get accurate information.
Also, uname does not work from within a jail. Much like MOTD, it gives you the
version information about the host system instead of the jail. If you need to
check the version of freebsd running on the jail use the freebsd-version command
to get accurate information.
Bastille can create many different types of jails, along with many different options. See
the below help output.
Bastille can create many different types of jails, along with many different
options. See the below help output.
.. code-block:: shell
@@ -72,4 +69,3 @@ the below help output.
-v | --vlan VLANID Creates the jail with specified VLAN ID (VNET only).
-x | --debug Enable debug mode.
-Z | --zfs-opts [zfs,options] Comma separated list of ZFS options to create the jail with. This overrides the defaults.

10
docs/chapters/subcommands/destroy.rst
View File

@@ -1,9 +1,9 @@
destroy
=======
Jails can be destroyed and thrown away just as easily as they were
created. Note: containers must be stopped before destroyed. Using
the ``-a|--auto`` option will automatically stop the jail before destroying it.
Jails can be destroyed and thrown away just as easily as they were created.
Note: containers must be stopped before destroyed. Using the ``-a|--auto``
option will automatically stop the jail before destroying it.
.. code-block:: shell
@@ -14,8 +14,8 @@ the ``-a|--auto`` option will automatically stop the jail before destroying it.
Note: containers console logs not destroyed.
/usr/local/bastille/logs/folsom_console.log
Release can be destroyed provided there are no child jails. The `-c|--no-cache` option
will retain the release cache directory, if you choose to keep it.
Release can be destroyed provided there are no child jails. The `-c|--no-cache`
option will retain the release cache directory, if you choose to keep it.
.. code-block:: shell

8
docs/chapters/subcommands/etcupdate.rst
View File

@@ -1,7 +1,8 @@
etcupdate
=========
This command will update the contents of ``/etc`` inside a jail. It should be run after a jail upgrade
This command will update the contents of ``/etc`` inside a jail. It should be
run after a jail upgrade
First we need to bootstrap a release for ``etcupdate`` to use.
@@ -21,8 +22,9 @@ Next we can use the ``update`` command to apply the update to the jail.
ishmael ~ # bastille etcupdate ishmael update 14.1-RELEASE
The output will show you which files were added, updated, changed, deleted, or have conflicts.
To automatically resolve the conflicts, run the ``resolve`` command.
The output will show you which files were added, updated, changed, deleted, or
have conflicts. To automatically resolve the conflicts, run the ``resolve``
command.
.. code-block:: shell

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

@@ -1,8 +1,8 @@
htop
====
This command runs ``htop`` in the targeted jail.
Requires htop to be installed in the jail.
This command runs ``htop`` in the targeted jail. Requires htop to be installed
in the jail.
.. image:: ../../images/htop.png
:align: center

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

@@ -7,7 +7,8 @@ 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, use ``bastille limits TARGET reset``
To clear the limits, and remove the rctl.conf, use ``bastille limits TARGET
reset``
To remove a limit, use ``bastille limits TARGET remove OPTION``

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

@@ -1,7 +1,8 @@
list
====
List jails, ports, releases, templates, logs, limits, exports and imports managed by bastille.
List jails, ports, releases, templates, logs, limits, exports and imports
managed by bastille.
.. code-block:: shell

20
docs/chapters/subcommands/mount.rst
View File

@@ -9,7 +9,8 @@ Syntax follows standard ``/etc/fstab`` format:
Usage: bastille mount TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number]
The ``options`` string can include a comma-separated list of mount options, but must include one of (rw,ro,rq,sw,xx) according to fstab documentation.
The ``options`` string can include a comma-separated list of mount options, but
must include one of (rw,ro,rq,sw,xx) according to fstab documentation.
Example: Mount a tmpfs filesystem with options.
@@ -31,11 +32,16 @@ Example: Mount a nullfs filesystem
[azkaban]:
Added: /media/bar /usr/local/bastille/jails/azkaban/root/media/bar nullfs ro 0 0
Notice the JAIL_PATH format can be /media/foo or simply media/bar. The leading slash / is optional. The HOST_PATH howerver, must be the full path including the leading slash /.
Notice the JAIL_PATH format can be /media/foo or simply media/bar. The leading
slash / is optional. The HOST_PATH howerver, must be the full path including the
leading slash /.
It is also possible to mount individual files into a jail as seen below.
Bastille will not mount if a file is already present at the specified mount point.
If the jail file name does not match the host file name, bastille will treat the jail path as a directory, and mount the file underneath as seen in the second example below.
Bastille will not mount if a file is already present at the specified mount
point.
If the jail file name does not match the host file name, bastille will treat the
jail path as a directory, and mount the file underneath as seen in the second
example below.
.. code-block:: shell
@@ -46,8 +52,10 @@ If the jail file name does not match the host file name, bastille will treat the
[azkaban]:
Added: /etc/rc.conf usr/local/bastille/jails/azkaban/root/media/bar/rc.conf nullfs ro 0 0
It is also possible (but not recommended) to have spaces in the directories that are mounted.
It is necessary to escape each space with a backslash \ and enclose the mount point in quotes "" as seen below.
It is also possible (but not recommended) to have spaces in the directories that
are mounted.
It is necessary to escape each space with a backslash \ and enclose the mount
point in quotes "" as seen below.
It is possible to do the same for the jail path, but again, not recommemded.
.. code-block:: shell

25
docs/chapters/subcommands/network.rst
View File

@@ -5,15 +5,30 @@ Add or remove interfaces to existing jails.
You can only add an interface once to a jail, with two exceptions.
1. For classic jails, you can add an interface as many times as you want, but each time with a different IP. All this does is add the IP as another alias on that interface.
1. For classic jails, you can add an interface as many times as you want, but
each time with a different IP. All this does is add the IP as another alias
on that interface.
2. For VNET jails, if the ``-v|--vlan`` switch is given along with a numerical VLAN ID, Bastille will add the VLAN ID to the jail as a vnetX.X interface, depending on which interface is specified.
2. For VNET jails, if the ``-v|--vlan`` switch is given along with a numerical
VLAN ID, Bastille will add the VLAN ID to the jail as a vnetX.X interface,
depending on which interface is specified.
Bridges and VNET interfaces can be added to VNET jails, no matter if they were created with ``-V`` or ``-B``.
Bridges and VNET interfaces can be added to VNET jails, no matter if they were
created with ``-V`` or ``-B``.
It is possible to passthrough an entire interface from the host to the jail using the ``-P|--passthrough`` option. This will make the interface fully available without the need for additional configuration. It will be available inside the jail just like it would be on the host. Adding an interface using this method will render it only available inside the jail. It will not be present on the host until the jail is stopped.
It is possible to passthrough an entire interface from the host to the jail
using the ``-P|--passthrough`` option. This will make the interface fully
available without the need for additional configuration. It will be available
inside the jail just like it would be on the host. Adding an interface using
this method will render it only available inside the jail. It will not be
present on the host until the jail is stopped.
When cloning a jail that has a ``-P|--passthrough`` interface, you will have warnings when running both jails at the same time. The first jail to start will be assigned the interface, and since it will no longer be available to the host, it will not be possible to add it to the second jail. To solve this, you must manually remove the interface from the jail.conf file, or running ``bastille network TARGET remove INTERFACE`` while both jails are stopped.
When cloning a jail that has a ``-P|--passthrough`` interface, you will have
warnings when running both jails at the same time. The first jail to start will
be assigned the interface, and since it will no longer be available to the host,
it will not be possible to add it to the second jail. To solve this, you must
manually remove the interface from the jail.conf file, or running ``bastille
network TARGET remove INTERFACE`` while both jails are stopped.
.. code-block:: shell

6
docs/chapters/subcommands/pkg.rst
View File

@@ -20,9 +20,9 @@ Manage binary packages inside jails.
...[snip]...
The PKG sub-command can do more than just ``install``. The
expectation is that you can fully leverage the pkg manager. This means,
``install``, ``update``, ``upgrade``, ``audit``, ``clean``, ``autoremove``, etc...
The PKG sub-command can do more than just ``install``. The expectation is that
you can fully leverage the pkg manager. This means, ``install``, ``update``,
``upgrade``, ``audit``, ``clean``, ``autoremove``, etc...
.. code-block:: shell

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

@@ -3,12 +3,12 @@ rdr
``bastille rdr`` allows you to configure dynamic rdr rules for your containers
without modifying pf.conf (assuming you are using the ``bastille0`` interface
for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf
as described in the Networking section).
for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf as
described in the Networking section).
Note: you need to be careful if host services are configured to run
on all interfaces as this will include the jail interface - you should
specify the interface they run on in rc.conf (or other config files)
Note: you need to be careful if host services are configured to run on all
interfaces as this will include the jail interface - you should specify the
interface they run on in rc.conf (or other config files)
.. code-block:: shell

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

@@ -2,8 +2,8 @@ service
=======
The ``service`` sub-command allows for managing services within jails. This
allows you to start, stop, restart, and otherwise interact with services
running inside the jail(s).
allows you to start, stop, restart, and otherwise interact with services running
inside the jail(s).
.. code-block:: shell

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

@@ -2,8 +2,8 @@ setup
=====
The ``setup`` sub-command attempts to automatically configure a host system for
Bastille containers. This allows you to configure networking, firewall, and storage
options for a Bastille host with one command.
Bastille containers. This allows you to configure networking, firewall, and
storage options for a Bastille host with one command.
.. code-block:: shell

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

@@ -7,8 +7,9 @@ Run preconfigured template files inside targeted jail(s).
ishmael ~ # bastille template azkaban project/template
Templates should be structured in ``project/template/Bastillefile`` format, and placed in the template
directory, which defaults to ``/usr/local/bastille/templates``. The Bastillefile should contain the template
Templates should be structured in ``project/template/Bastillefile`` format, and
placed in the template directory, which defaults to
``/usr/local/bastille/templates``. The Bastillefile should contain the template
hooks. See the chapter called Template for a list of supported hooks.
.. code-block:: shell

3
docs/chapters/subcommands/umount.rst
View File

@@ -18,7 +18,8 @@ Syntax requires only the jail path to unmount.
Usage: bastille umount TARGET JAIL_PATH
If the directory you are unmounting has spaces, make sure to escape them with a backslash \, and enclose the mount point in quotes "".
If the directory you are unmounting has spaces, make sure to escape them with a
backslash \, and enclose the mount point in quotes "".
.. code-block:: shell

10
docs/chapters/subcommands/update.rst
View File

@@ -2,8 +2,8 @@ update
======
The ``update`` command targets a release or a thick jail. Because thin jails are
based on a release, when the release is updated all the thin jails are automatically
updated as well.
based on a release, when the release is updated all the thin jails are
automatically updated as well.
If no updates are available, a message will be shown:
@@ -38,8 +38,8 @@ The older the release or jail, however, the more updates will be available:
To be safe, you may want to restart any jails that have been updated live.
If the jail is a thin jail, an error will be shown. If it is a thick jail, it will be updated just like
the release shown above.
If the jail is a thin jail, an error will be shown. If it is a thick jail, it
will be updated just like the release shown above.
.. code-block:: shell
@@ -49,4 +49,4 @@ the release shown above.
-a | --auto Auto mode. Start/stop jail(s) if required.
-f | --force Force update a release.
-x | --debug Enable debug mode.
-x | --debug Enable debug mode.

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

@@ -1,8 +1,9 @@
upgrade
=======
The ``upgrade`` command targets a thick or thin jail. Thin jails will be updated by changing the
release mount point that it is based on. Thick jails will be upgraded normally.
The ``upgrade`` command targets a thick or thin jail. Thin jails will be updated
by changing the release mount point that it is based on. Thick jails will be
upgraded normally.
.. code-block:: shell

10
docs/chapters/subcommands/verify.rst
View File

@@ -1,12 +1,12 @@
verify
======
This command scans a bootstrapped release or template and validates that everything looks
in order. This is not a 100% comprehensive check, but it compares the release or template
against a "known good" index.
This command scans a bootstrapped release or template and validates that
everything looks in order. This is not a 100% comprehensive check, but it
compares the release or template against a "known good" index.
If you see errors or issues here, consider deleting and re-bootstrapping
the release or template .
If you see errors or issues here, consider deleting and re-bootstrapping the
release or template .
.. code-block:: shell

3
docs/chapters/subcommands/zfs.rst
View File

@@ -1,7 +1,8 @@
zfs
===
Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for targeted jail(s).
Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for
targeted jail(s).
.. code-block:: shell

29
docs/chapters/targeting.rst
View File

@@ -4,15 +4,16 @@ Targeting
Bastille uses a ``subcommand TARGET ARGS`` syntax, meaning that each command
requires a target. Targets are usually containers, but can also be releases.
Targeting a container is done by providing the exact jail name, the JID of the jail, or by typing the
starting few characters of a jail. If more than one matching jail will be found, you will see a message
saying so.
Targeting a container is done by providing the exact jail name, the JID of the
jail, or by typing the starting few characters of a jail. If more than one
matching jail will be found, you will see a message saying so.
Targeting a release is done by providing the exact release name. (Note: do not
include the ``-pX`` point-release version.)
Bastille includes a pre-defined keyword [ALL|all] to target all running containers.
It is also possible to target multiple jails by grouping them in quotes, as seen below.
Bastille includes a pre-defined keyword [ALL|all] to target all running
containers. It is also possible to target multiple jails by grouping them in
quotes, as seen below.
.. code-block:: shell
@@ -57,12 +58,12 @@ Examples: Releases
ishmael ~ # bastille ...
+-----------+--------------+--------------+-------------------------------------------------------------+
| command | target | args | description |
+===========+==============+==============+=============================================================+
| bootstrap | 13.2-RELEASE | --- | bootstrap 13.2-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| update | 12.4-RELEASE | --- | update 12.4-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| verify | 12.4-RELEASE | --- | verify 12.4-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
+-----------+--------------+--------------+------------------------------------+
| command | target | args | description |
+===========+==============+==============+====================================+
| bootstrap | 13.2-RELEASE | --- | bootstrap 13.2-RELEASE release |
+-----------+--------------+--------------+------------------------------------+
| update | 12.4-RELEASE | --- | update 12.4-RELEASE release |
+-----------+--------------+--------------+------------------------------------+
| verify | 12.4-RELEASE | --- | verify 12.4-RELEASE release |
+-----------+--------------+--------------+------------------------------------+

69
docs/chapters/template.rst
View File

@@ -5,11 +5,12 @@ Looking for ready made CI/CD validated `Bastille Templates`_?
Bastille supports a templating system allowing you to apply files, pkgs and
execute commands inside the containers automatically.
Currently supported template hooks are: ``ARG``, ``CMD``, ``CONFIG``, ``CP``, ``INCLUDE``,
``LIMITS``, ``MOUNT``, ``OVERLAY``, ``PKG``, ``RDR``, ``RENDER``, ``RESTART``, ``SERVICE``, ``SYSRC``.
Currently supported template hooks are: ``ARG``, ``CMD``, ``CONFIG``, ``CP``,
``INCLUDE``, ``LIMITS``, ``MOUNT``, ``OVERLAY``, ``PKG``, ``RDR``, ``RENDER``,
``RESTART``, ``SERVICE``, ``SYSRC``.
Templates are created in ``${bastille_prefix}/templates`` and can leverage any of
the template hooks.
Templates are created in ``${bastille_prefix}/templates`` and can leverage any
of the template hooks.
Bastille 0.7.x+
---------------
@@ -59,8 +60,9 @@ Template Hook Descriptions
ARG - set an ARG value to be used in the template
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, the ``template`` command
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, the ``template`` command
will exit.
.. code-block:: shell
@@ -72,9 +74,11 @@ CMD - run the specified command
CONFIG - set the specified property and value
CP/OVERLAY - copy specified files from template directory to specified path inside jail
CP/OVERLAY - copy specified files from template directory to specified path
inside jail
INCLUDE - specify a template to include. Make sure the template is bootstrapped, or you are using the template url
INCLUDE - specify a template to include. Make sure the template is
bootstrapped, or you are using the template url
LIMITS - set the specified resource value for the jail
@@ -84,7 +88,9 @@ PKG - install specified packages inside jail
RDR - redirect specified ports to the jail
RENDER - replace ARG values inside specified files inside the jail. If a directory is specified, ARGS will be replaced in all files underneath
RENDER - replace ARG values inside specified files inside the jail. If a
directory is specified, ARGS will be replaced in all files
underneath
RESTART - restart the jail
@@ -95,21 +101,21 @@ SYSRC - run `sysrc` inside the jail with specified arguments
Special Hook Cases
------------------
SYSRC requires that NO quotes be used or that quotes (``"``) be escaped
ie; (``\\"``)
SYSRC requires that NO quotes be used or that quotes (``"``) be escaped ie;
(``\\"``)
ARG will always treat an ampersand "\``&``" literally, without the need to escape it.
Escaping it will cause errors.
ARG will always treat an ampersand "\``&``" literally, without the need to
escape it. Escaping it will cause errors.
Template Examples
-----------------
Place these uppercase template hook commands into a ``Bastillefile`` in any order
and automate container setup as needed.
Place these uppercase template hook commands into a ``Bastillefile`` in any
order and automate container setup as needed.
In addition to supporting template hooks, Bastille supports overlaying
files into the container. This is done by placing the files in their full path,
using the template directory as "/".
In addition to supporting template hooks, Bastille supports overlaying files
into the container. This is done by placing the files in their full path, using
the template directory as "/".
An example here may help. Think of ``bastille/templates/username/template``, our
example template, as the root of our filesystem overlay. If you create an
@@ -117,18 +123,18 @@ example template, as the root of our filesystem overlay. If you create an
can be overlayed into your container.
Note: due to the way FreeBSD segregates user-space, the majority of your
overlayed template files will be in ``/usr/local``. The few general
exceptions are the ``/etc/hosts``, ``/etc/resolv.conf``, and
``/etc/rc.conf.local``.
overlayed template files will be in ``/usr/local``. The few general exceptions
are the ``/etc/hosts``, ``/etc/resolv.conf``, and ``/etc/rc.conf.local``.
After populating ``/usr/local`` with custom config files that your container will
use, be sure to include ``/usr`` in the template OVERLAY definition. eg;
After populating ``/usr/local`` with custom config files that your container
will use, be sure to include ``/usr`` in the template OVERLAY definition. eg;
.. code-block:: shell
echo "CP /usr /" >> /usr/local/bastille/templates/username/template/Bastillefile
The above example ``/usr`` will include anything under ``/usr`` inside the template.
The above example ``/usr`` will include anything under ``/usr`` inside the
template.
You do not need to list individual files. Just include the top-level directory
name. List these top-level directories one per line.
@@ -200,7 +206,13 @@ directory names in the ``bastille/templates`` directory.
Using Ports in Templates
------------------------
Sometimes when you make a template you need special options for a package, or you need a newer version than what is in the pkgs. The solution for these cases, or a case like minecraft server that has NO compiled option, is to use the ports. A working example of this is the minecraft server template in the template repo. The main lines needed to use this is first to mount the ports directory, then compile the port. Below is an example of the minecraft template where this was used.
Sometimes when you make a template you need special options for a package, or
you need a newer version than what is in the pkgs. The solution for these
cases, or a case like minecraft server that has NO compiled option, is to use
the ports. A working example of this is the minecraft server template in the
template repo. The main lines needed to use this is first to mount the ports
directory, then compile the port. Below is an example of the minecraft template
where this was used.
.. code-block:: shell
@@ -224,8 +236,5 @@ Sometimes when you make a template you need special options for a package, or yo
SERVICE minecraft restart
RDR tcp 25565 25565
The MOUNT line mounts the ports directory, then the CMD make line makes the port. This can be modified to use any port in the port tree.
The MOUNT line mounts the ports directory, then the CMD make line makes the
port. This can be modified to use any port in the port tree.

71
docs/chapters/upgrading.rst
View File

@@ -3,7 +3,10 @@ Upgrading
This document outlines updating and upgrading jails hosted by Bastille.
Bastille can "bootstrap" multiple versions of FreeBSD to be used by jails. All jails do not NEED to be the same version (even if they often are), the only requirement here is that the "bootstrapped" versions are less than or equal to the host version of FreeBSD.
Bastille can "bootstrap" multiple versions of FreeBSD to be used by jails. All
jails do not NEED to be the same version (even if they often are), the only
requirement here is that the "bootstrapped" versions are less than or equal to
the host version of FreeBSD.
To keep releases updated, use ``bastille update RELEASE``
@@ -13,26 +16,33 @@ To keep thick jails updated, use ``bastille update TARGET``
Minor Release Upgrades
----------------------
To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the following:
To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the
following:
Thick Jails
-----------
1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE
1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to
13.2-RELEASE
2. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates
3. Reboot the jail ``bastille restart TARGET``
4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade
4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the
upgrade
5. Upgrade complete!
Thin Jails
----------
1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE``
1. Ensure the new release version is bootstrapped and updated to the latest
patch release: ``bastille bootstrap 13.2-RELEASE``
2. Update the release: ``bastille update 13.2-RELEASE``
3. Stop the jail(s) that need to be updated.
4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the mount points to 13.2-RELEASE
5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for 13.2-RELEASE
6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents of /etc for 13.2-RELEASE
4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the
mount points to 13.2-RELEASE
5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for
13.2-RELEASE
6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents
of /etc for 13.2-RELEASE
7. Use ``bastille etcupdate TARGET resolve`` to resolve any conflicts
8. Start the jail(s)
9. Upgrade complete!
@@ -41,36 +51,46 @@ Thin Jails
Major Release Upgrades
----------------------
To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the following:
To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the
following:
Thick Jails
-----------
1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE
1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to
13.2-RELEASE
2. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates
3. Reboot the jail ``bastille restart TARGET``
4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade
5. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the
upgrade
5. Force the reinstallation or upgrade of all installed packages (ABI change):
``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
6. Upgrade complete!
Thin Jails
----------
1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE``
1. Ensure the new release version is bootstrapped and updated to the latest
patch release: ``bastille bootstrap 13.2-RELEASE``
2. Update the release: ``bastille update 13.2-RELEASE``
3. Stop the jail(s) that need to be updated.
4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the mount points to 13.2-RELEASE
5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for 13.2-RELEASE
6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents of /etc for 13.2-RELEASE
4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the
mount points to 13.2-RELEASE
5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for
13.2-RELEASE
6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents
of /etc for 13.2-RELEASE
7. Use ``bastille etcupdate TARGET resolve`` to resolve any conflicts
8. Start the jail(s)
9. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
9. Force the reinstallation or upgrade of all installed packages (ABI change):
``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
10. Upgrade complete!
----------------------------------
Revert Upgrade / Downgrade Process
----------------------------------
The downgrade process (not usually needed) is similar to the upgrade process only in reverse.
The downgrade process (not usually needed) is similar to the upgrade process
only in reverse.
Thick Jails
-----------
@@ -80,20 +100,25 @@ Thick jails should not be downgraded and is not supported in general on FreeBSD.
Thin Jails
----------
Not recommended, but you can run ``bastille upgrade TARGET 13.1-RELEASE`` to downgrade a thin jail.
Make sure to run ``bastille etcupdate TARGET update 13.1-RELEASE`` to keep the contents of /etc updated with each release.
Not recommended, but you can run ``bastille upgrade TARGET 13.1-RELEASE`` to
downgrade a thin jail. Make sure to run ``bastille etcupdate TARGET update
13.1-RELEASE`` to keep the contents of /etc updated with each release.
The pkg reinstallation will also need to be repeated after the jail restarts on the previous release.
The pkg reinstallation will also need to be repeated after the jail restarts on
the previous release.
------------
Old Releases
------------
After upgrading all jails from one release to the next you may find that you now have bootstrapped a release that is no longer used. Once you've decided that you no longer need the option to revert the change you can destroy the old release.
After upgrading all jails from one release to the next you may find that you now
have bootstrapped a release that is no longer used. Once you've decided that you
no longer need the option to revert the change you can destroy the old release.
``bastille list releases`` to list all bootstrapped releases.
``bastille destroy X.Y-RELEASE`` to fully delete the release, including the cache.
``bastille destroy X.Y-RELEASE`` to fully delete the release, including the
cache.
``bastille destroy [-c|--no-cache] X.Y-RELEASE`` to retain the cache directory.

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

@@ -4,14 +4,22 @@ ZFS Support
:width: 400
:alt: Alternative text
Bastille 0.4 added initial support for ZFS. ``bastille bootstrap`` and ``bastille create`` will generate ZFS volumes based on settings found in the ``bastille.conf``. This section outlines how to enable and configure Bastille for ZFS. As of Bastille 0.13 you no longer need to do these steps manually. The setup program when you run:
Bastille 0.4 added initial support for ZFS. ``bastille bootstrap`` and
``bastille create`` will generate ZFS volumes based on settings found in the
``bastille.conf``. This section outlines how to enable and configure Bastille
for ZFS. As of Bastille 0.13 you no longer need to do these steps manually. The
setup program when you run:
.. code-block:: shell
bastille setup
will create the zfs settings for you IF you are running zfs. This section is left in the documents for historical purposes, and so you can understand what the setup program is doing AND so if you need to tweak your settings for some reason.
will create the zfs settings for you IF you are running zfs. This section is
left in the documents for historical purposes, and so you can understand what
the setup program is doing AND so if you need to tweak your settings for some
reason.
Two values are required for Bastille to use ZFS. The default values in the ``bastille.conf`` are NO and empty. Populate these two to enable ZFS.
Two values are required for Bastille to use ZFS. The default values in the
``bastille.conf`` are NO and empty. Populate these two to enable ZFS.
.. code-block:: shell
@@ -28,11 +36,15 @@ Example
ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_enable=YES
ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_zpool=ZPOOL_NAME
Replace ``ZPOOL_NAME`` with the zpool you want Bastille to use. Tip: ``zpool list`` and ``zpool status`` will help.
If you get 'no pools available' you are likely not using ZFS and can safely ignore these settings.
Replace ``ZPOOL_NAME`` with the zpool you want Bastille to use. Tip: ``zpool
list`` and ``zpool status`` will help.
If you get 'no pools available' you are likely not using ZFS and can safely
ignore these settings.
By default, bastille will use ``ZPOOL_NAME/bastille`` as its working zfs dataset. If you want it to use a specific dataset
on your pool, set ``bastille_zfs_prefix`` to the dataset you want bastille to use. DO NOT include the pool name.
By default, bastille will use ``ZPOOL_NAME/bastille`` as its working zfs
dataset. If you want it to use a specific dataset
on your pool, set ``bastille_zfs_prefix`` to the dataset you want bastille to
use. DO NOT include the pool name.
Example
@@ -40,7 +52,9 @@ Example
ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_prefix=apps/bastille
The above example will set ``ZPOOL_NAME/apps/bastille`` as the working zfs dataset for bastille.
The above example will set ``ZPOOL_NAME/apps/bastille`` as the working zfs
dataset for bastille.
Bastille will mount the datasets it creates at ``bastille_prefix`` which defaults to ``/usr/local/bastille``
Bastille will mount the datasets it creates at ``bastille_prefix`` which
defaults to ``/usr/local/bastille``
If this is not desirable, you can change it at the top of the config file.

4
docs/copyright.rst
View File

@@ -4,5 +4,5 @@ Copyright
This content is copyright Christer Edwards. All rights reserved.
Duplication of this content without the express written permission of the
author is not permitted.
Duplication of this content without the express written permission of the author
is not permitted.