diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml index 4851b20f..b706ca28 100644 --- a/.github/workflows/shellcheck.yml +++ b/.github/workflows/shellcheck.yml @@ -17,13 +17,18 @@ jobs: - name: Run ShellCheck uses: ludeeus/action-shellcheck@2.0.0 env: - # Excluding SC3043: In POSIX sh, 'local' is undefined. Ignoring because local is a built-in command in FreeBSD - # Excluding SC2154: Variable is referenced but not assigned. Because we include files in the scripts - # Excluding SC3037: In POSIX sh, echo flags are undefined. Ignoring temporarily until we decide to keep it or - # use printf instead - # Excluding SC2155: Declare and assign separately to avoid masking return values. - # Excluding SC2124: Assigning an array to a string! Check instead if this is a false positive or if there is - # a better way to do it. + # Excluding SC3043: In POSIX sh, 'local' is undefined. Ignoring + # because local is a built-in command in FreeBSD + # Excluding SC2154: Variable is referenced but not assigned. Because + # we include files in the scripts + # Excluding SC3037: In POSIX sh, echo flags are undefined. Ignoring + # temporarily until we decide to keep it or use + # printf instead + # Excluding SC2155: Declare and assign separately to avoid masking + # return values. + # Excluding SC2124: Assigning an array to a string! Check instead if + # this is a false positive or if there is a better + # way to do it. SHELLCHECK_OPTS: -e SC3043 -e SC2154 -e SC3037 -e SC2155 -e SC2124 with: severity: warning diff --git a/README.md b/README.md index 813b1b10..38952224 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ Use "bastille [-c|--config FILE] command" to specify a non-default config file. ``` -## 0.13-beta +## 0.14-beta This document outlines the basic usage of the Bastille container management framework. This release is still considered beta. diff --git a/docs/chapters/boot-and-priority.rst b/docs/chapters/boot-and-priority.rst new file mode 100644 index 00000000..713170aa --- /dev/null +++ b/docs/chapters/boot-and-priority.rst @@ -0,0 +1,46 @@ +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. + +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. + +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]``. + +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. + +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``. + +This value will be shown using ``bastille list all``. diff --git a/docs/chapters/configuration.rst b/docs/chapters/configuration.rst index 1249c822..57c3d255 100644 --- a/docs/chapters/configuration.rst +++ b/docs/chapters/configuration.rst @@ -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 will be asked if you want to copy the sample config file to this location. The default 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,24 +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. -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. +The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at +``/usr/local/etc/bastille`` or it will not work. -1. Run Bastille using `bastille --config /path/to/config.conf bootstrap 14.2-RELEASE` to bootstrap the release using the new config. +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. -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... +1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE`` + to bootstrap the release using the new config. -- 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. +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... -- 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. +- 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 do set the `BASTILLE_CONFIG` variable, you do not need to specify the config file when running Bastille as that specified user. +- 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. diff --git a/docs/chapters/gcp.rst b/docs/chapters/gcp.rst index b049337b..c6fb5e72 100644 --- a/docs/chapters/gcp.rst +++ b/docs/chapters/gcp.rst @@ -10,9 +10,11 @@ Bastille VNET runs on GCP with a few small tweaks. In summary, they are: ## 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 +41,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 +52,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 +72,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 metric 0 mtu 1460 @@ -83,11 +88,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`` diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst index 2d776fac..4645c7bc 100644 --- a/docs/chapters/gettingstarted.rst +++ b/docs/chapters/gettingstarted.rst @@ -1,34 +1,42 @@ 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. +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 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 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 `-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. @@ -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 @@ -84,4 +95,4 @@ Then we can create our linux jail using this release. This will take a while... .. code-block:: shell - ishmael ~ # bastille create -L linuxjail bionic 10.1.1.7/24 vtnet0 + ishmael ~ # bastille create -L linux_jail bionic 10.1.1.7/24 vtnet0 diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index c083919f..4f3122da 100644 --- a/docs/chapters/installation.rst +++ b/docs/chapters/installation.rst @@ -1,10 +1,10 @@ Installation ============ Bastille is available in the official FreeBSD ports tree at -`sysutils/bastille`. Binary packages are available in `quarterly` and `latest` +``sysutils/bastille``. Binary packages are available in quarterly and latest repositories. -Current version is `0.13.20250126`. +Current version is ``0.14.20250420``. To install from the FreeBSD package repository: @@ -18,9 +18,7 @@ pkg .. code-block:: shell pkg install bastille - sysrc bastille_enable=YES - sysrc bastille_rcorder=YES - + bastille setup To install from source (don't worry, no compiling): @@ -30,9 +28,7 @@ ports .. code-block:: shell make -C /usr/ports/sysutils/bastille install clean - sysrc bastille_enable=YES - sysrc bastille_rcorder=YES - + bastille setup git --- @@ -42,14 +38,13 @@ git git clone https://github.com/BastilleBSD/bastille.git cd bastille make install - sysrc bastille_enable=YES - sysrc bastille_rcorder=YES + bastille setup 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 `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; -`/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. diff --git a/docs/chapters/jail-config.rst b/docs/chapters/jail-config.rst index bdc9b1a6..8b15029b 100644 --- a/docs/chapters/jail-config.rst +++ b/docs/chapters/jail-config.rst @@ -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 diff --git a/docs/chapters/migration.rst b/docs/chapters/migration.rst index 5e5c4c76..8fd05f4f 100644 --- a/docs/chapters/migration.rst +++ b/docs/chapters/migration.rst @@ -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. diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 520b936e..b877130b 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -96,8 +132,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. @@ -107,11 +143,12 @@ interface and a free IP on your local network. Shared Interface on IPV6 network (vultr.com) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some ISP's, such as `Vultr `_, give you a single ipv4 address, +Some ISP's, such as `Vultr `_, 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 @@ -131,7 +168,7 @@ The `vultr ipv6 subnet calculator `_ 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, @@ -146,10 +183,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) @@ -157,11 +194,11 @@ 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 +To create a VNET based container use the ``-V`` option, an IP/netmask and external interface. .. code-block:: shell @@ -170,13 +207,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 @@ -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 @@ -197,7 +234,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 @@ -221,7 +258,45 @@ Below is the definition of what these three parameters are used for and mean: net.link.bridge.pfil_bridge Set to 1 to enable filtering on the bridge interface, set to 0 to disable it. - +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: + +.. 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). + +.. 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: + +.. 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. + +.. 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. + +.. code-block:: shell + cloned_interfaces="bridge0" + ifconfig_bridge0_name="bastille0bridge" + ifconfig_bastille0bridge="addm vtnet0 up" + Regarding Routes ---------------- @@ -229,7 +304,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 +312,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 +325,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 @@ -264,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 @@ -275,9 +351,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 +403,9 @@ 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 +414,15 @@ to containers are: nat on $ext_if from 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 @@ -376,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: @@ -387,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. diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst index 39a3606b..5a6c0fb2 100644 --- a/docs/chapters/subcommands/bootstrap.rst +++ b/docs/chapters/subcommands/bootstrap.rst @@ -1,17 +1,16 @@ 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 +In this document we will describe using the ``bootstrap`` sub-command with both releases and templates. We begin with releases. Releases @@ -20,7 +19,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 +27,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 +36,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,9 +58,9 @@ 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 -immediately after the bootstrap, effectively bootstrapping and applying +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. Notes @@ -71,11 +70,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 +110,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 +118,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. diff --git a/docs/chapters/subcommands/clone.rst b/docs/chapters/subcommands/clone.rst index c433f3ca..50defd8d 100644 --- a/docs/chapters/subcommands/clone.rst +++ b/docs/chapters/subcommands/clone.rst @@ -1,8 +1,8 @@ clone ===== -To clone a container and make a duplicate, use the `bastille clone` -sub-command.. +To clone a container and make a duplicate, use the ``bastille clone`` +sub-command. .. code-block:: shell diff --git a/docs/chapters/subcommands/cmd.rst b/docs/chapters/subcommands/cmd.rst index d6b95e01..f4f6fcd3 100644 --- a/docs/chapters/subcommands/cmd.rst +++ b/docs/chapters/subcommands/cmd.rst @@ -15,7 +15,7 @@ Execute commands inside targeted jail(s). .. code-block:: shell ishmael ~ # bastille cmd help - Usage: bastille cmd [option(s)] TARGET command" + Usage: bastille cmd [option(s)] TARGET command Options: -a | --auto Auto mode. Start/stop jail(s) if required. diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst index d25e1a3b..3e5276f9 100644 --- a/docs/chapters/subcommands/console.rst +++ b/docs/chapters/subcommands/console.rst @@ -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,14 +10,15 @@ 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. .. 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. diff --git a/docs/chapters/subcommands/convert.rst b/docs/chapters/subcommands/convert.rst index b2f35093..8a4d6638 100644 --- a/docs/chapters/subcommands/convert.rst +++ b/docs/chapters/subcommands/convert.rst @@ -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. diff --git a/docs/chapters/subcommands/cp.rst b/docs/chapters/subcommands/cp.rst index 5496e526..afd7d1cd 100644 --- a/docs/chapters/subcommands/cp.rst +++ b/docs/chapters/subcommands/cp.rst @@ -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 diff --git a/docs/chapters/subcommands/create.rst b/docs/chapters/subcommands/create.rst index d577c7e0..c12db4ba 100644 --- a/docs/chapters/subcommands/create.rst +++ b/docs/chapters/subcommands/create.rst @@ -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,38 +23,36 @@ 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 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 +62,10 @@ 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. - diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst index e3e49133..f263ce7d 100644 --- a/docs/chapters/subcommands/destroy.rst +++ b/docs/chapters/subcommands/destroy.rst @@ -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 releas 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 @@ -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. diff --git a/docs/chapters/subcommands/edit.rst b/docs/chapters/subcommands/edit.rst index a29f5f6c..c059f1c8 100644 --- a/docs/chapters/subcommands/edit.rst +++ b/docs/chapters/subcommands/edit.rst @@ -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: diff --git a/docs/chapters/subcommands/etcupdate.rst b/docs/chapters/subcommands/etcupdate.rst index 4d21f3f2..03a71414 100644 --- a/docs/chapters/subcommands/etcupdate.rst +++ b/docs/chapters/subcommands/etcupdate.rst @@ -1,9 +1,10 @@ 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 +16,21 @@ 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. +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 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 diff --git a/docs/chapters/subcommands/export.rst b/docs/chapters/subcommands/export.rst index 848c1026..506638a4 100644 --- a/docs/chapters/subcommands/export.rst +++ b/docs/chapters/subcommands/export.rst @@ -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. diff --git a/docs/chapters/subcommands/htop.rst b/docs/chapters/subcommands/htop.rst index eef6ef56..afd1d7f7 100644 --- a/docs/chapters/subcommands/htop.rst +++ b/docs/chapters/subcommands/htop.rst @@ -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 diff --git a/docs/chapters/subcommands/import.rst b/docs/chapters/subcommands/import.rst index 85100f01..c6c48e21 100644 --- a/docs/chapters/subcommands/import.rst +++ b/docs/chapters/subcommands/import.rst @@ -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. \ No newline at end of file diff --git a/docs/chapters/subcommands/index.rst b/docs/chapters/subcommands/index.rst index 7ea0739b..1f2ac3cf 100644 --- a/docs/chapters/subcommands/index.rst +++ b/docs/chapters/subcommands/index.rst @@ -6,8 +6,8 @@ Bastille sub-commands :caption: Contents: bootstrap - clone cmd + clone config console convert diff --git a/docs/chapters/subcommands/jcp.rst b/docs/chapters/subcommands/jcp.rst index 6035d370..37486a71 100644 --- a/docs/chapters/subcommands/jcp.rst +++ b/docs/chapters/subcommands/jcp.rst @@ -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 diff --git a/docs/chapters/subcommands/limits.rst b/docs/chapters/subcommands/limits.rst index 33f66d63..015fa149 100644 --- a/docs/chapters/subcommands/limits.rst +++ b/docs/chapters/subcommands/limits.rst @@ -3,18 +3,18 @@ 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" diff --git a/docs/chapters/subcommands/list.rst b/docs/chapters/subcommands/list.rst index 82b78f12..860647bc 100644 --- a/docs/chapters/subcommands/list.rst +++ b/docs/chapters/subcommands/list.rst @@ -1,13 +1,16 @@ 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. diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst index c3e643c3..dd5bf73b 100644 --- a/docs/chapters/subcommands/mount.rst +++ b/docs/chapters/subcommands/mount.rst @@ -1,23 +1,28 @@ 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 + ishmael ~ # bastille mount azkaban tmpfs tmp tmpfs rw,nosuid,mode=01777 0 0 Detected advanced mount type tmpfs [azkaban]: Added: tmpfs /usr/local/bastille/jails/azkaban/root/tmp tmpfs rw,nosuid,mode=01777 0 0 +Example: Mount a nullfs filesystem + .. code-block:: shell ishmael ~ # bastille mount azkaban /storage/foo media/foo nullfs ro 0 0 @@ -27,11 +32,16 @@ Example: Mount a tmpfs filesystem with options. [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 @@ -42,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 @@ -51,3 +63,12 @@ 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 + +.. 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. diff --git a/docs/chapters/subcommands/network.rst b/docs/chapters/subcommands/network.rst index 13c4bb55..33af0767 100644 --- a/docs/chapters/subcommands/network.rst +++ b/docs/chapters/subcommands/network.rst @@ -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 diff --git a/docs/chapters/subcommands/pkg.rst b/docs/chapters/subcommands/pkg.rst index bd999227..d27badd7 100644 --- a/docs/chapters/subcommands/pkg.rst +++ b/docs/chapters/subcommands/pkg.rst @@ -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 @@ -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. diff --git a/docs/chapters/subcommands/rcp.rst b/docs/chapters/subcommands/rcp.rst index c01bcc90..ffd8d934 100644 --- a/docs/chapters/subcommands/rcp.rst +++ b/docs/chapters/subcommands/rcp.rst @@ -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 diff --git a/docs/chapters/subcommands/rdr.rst b/docs/chapters/subcommands/rdr.rst index e5ca6bc2..9298b09d 100644 --- a/docs/chapters/subcommands/rdr.rst +++ b/docs/chapters/subcommands/rdr.rst @@ -1,14 +1,14 @@ 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). +``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 -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 @@ -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 diff --git a/docs/chapters/subcommands/rename.rst b/docs/chapters/subcommands/rename.rst index ccd812a7..d823c5b8 100644 --- a/docs/chapters/subcommands/rename.rst +++ b/docs/chapters/subcommands/rename.rst @@ -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: diff --git a/docs/chapters/subcommands/restart.rst b/docs/chapters/subcommands/restart.rst index 2f6bf52a..fe78b3ae 100644 --- a/docs/chapters/subcommands/restart.rst +++ b/docs/chapters/subcommands/restart.rst @@ -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 (seconds) to wait after starting/stopping jail(s). + -v | --verbose Print every action on jail start. + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/service.rst b/docs/chapters/subcommands/service.rst index 1f67a045..458006de 100644 --- a/docs/chapters/subcommands/service.rst +++ b/docs/chapters/subcommands/service.rst @@ -1,9 +1,9 @@ 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). +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). .. code-block:: shell diff --git a/docs/chapters/subcommands/setup.rst b/docs/chapters/subcommands/setup.rst index 39a2a09f..76f668b1 100644 --- a/docs/chapters/subcommands/setup.rst +++ b/docs/chapters/subcommands/setup.rst @@ -1,9 +1,9 @@ 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. +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. .. code-block:: shell diff --git a/docs/chapters/subcommands/start.rst b/docs/chapters/subcommands/start.rst index 6f1ddfc6..54be65bc 100644 --- a/docs/chapters/subcommands/start.rst +++ b/docs/chapters/subcommands/start.rst @@ -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 (seconds) to wait after starting jail(s). + -v | --verbose Print every action on jail start. + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/stop.rst b/docs/chapters/subcommands/stop.rst index 4642d035..4a9ff050 100644 --- a/docs/chapters/subcommands/stop.rst +++ b/docs/chapters/subcommands/stop.rst @@ -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 (seconds) to wait after stopping jail(s). + -v | --verbose Print every action on jail stop. + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/sysrc.rst b/docs/chapters/subcommands/sysrc.rst index 9aa21871..04a875f3 100644 --- a/docs/chapters/subcommands/sysrc.rst +++ b/docs/chapters/subcommands/sysrc.rst @@ -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. diff --git a/docs/chapters/subcommands/tags.rst b/docs/chapters/subcommands/tags.rst index 96adf7da..45b62bd6 100644 --- a/docs/chapters/subcommands/tags.rst +++ b/docs/chapters/subcommands/tags.rst @@ -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. diff --git a/docs/chapters/subcommands/template.rst b/docs/chapters/subcommands/template.rst index 425b928c..c79bcc87 100644 --- a/docs/chapters/subcommands/template.rst +++ b/docs/chapters/subcommands/template.rst @@ -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 diff --git a/docs/chapters/subcommands/top.rst b/docs/chapters/subcommands/top.rst index 3e65815d..97d35b38 100644 --- a/docs/chapters/subcommands/top.rst +++ b/docs/chapters/subcommands/top.rst @@ -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 diff --git a/docs/chapters/subcommands/umount.rst b/docs/chapters/subcommands/umount.rst index 849d4f53..c65c4a00 100644 --- a/docs/chapters/subcommands/umount.rst +++ b/docs/chapters/subcommands/umount.rst @@ -1,7 +1,7 @@ umount ====== -To unmount storage from a container use `bastille umount`. +Unmount storage from jail(s). .. code-block:: shell @@ -18,10 +18,20 @@ 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 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. \ No newline at end of file diff --git a/docs/chapters/subcommands/update.rst b/docs/chapters/subcommands/update.rst index 259813fa..4f418c87 100644 --- a/docs/chapters/subcommands/update.rst +++ b/docs/chapters/subcommands/update.rst @@ -1,9 +1,9 @@ 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. +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. If no updates are available, a message will be shown: @@ -38,5 +38,15 @@ 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 + + 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. diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst index daebb503..afeedf13 100644 --- a/docs/chapters/subcommands/upgrade.rst +++ b/docs/chapters/subcommands/upgrade.rst @@ -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 diff --git a/docs/chapters/subcommands/verify.rst b/docs/chapters/subcommands/verify.rst index fe5b3cd7..e33178d4 100644 --- a/docs/chapters/subcommands/verify.rst +++ b/docs/chapters/subcommands/verify.rst @@ -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 @@ -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. diff --git a/docs/chapters/subcommands/zfs.rst b/docs/chapters/subcommands/zfs.rst index d2388f1d..063a4513 100644 --- a/docs/chapters/subcommands/zfs.rst +++ b/docs/chapters/subcommands/zfs.rst @@ -1,13 +1,13 @@ 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 ishmael ~ # bastille zfs help Usage: bastille zfs TARGET [set|get|snap|destroy_snap|df|usage] [key=value|date] - Options: -x | --debug Enable debug mode. diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index 63df3575..4073e377 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -1,25 +1,26 @@ Targeting ========= -Bastille uses a `command target arguments` syntax, meaning that each command +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.) +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 ishmael ~ # bastille cmd "jail1 jail2 jail3" echo Hello! Examples: Containers -==================== +-------------------- .. code-block:: shell @@ -51,18 +52,18 @@ Examples: Containers Examples: Releases -================== +------------------ .. code-block:: shell 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 | ++-----------+--------------+--------------+------------------------------------+ diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index a2a317cf..417f4105 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -5,18 +5,19 @@ 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+ --------------- 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 +60,10 @@ 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 @@ -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,40 +101,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. -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 +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 +143,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 @@ -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. diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index 0ae3fc0c..a30a718a 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -1,80 +1,96 @@ -========= Upgrading ========= -This document outlines upgrading jails hosted using 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. +This document outlines updating and upgrading jails hosted by Bastille. -To keep releases updated, use `bastille update RELEASE` +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 thick jails updated, use `bastille update TARGET` +To keep releases updated, use ``bastille update RELEASE`` + +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. 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. 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. 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 resolve`` to resolve any conflicts +8. Start the jail(s) +9. Upgrade complete! ---------------------- 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. 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. 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``) +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` -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 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``) +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 ----------- @@ -84,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 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. diff --git a/docs/chapters/usage.rst b/docs/chapters/usage.rst index c9c5c6f0..2086d6db 100644 --- a/docs/chapters/usage.rst +++ b/docs/chapters/usage.rst @@ -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). diff --git a/docs/chapters/zfs-support.rst b/docs/chapters/zfs-support.rst index 52a0c7d7..b00fcf62 100644 --- a/docs/chapters/zfs-support.rst +++ b/docs/chapters/zfs-support.rst @@ -4,14 +4,27 @@ 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. +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: -Two values are required for Bastille to use ZFS. The default values in the ``bastille.conf`` are empty. Populate these two to enable ZFS. +.. 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. + +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 ## ZFS options - bastille_zfs_enable="" ## default: "" + bastille_zfs_enable="" ## default: "NO" bastille_zfs_zpool="" ## default: "" bastille_zfs_prefix="bastille" ## default: "${bastille_zfs_zpool}/bastille" bastille_zfs_options="-o compress=lz4 -o atime=off" ## default: "-o compress=lz4 -o atime=off" @@ -23,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 @@ -35,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. diff --git a/docs/conf.py b/docs/conf.py index c2f36b89..7ae699bd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,9 +12,9 @@ copyright = '2018-2025, Christer Edwards' author = 'Christer Edwards' # The short X.Y version -version = '0.13.20250126' +version = '0.14.20250420' # The full version, including alpha/beta/rc tags -release = '0.13.20250126-beta' +release = '0.14.20250420-beta' # -- General configuration --------------------------------------------------- diff --git a/docs/copyright.rst b/docs/copyright.rst index 88f1804c..56c367e9 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -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. diff --git a/docs/index.rst b/docs/index.rst index b0aaff65..29611ede 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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``. diff --git a/usr/local/bin/bastille b/usr/local/bin/bastille index 1d94bb1a..715cadfe 100755 --- a/usr/local/bin/bastille +++ b/usr/local/bin/bastille @@ -32,7 +32,7 @@ PATH=${PATH}:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin -BASTILLE_VERSION=904f855 +BASTILLE_VERSION="0.14.20250420" ## check for config existence bastille_conf_check() { @@ -91,8 +91,8 @@ Available Commands: export Exports a specified container. help Help about any command. htop Interactive process viewer (requires htop). - jcp cp(1) files from a jail to jail(s). import Import a specified container. + jcp cp(1) files from a jail to 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). @@ -129,16 +129,16 @@ bastille_conf_check bastille_perms_check if [ -z "${BASTILLE_CONFIG}" ]; then - BASTILLE_CONFIG=/usr/local/etc/bastille/bastille.conf - export BASTILLE_CONFIG -elif [ -r "${BASTILLE_CONFIG}" ]; then - export BASTILLE_CONFIG -elif [ -r "/usr/local/etc/bastille/${BASTILLE_CONFIG}" ]; then - BASTILLE_CONFIG="/usr/local/etc/bastille/${BASTILLE_CONFIG}" - export BASTILLE_CONFIG -else - echo "Not a valid config file: ${BASTILLE_CONFIG}" - exit 1 + if [ -z "${BASTILLE_CONFIG}" ]; then + BASTILLE_CONFIG=/usr/local/etc/bastille/bastille.conf + export BASTILLE_CONFIG + elif [ -r "/usr/local/etc/bastille/${BASTILLE_CONFIG}" ]; then + BASTILLE_CONFIG="/usr/local/etc/bastille/${BASTILLE_CONFIG}" + export BASTILLE_CONFIG + else + echo "Not a valid config file: ${BASTILLE_CONFIG}" + exit 1 + fi fi # Load common.sh after setting BASTILLE_CONFIG @@ -157,10 +157,7 @@ while [ "$#" -gt 0 ]; do ;; -c|--config) BASTILLE_CONFIG="${2}" - if [ -r "${BASTILLE_CONFIG}" ]; then - info "Using custom config: ${BASTILLE_CONFIG}" - export BASTILLE_CONFIG - elif [ -r "/usr/local/etc/bastille/${BASTILLE_CONFIG}" ]; then + if [ -r "/usr/local/etc/bastille/${BASTILLE_CONFIG}" ]; then BASTILLE_CONFIG="/usr/local/etc/bastille/${BASTILLE_CONFIG}" info "Using custom config: ${BASTILLE_CONFIG}" export BASTILLE_CONFIG @@ -207,8 +204,9 @@ case "${CMD}" in edit| \ export| \ htop| \ - jcp | \ import| \ + jcp| \ + limits| \ list| \ network| \ rcp| \ diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index 8315dd33..cb24c9fa 100644 --- a/usr/local/share/bastille/clone.sh +++ b/usr/local/share/bastille/clone.sh @@ -112,6 +112,8 @@ validate_ip() { if [ -n "${ip6}" ]; then info "Valid: (${ip6})." IP6_MODE="new" + elif { [ "${IP}" = "0.0.0.0" ] || [ "${IP}" = "DHCP" ]; } && [ "$(bastille config ${TARGET} get vnet)" = "enabled" ]; then + info "Valid: (${IP})." else local IFS if echo "${IP}" | grep -Eq '^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])(\/([0-9]|[1-2][0-9]|3[0-2]))?$'; then @@ -195,14 +197,13 @@ update_jailconf_vnet() { # Determine number of interfaces and define a uniq_epair local _if_list="$(grep -Eo 'epair[0-9]+|bastille[0-9]+' ${_jail_conf} | sort -u)" for _if in ${_if_list}; do - local _epair_if_count="$( (grep -Eo 'epair[0-9]+' ${bastille_jailsdir}/*/jail.conf; ifconfig | grep -Eo '(e[0-9]+a|epair[0-9]+a)' ) | sort -u | wc -l | awk '{print $1}')" - local _bastille_if_count="$(grep -Eo 'bastille[0-9]+' ${bastille_jailsdir}/*/jail.conf | sort -u | wc -l | awk '{print $1}')" - local epair_num_range=$((_epair_if_count + 1)) - local bastille_num_range=$((_bastille_if_count + 1)) + # Get number of epairs on the system + get_epair_count + local _epair_num_range=$((_epair_count + 1)) if echo ${_if} | grep -Eoq 'epair[0-9]+'; then # Update bridged VNET config - for _num in $(seq 0 "${epair_num_range}"); do - if ! grep -Eoq "epair${_num}" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eoq "(e${_num}a|epair${_num}a)"; then + for _num in $(seq 0 "${_epair_num_range}"); do + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then # Generate new epair name if [ "$(echo -n "e${_num}a_${NEWNAME}" | awk '{print length}')" -lt 16 ]; then local _new_host_epair="e${_num}a_${NEWNAME}" @@ -270,8 +271,8 @@ update_jailconf_vnet() { done elif echo ${_if} | grep -Eoq 'bastille[0-9]+'; then # Update VNET config - for _num in $(seq 0 "${bastille_num_range}"); do - if ! grep -oq "bastille${_num}" ${bastille_jailsdir}/*/jail.conf; then + for _num in $(seq 0 "${_epair_num_range}"); do + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then # Update jail.conf epair name local uniq_epair="bastille${_num}" local _jail_vnet="$(grep ${_if} "${_rc_conf}" | grep -Eo -m 1 "vnet[0-9]+")" diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 0f4cb57f..a5430a5a 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -118,6 +118,16 @@ check_target_is_stopped() { fi } +get_epair_count() { + for _config in /usr/local/etc/bastille/*.conf; do + local bastille_jailsdir="$(sysrc -f "${_config}" -n bastille_jailsdir)" + _epair_list="$(printf '%s\n%s' "$( (grep -Ehos '(epair[0-9]+|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair | grep -Eos "_bastille[0-9]+$"; ifconfig -g epair | grep -vs 'bastille' | grep -Eos 'e[0-9]+a_') | grep -Eos '[0-9]+')" "${_epair_list}")" + done + _epair_count=$(printf '%s' "${_epair_list}" | sort -u | wc -l | awk '{print $1}') + export _epair_list + export _epair_count +} + get_jail_name() { local _JID="${1}" local _jailname="$(jls -j ${_JID} name 2>/dev/null)" @@ -277,17 +287,13 @@ generate_vnet_jail_netblock() { local use_unique_bridge="${2}" local external_interface="${3}" local static_mac="${4}" - ## determine number of interfaces + 1 - ## iterate num and grep all jail configs - ## define uniq_epair - local _epair_if_count="$( (grep -Eos 'epair[0-9]+' ${bastille_jailsdir}/*/jail.conf; ifconfig | grep -Eo '(e[0-9]+a|epair[0-9]+a)' ) | sort -u | wc -l | awk '{print $1}')" - local _bastille_if_count="$(grep -Eos 'bastille[0-9]+' ${bastille_jailsdir}/*/jail.conf | sort -u | wc -l | awk '{print $1}')" - local epair_num_range=$((_epair_if_count + 1)) - local bastille_num_range=$((_bastille_if_count + 1)) + # Get number of epairs on the system + get_epair_count + local _epair_num_range=$((_epair_count + 1)) if [ -n "${use_unique_bridge}" ]; then - if [ "${_epair_if_count}" -gt 0 ]; then - for _num in $(seq 0 "${epair_num_range}"); do - if ! grep -Eosq "epair${_num}" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a)"; then + if [ "${_epair_count}" -gt 0 ]; then + for _num in $(seq 0 "${_epair_num_range}"); do + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then if [ "$(echo -n "e${_num}a_${jail_name}" | awk '{print length}')" -lt 16 ]; then local host_epair=e${_num}a_${jail_name} local jail_epair=e${_num}b_${jail_name} @@ -310,9 +316,9 @@ generate_vnet_jail_netblock() { fi fi else - if [ "${_bastille_if_count}" -gt 0 ]; then - for _num in $(seq 0 "${bastille_num_range}"); do - if ! grep -Eosq "bastille${_num}" ${bastille_jailsdir}/*/jail.conf; then + if [ "${_epair_count}" -gt 0 ]; then + for _num in $(seq 0 "${_epair_num_range}"); do + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then local uniq_epair="bastille${_num}" break fi diff --git a/usr/local/share/bastille/create.sh b/usr/local/share/bastille/create.sh index 4e5f5186..5c0cf31a 100644 --- a/usr/local/share/bastille/create.sh +++ b/usr/local/share/bastille/create.sh @@ -47,7 +47,7 @@ usage() { -M | --static-mac Generate a static MAC address for jail (VNET only). --no-boot Create jail with boot=off. --no-validate Do not validate the release when creating the jail. - -p | --priority VALUE Sets the priority value for jail startup and shutdown. + -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). @@ -92,10 +92,9 @@ validate_ip() { done if ifconfig | grep -qwF "${TEST_IP}"; then warn "Warning: IP address already in use (${TEST_IP})." - else - ipx_addr="ip4.addr" - info "Valid: (${_ip})." fi + ipx_addr="ip4.addr" + info "Valid: (${_ip})." else error_continue "Invalid: (${_ip})." fi @@ -810,6 +809,17 @@ if [ -n "${NAME}" ]; then validate_name fi +# Validate interface type +if [ -n "${VNET_JAIL}" ] && [ -n "${VNET_JAIL_BRIDGE}" ]; then + if ! ifconfig -g bridge | grep -owq "${INTERFACE}"; then + error_exit "Interface is not a bridge: ${INTERFACE}" + fi +elif [ -n "${VNET_JAIL}" ] && [ -z "${VNET_JAIL_BRIDGE}" ]; then + if ifconfig -g bridge | grep -owq "${INTERFACE}"; then + error_exit "Interface is a bridge: ${INTERFACE}" + fi +fi + if [ -n "${LINUX_JAIL}" ] && [ -n "${VALIDATE_RELEASE}" ]; then case "${RELEASE}" in bionic|ubuntu_bionic|ubuntu|ubuntu-bionic) diff --git a/usr/local/share/bastille/destroy.sh b/usr/local/share/bastille/destroy.sh index f5c5ae4c..f81df036 100644 --- a/usr/local/share/bastille/destroy.sh +++ b/usr/local/share/bastille/destroy.sh @@ -48,16 +48,16 @@ EOF destroy_jail() { - local OPTIONS + local OPTIONS for _jail in ${JAILS}; do - + bastille_jail_base="${bastille_jailsdir}/${_jail}" ## dir bastille_jail_log="${bastille_logsdir}/${_jail}_console.log" ## file - + check_target_is_stopped "${_jail}" || if [ "${AUTO}" -eq 1 ]; then bastille stop "${_jail}" - else + else error_notify "Jail is running." error_continue "Use [-a|--auto] to auto-stop the jail." fi @@ -77,8 +77,12 @@ destroy_jail() { if [ "${FORCE}" = "1" ]; then OPTIONS="-rf" fi - ## remove jail zfs dataset recursively - zfs destroy "${OPTIONS}" "${bastille_zfs_zpool}/${bastille_zfs_prefix}/jails/${_jail}" + # Remove jail zfs dataset recursively, or abort if error thus precerving jail content. + # This will deal with the common "cannot unmount 'XYZ': pool or dataset is busy" + # unless the force option is defined by the user, otherwise will have a partially deleted jail. + if ! zfs destroy "${OPTIONS}" "${bastille_zfs_zpool}/${bastille_zfs_prefix}/jails/${_jail}"; then + error_exit "Jail dataset(s) appears to be busy, exiting." + fi fi fi fi @@ -86,7 +90,7 @@ destroy_jail() { if [ -d "${bastille_jail_base}" ]; then ## removing all flags chflags -R noschg "${bastille_jail_base}" - + ## remove jail base rm -rf "${bastille_jail_base}" fi @@ -110,7 +114,7 @@ destroy_jail() { pfctl -a "rdr/${_jail}" -Fn fi fi - done + done } destroy_rel() { @@ -198,18 +202,18 @@ destroy_rel() { } # Handle options. -AUTO=0 -FORCE=0 -NO_CACHE=0 +AUTO="0" +FORCE="0" +NO_CACHE="0" while [ "$#" -gt 0 ]; do case "${1}" in - -h|--help|help) - usage - ;; + -h|--help|help) + usage + ;; -a|--auto) - AUTO=1 - shift - ;; + AUTO=1 + shift + ;; -c|--no-cache) NO_CACHE=1 shift @@ -226,10 +230,10 @@ while [ "$#" -gt 0 ]; do for _opt in $(echo ${1} | sed 's/-//g' | fold -w1); do case ${_opt} in a) AUTO=1 ;; - c) NO_CACHE=1 ;; + c) NO_CACHE=1 ;; f) FORCE=1 ;; x) enable_debug ;; - *) error_exit "Unknown Option: \"${1}\"" ;; + *) error_exit "Unknown Option: \"${1}\"" ;; esac done shift diff --git a/usr/local/share/bastille/htop.sh b/usr/local/share/bastille/htop.sh index fe2607d0..6aeaa3cf 100644 --- a/usr/local/share/bastille/htop.sh +++ b/usr/local/share/bastille/htop.sh @@ -94,6 +94,6 @@ fi if [ ! -x "${bastille_jailsdir}/${TARGET}/root/usr/local/bin/htop" ]; then error_notify "htop not found on ${TARGET}." -elif [ -x "${bastille_jail_path}/usr/local/bin/htop" ]; then +elif [ -x "${bastille_jailsdir}/${TARGET}/root/usr/local/bin/htop" ]; then jexec -l ${TARGET} /usr/local/bin/htop fi diff --git a/usr/local/share/bastille/list.sh b/usr/local/share/bastille/list.sh index 94d436d1..22f81f3f 100644 --- a/usr/local/share/bastille/list.sh +++ b/usr/local/share/bastille/list.sh @@ -119,10 +119,11 @@ list_all(){ else JAIL_STATE=$(if [ "$(sed -n "/^${JAIL_NAME} {$/,/^}$/p" "${bastille_jailsdir}/${JAIL_NAME}/jail.conf" 2> /dev/null | awk '$0 ~ /^'${JAIL_NAME}' \{|\}/ { printf "%s",$0 }')" = "${JAIL_NAME} {}" ]; then echo "Down"; else echo "n/a"; fi) if [ "$(awk '$1 == "vnet;" { print $1 }' "${bastille_jailsdir}/${JAIL_NAME}/jail.conf" 2> /dev/null)" ]; then - JAIL_IP=$(grep -E "^ifconfig_vnet.*inet.*" "${bastille_jailsdir}/${JAIL_NAME}/root/etc/rc.conf" 2> /dev/null | grep -o "inet.*" | awk '{print $2}' | sed -E 's#/[0-9]+$##g') + JAIL_IP=$(grep -E "^ifconfig_vnet.*inet.*" "${bastille_jailsdir}/${JAIL_NAME}/root/etc/rc.conf" 2> /dev/null | grep -o "inet.*" | awk '{print $2}' | sed -E 's#/[0-9]+.*##g') else - JAIL_IP=$(sed -n "s/^[ ]*ip[4,6].addr[ ]*=[ ]*\(.*\);$/\1/p" "${bastille_jailsdir}/${JAIL_NAME}/jail.conf" 2> /dev/null | sed "s/\// /g" | awk '{ print $1 }') - fi + JAIL_IP=$(bastille config ${JAIL_NAME} get ip4.addr | sed 's/,/\n/g') + if [ "${JAIL_IP}" = "not set" ]; then JAIL_IP=$(bastille config ${JAIL_NAME} get ip6.addr | sed 's/,/\n/g'); fi + fi JAIL_HOSTNAME=$(sed -n "s/^[ ]*host.hostname[ ]*=[ ]*\(.*\);$/\1/p" "${bastille_jailsdir}/${JAIL_NAME}/jail.conf" 2> /dev/null) if [ -f "${bastille_jailsdir}/${JAIL_NAME}/rdr.conf" ]; then JAIL_PORTS=$(awk '$1 ~ /^[tcp|udp]/ { printf "%s/%s:%s,",$1,$2,$3 }' "${bastille_jailsdir}/${JAIL_NAME}/rdr.conf" 2> /dev/null | sed "s/,$//"); else JAIL_PORTS=""; fi JAIL_PATH=$(sed -n "s/^[ ]*path[ ]*=[ ]*\(.*\);$/\1/p" "${bastille_jailsdir}/${JAIL_NAME}/jail.conf" 2> /dev/null) @@ -164,14 +165,14 @@ list_all(){ # 10.10.10.11 # 10.10.10.12 FIRST_IP="$(echo "${JAIL_IP}" | head -n 1)" - if echo "${FIRST_IP}" | grep -q "|"; then FIRST_IP=$(echo ${FIRST_IP} | awk -F"|" '{print $2}'); fi + if echo "${FIRST_IP}" | grep -q "|"; then FIRST_IP=$(echo ${FIRST_IP} | awk -F"|" '{print $2}' | sed 's#/.*##g'); fi printf " ${JID}%*s${BOOT}%*s${PRIORITY}%*s${JAIL_STATE}%*s${FIRST_IP}%*s${JAIL_PORTS}%*s${JAIL_HOSTNAME}%*s${JAIL_RELEASE}%*s${JAIL_PATH}\n" "$((${MAX_LENGTH_JID} - ${#JID} + ${SPACER}))" "" "$((4 - ${#BOOT} + ${SPACER}))" "" "$((4 - ${#PRIORITY} + ${SPACER}))" "" "$((5 - ${#JAIL_STATE} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_IP} - ${#FIRST_IP} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_PORTS} - ${#JAIL_PORTS} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_HOSTNAME} - ${#JAIL_HOSTNAME} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_RELEASE} - ${#JAIL_RELEASE} + ${SPACER}))" "" for IP in $(echo "${JAIL_IP}" | tail -n +2); do if echo "${IP}" | grep -q "|"; then IP=$(echo ${IP} | awk -F"|" '{print $2}'); fi printf "%*s%*s%*s%*s ${IP}\n" "$((${MAX_LENGTH_JID} + ${SPACER}))" "" "$((4 + ${SPACER}))" "" "$((4 + ${SPACER}))" "" "$((5 + ${SPACER}))" "" done else - if echo "${JAIL_IP}" | grep -q "|"; then JAIL_IP="$(echo ${JAIL_IP} | awk -F"|" '{print $2}')"; fi + if echo "${JAIL_IP}" | grep -q "|"; then JAIL_IP="$(echo ${JAIL_IP} | awk -F"|" '{print $2}' | sed 's#/.*##g')"; fi printf " ${JID}%*s${BOOT}%*s${PRIORITY}%*s${JAIL_STATE}%*s${JAIL_IP}%*s${JAIL_PORTS}%*s${JAIL_HOSTNAME}%*s${JAIL_RELEASE}%*s${JAIL_PATH}\n" "$((${MAX_LENGTH_JID} - ${#JID} + ${SPACER}))" "" "$((4 - ${#BOOT} + ${SPACER}))" "" "$((4 - ${#PRIORITY} + ${SPACER}))" "" "$((5 - ${#JAIL_STATE} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_IP} - ${#JAIL_IP} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_PORTS} - ${#JAIL_PORTS} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_HOSTNAME} - ${#JAIL_HOSTNAME} + ${SPACER}))" "" "$((${MAX_LENGTH_JAIL_RELEASE} - ${#JAIL_RELEASE} + ${SPACER}))" "" fi fi diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index 54d52738..92bef8a1 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -1,5 +1,7 @@ #!/bin/sh # +# SPDX-License-Identifier: BSD-3-Clause +# # Copyright (c) 2018-2025, Christer Edwards # All rights reserved. # @@ -231,16 +233,15 @@ add_interface() { local _ip="${3}" local _jail_config="${bastille_jailsdir}/${_jailname}/jail.conf" local _jail_rc_config="${bastille_jailsdir}/${_jailname}/root/etc/rc.conf" - local _epair_if_count="$( (grep -Eos 'epair[0-9]+' ${bastille_jailsdir}/*/jail.conf; ifconfig | grep -Eo '(e[0-9]+a|epair[0-9]+a)' ) | sort -u | wc -l | awk '{print $1}')" - local _bastille_if_count="$(grep -Eos 'bastille[0-9]+' ${bastille_jailsdir}/*/jail.conf | sort -u | wc -l | awk '{print $1}')" + # Get number of epairs on the system + get_epair_count local _vnet_if_count="$(grep -Eo 'vnet[1-9]+' ${_jail_rc_config} | sort -u | wc -l | awk '{print $1}')" local _if_vnet="vnet$((_vnet_if_count + 1))" - local epair_num_range=$((_epair_if_count + 1)) - local bastille_num_range=$((_bastille_if_count + 1)) + local _epair_num_range=$((_epair_count + 1)) if [ "${BRIDGE}" -eq 1 ]; then - if [ "${_epair_if_count}" -gt 0 ]; then - for _num in $(seq 0 "${epair_num_range}"); do - if ! grep -Eosq "epair${_num}" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a)"; then + if [ "${_epair_count}" -gt 0 ]; then + for _num in $(seq 0 "${_epair_num_range}"); do + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then if [ "$(echo -n "e${_num}a_${jail_name}" | awk '{print length}')" -lt 16 ]; then local host_epair=e${_num}a_${_jailname} local jail_epair=e${_num}b_${_jailname} @@ -312,8 +313,8 @@ EOF echo "Added interface: \"${_if}\"" elif [ "${VNET}" -eq 1 ]; then - for _num in $(seq 0 "${bastille_num_range}"); do - if ! grep -Eq "bastille${_num}" "${bastille_jailsdir}"/*/jail.conf; then + for _num in $(seq 0 "${_epair_num_range}"); do + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then local bastille_epair="bastille${_num}" break fi diff --git a/usr/local/share/bastille/restart.sh b/usr/local/share/bastille/restart.sh index ebc70dd7..895313f5 100644 --- a/usr/local/share/bastille/restart.sh +++ b/usr/local/share/bastille/restart.sh @@ -36,7 +36,7 @@ usage() { Options: -b | --boot Respect jail boot setting. - -d | --delay VALUE Time to wait between starting/stopping each jail. + -d | --delay VALUE Time (seconds) to wait after starting/stopping jail(s). -v | --verbose Print every action on jail start. -x | --debug Enable debug mode. diff --git a/usr/local/share/bastille/setup.sh b/usr/local/share/bastille/setup.sh index 71b9d1c0..8cedee2d 100644 --- a/usr/local/share/bastille/setup.sh +++ b/usr/local/share/bastille/setup.sh @@ -117,11 +117,11 @@ configure_zfs() { bastille_zroot=$(zpool list | grep -v NAME | awk '{print $1}') if [ "$(echo "${bastille_zroot}" | wc -l)" -gt 1 ]; then error_notify "Error: Multiple ZFS pools available:\n${bastille_zroot}" - error_notify "Set desired pool using \"sysrc -f ${bastille_config} bastille_zfs_zpool=ZPOOL_NAME\"" - error_exit "Don't forget to also enable ZFS using \"sysrc -f ${bastille_config} bastille_zfs_enable=YES\"" + error_notify "Set desired pool using \"sysrc -f ${BASTILLE_CONFIG} bastille_zfs_zpool=ZPOOL_NAME\"" + error_exit "Don't forget to also enable ZFS using \"sysrc -f ${BASTILLE_CONFIG} bastille_zfs_enable=YES\"" fi - sysrc -f "${bastille_config}" bastille_zfs_enable=YES - sysrc -f "${bastille_config}" bastille_zfs_zpool="${bastille_zroot}" + sysrc -f "${BASTILLE_CONFIG}" bastille_zfs_enable=YES + sysrc -f "${BASTILLE_CONFIG}" bastille_zfs_zpool="${bastille_zroot}" fi } @@ -141,11 +141,6 @@ help|-h|--help) pf|firewall) configure_pf ;; -bastille0) - # TODO remove in future release 0.13 - warn "'bastille setup bastille0' will be deprecated in the next 0.13 version." - configure_network - ;; network|loopback) configure_network ;; diff --git a/usr/local/share/bastille/start.sh b/usr/local/share/bastille/start.sh index 44f518b8..93413eb2 100644 --- a/usr/local/share/bastille/start.sh +++ b/usr/local/share/bastille/start.sh @@ -38,7 +38,7 @@ usage() { Options: -b | --boot Respect jail boot setting. - -d | --delay VALUE Time to wait between starting each jail. + -d | --delay VALUE Time (seconds) to wait after starting jail(s). -v | --verbose Print every action on jail start. -x | --debug Enable debug mode. diff --git a/usr/local/share/bastille/stop.sh b/usr/local/share/bastille/stop.sh index d0d080a6..fa84d00b 100644 --- a/usr/local/share/bastille/stop.sh +++ b/usr/local/share/bastille/stop.sh @@ -38,7 +38,7 @@ usage() { Options: -b | --boot Respect jail boot setting. - -d | --delay VALUE Time to wait between stopping each jail. + -d | --delay VALUE Time (seconds) to wait after stopping jail(s). -v | --verbose Print every action on jail stop. -x | --debug Enable debug mode.