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

docs: Once over error correction

Browse Source
This commit is contained in:
tschettervictor
2025-04-10 06:53:03 -06:00
parent fbb1c5367f
commit 37be5e52c8
48 changed files with 306 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/chapters/boot-and-priority.rst Normal file
View File

@@ -0,0 +1,26 @@
Boot and Priority
=================
Boot
----
The boot setting control whether a jail will be started on system startup if you have enabled bastille
with ``sysrc bastille_enable=YES``. You can also use ``bastille start -b TARGET`` to respect this boot setting.
If it is off, the jail(s) will not be started if ``-b`` is used with ``start/stop/restart`` or on system
startup. Jails will still shut down on system shutdown, regardless of this setting.
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 also be changed using ``bastille config TARGET boot [on|off]``.
Priority
--------
The priority value determines in what order commands are executed. This also controls in what order jails are started
and stopped.
When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on
creation. See ``bastille create -p 90 TARGET...``.
This value can also be changed using ``bastille config TARGET priority VALUE``.

18
docs/chapters/configuration.rst
View File

@@ -1,8 +1,8 @@
Configuration
=============
Bastille is configured using a default config file located at `/usr/local/etc/bastille/bastille.conf`. When first installing
bastille, you will be asked if you want to copy the sample config file to this location. The default are sensible for UFS, but
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,9 +83,9 @@ 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
--------------------
@@ -95,12 +95,12 @@ jails at different locations based on your needs.
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 /path/to/config.conf bootstrap 14.2-RELEASE` to bootstrap the release using the new config.
1. Run Bastille using ``bastille --config /path/to/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=/path/to/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=/path/to/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.

18
docs/chapters/gettingstarted.rst
View File

@@ -4,7 +4,7 @@ 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.
The first step is running `bastille setup` to try to configure bastille initially.
The first step is running ``bastille setup`` to try to configure bastille initially.
.. code-block:: shell
@@ -20,15 +20,15 @@ Next we can create our first jail. Bastille can create a few different types of
* 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 independant of the release. Created with `-T`.
* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independant 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 `-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 `-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 `-L`.
* Linux jails are jails that run linux. Created with ``bastille create -L``.
Only clone, thin, and thick jails can be created with `-V` `-B` and `-M`.
Only clone, thin, and thick jails can be created with ``-V`` ``-B`` and ``-M``.
We will focus on thin jails for the guide.
@@ -41,7 +41,7 @@ Classic/Standard Jail
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`
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.
@@ -55,8 +55,8 @@ 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

8
docs/chapters/installation.rst
View File

@@ -1,10 +1,10 @@
Installation
============
Bastille is available in the official FreeBSD ports tree at
:code:`sysutils/bastille`. Binary packages are available in quarterly and latest
``sysutils/bastille``. Binary packages are available in quarterly and latest
repositories.
Current version is :code:`0.13.20250126`.
Current version is ``0.13.20250126``.
To install from the FreeBSD package repository:
@@ -42,9 +42,9 @@ git
This method will install the latest files from GitHub directly onto your
system. It is verbose about the files it installs (for later removal), and also
has a :code:`make uninstall` target. You may need to manually copy the sample
has a ``make uninstall`` target. You may need to manually copy the sample
config into place before Bastille will run. (ie;
:code:`/usr/local/etc/bastille/bastille.conf.sample`)
``/usr/local/etc/bastille/bastille.conf.sample``)
Note: installing using this method overwrites the version variable to match
that of the source revision commit hash.

17
docs/chapters/jail-config.rst
View File

@@ -8,7 +8,7 @@ In this section we'll look at the default config for a new container. The
defaults are sane for most applications, but if you want to tweak the settings
here they are.
A `jail.conf` template is used each time a new container is created. This
A ``jail.conf`` template is used each time a new container is created. This
template looks like this:
.. code-block:: shell
@@ -27,7 +27,7 @@ template looks like this:
path = /usr/local/bastille/jails/{name}/root;
securelevel = 2;
ip4.addr = x.x.x.x;
ip4.addr = interface|x.x.x.x;
ip6 = disable;
}
@@ -122,17 +122,6 @@ host.hostname
host.domainname, host.hostuuid and host.hostid.
interface
---------
.. code-block:: shell
interface
A network interface to add the jail's IP addresses (ip4.addr and
ip6.addr) to. An alias for each address will be added to the
interface before the jail is created, and will be removed from
the interface after the jail is removed.
mount.devfs
-----------
.. code-block:: shell
@@ -165,7 +154,7 @@ path
securelevel
-----------
By default, Bastille containers run at `securelevel = 2;`. See below for the
By default, Bastille containers run at ``securelevel = 2;``. See below for the
implications of kernel security levels and when they might be altered.
Note: Bastille does not currently have any mechanism to automagically change

4
docs/chapters/migration.rst
View File

@@ -31,11 +31,11 @@ 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.

72
docs/chapters/networking.rst
View File

@@ -12,17 +12,17 @@ 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.
@@ -33,24 +33,24 @@ Bastille also supports IPv6. Instead of an IPv4 address, you can specify and IPv
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.
* 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.
* 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
-----------------
@@ -72,12 +72,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
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.
test with ``wget/curl/fetch`` instead.
Shared Interface on Home or Small Office Network
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -96,8 +96,8 @@ unique private ip address, and attach its ip address to your primary interface.
You may have to change em0
When the `alcatraz` container is started it will add `192.168.1.50` as an IP
alias to the `em0` interface. It will then simply be another member of the
When the ``alcatraz`` container is started it will add ``192.168.1.50`` as an IP
alias to the ``em0`` interface. It will then simply be another member of the
hosts network. Other networked systems (firewall permitting) should be able to
reach services at that address.
@@ -111,7 +111,7 @@ 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.
On a virtual machine such as vultr.com the virtual interface may be `vtnet0`.
On a virtual machine such as vultr.com the virtual interface may be ``vtnet0``.
So we issue the command:
.. code-block:: shell
@@ -146,10 +146,10 @@ freebsd with the following command
At that point your container can talk to the world, and the world can ping your
container. Of course when you reboot the machine, that command will be
forgotten. To make it permanent, prefix the same command with `sysrc`
forgotten. To make it permanent, prefix the same command with ``sysrc``
Just remember you cannot ping out from the container. Instead, install and
use `wget`/`curl`/`fetch` to test the connectivity.
use ``wget/curl/fetch`` to test the connectivity.
Virtual Network (VNET)
@@ -161,7 +161,7 @@ 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
To create a VNET based container use the ``-V`` option, an IP/netmask and
external interface.
.. code-block:: shell
@@ -170,13 +170,13 @@ external interface.
Bastille will automagically create the bridge interface and connect /
disconnect containers as they are started and stopped. A new interface will be
created on the host matching the pattern `interface0bridge`. In the example
here, `em0bridge`.
created on the host matching the pattern ``interface0bridge``. In the example
here, ``em0bridge``.
The `em0` interface will be attached to the bridge along with the unique
The ``em0`` interface will be attached to the bridge along with the unique
container interfaces as they are started and stopped. These interface names
match the pattern `eXb_bastilleX`. Internally to the containers these
interfaces are presented as `vnet0`.
match the pattern ``eXb_bastilleX``. Internally to the containers these
interfaces are presented as ``vnet0``.
If you do not specify a subnet mask, you might have issues with jail to jail
networking, especially VLAN to VLAN. We recommend always adding a subnet to
@@ -197,7 +197,7 @@ host system:
add include $devfsrules_jail_vnet
add path 'bpf*' unhide
Lastly, you may want to consider these three `sysctl` values:
Lastly, you may want to consider these three ``sysctl`` values:
.. code-block:: shell
@@ -229,7 +229,7 @@ Bastille will attempt to auto-detect the default route from the host system and
assign it to the VNET container. This auto-detection may not always be accurate
for your needs for the particular container. In this case you'll need to add a
default route manually or define the preferred default route in the
`bastille.conf`.
``bastille.conf``.
.. code-block:: shell
@@ -237,7 +237,7 @@ default route manually or define the preferred default route in the
bastille service TARGET routing restart
To define a default route / gateway for all VNET containers define the value in
`bastille.conf`:
``bastille.conf``:
.. code-block:: shell
@@ -250,7 +250,7 @@ Virtual Network (VNET) on External Bridge
-----------------------------------------
To create a VNET based container and attach it to an external, already existing
bridge, use the `-B` option, an IP/netmask and external bridge.
bridge, use the ``-B`` option, an IP/netmask and external bridge.
.. code-block:: shell
@@ -275,9 +275,9 @@ network.
loopback (bastille0)
--------------------
What we recommend is creating a cloned loopback interface (`bastille0`) and
What we recommend is creating a cloned loopback interface (``bastille0``) and
assigning all the containers private (rfc1918) addresses on that interface. The
setup I develop on and use Bastille day-to-day uses the `10.0.0.0/8` address
setup I develop on and use Bastille day-to-day uses the ``10.0.0.0/8`` address
range. I have the ability to use whatever address I want within that range
because I've created my own private network. The host system then acts as the
firewall, permitting and denying traffic as needed.
@@ -327,8 +327,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 include the last line (`port ssh`) or you'll end up locked out.
- 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
to containers are:
@@ -337,15 +337,15 @@ to containers are:
nat on $ext_if from <jails> to any -> ($ext_if:0)
The `nat` routes traffic from the loopback interface to the external
The ``nat`` routes traffic from the loopback interface to the external
interface for outbound access.
.. code-block:: shell
rdr-anchor "rdr/*"
The `rdr-anchor "rdr/*"` enables dynamic rdr rules to be setup using the
`bastille rdr` command at runtime - eg.
The ``rdr-anchor "rdr/*"`` enables dynamic rdr rules to be setup using the
``bastille rdr`` command at runtime - eg.
.. code-block:: shell
@@ -389,4 +389,4 @@ To resolve this, add the following configuration to local_unbound:
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.
Adjust the above "access-control" strings to fit your network.

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

@@ -11,7 +11,7 @@ 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
In this document we will describe using the ``bootstrap`` sub-command with both
releases and templates. We begin with releases.
Releases
@@ -20,7 +20,7 @@ Releases
Example
^^^^^^^
To `bootstrap` a FreeBSD release, run the bootstrap sub-command with the
To ``bootstrap`` a FreeBSD release, run the bootstrap sub-command with the
release version as the argument.
.. code-block:: shell
@@ -28,7 +28,7 @@ release version as the argument.
ishmael ~ # bastille bootstrap 14.0-RELEASE [update]
ishmael ~ # bastille bootstrap 13.2-RELEASE [update]
To `bootstrap` a HardenedBSD release, run the bootstrap sub-command with the
To ``bootstrap`` a HardenedBSD release, run the bootstrap sub-command with the
build version as the argument.
.. code-block:: shell
@@ -37,7 +37,7 @@ build version as the argument.
This command will ensure the required directory structures are in place and
download the requested release. For each requested release, `bootstrap` will
download the requested release. For each requested release, ``bootstrap`` will
download the base.txz. These files are verified (sha256 via MANIFEST file)
before they are extracted for use.
@@ -59,8 +59,8 @@ releases from the FTP archive.
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
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
security patches and errata in one motion.
@@ -71,11 +71,11 @@ The bootstrap subcommand is generally only used once to prepare the system. The
only other use case for the bootstrap command is when a new FreeBSD version is
released and you want to start deploying containers on that version.
To update a release as patches are made available, see the `bastille update`
To update a release as patches are made available, see the ``bastille update``
command.
Downloaded artifacts are stored in the `bastille/cache/version` directory.
"bootstrapped" releases are stored in `bastille/releases/version`.
Downloaded artifacts are stored in the ``bastille/cache/version`` directory.
"bootstrapped" releases are stored in ``bastille/releases/version``.
To manually bootstrap a release (aka bring your own archive), place your
archive in bastille/cache/name and extract to bastille/releases/name. Your
@@ -111,7 +111,7 @@ Notes
If you don't want to bother with git to use templates you can create them
manually on the Bastille system and apply them.
Templates are stored in `bastille/templates/namespace/name`. If you'd like to
Templates are stored in ``bastille/templates/namespace/name``. If you'd like to
create a new template on your local system, simply create a new namespace
within the templates directory and then one for the template. This namespacing
allows users and groups to have templates without conflicting template names.
@@ -119,3 +119,11 @@ allows users and groups to have templates without conflicting template names.
Once you've created the directory structure you can begin filling it with
template hooks. Once you have a minimum number of hooks (at least one) you can
begin applying your template.
.. code-block:: shell
ishmael ~ # bastille bootstrap help
Usage: bastille bootstrap [option(s)] [RELEASE|TEMPLATE] [update|arch]
Options:
-x | --debug Enable debug mode.

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

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

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

@@ -15,8 +15,9 @@ container are limited to the container.
.. code-block:: shell
"Usage: bastille console [option(s)] TARGET [user]"
Options:
ishmael ~ # bastille console help
Usage: bastille console [option(s)] TARGET [user]
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.
-x | --debug Enable debug mode.

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

@@ -15,8 +15,7 @@ Syntax requires only the target jail to convert.
ishmael ~ # bastille convert help
Usage: bastille convert [option(s)] TARGET
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.
-x | --debug Enable debug mode.

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

@@ -19,7 +19,7 @@ This command allows copying files from host to jail(s).
[folsom]:
/tmp/resolv.conf-cf -> /usr/local/bastille/jails/folsom/root/etc/resolv.conf
Unless you see errors reported in the output the `cp` was successful.
Unless you see errors reported in the output the ``cp`` was successful.
.. code-block:: shell

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

@@ -55,9 +55,7 @@ the below help output.
.. code-block:: shell
ishmael ~ # bastille create help
Usage: bastille create [option(s)] NAME RELEASE IP_ADDRESS [interface]"
Options:
-B | --bridge Enables VNET, VNET containers are attached to a specified, already existing external bridge.
@@ -67,8 +65,11 @@ the below help output.
-L | --linux This option is intended for testing with Linux jails, this is considered experimental.
-M | --static-mac Generate a static MAC address for jail (VNET only).
--no-validate Do not validate the release when creating the jail.
--no-boot Create jail with boot=off.
-p | --priority VALUE Set priority value for jail.
-T | --thick Creates a thick container, they consume more space as they are self contained and independent.
-V | --vnet Enables VNET, VNET containers are attached to a virtual bridge interface for connectivity.
-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.

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

@@ -3,7 +3,7 @@ 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.
the ``-a|--auto`` option will automatically stop the jail before destroying it.
.. code-block:: shell
@@ -24,6 +24,6 @@ will retain the releas cache directory, if you choose to keep it.
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.
-f | --force Force unmount any mounted datasets when destroying a jail or release (ZFS only).
-c | --no-cache Do no destroy cache when destroying a release.
-f | --force Force unmount any mounted datasets when destroying a jail or release (ZFS only).
-x | --debug Enable debug mode.

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

@@ -1,19 +1,18 @@
edit
====
To edit a jails configuration, use `bastille edit TARGET`.
To edit a jails configuration, use ``bastille edit TARGET``.
.. code-block:: shell
ishmael ~ # bastille edit azkaban [filename]
Syntax requires a target an optional filename. By default the file edited will
be `jail.conf`. Other common filenames are `fstab` or `rctl.conf`.
be ``jail.conf``. Other common filenames are ``fstab`` or ``rctl.conf``.
.. code-block:: shell
ishmael ~ # bastille edit help
Usage: bastille edit [option(s)] TARGET [filename]
Options:

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

@@ -1,9 +1,9 @@
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.
First we need to bootstrap a release for ``etcupdate`` to use.
.. code-block:: shell
@@ -15,20 +15,20 @@ First we need to bootstrap a release for `etcupdate` to use.
Building tarball, please wait...
Etcupdate bootstrap complete: 14.1-RELEASE
Next we can use the `update` command to apply the update to the jail.
Next we can use the ``update`` command to apply the update to the jail.
.. code-block:: shell
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.
To automatically resolve the conflicts, run the ``resolve`` command.
.. code-block:: shell
ishmael ~ # bastille etcupdate ishmael resolve
To show only the differences between the releases, use the `diff` command.
To show only the differences between the releases, use the ``diff`` command.
.. code-block:: shell

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

@@ -10,7 +10,7 @@ container backups.
ishmael ~ # bastille export azkaban
The export sub-command supports both UFS and ZFS storage. ZFS based containers
will use ZFS snapshots. UFS based containers will use `txz` archives and they
will use ZFS snapshots. UFS based containers will use ``txz`` archives and they
can be exported only when the jail is not running.
.. code-block:: shell
@@ -21,6 +21,10 @@ Available options are:
.. code-block:: shell
ishmael ~ # bastille export help
Usage: bastille export [option(s)] TARGET PATH
Options:
--gz Export a ZFS jail using GZIP(.gz) compressed image.
-r | --raw Export a ZFS jail to an uncompressed RAW image.
-s | --safe Safely stop and start a ZFS jail before the exporting process.
@@ -28,3 +32,5 @@ Available options are:
--txz Export a jail using simple .txz compressed archive instead.
-v | --verbose Be more verbose during the ZFS send operation.
--xz Export a ZFS jail using XZ(.xz) compressed image.
Note: If no export option specified, the container should be redirected to standard output.

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

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

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

@@ -8,10 +8,19 @@ Import a container backup image or archive.
ishmael ~ # bastille import /path/to/archive.file
The import sub-command supports both UFS and ZFS storage. ZFS based containers
will use ZFS snapshots. UFS based containers will use `txz` archives.
will use ZFS snapshots. UFS based containers will use ``txz`` archives.
To import to a specified release, specify it as the last argument.
.. code-block:: shell
Usage: bastille import [option(s)] file [RELEASE]
ishmael ~ # bastille import help
Usage: bastille import [option(s)] FILE [RELEASE]
Options:
-f | --force Force an archive import regardless if the checksum file does not match or missing.
-M | --static-mac Generate static MAC for jail when importing foreign jails like iocage.
-v | --verbose Be more verbose during the ZFS receive operation.
-x | --debug Enable debug mode.
Tip: If no option specified, container should be imported from standard input.

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

@@ -17,7 +17,7 @@ This command allows copying files from jail to jail(s).
[folsom]:
/usr/local/bastille/jails/bastion/root/tmp/resolv.conf-cf -> /usr/local/bastille/jails/folsom/root/etc/resolv.conf
Unless you see errors reported in the output the `jcp` was successful.
Unless you see errors reported in the output the ``jcp`` was successful.
.. code-block:: shell

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

@@ -3,18 +3,17 @@ limits
Set resourse limits for targeted jail(s).
To add a limit, use `bastille limits TARGET add OPTION VALUE`
To add a limit, use ``bastille limits TARGET add OPTION VALUE``
To clear the limits from the system, use `bastille limits TARGET clear`
To clear the limits from the system, use ``bastille limits TARGET clear``
To clear the limits, and remove the rctl.conf, 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`
To remove a limit, use ``bastille limits TARGET remove OPTION``
.. code-block:: shell
ishmael ~ # bastille limits help
Usage: bastille limits [option(s)] TARGET [add OPTION VALUE|remove OPTION|clear|reset|[list|show] (active)|stats]
Example: bastille limits TARGET add memoryuse 1G"

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

@@ -1,13 +1,15 @@
list
====
List jails, ports, releases, templates, logs, limits managed by bastille.
List jails, ports, releases, templates, logs, limits, exports and imports managed by bastille.
.. code-block:: shell
ishmael ~ # bastille list help
Usage: bastille list [option(s)] [-j|-a] [RELEASE [-p] [template] [JAIL|CONTAINER] [log] [limit] [import] [export] [backup]"
Usage: bastille list [option(s)] [-j|-a] [RELEASE (-p)|template|jails|logs|limits|imports|exports|backups]
Options:
-a | --all List all jails, running and stopped, in BastilleBSD format.
-j | --json List jails in json format.
-x | --debug Enable debug mode.

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

@@ -1,15 +1,15 @@
mount
=====
To mount storage within the container use `bastille mount`.
To mount storage within the container use ``bastille mount``.
Syntax follows standard `/etc/fstab` format:
Syntax follows standard ``/etc/fstab`` format:
.. code-block:: shell
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.
.. code-block:: shell
@@ -50,4 +50,13 @@ It is possible to do the same for the jail path, but again, not recommemded.
ishmael ~ # bastille mount azkaban "/storage/my\ directory\ with\ spaces" /media/foo nullfs ro 0 0
[azkaban]:
Added: /storage/my\040directory\040with\040spaces /usr/local/bastille/jails/azkaban/root/media/foo nullfs ro 0 0
Add
.. code-block:: shell
ishmael ~ # bastille mount help
Usage: bastille mount [option(s)] TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number]
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.
-x | --debug Enable debug mode.

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

@@ -7,13 +7,13 @@ 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.
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
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...
``install``, ``update``, ``upgrade``, ``audit``, ``clean``, ``autoremove``, etc...
.. code-block:: shell
@@ -107,7 +107,7 @@ expectation is that you can fully leverage the pkg manager. This means,
.. code-block:: shell
ishmael ~ # bastille pkg help
Usage: bastille pkg [option(s)] TARGET COMMAND args
Usage: bastille pkg [option(s)] TARGET COMMAND ARGS
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.

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

@@ -9,7 +9,7 @@ This command allows copying files from jail to host.
[bastion]:
/usr/local/bastille/jails/bastion/root/test/testfile.txt -> /tmp/testfile.txt
Unless you see errors reported in the output the `rcp` was successful.
Unless you see errors reported in the output the ``rcp`` was successful.
.. code-block:: shell

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

@@ -1,9 +1,9 @@
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
``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).
Note: you need to be careful if host services are configured to run
@@ -30,7 +30,7 @@ specify the interface they run on in rc.conf (or other config files)
# bastille rdr dev1 clear
nat cleared
The `rdr` command includes 4 additional options:
The ``rdr`` command includes 4 additional options:
.. code-block:: shell
@@ -65,7 +65,7 @@ The `rdr` command includes 4 additional options:
The options can be used together, as seen above.
If you have multiple interfaces assigned to your jail, `bastille rdr` will
If you have multiple interfaces assigned to your jail, ``bastille rdr`` will
only redirect using the default one.
.. code-block:: shell

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

@@ -1,7 +1,7 @@
rename
======
Rename a container.
Rename a jail.
.. code-block:: shell
@@ -9,7 +9,7 @@ Rename a container.
.. code-block:: shell
ishmael ~ # bastille rename azkaban arkham
ishmael ~ # bastille rename help
Usage: bastille rename [option(s)] TARGET NEW_NAME
Options:

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

@@ -1,7 +1,7 @@
restart
=======
To restart a container you can use the `bastille restart` command.
Restart jail(s).
.. code-block:: shell
@@ -11,3 +11,14 @@ To restart a container you can use the `bastille restart` command.
[folsom]:
folsom: created
.. code-block:: shell
ishmael ~ # bastille restart help
Usage: bastille start [option(s)] TARGET
Options:
-b | --boot Respect jail boot setting.
-d | --delay VALUE Time to wait between starting each jail.
-v | --verbose Print every action on jail start.
-x | --debug Enable debug mode.

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

@@ -1,7 +1,7 @@
service
=======
The `service` sub-command allows for managing services within jails. This
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).

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

@@ -1,7 +1,7 @@
setup
=====
The `setup` sub-command attempts to automatically configure a host system for
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.

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

@@ -1,7 +1,7 @@
start
=====
To start a container you can use the `bastille start` command.
Start jail(s).
.. code-block:: shell
@@ -15,5 +15,7 @@ To start a container you can use the `bastille start` command.
Usage: bastille start [option(s)] TARGET
Options:
-v | --verbose Print every action on jail start.
-x | --debug Enable debug mode.
-b | --boot Respect jail boot setting.
-d | --delay VALUE Time to wait between starting each jail.
-v | --verbose Print every action on jail start.
-x | --debug Enable debug mode.

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

@@ -1,7 +1,7 @@
stop
====
To stop a container you can use the `bastille stop` command.
Stop jail(s).
.. code-block:: shell
@@ -15,5 +15,7 @@ To stop a container you can use the `bastille stop` command.
Usage: bastille stop [option(s)] TARGET
Options:
-v | --verbose Print every action on jail stop.
-x | --debug Enable debug mode.
-b | --boot Respect jail boot setting.
-d | --delay VALUE Time to wait between stopping each jail.
-v | --verbose Print every action on jail stop.
-x | --debug Enable debug mode.

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

@@ -1,7 +1,7 @@
sysrc
=====
The `sysrc` sub-command allows for safely editing system configuration files.
The ``sysrc`` sub-command allows for safely editing system configuration files.
In jail terms, this allows us to toggle on/off services and options at startup.
.. code-block:: shell
@@ -10,13 +10,12 @@ In jail terms, this allows us to toggle on/off services and options at startup.
[nginx]:
nginx_enable: NO -> YES
See `man sysrc(8)` for more info.
See ``man sysrc(8)`` for more info.
.. code-block:: shell
ishmael ~ # bastille sysrc help
Usage: bastille sysrc [option(s)] TARGET args
cat << EOF
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.

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

@@ -1,7 +1,7 @@
tags
====
The `tags` sub-command adds, removes or lists arbitrary tags on your jail(s).
The ``tags`` sub-command adds, removes or lists arbitrary tags on your jail(s).
.. code-block:: shell
@@ -14,9 +14,7 @@ The `tags` sub-command adds, removes or lists arbitrary tags on your jail(s).
.. code-block:: shell
ishmael ~ # bastille tags help
Usage: bastille tags TARGET [add|delete|list] [tag1,tag2]
Options:
-x | --debug Enable debug mode.

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

@@ -7,8 +7,8 @@ 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

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

@@ -1,7 +1,7 @@
top
===
This command runs `top` in the targeted jail.
This command runs ``top`` in the targeted jail.
.. image:: ../../images/top.png

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

@@ -1,7 +1,7 @@
umount
======
To unmount storage from a container use `bastille umount`.
Unmount storage from jail(s).
.. code-block:: shell
@@ -25,3 +25,12 @@ If the directory you are unmounting has spaces, make sure to escape them with a
ishmael ~ # bastille umount azkaban "/media/foo\ with\ spaces"
[azkaban]:
Unmounted: /usr/local/bastille/jails/jail4/root/media/foo with spaces
.. code-block:: shell
ishmael ~ # bastille umount help
Usage: bastille umount [option(s)] TARGET JAIL_PATH
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.
-x | --debug Enable debug mode.

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

@@ -1,7 +1,7 @@
update
======
The `update` command targets a release or a thick jail. Because thin jails are
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.
@@ -40,3 +40,13 @@ 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.
.. code-block:: shell
ishmael ~ # bastille update help
Usage: bastille update [option(s)] TARGET
Options:
-a | --auto Auto mode. Start/stop jail(s) if required.
-f | --force Force update a release.
-x | --debug Enable debug mode.

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

@@ -1,7 +1,7 @@
upgrade
=======
The `upgrade` command targets a thick or thin jail. Thin jails will be updated by changing the
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

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

@@ -35,9 +35,8 @@ the release or template .
.. code-block:: shell
ishmael ~ # bastille verify 11.2-RELEASE
ishmael ~ # bastille verify help
Usage: bastille verify [RELEASE|TEMPLATE]
Options:
-x | --debug Enable debug mode.

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

@@ -7,7 +7,6 @@ Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for targ
ishmael ~ # bastille zfs help
Usage: bastille zfs TARGET [set|get|snap|destroy_snap|df|usage] [key=value|date]
Options:
-x | --debug Enable debug mode.

6
docs/chapters/targeting.rst
View File

@@ -1,7 +1,7 @@
Targeting
=========
Bastille uses a `command target arguments` syntax, meaning that each command
Bastille uses a ``command 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
@@ -9,9 +9,9 @@ starting few characters of a jail. If more than one matching jail will be found,
saying so.
Targeting a release is done by providing the exact release name. (Note: do not
include the `-pX` point-release version.)
include the ``-pX`` point-release version.)
Bastille includes a pre-defined keyword [ALL|all} to target all running containers.
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

44
docs/chapters/template.rst
View File

@@ -5,10 +5,10 @@ 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
Templates are created in ``${bastille_prefix}/templates`` and can leverage any of
the template hooks.
Bastille 0.7.x+
@@ -16,7 +16,7 @@ Bastille 0.7.x+
Bastille 0.7.x introduces a template syntax that is more flexible and allows
any-order scripting. Previous versions had a hard template execution order and
instructions were spread across multiple files. The new syntax is done in a
`Bastillefile` and the template hook (see below) files are replaced with
``Bastillefile`` and the template hook (see below) files are replaced with
template hook commands.
Template Automation Hooks
@@ -59,9 +59,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
will show a warning, but will still continue.
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
@@ -95,40 +95,40 @@ 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.
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
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 "/".
An example here may help. Think of `bastille/templates/username/template`, our
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
`etc/hosts` or `etc/resolv.conf` *inside* the template directory, these
``/etc/hosts`` or ``/etc/resolv.conf`` *inside* the template directory, these
can be overlayed into your container.
Note: due to the way FreeBSD segregates user-space, the majority of your
overlayed template files will be in `usr/local`. The few general
exceptions are the `etc/hosts`, `etc/resolv.conf`, and
`etc/rc.conf.local`.
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
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.
@@ -137,9 +137,9 @@ Applying Templates
Containers must be running to apply templates.
Bastille includes a `template` command. This command requires a target and a
Bastille includes a ``template`` command. This command requires a target and a
template name. As covered in the previous section, template names correspond to
directory names in the `bastille/templates` directory.
directory names in the ``bastille/templates`` directory.
.. code-block:: shell

86
docs/chapters/upgrading.rst
View File

@@ -1,13 +1,13 @@
=========
Upgrading
=========
This document outlines upgrading jails hosted using Bastille.
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.
To keep releases updated, use `bastille update RELEASE`
To keep releases updated, use ``bastille update RELEASE``
To keep thick jails updated, use `bastille update TARGET`
To keep thick jails updated, use ``bastille update TARGET``
----------------------
Minor Release Upgrades
@@ -18,26 +18,26 @@ To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the f
Thick Jails
-----------
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. use `bastille upgrade TARGET 13.2-RELEASE` to upgrade the jail to 13.2-RELEASE
4. use `bastille upgrade TARGET 13.2-RELEASE update` to apply the updates
5. reboot the jail `bastille restart TARGET`
6. use `bastille upgrade TARGET 13.2-RELEASE update` to finish applying the upgrade
7. upgrade complete!
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. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE
4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates
5. Reboot the jail ``bastille restart TARGET``
6. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade
7. Upgrade complete!
Thin Jails
----------
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
7. use `bastille etcupdate TARGET reslove` to resolve any conflicts
8. start the jail(s)
8. upgrade complete!
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
7. Use ``bastille etcupdate TARGET reslove`` to resolve any conflicts
8. Start the jail(s)
9. Upgrade complete!
----------------------
Major Release Upgrades
@@ -48,28 +48,28 @@ To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the f
Thick Jails
-----------
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. use `bastille upgrade TARGET 13.2-RELEASE` to upgrade the jail to 13.2-RELEASE
4. use `bastille upgrade TARGET 13.2-RELEASE update` to apply the updates
5. reboot the jail `bastille restart TARGET`
6. use `bastille upgrade TARGET 13.2-RELEASE update` to finish applying the upgrade
7. force the reinstallation or upgrade of all installed packages (ABI change): `pkg upgrade -f` within each jail (or `bastille pkg ALL upgrade -f`)
8. upgrade complete!
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. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE
4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates
5. Reboot the jail ``bastille restart TARGET``
6. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade
7. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
8. Upgrade complete!
Thin Jails
----------
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
7. use `bastille etcupdate TARGET reslove` 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`)
10. upgrade complete!
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
7. Use ``bastille etcupdate TARGET reslove`` 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``)
10. Upgrade complete!
----------------------------------
Revert Upgrade / Downgrade Process
@@ -84,8 +84,8 @@ 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.
@@ -96,8 +96,8 @@ 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.
`bastille list releases` to list all bootstrapped releases.
``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.
``bastille destroy [-c|--no-cache] X.Y-RELEASE`` to retain the cache directory.

2
docs/chapters/usage.rst
View File

@@ -25,7 +25,7 @@ Usage
help Help about any command.
htop Interactive process viewer (requires htop).
import Import a specified container.
jcp cp(1) files from a jail to jail(s).
jcp cp(1) files from a jail to targeted jail(s).
limits Apply resources limits to targeted container(s). See rctl(8).
list List containers (running).
mount Mount a volume inside the targeted container(s).

3
docs/index.rst
View File

@@ -14,6 +14,7 @@ https://docs.bastillebsd.org.
chapters/installation
chapters/gettingstarted
chapters/configuration
chapters/boot-and-priority
chapters/upgrading
chapters/networking
chapters/usage
@@ -28,4 +29,4 @@ https://docs.bastillebsd.org.
copyright
Note: this documentation is included with the source code in `docs`.
Note: this documentation is included with the source code in ``docs``.