From fbb1c5367f64aa56012b5b1bc778b6b1f0fe7775 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 9 Apr 2025 17:36:16 -0600 Subject: [PATCH 01/63] Update installation.rst --- docs/chapters/installation.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index c083919f..4ed64a36 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` +:code:`sysutils/bastille`. Binary packages are available in quarterly and latest repositories. -Current version is `0.13.20250126`. +Current version is :code:`0.13.20250126`. To install from the FreeBSD package repository: @@ -19,8 +19,6 @@ pkg pkg install bastille sysrc bastille_enable=YES - sysrc bastille_rcorder=YES - To install from source (don't worry, no compiling): @@ -31,8 +29,6 @@ ports make -C /usr/ports/sysutils/bastille install clean sysrc bastille_enable=YES - sysrc bastille_rcorder=YES - git --- @@ -43,13 +39,12 @@ git cd bastille make install sysrc bastille_enable=YES - sysrc bastille_rcorder=YES 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 :code:`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`) +:code:`/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. From a71d55b15e3b8383adbfdc25ea1659fdb2bbfde2 Mon Sep 17 00:00:00 2001 From: JRGTH Date: Wed, 9 Apr 2025 19:51:54 -0400 Subject: [PATCH 02/63] Don't delete jail content on error, cleanup Don't delete jail content on busy datasets by default, cleanup. --- usr/local/share/bastille/destroy.sh | 42 ++++++++++++++++------------- 1 file changed, 23 insertions(+), 19 deletions(-) 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 From 37be5e52c88add568caea61c65bbf4c395838424 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 10 Apr 2025 06:53:03 -0600 Subject: [PATCH 03/63] docs: Once over error correction --- docs/chapters/boot-and-priority.rst | 26 ++++++++ docs/chapters/configuration.rst | 18 +++--- docs/chapters/gettingstarted.rst | 18 +++--- docs/chapters/installation.rst | 8 +-- docs/chapters/jail-config.rst | 17 +---- docs/chapters/migration.rst | 4 +- docs/chapters/networking.rst | 72 ++++++++++----------- docs/chapters/subcommands/bootstrap.rst | 28 +++++--- docs/chapters/subcommands/clone.rst | 2 +- docs/chapters/subcommands/console.rst | 5 +- docs/chapters/subcommands/convert.rst | 3 +- docs/chapters/subcommands/cp.rst | 2 +- docs/chapters/subcommands/create.rst | 5 +- docs/chapters/subcommands/destroy.rst | 4 +- docs/chapters/subcommands/edit.rst | 5 +- docs/chapters/subcommands/etcupdate.rst | 10 +-- docs/chapters/subcommands/export.rst | 8 ++- docs/chapters/subcommands/htop.rst | 2 +- docs/chapters/subcommands/import.rst | 13 +++- docs/chapters/subcommands/jcp.rst | 2 +- docs/chapters/subcommands/limits.rst | 9 ++- docs/chapters/subcommands/list.rst | 6 +- docs/chapters/subcommands/mount.rst | 17 +++-- docs/chapters/subcommands/network.rst | 8 +-- docs/chapters/subcommands/pkg.rst | 6 +- docs/chapters/subcommands/rcp.rst | 2 +- docs/chapters/subcommands/rdr.rst | 10 +-- docs/chapters/subcommands/rename.rst | 4 +- docs/chapters/subcommands/restart.rst | 13 +++- docs/chapters/subcommands/service.rst | 2 +- docs/chapters/subcommands/setup.rst | 2 +- docs/chapters/subcommands/start.rst | 8 ++- docs/chapters/subcommands/stop.rst | 8 ++- docs/chapters/subcommands/sysrc.rst | 5 +- docs/chapters/subcommands/tags.rst | 4 +- docs/chapters/subcommands/template.rst | 4 +- docs/chapters/subcommands/top.rst | 2 +- docs/chapters/subcommands/umount.rst | 11 +++- docs/chapters/subcommands/update.rst | 12 +++- docs/chapters/subcommands/upgrade.rst | 2 +- docs/chapters/subcommands/verify.rst | 3 +- docs/chapters/subcommands/zfs.rst | 1 - docs/chapters/targeting.rst | 6 +- docs/chapters/template.rst | 44 ++++++------- docs/chapters/upgrading.rst | 86 ++++++++++++------------- docs/chapters/usage.rst | 2 +- docs/index.rst | 3 +- usr/local/share/bastille/create.sh | 2 +- 48 files changed, 306 insertions(+), 228 deletions(-) create mode 100644 docs/chapters/boot-and-priority.rst diff --git a/docs/chapters/boot-and-priority.rst b/docs/chapters/boot-and-priority.rst new file mode 100644 index 00000000..343d5539 --- /dev/null +++ b/docs/chapters/boot-and-priority.rst @@ -0,0 +1,26 @@ +Boot and Priority +================= + +Boot +---- + +The boot setting control whether a jail will be started on system startup if you have enabled bastille +with ``sysrc bastille_enable=YES``. You can also use ``bastille start -b TARGET`` to respect this boot setting. +If it is off, the jail(s) will not be started if ``-b`` is used with ``start/stop/restart`` or on system +startup. Jails will still shut down on system shutdown, regardless of this setting. + +When jails are created with Bastille, the boot setting is set to ``on`` by default. This can be overridden using +the ``--no-boot`` flag. See ``bastille create --no-boot TARGET...``. + +This value can also be changed using ``bastille config TARGET boot [on|off]``. + +Priority +-------- + +The priority value determines in what order commands are executed. This also controls in what order jails are started +and stopped. + +When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on +creation. See ``bastille create -p 90 TARGET...``. + +This value can also be changed using ``bastille config TARGET priority VALUE``. \ No newline at end of file diff --git a/docs/chapters/configuration.rst b/docs/chapters/configuration.rst index 1249c822..48db7dea 100644 --- a/docs/chapters/configuration.rst +++ b/docs/chapters/configuration.rst @@ -1,8 +1,8 @@ Configuration ============= -Bastille is configured using a default config file located at `/usr/local/etc/bastille/bastille.conf`. When first installing -bastille, you will be asked if you want to copy the sample config file to this location. The default are sensible for UFS, but +Bastille is configured using a default config file located at ``/usr/local/etc/bastille/bastille.conf``. When first installing +bastille, you should run ``bastille setup``. This will ask if you want to copy the sample config file to the above location. The defaults are sensible for UFS, but if you want to use ZFS, you will have to change a few options. See the chapter on ZFS Support. This is the default `bastille.conf` file. @@ -83,9 +83,9 @@ Notes The options here are fairly self-explanitory, but there are some things to note. -* If you use ZFS, DO NOT create the bastille dataset. You must only create the parent. Bastille must be allowed to create the `bastille` child dataset, or you will have issues. So, if you want bastille to live at `zroot/data/bastille` you should set `bastille_zfs_zpool` to `zroot` and `bastille_zfs_prefix` to `data/bastille` but you should only create `zroot/data` before running bastille for the first time. +* If you use ZFS, DO NOT create the bastille dataset. You must only create the parent. Bastille must be allowed to create the ``bastille`` child dataset, or you will have issues. So, if you want bastille to live at ``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and ``bastille_zfs_prefix`` to ``data/bastille`` but you should only create ``zroot/data`` before running bastille for the first time. -* Bastille will mount the dataset it creates at `bastille_prefix` which defaults to `/usr/local/bastille`. So if you want to navigate to your jails, you will use the `bastille_prefix` as the location because this is where the will be mounted. +* Bastille will mount the dataset it creates at ``bastille_prefix`` which defaults to ``/usr/local/bastille``. So if you want to navigate to your jails, you will use the ``bastille_prefix`` as the location because this is where the will be mounted. Custom Configuration -------------------- @@ -95,12 +95,12 @@ jails at different locations based on your needs. Simply copy the default config file and edit it according to your new environment or user. Then, it can be used in a couple of ways. -1. Run Bastille using `bastille --config /path/to/config.conf bootstrap 14.2-RELEASE` to bootstrap the release using the new config. +1. Run Bastille using ``bastille --config /path/to/config.conf bootstrap 14.2-RELEASE`` to bootstrap the release using the new config. -2. As a specific user, export the `BASTILLE_CONFIG` variable using `export BASTILLE_CONFIG=/path/to/config.conf`. This config will then always be used when running Bastille with that user. See notes below... +2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export BASTILLE_CONFIG=/path/to/config.conf``. This config will then always be used when running Bastille with that user. See notes below... -- Exporting the `BASTILLE_CONFIG` variable will only export it for the current session. If you want to persist the export, see documentation for the shell that you use. +- Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current session. If you want to persist the export, see documentation for the shell that you use. -- If you use sudo, you will need to run it with `sudo -E bastille bootstrap...` to preserve your users environment. This can also be persisted by editing the sudoers file. +- If you use sudo, you will need to run it with ``sudo -E bastille bootstrap...`` to preserve your users environment. This can also be persisted by editing the sudoers file. -- If you do set the `BASTILLE_CONFIG` variable, you do not need to specify the config file when running Bastille as that specified user. +- If you do set the ``BASTILLE_CONFIG`` variable, you do not need to specify the config file when running Bastille as that specified user. diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst index 2d776fac..56f75b81 100644 --- a/docs/chapters/gettingstarted.rst +++ b/docs/chapters/gettingstarted.rst @@ -4,7 +4,7 @@ Getting Started This guide is meant to get you up and running with bastille, and will show you a number of different options to create and manage your jails. -The first step is running `bastille setup` to try to configure bastille initially. +The first step is running ``bastille setup`` to try to configure bastille initially. .. code-block:: shell @@ -20,15 +20,15 @@ Next we can create our first jail. Bastille can create a few different types of * Thin jails are the default, and are called thin because they use symlinks to the bootstrapped release. They are lightweight and are created quickly. -* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independant of the release. Created with `-T`. +* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independant of the release. Created with ``bastille create -T``. -* Clone jails are essentially clones of the bootstrapped release. Changes to the release will affect the clone jail. Created with `-C`. +* Clone jails are essentially clones of the bootstrapped release. Changes to the release will affect the clone jail. Created with ``bastille create -C``. -* Empty jails are just that, empty. These should be used only if you know what you are doing. Created with `-E`. +* Empty jails are just that, empty. These should be used only if you know what you are doing. Created with ``bastille create -E``. -* Linux jails are jails that run linux. Created with `-L`. +* Linux jails are jails that run linux. Created with ``bastille create -L``. -Only clone, thin, and thick jails can be created with `-V` `-B` and `-M`. +Only clone, thin, and thick jails can be created with ``-V`` ``-B`` and ``-M``. We will focus on thin jails for the guide. @@ -41,7 +41,7 @@ Classic/Standard Jail This will create a classic jail and add the IP as an alias to the vtnet0 interface. This jail will use NAT for its outbound traffic. If you want to run a webserver of something similar inside it, you -will have to redirect traffic from the host using `bastille rdr` +will have to redirect traffic from the host using ``bastille rdr`` It the IP is reachable within your local subnet, however, then it is not necessary to redirect the traffic. It will pass in and out normally. @@ -55,8 +55,8 @@ This will forward traffic from port 80 on the host to port 80 inside the jail. VNET Jail --------- -VNET jails can use either a host interface with `-V` or a manually created bridge interface with `-B`. You can -also optionally set a static MAC for the jail interface with `-M`. +VNET jails can use either a host interface with ``-V`` or a manually created bridge interface with ``-B``. You can +also optionally set a static MAC for the jail interface with ``-M``. .. code-block:: shell diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index 4ed64a36..2058ff2d 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 -:code:`sysutils/bastille`. Binary packages are available in quarterly and latest +``sysutils/bastille``. Binary packages are available in quarterly and latest repositories. -Current version is :code:`0.13.20250126`. +Current version is ``0.13.20250126``. To install from the FreeBSD package repository: @@ -42,9 +42,9 @@ git This method will install the latest files from GitHub directly onto your system. It is verbose about the files it installs (for later removal), and also -has a :code:`make uninstall` target. You may need to manually copy the sample +has a ``make uninstall`` target. You may need to manually copy the sample config into place before Bastille will run. (ie; -:code:`/usr/local/etc/bastille/bastille.conf.sample`) +``/usr/local/etc/bastille/bastille.conf.sample``) Note: installing using this method overwrites the version variable to match that of the source revision commit hash. 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..c904c56a 100644 --- a/docs/chapters/migration.rst +++ b/docs/chapters/migration.rst @@ -31,11 +31,11 @@ Import the iocage backup file (use zip file name) bastille import jailname_$(date +%F).zip -Bastille will attempt to configure your interface and IP from the config.json file, but if you have issues you can configure it manully. +Bastille will attempt to configure your interface and IP from the ``config.json`` file, but if you have issues you can configure it manully. .. code-block:: shell bastille edit jailname ip4.addr = bastille0|192.168.0.1/24; -You can use your primary network interface instead of the virtual bastille0 interface as well if you know what you’re doing. +You can use your primary network interface instead of the virtual ``bastille0`` interface as well if you know what you’re doing. diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 520b936e..90c9a869 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -12,17 +12,17 @@ Bastille includes a number of IP options. The IP address specified above can be any of the following options. -* An IP in your local subnet should be chosen if you create your jail using -V or -B (VNET jail). It is also preferable to add the subnet mask (/24 or whaterver your subnet is) to the IP. +* An IP in your local subnet should be chosen if you create your jail using ``-V`` or ``-B`` (VNET jail). It is also preferable to add the subnet mask (/24 or whaterver your subnet is) to the IP. -* DHCP, SYNCDHCP, or 0.0.0.0 will configure your jail to use DHCP to obtain an address from your router. This should only be used with `-V` and `-B`. +* DHCP, SYNCDHCP, or 0.0.0.0 will configure your jail to use DHCP to obtain an address from your router. This should only be used with ``-V`` and ``-B``. -* Any IP address inside the RFC1918 range if you are not using a VNET jail. Bastille will automatically add this IP to the firewall table to allow outbound access. It you want traffic to be forwarded into the jail, you can use the `bastille rdr` command. +* Any IP address inside the RFC1918 range if you are not using a VNET jail. Bastille will automatically add this IP to the firewall table to allow outbound access. It you want traffic to be forwarded into the jail, you can use the ``bastille rdr`` command. -* Any IP in your local subnet without the `-V` or `-B` options will add the IP as an alias to the selected interface, which will simply end up sharing the interface. If the IP is in your local subnet, you will not need the `bastille rdr` command. Traffic will pass in and out just as in a VNET jail. +* Any IP in your local subnet without the ``-V`` or ``-B`` options will add the IP as an alias to the selected interface, which will simply end up sharing the interface. If the IP is in your local subnet, you will not need the ``bastille rdr`` command. Traffic will pass in and out just as in a VNET jail. -* Setting the IP to `inherit` will make the jail inherit the entire host network stack. +* Setting the IP to ``inherit`` will make the jail inherit the entire host network stack. -* Setting the IP to `ip_hostname` will add all the IPs that the hostname resolves to. This is an advanced option and should only be used if you know what you are doing. +* Setting the IP to ``ip_hostname`` will add all the IPs that the hostname resolves to. This is an advanced option and should only be used if you know what you are doing. Note that jails support specifying an IP without the subnet (/24 or whatever yours is) but we highly recommend setting it, especially on VNET jails. Not doing so can cause issues in some rare cases. @@ -33,24 +33,24 @@ Bastille also supports IPv6. Instead of an IPv4 address, you can specify and IPv bastille create alcatraz 13.2-RELEASE "192.168.1.50/24 2001:19f0:6c01:114c:0:100/64" vtnet0 -For the `inherit` and `ip_hostname` options, you can also specify `-D|--dual` to use both IPv4 and IPv6 inside the jail. +For the ``inherit`` and ``ip_hostname`` options, you can also specify ``-D|--dual`` to use both IPv4 and IPv6 inside the jail. Host Network Configuration -------------------------- Bastille will automatically add and remove IP addressess to specified interfaces as jails are started and stopped. Below is an outline of how Bastille handles different types of jail network configs. -* VNET mode. For VNET jails (non-bridged) bastille will create a bridge interface and attach your jail to it. It will be called `em0bridge` or whatever your interface is called. This will be used for the host/jail epairs. Bastille will create/destroy these epairs as the jail is started/stopped. +* VNET mode. For VNET jails (non-bridged) bastille will create a bridge interface and attach your jail to it. It will be called ``em0bridge`` or whatever your interface is called. This will be used for the host/jail epairs. Bastille will create/destroy these epairs as the jail is started/stopped. * Bridged VNET mode. For bridged VNET jails, you must manually create a bridge interface to attach your jail to. Bastille will then create and attach the host/jail epairs to this interface when the jail starts, and remove them when it stops. * Alias mode. For classic/standard jails that use an IP that is accessible within your local subnet (alias mode) bastille will add the IP to the specified interface as an alias. -* NAT mode. For classic/standard jails that use an IP not reachable in you local subnet, bastille will add the IP to the specified interface as an alias, and additionally add it the the pf firewall table to allow the jail outbound access. If you do not specify an interface, Bastille will assume you have run the `bastille setup` command and will attemplt to use `bastille0` (which is created using the setup command) as it's interface. If you have not run `bastille setup` and do not specify an interface, Bastille will error. +* NAT mode. For classic/standard jails that use an IP not reachable in you local subnet, bastille will add the IP to the specified interface as an alias, and additionally add it the the pf firewall table to allow the jail outbound access. If you do not specify an interface, Bastille will assume you have run the ``bastille setup`` command and will attemplt to use ``bastille0`` (which is created using the setup command) as it's interface. If you have not run ``bastille setup`` and do not specify an interface, Bastille will error. -* Inherit mode. For classic/standard jails that are set to `inherit` or `ip_hostname`, bastille will simply set `ip4` to `inherit` inside the jail config. The jail will then function according the jail(8) documentation. +* Inherit mode. For classic/standard jails that are set to ``inherit`` or ``ip_hostname``, bastille will simply set ``ip4`` to ``inherit`` inside the jail config. The jail will then function according the jail(8) documentation. -* ip_hostname mode. For classic/standard jails that are set to `ip_hostname`, bastille will simply set `ip4` to `ip_hostname` inside the jail config. The jail will then function according the jail(8) documentation. +* ip_hostname mode. For classic/standard jails that are set to ``ip_hostname``, bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. The jail will then function according the jail(8) documentation. Network Scenarios ----------------- @@ -72,12 +72,12 @@ Please choose the option which is most appropriate for your environment. First a few notes. Bastille tries to verify that the interface name you provide is a valid interface. In FreeBSD network interfaces have different names, but -look something like `em0`, `bge0`, `re0`, `vtnet0` etc. Running the ifconfig +look something like ``em0``, ``bge0``, ``re0``, ``vtnet0`` etc. Running the ifconfig commend will tell you the name of your existing interfaces. Bastille also checks for a valid syntax IP4 or IP6 address. When you are testing calling out from your containers, please note that the ping command is disabled within the containers, because raw socket access are a security hole. Instead, install and -test with `wget`/`curl`/`fetch` instead. +test with ``wget/curl/fetch`` instead. Shared Interface on Home or Small Office Network ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -96,8 +96,8 @@ unique private ip address, and attach its ip address to your primary interface. You may have to change em0 -When the `alcatraz` container is started it will add `192.168.1.50` as an IP -alias to the `em0` interface. It will then simply be another member of the +When the ``alcatraz`` container is started it will add ``192.168.1.50`` as an IP +alias to the ``em0`` interface. It will then simply be another member of the hosts network. Other networked systems (firewall permitting) should be able to reach services at that address. @@ -111,7 +111,7 @@ Some ISP's, such as `Vultr `_, give you a single ipv4 address and a large block of ipv6 addresses. You can then assign a unique ipv6 address to each Bastille Container. -On a virtual machine such as vultr.com the virtual interface may be `vtnet0`. +On a virtual machine such as vultr.com the virtual interface may be ``vtnet0``. So we issue the command: .. code-block:: shell @@ -146,10 +146,10 @@ freebsd with the following command At that point your container can talk to the world, and the world can ping your container. Of course when you reboot the machine, that command will be -forgotten. To make it permanent, prefix the same command with `sysrc` +forgotten. To make it permanent, prefix the same command with ``sysrc`` Just remember you cannot ping out from the container. Instead, install and -use `wget`/`curl`/`fetch` to test the connectivity. +use ``wget/curl/fetch`` to test the connectivity. Virtual Network (VNET) @@ -161,7 +161,7 @@ Virtual Network (VNET) creates a private network interface for a container. This includes a unique hardware address. This is required for VPN, DHCP, and similar containers. -To create a VNET based container use the `-V` option, an IP/netmask and +To create a VNET based container use the ``-V`` option, an IP/netmask and external interface. .. code-block:: shell @@ -170,13 +170,13 @@ external interface. Bastille will automagically create the bridge interface and connect / disconnect containers as they are started and stopped. A new interface will be -created on the host matching the pattern `interface0bridge`. In the example -here, `em0bridge`. +created on the host matching the pattern ``interface0bridge``. In the example +here, ``em0bridge``. -The `em0` interface will be attached to the bridge along with the unique +The ``em0`` interface will be attached to the bridge along with the unique container interfaces as they are started and stopped. These interface names -match the pattern `eXb_bastilleX`. Internally to the containers these -interfaces are presented as `vnet0`. +match the pattern ``eXb_bastilleX``. Internally to the containers these +interfaces are presented as ``vnet0``. If you do not specify a subnet mask, you might have issues with jail to jail networking, especially VLAN to VLAN. We recommend always adding a subnet to @@ -197,7 +197,7 @@ host system: add include $devfsrules_jail_vnet add path 'bpf*' unhide -Lastly, you may want to consider these three `sysctl` values: +Lastly, you may want to consider these three ``sysctl`` values: .. code-block:: shell @@ -229,7 +229,7 @@ Bastille will attempt to auto-detect the default route from the host system and assign it to the VNET container. This auto-detection may not always be accurate for your needs for the particular container. In this case you'll need to add a default route manually or define the preferred default route in the -`bastille.conf`. +``bastille.conf``. .. code-block:: shell @@ -237,7 +237,7 @@ default route manually or define the preferred default route in the bastille service TARGET routing restart To define a default route / gateway for all VNET containers define the value in -`bastille.conf`: +``bastille.conf``: .. code-block:: shell @@ -250,7 +250,7 @@ Virtual Network (VNET) on External Bridge ----------------------------------------- To create a VNET based container and attach it to an external, already existing -bridge, use the `-B` option, an IP/netmask and external bridge. +bridge, use the ``-B`` option, an IP/netmask and external bridge. .. code-block:: shell @@ -275,9 +275,9 @@ network. loopback (bastille0) -------------------- -What we recommend is creating a cloned loopback interface (`bastille0`) and +What we recommend is creating a cloned loopback interface (``bastille0``) and assigning all the containers private (rfc1918) addresses on that interface. The -setup I develop on and use Bastille day-to-day uses the `10.0.0.0/8` address +setup I develop on and use Bastille day-to-day uses the ``10.0.0.0/8`` address range. I have the ability to use whatever address I want within that range because I've created my own private network. The host system then acts as the firewall, permitting and denying traffic as needed. @@ -327,8 +327,8 @@ Create the firewall rules: antispoof for $ext_if inet pass in inet proto tcp from any to any port ssh flags S/SA modulate state -- Make sure to change the `ext_if` variable to match your host system interface. -- Make sure to include the last line (`port ssh`) or you'll end up locked out. +- Make sure to change the ``ext_if`` variable to match your host system interface. +- Make sure to include the last line (``port ssh``) or you'll end up locked out. Note: if you have an existing firewall, the key lines for in/out traffic to containers are: @@ -337,15 +337,15 @@ to containers are: nat on $ext_if from to any -> ($ext_if:0) -The `nat` routes traffic from the loopback interface to the external +The ``nat`` routes traffic from the loopback interface to the external interface for outbound access. .. code-block:: shell rdr-anchor "rdr/*" -The `rdr-anchor "rdr/*"` enables dynamic rdr rules to be setup using the -`bastille rdr` command at runtime - eg. +The ``rdr-anchor "rdr/*"`` enables dynamic rdr rules to be setup using the +``bastille rdr`` command at runtime - eg. .. code-block:: shell @@ -389,4 +389,4 @@ To resolve this, add the following configuration to local_unbound: Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf -Adjust the above "access-control" strings to fit your network. +Adjust the above "access-control" strings to fit your network. \ No newline at end of file diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst index 39a3606b..641be018 100644 --- a/docs/chapters/subcommands/bootstrap.rst +++ b/docs/chapters/subcommands/bootstrap.rst @@ -11,7 +11,7 @@ than the host system likely will NOT work at all. Bastille tries to filter for valid release names. If you find it will not bootstrap a valid release, please let us know. -In this document we will describe using the `bootstrap` sub-command with both +In this document we will describe using the ``bootstrap`` sub-command with both releases and templates. We begin with releases. Releases @@ -20,7 +20,7 @@ Releases Example ^^^^^^^ -To `bootstrap` a FreeBSD release, run the bootstrap sub-command with the +To ``bootstrap`` a FreeBSD release, run the bootstrap sub-command with the release version as the argument. .. code-block:: shell @@ -28,7 +28,7 @@ release version as the argument. ishmael ~ # bastille bootstrap 14.0-RELEASE [update] ishmael ~ # bastille bootstrap 13.2-RELEASE [update] -To `bootstrap` a HardenedBSD release, run the bootstrap sub-command with the +To ``bootstrap`` a HardenedBSD release, run the bootstrap sub-command with the build version as the argument. .. code-block:: shell @@ -37,7 +37,7 @@ build version as the argument. This command will ensure the required directory structures are in place and -download the requested release. For each requested release, `bootstrap` will +download the requested release. For each requested release, ``bootstrap`` will download the base.txz. These files are verified (sha256 via MANIFEST file) before they are extracted for use. @@ -59,8 +59,8 @@ releases from the FTP archive. Tips ^^^^ -The `bootstrap` sub-command can now take (0.5.20191125+) an optional second -argument of "update". If this argument is used, `bastille update` will be run +The ``bootstrap`` sub-command can now take (0.5.20191125+) an optional second +argument of ``update``. If this argument is used, ``bastille update`` will be run immediately after the bootstrap, effectively bootstrapping and applying security patches and errata in one motion. @@ -71,11 +71,11 @@ The bootstrap subcommand is generally only used once to prepare the system. The only other use case for the bootstrap command is when a new FreeBSD version is released and you want to start deploying containers on that version. -To update a release as patches are made available, see the `bastille update` +To update a release as patches are made available, see the ``bastille update`` command. -Downloaded artifacts are stored in the `bastille/cache/version` directory. -"bootstrapped" releases are stored in `bastille/releases/version`. +Downloaded artifacts are stored in the ``bastille/cache/version`` directory. +"bootstrapped" releases are stored in ``bastille/releases/version``. To manually bootstrap a release (aka bring your own archive), place your archive in bastille/cache/name and extract to bastille/releases/name. Your @@ -111,7 +111,7 @@ Notes If you don't want to bother with git to use templates you can create them manually on the Bastille system and apply them. -Templates are stored in `bastille/templates/namespace/name`. If you'd like to +Templates are stored in ``bastille/templates/namespace/name``. If you'd like to create a new template on your local system, simply create a new namespace within the templates directory and then one for the template. This namespacing allows users and groups to have templates without conflicting template names. @@ -119,3 +119,11 @@ allows users and groups to have templates without conflicting template names. Once you've created the directory structure you can begin filling it with template hooks. Once you have a minimum number of hooks (at least one) you can begin applying your template. + +.. code-block:: shell + + ishmael ~ # bastille bootstrap help + Usage: bastille bootstrap [option(s)] [RELEASE|TEMPLATE] [update|arch] + Options: + + -x | --debug Enable debug mode. \ No newline at end of file diff --git a/docs/chapters/subcommands/clone.rst b/docs/chapters/subcommands/clone.rst index c433f3ca..0b06c827 100644 --- a/docs/chapters/subcommands/clone.rst +++ b/docs/chapters/subcommands/clone.rst @@ -1,7 +1,7 @@ clone ===== -To clone a container and make a duplicate, use the `bastille clone` +To clone a container and make a duplicate, use the ``bastille clone`` sub-command.. .. code-block:: shell diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst index d25e1a3b..ab652581 100644 --- a/docs/chapters/subcommands/console.rst +++ b/docs/chapters/subcommands/console.rst @@ -15,8 +15,9 @@ container are limited to the container. .. code-block:: shell - "Usage: bastille console [option(s)] TARGET [user]" - Options: + ishmael ~ # bastille console help + Usage: bastille console [option(s)] TARGET [user] + Options: -a | --auto Auto mode. Start/stop jail(s) if required. -x | --debug Enable debug mode. 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..c45d0f64 100644 --- a/docs/chapters/subcommands/create.rst +++ b/docs/chapters/subcommands/create.rst @@ -55,9 +55,7 @@ the below help output. .. code-block:: shell ishmael ~ # bastille create help - Usage: bastille create [option(s)] NAME RELEASE IP_ADDRESS [interface]" - Options: -B | --bridge Enables VNET, VNET containers are attached to a specified, already existing external bridge. @@ -67,8 +65,11 @@ the below help output. -L | --linux This option is intended for testing with Linux jails, this is considered experimental. -M | --static-mac Generate a static MAC address for jail (VNET only). --no-validate Do not validate the release when creating the jail. + --no-boot Create jail with boot=off. + -p | --priority VALUE Set priority value for jail. -T | --thick Creates a thick container, they consume more space as they are self contained and independent. -V | --vnet Enables VNET, VNET containers are attached to a virtual bridge interface for connectivity. + -v | --vlan VLANID Creates the jail with specified VLAN ID (VNET only). -x | --debug Enable debug mode. -Z | --zfs-opts [zfs,options] Comma separated list of ZFS options to create the jail with. This overrides the defaults. diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst index e3e49133..066944fe 100644 --- a/docs/chapters/subcommands/destroy.rst +++ b/docs/chapters/subcommands/destroy.rst @@ -3,7 +3,7 @@ destroy Jails can be destroyed and thrown away just as easily as they were created. Note: containers must be stopped before destroyed. Using -the `-a|--auto` option will automatically stop the jail before destroying it. +the ``-a|--auto`` option will automatically stop the jail before destroying it. .. code-block:: shell @@ -24,6 +24,6 @@ will retain the releas cache directory, if you choose to keep it. Options: -a | --auto Auto mode. Start/stop jail(s) if required. - -f | --force Force unmount any mounted datasets when destroying a jail or release (ZFS only). -c | --no-cache Do no destroy cache when destroying a release. + -f | --force Force unmount any mounted datasets when destroying a jail or release (ZFS only). -x | --debug Enable debug mode. 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..2f6c88be 100644 --- a/docs/chapters/subcommands/etcupdate.rst +++ b/docs/chapters/subcommands/etcupdate.rst @@ -1,9 +1,9 @@ etcupdate ========= -This command will update the contents of `/etc` inside a jail. It should be run after a jail upgrade +This command will update the contents of ``/etc`` inside a jail. It should be run after a jail upgrade -First we need to bootstrap a release for `etcupdate` to use. +First we need to bootstrap a release for ``etcupdate`` to use. .. code-block:: shell @@ -15,20 +15,20 @@ First we need to bootstrap a release for `etcupdate` to use. Building tarball, please wait... Etcupdate bootstrap complete: 14.1-RELEASE -Next we can use the `update` command to apply the update to the jail. +Next we can use the ``update`` command to apply the update to the jail. .. code-block:: shell ishmael ~ # bastille etcupdate ishmael update 14.1-RELEASE The output will show you which files were added, updated, changed, deleted, or have conflicts. -To automatically resolve the conflicts, run the `resolve` command. +To automatically resolve the conflicts, run the ``resolve`` command. .. code-block:: shell ishmael ~ # bastille etcupdate ishmael resolve -To show only the differences between the releases, use the `diff` command. +To show only the differences between the releases, use the ``diff`` command. .. code-block:: shell 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..c7f8feba 100644 --- a/docs/chapters/subcommands/htop.rst +++ b/docs/chapters/subcommands/htop.rst @@ -1,7 +1,7 @@ htop ==== -This command runs `htop` in the targeted jail. +This command runs ``htop`` in the targeted jail. Requires htop to be installed in the jail. .. image:: ../../images/htop.png 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/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..ea362ef7 100644 --- a/docs/chapters/subcommands/limits.rst +++ b/docs/chapters/subcommands/limits.rst @@ -3,18 +3,17 @@ limits Set resourse limits for targeted jail(s). -To add a limit, use `bastille limits TARGET add OPTION VALUE` +To add a limit, use ``bastille limits TARGET add OPTION VALUE`` -To clear the limits from the system, use `bastille limits TARGET clear` +To clear the limits from the system, use ``bastille limits TARGET clear`` -To clear the limits, and remove the rctl.conf, use `bastille limits TARGET reset` +To clear the limits, and remove the rctl.conf, use ``bastille limits TARGET reset`` -To remove a limit, use `bastille limits TARGET remove OPTION` +To remove a limit, use ``bastille limits TARGET remove OPTION`` .. code-block:: shell ishmael ~ # bastille limits help - Usage: bastille limits [option(s)] TARGET [add OPTION VALUE|remove OPTION|clear|reset|[list|show] (active)|stats] Example: bastille limits TARGET add memoryuse 1G" diff --git a/docs/chapters/subcommands/list.rst b/docs/chapters/subcommands/list.rst index 82b78f12..e060db24 100644 --- a/docs/chapters/subcommands/list.rst +++ b/docs/chapters/subcommands/list.rst @@ -1,13 +1,15 @@ list ==== -List jails, ports, releases, templates, logs, limits managed by bastille. +List jails, ports, releases, templates, logs, limits, exports and imports managed by bastille. .. code-block:: shell ishmael ~ # bastille list help - Usage: bastille list [option(s)] [-j|-a] [RELEASE [-p] [template] [JAIL|CONTAINER] [log] [limit] [import] [export] [backup]" + Usage: bastille list [option(s)] [-j|-a] [RELEASE (-p)|template|jails|logs|limits|imports|exports|backups] Options: + -a | --all List all jails, running and stopped, in BastilleBSD format. + -j | --json List jails in json format. -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst index c3e643c3..2cc93130 100644 --- a/docs/chapters/subcommands/mount.rst +++ b/docs/chapters/subcommands/mount.rst @@ -1,15 +1,15 @@ mount ===== -To mount storage within the container use `bastille mount`. +To mount storage within the container use ``bastille mount``. -Syntax follows standard `/etc/fstab` format: +Syntax follows standard ``/etc/fstab`` format: .. code-block:: shell Usage: bastille mount TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number] -The 'options' string can include a comma-separated list of mount options, but must include one of (rw,ro,rq,sw,xx) according to fstab documentation. +The ``options`` string can include a comma-separated list of mount options, but must include one of (rw,ro,rq,sw,xx) according to fstab documentation. Example: Mount a tmpfs filesystem with options. .. code-block:: shell @@ -50,4 +50,13 @@ It is possible to do the same for the jail path, but again, not recommemded. ishmael ~ # bastille mount azkaban "/storage/my\ directory\ with\ spaces" /media/foo nullfs ro 0 0 [azkaban]: - Added: /storage/my\040directory\040with\040spaces /usr/local/bastille/jails/azkaban/root/media/foo nullfs ro 0 0 + Add + + .. code-block:: shell + + ishmael ~ # bastille mount help + Usage: bastille mount [option(s)] TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number] + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -x | --debug Enable debug mode. \ No newline at end of file diff --git a/docs/chapters/subcommands/network.rst b/docs/chapters/subcommands/network.rst index 13c4bb55..2d2a2bc7 100644 --- a/docs/chapters/subcommands/network.rst +++ b/docs/chapters/subcommands/network.rst @@ -7,13 +7,13 @@ You can only add an interface once to a jail, with two exceptions. 1. For classic jails, you can add an interface as many times as you want, but each time with a different IP. All this does is add the IP as another alias on that interface. -2. For VNET jails, if the `-v|--vlan` switch is given along with a numerical VLAN ID, Bastille will add the VLAN ID to the jail as a vnetX.X interface, depending on which interface is specified. +2. For VNET jails, if the ``-v|--vlan`` switch is given along with a numerical VLAN ID, Bastille will add the VLAN ID to the jail as a vnetX.X interface, depending on which interface is specified. -Bridges and VNET interfaces can be added to VNET jails, no matter if they were created with `-V` or `-B`. +Bridges and VNET interfaces can be added to VNET jails, no matter if they were created with ``-V`` or ``-B``. -It is possible to passthrough an entire interface from the host to the jail using the `-P|--passthrough` option. This will make the interface fully available without the need for additional configuration. It will be available inside the jail just like it would be on the host. Adding an interface using this method will render it only available inside the jail. It will not be present on the host until the jail is stopped. +It is possible to passthrough an entire interface from the host to the jail using the ``-P|--passthrough`` option. This will make the interface fully available without the need for additional configuration. It will be available inside the jail just like it would be on the host. Adding an interface using this method will render it only available inside the jail. It will not be present on the host until the jail is stopped. -When cloning a jail that has a `-P|--passthrough` interface, you will have warnings when running both jails at the same time. The first jail to start will be assigned the interface, and since it will no longer be available to the host, it will not be possible to add it to the second jail. To solve this, you must manually remove the interface from the jail.conf file, or running `bastille network TARGET remove INTERFACE` while both jails are stopped. +When cloning a jail that has a ``-P|--passthrough`` interface, you will have warnings when running both jails at the same time. The first jail to start will be assigned the interface, and since it will no longer be available to the host, it will not be possible to add it to the second jail. To solve this, you must manually remove the interface from the jail.conf file, or running ``bastille network TARGET remove INTERFACE`` while both jails are stopped. .. code-block:: shell diff --git a/docs/chapters/subcommands/pkg.rst b/docs/chapters/subcommands/pkg.rst index bd999227..f8a44e29 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 +The PKG sub-command can do more than just ``install``. The expectation is that you can fully leverage the pkg manager. This means, -`install`, `update`, `upgrade`, `audit`, `clean`, `autoremove`, etc... +``install``, ``update``, ``upgrade``, ``audit``, ``clean``, ``autoremove``, etc... .. code-block:: shell @@ -107,7 +107,7 @@ expectation is that you can fully leverage the pkg manager. This means, .. code-block:: shell ishmael ~ # bastille pkg help - Usage: bastille pkg [option(s)] TARGET COMMAND args + Usage: bastille pkg [option(s)] TARGET COMMAND ARGS Options: -a | --auto Auto mode. Start/stop jail(s) if required. 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..03276669 100644 --- a/docs/chapters/subcommands/rdr.rst +++ b/docs/chapters/subcommands/rdr.rst @@ -1,9 +1,9 @@ rdr === -`bastille rdr` allows you to configure dynamic rdr rules for your containers -without modifying pf.conf (assuming you are using the `bastille0` interface -for a private network and have enabled `rdr-anchor 'rdr/*'` in /etc/pf.conf +``bastille rdr`` allows you to configure dynamic rdr rules for your containers +without modifying pf.conf (assuming you are using the ``bastille0`` interface +for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf as described in the Networking section). Note: you need to be careful if host services are configured to run @@ -30,7 +30,7 @@ specify the interface they run on in rc.conf (or other config files) # bastille rdr dev1 clear nat cleared -The `rdr` command includes 4 additional options: +The ``rdr`` command includes 4 additional options: .. code-block:: shell @@ -65,7 +65,7 @@ The `rdr` command includes 4 additional options: The options can be used together, as seen above. -If you have multiple interfaces assigned to your jail, `bastille rdr` will +If you have multiple interfaces assigned to your jail, ``bastille rdr`` will only redirect using the default one. .. code-block:: shell 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..2f3bf9cc 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 to wait between starting each jail. + -v | --verbose Print every action on jail start. + -x | --debug Enable debug mode. \ No newline at end of file diff --git a/docs/chapters/subcommands/service.rst b/docs/chapters/subcommands/service.rst index 1f67a045..15811d06 100644 --- a/docs/chapters/subcommands/service.rst +++ b/docs/chapters/subcommands/service.rst @@ -1,7 +1,7 @@ service ======= -The `service` sub-command allows for managing services within jails. This +The ``service`` sub-command allows for managing services within jails. This allows you to start, stop, restart, and otherwise interact with services running inside the jail(s). diff --git a/docs/chapters/subcommands/setup.rst b/docs/chapters/subcommands/setup.rst index 39a2a09f..83062146 100644 --- a/docs/chapters/subcommands/setup.rst +++ b/docs/chapters/subcommands/setup.rst @@ -1,7 +1,7 @@ setup ===== -The `setup` sub-command attempts to automatically configure a host system for +The ``setup`` sub-command attempts to automatically configure a host system for Bastille containers. This allows you to configure networking, firewall, and storage options for a Bastille host with one command. diff --git a/docs/chapters/subcommands/start.rst b/docs/chapters/subcommands/start.rst index 6f1ddfc6..09a798b1 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 to wait between starting each jail. + -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..851458fb 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 to wait between stopping each jail. + -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..1c96bbe5 100644 --- a/docs/chapters/subcommands/template.rst +++ b/docs/chapters/subcommands/template.rst @@ -7,8 +7,8 @@ Run preconfigured template files inside targeted jail(s). ishmael ~ # bastille template azkaban project/template -Templates should be structured in `project/template/Bastillefile` format, and placed in the template -directory, which defaults to `/usr/local/bastille/templates`. The Bastillefile should contain the template +Templates should be structured in ``project/template/Bastillefile`` format, and placed in the template +directory, which defaults to ``/usr/local/bastille/templates``. The Bastillefile should contain the template hooks. See the chapter called Template for a list of supported hooks. .. code-block:: shell 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..985d04f8 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 @@ -25,3 +25,12 @@ If the directory you are unmounting has spaces, make sure to escape them with a ishmael ~ # bastille umount azkaban "/media/foo\ with\ spaces" [azkaban]: Unmounted: /usr/local/bastille/jails/jail4/root/media/foo with spaces + +.. code-block:: shell + + ishmael ~ # bastille umount help + Usage: bastille umount [option(s)] TARGET JAIL_PATH + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -x | --debug Enable debug mode. \ No newline at end of file diff --git a/docs/chapters/subcommands/update.rst b/docs/chapters/subcommands/update.rst index 259813fa..92900f6c 100644 --- a/docs/chapters/subcommands/update.rst +++ b/docs/chapters/subcommands/update.rst @@ -1,7 +1,7 @@ update ====== -The `update` command targets a release or a thick jail. Because thin jails are +The ``update`` command targets a release or a thick jail. Because thin jails are based on a release, when the release is updated all the thin jails are automatically updated as well. @@ -40,3 +40,13 @@ To be safe, you may want to restart any jails that have been updated live. If the jail is a thin jail, an error will be shown. If it is a thick jail, it will be updated just like the release shown above. + +.. code-block:: shell + + ishmael ~ # bastille update help + Usage: bastille update [option(s)] TARGET + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -f | --force Force update a release. + -x | --debug Enable debug mode. \ No newline at end of file diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst index daebb503..f7b2042c 100644 --- a/docs/chapters/subcommands/upgrade.rst +++ b/docs/chapters/subcommands/upgrade.rst @@ -1,7 +1,7 @@ upgrade ======= -The `upgrade` command targets a thick or thin jail. Thin jails will be updated by changing the +The ``upgrade`` command targets a thick or thin jail. Thin jails will be updated by changing the release mount point that it is based on. Thick jails will be upgraded normally. .. code-block:: shell diff --git a/docs/chapters/subcommands/verify.rst b/docs/chapters/subcommands/verify.rst index fe5b3cd7..3f49fbf2 100644 --- a/docs/chapters/subcommands/verify.rst +++ b/docs/chapters/subcommands/verify.rst @@ -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..5ca75820 100644 --- a/docs/chapters/subcommands/zfs.rst +++ b/docs/chapters/subcommands/zfs.rst @@ -7,7 +7,6 @@ Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for targ ishmael ~ # bastille zfs help Usage: bastille zfs TARGET [set|get|snap|destroy_snap|df|usage] [key=value|date] - Options: -x | --debug Enable debug mode. diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index 63df3575..8e5e538a 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -1,7 +1,7 @@ Targeting ========= -Bastille uses a `command target arguments` syntax, meaning that each command +Bastille uses a ``command TARGET ARGS`` syntax, meaning that each command requires a target. Targets are usually containers, but can also be releases. Targeting a container is done by providing the exact jail name, the JID of the jail, or by typing the @@ -9,9 +9,9 @@ starting few characters of a jail. If more than one matching jail will be found, saying so. Targeting a release is done by providing the exact release name. (Note: do not -include the `-pX` point-release version.) +include the ``-pX`` point-release version.) -Bastille includes a pre-defined keyword [ALL|all} to target all running containers. +Bastille includes a pre-defined keyword [ALL|all] to target all running containers. It is also possible to target multiple jails by grouping them in quotes, as seen below. .. code-block:: shell diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index a2a317cf..da4d2b7d 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -5,10 +5,10 @@ Looking for ready made CI/CD validated `Bastille Templates`_? Bastille supports a templating system allowing you to apply files, pkgs and execute commands inside the containers automatically. -Currently supported template hooks are: `ARG`, `CMD`, `CONFIG`, `CP`, `INCLUDE`, -`LIMITS`, `MOUNT`, `OVERLAY`, `PKG`, `RDR`, `RENDER`, `RESTART`, `SERVICE`, `SYSRC`. +Currently supported template hooks are: ``ARG``, ``CMD``, ``CONFIG``, ``CP``, ``INCLUDE``, +``LIMITS``, ``MOUNT``, ``OVERLAY``, ``PKG``, ``RDR``, ``RENDER``, ``RESTART``, ``SERVICE``, ``SYSRC``. -Templates are created in `${bastille_prefix}/templates` and can leverage any of +Templates are created in ``${bastille_prefix}/templates`` and can leverage any of the template hooks. Bastille 0.7.x+ @@ -16,7 +16,7 @@ Bastille 0.7.x+ Bastille 0.7.x introduces a template syntax that is more flexible and allows any-order scripting. Previous versions had a hard template execution order and instructions were spread across multiple files. The new syntax is done in a -`Bastillefile` and the template hook (see below) files are replaced with +``Bastillefile`` and the template hook (see below) files are replaced with template hook commands. Template Automation Hooks @@ -59,9 +59,9 @@ Template Hook Descriptions ARG - set an ARG value to be used in the template -ARGS will default to the value set inside the template, but can be changed by including `--arg ARG=VALUE` when -running the template. Multiple ARGS can also be specified as seen below. If no ARG value is given, the template -will show a warning, but will still continue. +ARGS will default to the value set inside the template, but can be changed by including ``--arg ARG=VALUE`` when +running the template. Multiple ARGS can also be specified as seen below. If no ARG value is given, the ``template`` command +will exit. .. code-block:: shell @@ -95,40 +95,40 @@ SYSRC - run `sysrc` inside the jail with specified arguments Special Hook Cases ------------------ -SYSRC requires that NO quotes be used or that quotes (`"`) be escaped -ie; (`\\"`) +SYSRC requires that NO quotes be used or that quotes (``"``) be escaped +ie; (``\\"``) -ARG will always treat an ampersand "\&" literally, without the need to escape it. +ARG will always treat an ampersand "\``&``" literally, without the need to escape it. Escaping it will cause errors. Template Examples ----------------- -Place these uppercase template hook commands into a `Bastillefile` in any order +Place these uppercase template hook commands into a ``Bastillefile`` in any order and automate container setup as needed. In addition to supporting template hooks, Bastille supports overlaying files into the container. This is done by placing the files in their full path, using the template directory as "/". -An example here may help. Think of `bastille/templates/username/template`, our +An example here may help. Think of ``bastille/templates/username/template``, our example template, as the root of our filesystem overlay. If you create an -`etc/hosts` or `etc/resolv.conf` *inside* the template directory, these +``/etc/hosts`` or ``/etc/resolv.conf`` *inside* the template directory, these can be overlayed into your container. Note: due to the way FreeBSD segregates user-space, the majority of your -overlayed template files will be in `usr/local`. The few general -exceptions are the `etc/hosts`, `etc/resolv.conf`, and -`etc/rc.conf.local`. +overlayed template files will be in ``/usr/local``. The few general +exceptions are the ``/etc/hosts``, ``/etc/resolv.conf``, and +``/etc/rc.conf.local``. -After populating `usr/local` with custom config files that your container will -use, be sure to include `usr` in the template OVERLAY definition. eg; +After populating ``/usr/local`` with custom config files that your container will +use, be sure to include ``/usr`` in the template OVERLAY definition. eg; .. code-block:: shell - echo "CP usr /" >> /usr/local/bastille/templates/username/template/Bastillefile + echo "CP /usr /" >> /usr/local/bastille/templates/username/template/Bastillefile -The above example "usr" will include anything under "usr" inside the template. +The above example ``/usr`` will include anything under ``/usr`` inside the template. You do not need to list individual files. Just include the top-level directory name. List these top-level directories one per line. @@ -137,9 +137,9 @@ Applying Templates Containers must be running to apply templates. -Bastille includes a `template` command. This command requires a target and a +Bastille includes a ``template`` command. This command requires a target and a template name. As covered in the previous section, template names correspond to -directory names in the `bastille/templates` directory. +directory names in the ``bastille/templates`` directory. .. code-block:: shell diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index 0ae3fc0c..d2bd8aaf 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -1,13 +1,13 @@ -========= Upgrading ========= -This document outlines upgrading jails hosted using Bastille. + +This document outlines updating and upgrading jails hosted by Bastille. Bastille can "bootstrap" multiple versions of FreeBSD to be used by jails. All jails do not NEED to be the same version (even if they often are), the only requirement here is that the "bootstrapped" versions are less than or equal to the host version of FreeBSD. -To keep releases updated, use `bastille update RELEASE` +To keep releases updated, use ``bastille update RELEASE`` -To keep thick jails updated, use `bastille update TARGET` +To keep thick jails updated, use ``bastille update TARGET`` ---------------------- Minor Release Upgrades @@ -18,26 +18,26 @@ To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the f Thick Jails ----------- -1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` -2. update the release: `bastille update 13.2-RELEASE` -3. use `bastille upgrade TARGET 13.2-RELEASE` to upgrade the jail to 13.2-RELEASE -4. use `bastille upgrade TARGET 13.2-RELEASE update` to apply the updates -5. reboot the jail `bastille restart TARGET` -6. use `bastille upgrade TARGET 13.2-RELEASE update` to finish applying the upgrade -7. upgrade complete! +1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` +2. Update the release: ``bastille update 13.2-RELEASE`` +3. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE +4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates +5. Reboot the jail ``bastille restart TARGET`` +6. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade +7. Upgrade complete! Thin Jails ---------- -1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` -2. update the release: `bastille update 13.2-RELEASE` -3. stop the jail(s) that need to be updated. -4. use `bastille upgrade TARGET 13.2-RELEASE` to automatically change the mount points to 13.2-RELEASE -5. use `bastille etcupdate bootstrap 13.2-RELEASE` to bootstrap src for 13.2-RELEASE -6. use `bastille etcupdate TARGET update 13.2-RELEASE` to update the contents of /etc for 13.2-RELEASE -7. use `bastille etcupdate TARGET reslove` to resolve any conflicts -8. start the jail(s) -8. upgrade complete! +1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` +2. Update the release: ``bastille update 13.2-RELEASE`` +3. Stop the jail(s) that need to be updated. +4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the mount points to 13.2-RELEASE +5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for 13.2-RELEASE +6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents of /etc for 13.2-RELEASE +7. Use ``bastille etcupdate TARGET reslove`` to resolve any conflicts +8. Start the jail(s) +9. Upgrade complete! ---------------------- Major Release Upgrades @@ -48,28 +48,28 @@ To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the f Thick Jails ----------- -1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` -2. update the release: `bastille update 13.2-RELEASE` -3. use `bastille upgrade TARGET 13.2-RELEASE` to upgrade the jail to 13.2-RELEASE -4. use `bastille upgrade TARGET 13.2-RELEASE update` to apply the updates -5. reboot the jail `bastille restart TARGET` -6. use `bastille upgrade TARGET 13.2-RELEASE update` to finish applying the upgrade -7. force the reinstallation or upgrade of all installed packages (ABI change): `pkg upgrade -f` within each jail (or `bastille pkg ALL upgrade -f`) -8. upgrade complete! +1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` +2. Update the release: ``bastille update 13.2-RELEASE`` +3. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE +4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates +5. Reboot the jail ``bastille restart TARGET`` +6. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade +7. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) +8. Upgrade complete! Thin Jails ---------- -1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` -2. update the release: `bastille update 13.2-RELEASE` -3. stop the jail(s) that need to be updated. -4. use `bastille upgrade TARGET 13.2-RELEASE` to automatically change the mount points to 13.2-RELEASE -5. use `bastille etcupdate bootstrap 13.2-RELEASE` to bootstrap src for 13.2-RELEASE -6. use `bastille etcupdate TARGET update 13.2-RELEASE` to update the contents of /etc for 13.2-RELEASE -7. use `bastille etcupdate TARGET reslove` to resolve any conflicts -8. start the jail(s) -9. force the reinstallation or upgrade of all installed packages (ABI change): `pkg upgrade -f` within each jail (or `bastille pkg ALL upgrade -f`) -10. upgrade complete! +1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` +2. Update the release: ``bastille update 13.2-RELEASE`` +3. Stop the jail(s) that need to be updated. +4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the mount points to 13.2-RELEASE +5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for 13.2-RELEASE +6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents of /etc for 13.2-RELEASE +7. Use ``bastille etcupdate TARGET reslove`` to resolve any conflicts +8. Start the jail(s) +9. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) +10. Upgrade complete! ---------------------------------- Revert Upgrade / Downgrade Process @@ -84,8 +84,8 @@ Thick jails should not be downgraded and is not supported in general on FreeBSD. Thin Jails ---------- -Not recommended, but you can run `bastille upgrade TARGET 13.1-RELEASE` to downgrade a thin jail. -Make sure to run `bastille etcupdate TARGET update 13.1-RELEASE` to keep the contents of /etc updated with each release. +Not recommended, but you can run ``bastille upgrade TARGET 13.1-RELEASE`` to downgrade a thin jail. +Make sure to run ``bastille etcupdate TARGET update 13.1-RELEASE`` to keep the contents of /etc updated with each release. The pkg reinstallation will also need to be repeated after the jail restarts on the previous release. @@ -96,8 +96,8 @@ Old Releases After upgrading all jails from one release to the next you may find that you now have bootstrapped a release that is no longer used. Once you've decided that you no longer need the option to revert the change you can destroy the old release. -`bastille list releases` to list all bootstrapped releases. +``bastille list releases`` to list all bootstrapped releases. -`bastille destroy X.Y-RELEASE` to fully delete the release, including the cache. +``bastille destroy X.Y-RELEASE`` to fully delete the release, including the cache. -`bastille destroy [-c|--no-cache] X.Y-RELEASE` to retain the cache directory. +``bastille destroy [-c|--no-cache] X.Y-RELEASE`` to retain the cache directory. 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/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/share/bastille/create.sh b/usr/local/share/bastille/create.sh index 4e5f5186..4b0bc56c 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). From 79f11dd61a189b9d580c99b075100ac19c56f89d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 10 Apr 2025 06:56:44 -0600 Subject: [PATCH 04/63] docs: Add note that boot and prio will show on list command --- docs/chapters/boot-and-priority.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/chapters/boot-and-priority.rst b/docs/chapters/boot-and-priority.rst index 343d5539..811f7d60 100644 --- a/docs/chapters/boot-and-priority.rst +++ b/docs/chapters/boot-and-priority.rst @@ -14,6 +14,8 @@ the ``--no-boot`` flag. See ``bastille create --no-boot TARGET...``. This value can also be changed using ``bastille config TARGET boot [on|off]``. +This value will be shown using ``bastille list all``. + Priority -------- @@ -23,4 +25,6 @@ and stopped. When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on creation. See ``bastille create -p 90 TARGET...``. -This value can also be changed using ``bastille config TARGET priority VALUE``. \ No newline at end of file +This value can also be changed using ``bastille config TARGET priority VALUE``. + +This value will be shown using ``bastille list all``. From 2c7d0cb3d466ddc9ac04711999fd246c10c400fa Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 10 Apr 2025 13:35:54 -0600 Subject: [PATCH 05/63] docs: clearer boot and priority --- docs/chapters/boot-and-priority.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/chapters/boot-and-priority.rst b/docs/chapters/boot-and-priority.rst index 811f7d60..322b164d 100644 --- a/docs/chapters/boot-and-priority.rst +++ b/docs/chapters/boot-and-priority.rst @@ -4,27 +4,35 @@ Boot and Priority Boot ---- -The boot setting control whether a jail will be started on system startup if you have enabled bastille -with ``sysrc bastille_enable=YES``. You can also use ``bastille start -b TARGET`` to respect this boot setting. -If it is off, the jail(s) will not be started if ``-b`` is used with ``start/stop/restart`` or on system -startup. Jails will still shut down on system shutdown, regardless of this setting. +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 also be changed using ``bastille config TARGET boot [on|off]``. +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. This also controls in what order jails are started -and stopped. +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``. When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on -creation. See ``bastille create -p 90 TARGET...``. +creation. See ``bastille create --priority 90 TARGET...``. -This value can also be changed using ``bastille config TARGET priority VALUE``. +This value can be changed using ``bastille config TARGET priority VALUE``. This value will be shown using ``bastille list all``. From e3dfa3f5351deb74f7b3aac6001058914358ac42 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 10 Apr 2025 14:16:02 -0600 Subject: [PATCH 06/63] =?UTF-8?q?docs:=20Upgrading=20thick=20jails=20doesn?= =?UTF-8?q?=E2=80=99t=20need=20bootstrapped=20release?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/chapters/upgrading.rst | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index d2bd8aaf..dcf8f619 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -18,13 +18,11 @@ To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the f Thick Jails ----------- -1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` -2. Update the release: ``bastille update 13.2-RELEASE`` -3. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE -4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates -5. Reboot the jail ``bastille restart TARGET`` -6. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade -7. Upgrade complete! +1. 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 ---------- @@ -48,14 +46,12 @@ To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the f Thick Jails ----------- -1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` -2. Update the release: ``bastille update 13.2-RELEASE`` -3. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE -4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates -5. Reboot the jail ``bastille restart TARGET`` -6. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade -7. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) -8. Upgrade complete! +1. 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 ---------- From cbaf042e5dc0ab48edf51b4ea4516fa3c8abeff5 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Fri, 11 Apr 2025 16:36:39 -0600 Subject: [PATCH 07/63] docs: Fix mount shell block --- docs/chapters/subcommands/mount.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst index 2cc93130..2d86a273 100644 --- a/docs/chapters/subcommands/mount.rst +++ b/docs/chapters/subcommands/mount.rst @@ -12,12 +12,16 @@ Syntax follows standard ``/etc/fstab`` format: 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 @@ -59,4 +63,4 @@ It is possible to do the same for the jail path, but again, not recommemded. Options: -a | --auto Auto mode. Start/stop jail(s) if required. - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. From 59d06b36cc75fbd202528322a2859452b8f36f56 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Fri, 11 Apr 2025 16:43:40 -0600 Subject: [PATCH 08/63] docs: Fix code block --- docs/chapters/subcommands/mount.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst index 2d86a273..180811b2 100644 --- a/docs/chapters/subcommands/mount.rst +++ b/docs/chapters/subcommands/mount.rst @@ -54,9 +54,9 @@ 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]: - Add + Added: /storage/my\040directory\040with\040spaces /usr/local/bastille/jails/azkaban/root/media/foo nullfs ro 0 0 - .. code-block:: shell +.. code-block:: shell ishmael ~ # bastille mount help Usage: bastille mount [option(s)] TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number] From cf55e96025afb3471775842f69626db9efc8802b Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Fri, 11 Apr 2025 17:32:22 -0600 Subject: [PATCH 09/63] docs: Be more clear on priority value --- docs/chapters/boot-and-priority.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/chapters/boot-and-priority.rst b/docs/chapters/boot-and-priority.rst index 322b164d..fff7cb09 100644 --- a/docs/chapters/boot-and-priority.rst +++ b/docs/chapters/boot-and-priority.rst @@ -28,7 +28,8 @@ 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``. +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...``. From 4d02ce7e370e16261a75ed7b72e71d06ed216e69 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sun, 13 Apr 2025 20:22:10 -0600 Subject: [PATCH 10/63] htop: Bugfix for binary location --- usr/local/share/bastille/htop.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 159273e8ecf8032aa06f03cad956da3416cf0b9d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:30:12 -0600 Subject: [PATCH 11/63] docs: Targeting subheadings --- docs/chapters/targeting.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index 8e5e538a..ed1b770e 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -19,7 +19,7 @@ It is also possible to target multiple jails by grouping them in quotes, as seen ishmael ~ # bastille cmd "jail1 jail2 jail3" echo Hello! Examples: Containers -==================== +-------------------- .. code-block:: shell @@ -51,7 +51,7 @@ Examples: Containers Examples: Releases -================== +------------------ .. code-block:: shell From bc5160b4184826019f76b433d9c2fde54255e3df Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:38:06 -0600 Subject: [PATCH 12/63] create: Bugfix for attempling to create a -B with non-bridge interface --- usr/local/share/bastille/create.sh | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/usr/local/share/bastille/create.sh b/usr/local/share/bastille/create.sh index 4b0bc56c..ee1538a7 100644 --- a/usr/local/share/bastille/create.sh +++ b/usr/local/share/bastille/create.sh @@ -810,6 +810,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) From 023514898926f1c08729ba27bf05ff74c2a0e224 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 20:27:36 -0600 Subject: [PATCH 13/63] list: Fix listing jail IP with / subnet --- usr/local/share/bastille/list.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/list.sh b/usr/local/share/bastille/list.sh index 94d436d1..59b76e8f 100644 --- a/usr/local/share/bastille/list.sh +++ b/usr/local/share/bastille/list.sh @@ -119,7 +119,7 @@ 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 From 12f7cf2027c874ca52ee6add368829d8c1ce7808 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 20:34:17 -0600 Subject: [PATCH 14/63] list: Properly list jail ip on stopped thin jail --- usr/local/share/bastille/list.sh | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/list.sh b/usr/local/share/bastille/list.sh index 59b76e8f..6285bd5e 100644 --- a/usr/local/share/bastille/list.sh +++ b/usr/local/share/bastille/list.sh @@ -121,8 +121,9 @@ list_all(){ 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') 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) From 8e559b61147ddbdf89db21a47af4b3cfe810e3f9 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 20:46:43 -0600 Subject: [PATCH 15/63] create: Fix jail not applying IP when IP already in use --- usr/local/share/bastille/create.sh | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/usr/local/share/bastille/create.sh b/usr/local/share/bastille/create.sh index ee1538a7..5c0cf31a 100644 --- a/usr/local/share/bastille/create.sh +++ b/usr/local/share/bastille/create.sh @@ -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 From 0ea6e1966dde40f0f4206a1e89bceaa14346e987 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 20:50:00 -0600 Subject: [PATCH 16/63] list: Properly list jail ip if subnet is included --- usr/local/share/bastille/list.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/list.sh b/usr/local/share/bastille/list.sh index 6285bd5e..6038877d 100644 --- a/usr/local/share/bastille/list.sh +++ b/usr/local/share/bastille/list.sh @@ -165,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}' | s'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 From 9fe20252d4297f54fa3f2fad1733328d9648ef10 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Mon, 14 Apr 2025 20:52:59 -0600 Subject: [PATCH 17/63] list: typo s > sed --- usr/local/share/bastille/list.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/list.sh b/usr/local/share/bastille/list.sh index 6038877d..22f81f3f 100644 --- a/usr/local/share/bastille/list.sh +++ b/usr/local/share/bastille/list.sh @@ -172,7 +172,7 @@ list_all(){ 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}' | s's#/.*##g')"; 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 From 9b8082c2edee50be67c5f14c778182e08651f429 Mon Sep 17 00:00:00 2001 From: Barry McCormick Date: Tue, 15 Apr 2025 09:26:29 -0700 Subject: [PATCH 18/63] Update upgrading.rst --- docs/chapters/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index dcf8f619..fce25ddd 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -62,7 +62,7 @@ Thin Jails 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 +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! From d5deb9bd1be1d686cd250db7bbb84d060f92c553 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 12:07:15 -0600 Subject: [PATCH 19/63] Fix epair numbering when mixing -V and -B jails on one systme --- usr/local/share/bastille/clone.sh | 18 +++++++++--------- usr/local/share/bastille/common.sh | 18 ++++++++---------- usr/local/share/bastille/network.sh | 16 +++++++--------- 3 files changed, 24 insertions(+), 28 deletions(-) diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index 8315dd33..3800aec5 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,12 @@ 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)) + local _epair_count="$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair ) | grep -Eo "[0-9]+" | sort -u | wc -l | awk '{print $1}')" + 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 ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eoq "(e${_num}a|epair${_num}a|bastille${_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 +270,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 ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eoq "(e${_num}a|epair${_num}a|bastille${_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]+")" @@ -380,4 +380,4 @@ else usage fi -clone_jail +clone_jail \ No newline at end of file diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 0f4cb57f..0edf2eae 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -280,14 +280,12 @@ generate_vnet_jail_netblock() { ## 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)) + local _epair_count="$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair ) | grep -Eo "[0-9]+" | sort -u | wc -l | awk '{print $1}')" + 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 ! grep -Eosq "epair${_num}" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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,8 +308,8 @@ generate_vnet_jail_netblock() { fi fi else - if [ "${_bastille_if_count}" -gt 0 ]; then - for _num in $(seq 0 "${bastille_num_range}"); do + if [ "${_epair_count}" -gt 0 ]; then + for _num in $(seq 0 "${_epair_num_range}"); do if ! grep -Eosq "bastille${_num}" ${bastille_jailsdir}/*/jail.conf; then local uniq_epair="bastille${_num}" break @@ -398,4 +396,4 @@ checkyesno() { return 1 ;; esac -} +} \ No newline at end of file diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index 54d52738..770dfb52 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -231,16 +231,14 @@ 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}')" + local _epair_count="$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair ) | grep -Eo "[0-9]+" | sort -u | wc -l | awk '{print $1}')" 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_if_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 + for _num in $(seq 0 "${_epair_num_range}"); do + if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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 +310,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 ! grep -Eq "(bastille${_num}|epair${_num})" "${bastille_jailsdir}"/*/jail.conf; then local bastille_epair="bastille${_num}" break fi @@ -597,4 +595,4 @@ case "${ACTION}" in *) error_exit "Only [add|remove] are supported." ;; -esac +esac \ No newline at end of file From 0fe4bec89fab0a25a2bf68d6d53435aeccbed4c6 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 15:57:07 -0600 Subject: [PATCH 20/63] common: Add function to count epairs --- usr/local/share/bastille/common.sh | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 0edf2eae..deeff781 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -118,6 +118,15 @@ 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)" + local _epair_list="$(printf '%s\n' $( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+") ${_epair_list} | sort -u)" + done + _epair_count="$(echo ${_epair_list} | wc -l | awk '{print $1}')" + export _epair_count +} + get_jail_name() { local _JID="${1}" local _jailname="$(jls -j ${_JID} name 2>/dev/null)" From c2b756219c81eb8063faa9696b78989556866789 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 16:08:17 -0600 Subject: [PATCH 21/63] Force config file in default location This will prevent errors when bastille gathers the number of epairs on the system. --- docs/chapters/configuration.rst | 6 ++++-- usr/local/bin/bastille | 7 +------ usr/local/share/bastille/clone.sh | 3 ++- usr/local/share/bastille/common.sh | 6 ++---- usr/local/share/bastille/network.sh | 7 ++++--- 5 files changed, 13 insertions(+), 16 deletions(-) diff --git a/docs/chapters/configuration.rst b/docs/chapters/configuration.rst index 48db7dea..38ef7617 100644 --- a/docs/chapters/configuration.rst +++ b/docs/chapters/configuration.rst @@ -93,11 +93,13 @@ 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 jails at different locations based on your needs. +The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at ``/usr/local/etc/bastille`` or it will not work. + Simply copy the default config file and edit it according to your new environment or user. Then, it can be used in a couple of ways. -1. Run Bastille using ``bastille --config /path/to/config.conf bootstrap 14.2-RELEASE`` to bootstrap the release using the new config. +1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE`` to bootstrap the release using the new config. -2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export BASTILLE_CONFIG=/path/to/config.conf``. This config will then always be used when running Bastille with that user. See notes below... +2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export BASTILLE_CONFIG=config.conf``. This config will then always be used when running Bastille with that user. See notes below... - Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current session. If you want to persist the export, see documentation for the shell that you use. diff --git a/usr/local/bin/bastille b/usr/local/bin/bastille index be4ee758..5a9dffc7 100755 --- a/usr/local/bin/bastille +++ b/usr/local/bin/bastille @@ -130,8 +130,6 @@ 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 @@ -155,10 +153,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 diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index 3800aec5..4db5d0f5 100644 --- a/usr/local/share/bastille/clone.sh +++ b/usr/local/share/bastille/clone.sh @@ -197,7 +197,8 @@ 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_count="$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair ) | grep -Eo "[0-9]+" | sort -u | wc -l | awk '{print $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 diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index deeff781..bf71cf4a 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -286,10 +286,8 @@ 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_count="$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair ) | grep -Eo "[0-9]+" | sort -u | wc -l | awk '{print $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_count}" -gt 0 ]; then diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index 770dfb52..ea32e611 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -231,12 +231,13 @@ 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_count="$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair ) | grep -Eo "[0-9]+" | 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 _epair_num_range=$((_epair_count + 1)) if [ "${BRIDGE}" -eq 1 ]; then - if [ "${_epair_if_count}" -gt 0 ]; then + if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then if [ "$(echo -n "e${_num}a_${jail_name}" | awk '{print length}')" -lt 16 ]; then From 741d2c6e12aeb6004c97bb3808c1f8e8584e274b Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 16:10:09 -0600 Subject: [PATCH 22/63] fix shellcheck --- usr/local/share/bastille/common.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index bf71cf4a..ece20d74 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -121,7 +121,7 @@ check_target_is_stopped() { get_epair_count() { for _config in /usr/local/etc/bastille/*.conf; do local bastille_jailsdir="$(sysrc -f "${_config}" -n bastille_jailsdir)" - local _epair_list="$(printf '%s\n' $( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+") ${_epair_list} | sort -u)" + local _epair_list="$(printf '%s\n' "$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" done _epair_count="$(echo ${_epair_list} | wc -l | awk '{print $1}')" export _epair_count From c8e0cc0a78f41d15eeb501a25de29121f93ce314 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 16:24:05 -0600 Subject: [PATCH 23/63] fix BASTILLE_CONFIG var --- usr/local/bin/bastille | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/usr/local/bin/bastille b/usr/local/bin/bastille index 5a9dffc7..12de3d5d 100755 --- a/usr/local/bin/bastille +++ b/usr/local/bin/bastille @@ -128,14 +128,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 "/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 From 0590253acbd1541395dd0d2bc8f0125f440b1908 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 16:30:12 -0600 Subject: [PATCH 24/63] fix epair listin --- usr/local/share/bastille/common.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index ece20d74..680a1cef 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -123,7 +123,7 @@ get_epair_count() { local bastille_jailsdir="$(sysrc -f "${_config}" -n bastille_jailsdir)" local _epair_list="$(printf '%s\n' "$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" done - _epair_count="$(echo ${_epair_list} | wc -l | awk '{print $1}')" + _epair_count=$(printf '%s' "${_epair_list}" | wc -l | awk '{print $1}') export _epair_count } From 4d9d1d105030b9491d3e05b3fcca798780030e04 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 16:35:39 -0600 Subject: [PATCH 25/63] fix bastille listing --- usr/local/share/bastille/common.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 680a1cef..b7b9754a 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -292,7 +292,7 @@ generate_vnet_jail_netblock() { if [ -n "${use_unique_bridge}" ]; then if [ "${_epair_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|bastille${_num})"; then + if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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} @@ -317,7 +317,7 @@ generate_vnet_jail_netblock() { else if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "bastille${_num}" ${bastille_jailsdir}/*/jail.conf; then + if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then local uniq_epair="bastille${_num}" break fi From 22516288671b79751791ee235adca2104f9820b5 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 17:03:22 -0600 Subject: [PATCH 26/63] fix one last count --- usr/local/share/bastille/common.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index b7b9754a..303df0fa 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -292,7 +292,7 @@ generate_vnet_jail_netblock() { if [ -n "${use_unique_bridge}" ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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} @@ -317,7 +317,7 @@ generate_vnet_jail_netblock() { else if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then local uniq_epair="bastille${_num}" break fi From 353a63eef8344ddba401c53e828bbe7202c0eebd Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 17:04:51 -0600 Subject: [PATCH 27/63] fix clone and network numbering epair --- usr/local/share/bastille/clone.sh | 4 ++-- usr/local/share/bastille/network.sh | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index 4db5d0f5..80a53e69 100644 --- a/usr/local/share/bastille/clone.sh +++ b/usr/local/share/bastille/clone.sh @@ -203,7 +203,7 @@ update_jailconf_vnet() { 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 "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eoq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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}" @@ -272,7 +272,7 @@ update_jailconf_vnet() { elif echo ${_if} | grep -Eoq 'bastille[0-9]+'; then # Update VNET config for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eoq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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/network.sh b/usr/local/share/bastille/network.sh index ea32e611..a1e6a915 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -239,7 +239,7 @@ add_interface() { if [ "${BRIDGE}" -eq 1 ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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} From dd2a56af6d764240dbba9fa4e6c97b104dfc45c0 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 17:22:51 -0600 Subject: [PATCH 28/63] epair: Use full list --- usr/local/share/bastille/clone.sh | 4 ++-- usr/local/share/bastille/common.sh | 7 ++++--- usr/local/share/bastille/network.sh | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index 80a53e69..d1a00a0f 100644 --- a/usr/local/share/bastille/clone.sh +++ b/usr/local/share/bastille/clone.sh @@ -203,7 +203,7 @@ update_jailconf_vnet() { 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 "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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}" @@ -272,7 +272,7 @@ update_jailconf_vnet() { elif echo ${_if} | grep -Eoq 'bastille[0-9]+'; then # Update VNET config for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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 303df0fa..681b0ac7 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -121,9 +121,10 @@ check_target_is_stopped() { get_epair_count() { for _config in /usr/local/etc/bastille/*.conf; do local bastille_jailsdir="$(sysrc -f "${_config}" -n bastille_jailsdir)" - local _epair_list="$(printf '%s\n' "$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" + _epair_list="$(printf '%s\n' "$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" done _epair_count=$(printf '%s' "${_epair_list}" | wc -l | awk '{print $1}') + export _epair_list export _epair_count } @@ -292,7 +293,7 @@ generate_vnet_jail_netblock() { if [ -n "${use_unique_bridge}" ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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} @@ -317,7 +318,7 @@ generate_vnet_jail_netblock() { else if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then local uniq_epair="bastille${_num}" break fi diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index a1e6a915..e6a55a2d 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -239,7 +239,7 @@ add_interface() { if [ "${BRIDGE}" -eq 1 ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_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} From 745f312681e740e6f961845b810057113bf82de7 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 17:48:39 -0600 Subject: [PATCH 29/63] fix epair listing again --- usr/local/share/bastille/common.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 681b0ac7..58500a92 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -121,7 +121,7 @@ check_target_is_stopped() { 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' "$( (grep -Eos '(e[0-9]+b|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair) | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" + _epair_list="$(printf '%s\n' "$( (grep -Eo '(epair[0-9]+|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair | grep -Eo "_bastille[0-9]+$"; ifconfig -g epair | grep -v "bastille" | grep -Eo "e[0-9]+a_") | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" done _epair_count=$(printf '%s' "${_epair_list}" | wc -l | awk '{print $1}') export _epair_list From deab7e39f73081e64b21c46ce508d4cd70a7e2da Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 17:52:32 -0600 Subject: [PATCH 30/63] keep grep errors silent --- usr/local/share/bastille/common.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 58500a92..a3d24b09 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -121,7 +121,7 @@ check_target_is_stopped() { 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' "$( (grep -Eo '(epair[0-9]+|bastille[0-9]+)' ${bastille_jailsdir}/*/jail.conf; ifconfig -g epair | grep -Eo "_bastille[0-9]+$"; ifconfig -g epair | grep -v "bastille" | grep -Eo "e[0-9]+a_") | grep -Eo "[0-9]+")" "${_epair_list}" | sort -u)" + _epair_list="$(printf '%s\n' "$( (grep -Eos '(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}" | sort -u)" done _epair_count=$(printf '%s' "${_epair_list}" | wc -l | awk '{print $1}') export _epair_list @@ -404,4 +404,4 @@ checkyesno() { return 1 ;; esac -} \ No newline at end of file +} From 8c20d534d7133e7eddc951e04c7a11e55f150786 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 19:11:09 -0600 Subject: [PATCH 31/63] clone: Use epair list to find next epair number --- usr/local/share/bastille/clone.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index d1a00a0f..7d7a7990 100644 --- a/usr/local/share/bastille/clone.sh +++ b/usr/local/share/bastille/clone.sh @@ -203,7 +203,7 @@ update_jailconf_vnet() { if echo ${_if} | grep -Eoq 'epair[0-9]+'; then # Update bridged VNET config for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_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}" @@ -272,7 +272,7 @@ update_jailconf_vnet() { elif echo ${_if} | grep -Eoq 'bastille[0-9]+'; then # Update VNET config for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eoq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_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]+")" @@ -381,4 +381,4 @@ else usage fi -clone_jail \ No newline at end of file +clone_jail From aa411d26d09cb8df48bee350d3292d6e99597899 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 19:12:33 -0600 Subject: [PATCH 32/63] common: Better epair searching --- usr/local/share/bastille/common.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index a3d24b09..5d35a71d 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -121,9 +121,9 @@ check_target_is_stopped() { 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' "$( (grep -Eos '(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}" | sort -u)" + _epair_list="$(printf '%s\n%s' "$( (grep -Eos '(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}" | sort -u)" done - _epair_count=$(printf '%s' "${_epair_list}" | wc -l | awk '{print $1}') + _epair_count=$(printf '%s' "${_epair_list}" | sort -u | wc -l | awk '{print $1}') export _epair_list export _epair_count } @@ -293,7 +293,7 @@ generate_vnet_jail_netblock() { if [ -n "${use_unique_bridge}" ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_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} @@ -318,7 +318,7 @@ generate_vnet_jail_netblock() { else if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_num}"; then local uniq_epair="bastille${_num}" break fi From 9462d75fe9763b2dd5c002a4c4f84755d6782dac Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 19:15:16 -0600 Subject: [PATCH 33/63] network: Use epair list to find next epair --- usr/local/share/bastille/network.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index e6a55a2d..623c5b82 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -239,7 +239,7 @@ add_interface() { if [ "${BRIDGE}" -eq 1 ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}" && ! grep -Eosq "(bastille${_num}|epair${_num})" ${bastille_jailsdir}/*/jail.conf && ! ifconfig -g epair | grep -Eosq "(e${_num}a|epair${_num}a|bastille${_num})"; then + if ! echo "${_epair_list}" | grep -osq "${_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,7 +312,7 @@ EOF elif [ "${VNET}" -eq 1 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! grep -Eq "(bastille${_num}|epair${_num})" "${bastille_jailsdir}"/*/jail.conf; then + if ! echo "${_epair_list}" | grep -osq "${_num}"; then local bastille_epair="bastille${_num}" break fi From e70d8b0a1ec3a15507fc3ef41ae8bd96eab8a84b Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 20:00:38 -0600 Subject: [PATCH 34/63] Update network.sh --- usr/local/share/bastille/network.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index 623c5b82..881f29d7 100644 --- a/usr/local/share/bastille/network.sh +++ b/usr/local/share/bastille/network.sh @@ -239,7 +239,7 @@ add_interface() { if [ "${BRIDGE}" -eq 1 ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}"; then + 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,7 +312,7 @@ EOF elif [ "${VNET}" -eq 1 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}"; then + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then local bastille_epair="bastille${_num}" break fi From 9091fa3880e0a9b822e312bd2aad0b5bd36ae0c7 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 20:01:15 -0600 Subject: [PATCH 35/63] Update clone.sh --- usr/local/share/bastille/clone.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/usr/local/share/bastille/clone.sh b/usr/local/share/bastille/clone.sh index 7d7a7990..cb24c9fa 100644 --- a/usr/local/share/bastille/clone.sh +++ b/usr/local/share/bastille/clone.sh @@ -203,7 +203,7 @@ update_jailconf_vnet() { if echo ${_if} | grep -Eoq 'epair[0-9]+'; then # Update bridged VNET config for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}"; then + 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}" @@ -272,7 +272,7 @@ update_jailconf_vnet() { elif echo ${_if} | grep -Eoq 'bastille[0-9]+'; then # Update VNET config for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}"; then + 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]+")" From 82d3a18366915d16bda414a7b8f04ecb56ac07a1 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Wed, 16 Apr 2025 20:02:41 -0600 Subject: [PATCH 36/63] Update common.sh --- usr/local/share/bastille/common.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/usr/local/share/bastille/common.sh b/usr/local/share/bastille/common.sh index 5d35a71d..a5430a5a 100644 --- a/usr/local/share/bastille/common.sh +++ b/usr/local/share/bastille/common.sh @@ -121,7 +121,7 @@ check_target_is_stopped() { 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 -Eos '(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}" | sort -u)" + _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 @@ -293,7 +293,7 @@ generate_vnet_jail_netblock() { if [ -n "${use_unique_bridge}" ]; then if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}"; then + 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} @@ -318,7 +318,7 @@ generate_vnet_jail_netblock() { else if [ "${_epair_count}" -gt 0 ]; then for _num in $(seq 0 "${_epair_num_range}"); do - if ! echo "${_epair_list}" | grep -osq "${_num}"; then + if ! echo "${_epair_list}" | grep -oqswx "${_num}"; then local uniq_epair="bastille${_num}" break fi From 531b5d14bf23f4387496b3d98a19805f7ffd9f31 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:01:00 -0600 Subject: [PATCH 37/63] stop: Small typo clarification --- usr/local/share/bastille/stop.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/stop.sh b/usr/local/share/bastille/stop.sh index d0d080a6..f26890cb 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 to wait after stopping each jail. -v | --verbose Print every action on jail stop. -x | --debug Enable debug mode. From 1a68f3db0be7f459f629d08c1a41fa818989ec56 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:01:32 -0600 Subject: [PATCH 38/63] start: Small typo clarification --- usr/local/share/bastille/start.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/start.sh b/usr/local/share/bastille/start.sh index 44f518b8..c73a4cf9 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 to wait after starting each jail. -v | --verbose Print every action on jail start. -x | --debug Enable debug mode. From ce6f0ac953cc2f392d5185bda81c40c41383816e Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:02:38 -0600 Subject: [PATCH 39/63] restart: Small typo clarification --- usr/local/share/bastille/restart.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/restart.sh b/usr/local/share/bastille/restart.sh index ebc70dd7..cd2f9072 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 to wait after starting/stopping jail(s). -v | --verbose Print every action on jail start. -x | --debug Enable debug mode. From 5a46f36456298f40f4894b1fdfce181732549141 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:04:51 -0600 Subject: [PATCH 40/63] Update start.sh --- usr/local/share/bastille/start.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/start.sh b/usr/local/share/bastille/start.sh index c73a4cf9..ef6f200d 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 after starting each jail. + -d | --delay VALUE Time to wait after starting jail(s). -v | --verbose Print every action on jail start. -x | --debug Enable debug mode. From 91e230156b154183c0c9651a09fe3c84b8d4f935 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:05:45 -0600 Subject: [PATCH 41/63] Update stop.sh --- usr/local/share/bastille/stop.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/stop.sh b/usr/local/share/bastille/stop.sh index f26890cb..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 after 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. From 72b434bf649f6e8b4f615e245587e0e54792b3ba Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:06:02 -0600 Subject: [PATCH 42/63] Update start.sh --- usr/local/share/bastille/start.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/start.sh b/usr/local/share/bastille/start.sh index ef6f200d..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 after starting jail(s). + -d | --delay VALUE Time (seconds) to wait after starting jail(s). -v | --verbose Print every action on jail start. -x | --debug Enable debug mode. From a46c62686657cf66a61f89ceb6381a5a48d02365 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:06:42 -0600 Subject: [PATCH 43/63] Update restart.sh --- usr/local/share/bastille/restart.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/usr/local/share/bastille/restart.sh b/usr/local/share/bastille/restart.sh index cd2f9072..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 after starting/stopping jail(s). + -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. From 053e013a355cf71573822ccc60ebaa6ee06175de Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:07:49 -0600 Subject: [PATCH 44/63] Update restart.rst --- docs/chapters/subcommands/restart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/chapters/subcommands/restart.rst b/docs/chapters/subcommands/restart.rst index 2f3bf9cc..538620cc 100644 --- a/docs/chapters/subcommands/restart.rst +++ b/docs/chapters/subcommands/restart.rst @@ -19,6 +19,6 @@ Restart jail(s). Options: -b | --boot Respect jail boot setting. - -d | --delay VALUE Time to wait between starting each jail. + -d | --delay VALUE Time (seconds) to wait between starting jails(s). -v | --verbose Print every action on jail start. - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. From 2525c0cfd8952f7da8ec59491ca202d51c1aceab Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:08:18 -0600 Subject: [PATCH 45/63] Update start.rst --- docs/chapters/subcommands/start.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/start.rst b/docs/chapters/subcommands/start.rst index 09a798b1..54be65bc 100644 --- a/docs/chapters/subcommands/start.rst +++ b/docs/chapters/subcommands/start.rst @@ -16,6 +16,6 @@ Start jail(s). 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. From 26a5de91ab577452e4d97ce5ec12ca59aae223f3 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:08:46 -0600 Subject: [PATCH 46/63] Update stop.rst --- docs/chapters/subcommands/stop.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/stop.rst b/docs/chapters/subcommands/stop.rst index 851458fb..4a9ff050 100644 --- a/docs/chapters/subcommands/stop.rst +++ b/docs/chapters/subcommands/stop.rst @@ -16,6 +16,6 @@ Stop jail(s). 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. From ac2b37e56e3f18969977c9446a04f269cfd0b47d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:09:16 -0600 Subject: [PATCH 47/63] Update restart.rst --- docs/chapters/subcommands/restart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/restart.rst b/docs/chapters/subcommands/restart.rst index 538620cc..fe78b3ae 100644 --- a/docs/chapters/subcommands/restart.rst +++ b/docs/chapters/subcommands/restart.rst @@ -19,6 +19,6 @@ Restart jail(s). Options: -b | --boot Respect jail boot setting. - -d | --delay VALUE Time (seconds) to wait between starting jails(s). + -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. From fd70aa6526d6c918d9455be82da15b35b186e81c Mon Sep 17 00:00:00 2001 From: Lars E <1733402+bsdlme@users.noreply.github.com> Date: Fri, 18 Apr 2025 22:18:52 +0200 Subject: [PATCH 48/63] upgrading.rst: fix typo reslove -> resolve --- docs/chapters/upgrading.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index fce25ddd..a0fb1f31 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -33,7 +33,7 @@ Thin Jails 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 +7. Use ``bastille etcupdate TARGET resolve`` to resolve any conflicts 8. Start the jail(s) 9. Upgrade complete! From 2bfee0b2060c993d8b9e761025e28a247e317b1d Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sat, 19 Apr 2025 10:15:49 -0500 Subject: [PATCH 49/63] doc: cmd, removes unneeded quotation mark --- docs/chapters/subcommands/cmd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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. From 5de80fc27c300dee222d3539973fbaa43afd5e4a Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sat, 19 Apr 2025 10:20:22 -0500 Subject: [PATCH 50/63] doc: targeting, changes command for subcommand for consistency --- docs/chapters/targeting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index ed1b770e..e416e980 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -1,7 +1,7 @@ Targeting ========= -Bastille uses a ``command TARGET ARGS`` 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 From e9b267d882e7b5c54c7bb899db1141933795b7e2 Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sat, 19 Apr 2025 12:21:08 -0500 Subject: [PATCH 51/63] setup: fix to use the new BASTILLE_CONFIG variable This helps restore the autoconfiguration for ZFS --- usr/local/share/bastille/setup.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/usr/local/share/bastille/setup.sh b/usr/local/share/bastille/setup.sh index 71b9d1c0..6f8ec64c 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 } From e41a1e23bead18343a8c6c2870c77b8abfd7a70c Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sat, 19 Apr 2025 13:21:15 -0500 Subject: [PATCH 52/63] doc: destroy, typo --- docs/chapters/subcommands/destroy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst index 066944fe..e7bfc629 100644 --- a/docs/chapters/subcommands/destroy.rst +++ b/docs/chapters/subcommands/destroy.rst @@ -15,7 +15,7 @@ the ``-a|--auto`` option will automatically stop the jail before destroying it. /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. +will retain the release cache directory, if you choose to keep it. .. code-block:: shell From 7b3e6a087c1e1cb186d11f8e1d6ea05972c3677b Mon Sep 17 00:00:00 2001 From: Barry McCormick Date: Sun, 20 Apr 2025 08:07:32 -0700 Subject: [PATCH 53/63] documentation updates to match current state of code --- docs/chapters/gettingstarted.rst | 2 +- docs/chapters/installation.rst | 6 +- docs/chapters/networking.rst | 33 ++++- docs/chapters/zfs-support.rst | 11 +- usr/local/bin/bastille.orig | 208 +++++++++++++++++++++++++++++++ 5 files changed, 251 insertions(+), 9 deletions(-) create mode 100755 usr/local/bin/bastille.orig diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst index 56f75b81..86230d79 100644 --- a/docs/chapters/gettingstarted.rst +++ b/docs/chapters/gettingstarted.rst @@ -4,7 +4,7 @@ Getting Started This guide is meant to get you up and running with bastille, and will show you a number of different options to create and manage your jails. -The first step is running ``bastille setup`` to try to configure bastille initially. +The first step is running ``bastille setup`` to try to configure bastille initially, if you didn't during setup. Setup should only be run once. .. code-block:: shell diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index 2058ff2d..fe6f9288 100644 --- a/docs/chapters/installation.rst +++ b/docs/chapters/installation.rst @@ -18,7 +18,7 @@ pkg .. code-block:: shell pkg install bastille - sysrc bastille_enable=YES + bastille setup To install from source (don't worry, no compiling): @@ -28,7 +28,7 @@ ports .. code-block:: shell make -C /usr/ports/sysutils/bastille install clean - sysrc bastille_enable=YES + bastille setup git --- @@ -38,7 +38,7 @@ git git clone https://github.com/BastilleBSD/bastille.git cd bastille make install - sysrc bastille_enable=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 diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 90c9a869..b0652e2b 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -221,7 +221,36 @@ 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 ---------------- @@ -389,4 +418,4 @@ To resolve this, add the following configuration to local_unbound: Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf -Adjust the above "access-control" strings to fit your network. \ No newline at end of file +Adjust the above "access-control" strings to fit your network. diff --git a/docs/chapters/zfs-support.rst b/docs/chapters/zfs-support.rst index 52a0c7d7..7bf3c763 100644 --- a/docs/chapters/zfs-support.rst +++ b/docs/chapters/zfs-support.rst @@ -4,14 +4,19 @@ 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" diff --git a/usr/local/bin/bastille.orig b/usr/local/bin/bastille.orig new file mode 100755 index 00000000..d2449b4a --- /dev/null +++ b/usr/local/bin/bastille.orig @@ -0,0 +1,208 @@ +#!/bin/sh +# +# SPDX-License-Identifier: BSD-3-Clause +# +# Copyright (c) 2018-2025, Christer Edwards +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# * Neither the name of the copyright holder nor the names of its +# contributors may be used to endorse or promote products derived from +# this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +PATH=${PATH}:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin + +## check for config existence +bastille_conf_check() { + if [ ! -r "/usr/local/etc/bastille/bastille.conf" ]; then + echo "[INFO] Configuration file not found. Do you want to create it with default values? [y/N]" + read answer + case "${answer}" in + [Nn][Oo]|[Nn]|"") + echo "[INFO] No configuration file has been generated. Exiting." + exit + ;; + [Yy][Ee][Ss]|[Yy]) + cp /usr/local/etc/bastille/bastille.conf.sample /usr/local/etc/bastille/bastille.conf + echo "[INFO] Configuration file has been generated. Continuing with default values" + ;; + *) + echo "[ERROR] Invalid option. Please answer with 'y' or 'N'." + exit 1 + ;; + esac + fi +} + +bastille_conf_check + +## we only load this if conf_check passes +. /usr/local/share/bastille/common.sh +. /usr/local/etc/bastille/bastille.conf + +## bastille_prefix should be 0750 +## this restricts file system access to privileged users +bastille_perms_check() { + if [ -d "${bastille_prefix}" ]; then + BASTILLE_PREFIX_PERMS=$(stat -f "%Op" "${bastille_prefix}") + if [ "${BASTILLE_PREFIX_PERMS}" != 40750 ]; then + error_notify "Insecure permissions on ${bastille_prefix}" + error_exit "Try: chmod 0750 ${bastille_prefix}" + fi + fi +} + +bastille_perms_check + +## version +BASTILLE_VERSION=c6297d7 + +usage() { + cat << EOF +Bastille is an open-source system for automating deployment and management of +containerized applications on FreeBSD. + +Usage: + bastille command TARGET [args] + +Available Commands: + bootstrap Bootstrap a FreeBSD release for container base. + clone Clone an existing container. + cmd Execute arbitrary command on targeted container(s). + config Get or set a config value for the targeted container(s). + console Console into a running container. + convert Convert a Thin container into a Thick container. + cp cp(1) files from host to jail(s). + create Create a new thin container or a thick container if -T|--thick option specified. + destroy Destroy a stopped container or a FreeBSD release. + edit Edit container configuration files (advanced). + etcupdate Update /etc directory to specified release. + 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. + limits Apply resources limits to targeted container(s). See rctl(8). + list List containers (running). + mount Mount a volume inside the targeted container(s). + pkg Manipulate binary packages within targeted container(s). See pkg(8). + rcp cp(1) files from a jail to host. + rdr Redirect host port to container port. + rename Rename a container. + restart Restart a running container. + service Manage services within targeted container(s). + setup Attempt to auto-configure network, firewall and storage on new installs. + start Start a stopped container. + stop Stop a running container. + sysrc Safely edit rc files within targeted container(s). + tags Add or remove tags to targeted container(s). + template Apply file templates to targeted container(s). + top Display and update information about the top(1) cpu processes. + umount Unmount a volume from within the targeted container(s). + update Update container base -pX release. + upgrade Upgrade container release to X.Y-RELEASE. + verify Compare release against a "known good" index. + zfs Manage (get|set) ZFS attributes on targeted container(s). + +Use "bastille -v|--version" for version information. +Use "bastille command -h|--help" for more information about a command. + +EOF + exit 1 +} + +if [ "$#" -lt 1 ]; then + usage +else + CMD="${1}" + shift +fi + +# Handle special-case commands first. +case "${CMD}" in + version|-v|--version) + info "${BASTILLE_VERSION}" + exit 0 + ;; + help|-h|--help) + usage + ;; + bootstrap| \ + clone| \ + cmd| \ + config| \ + console| \ + convert| \ + cp| \ + create| \ + destroy| \ + edit| \ + etcupdate| \ + export| \ + htop| \ + jcp | \ + import| \ + limits| \ + list| \ + mount| \ + network| \ + pkg| \ + rcp| \ + rdr| \ + rename| \ + restart| \ + service| \ + setup| \ + start| \ + stop| \ + sysrc| \ + tags| \ + template| \ + top| \ + umount| \ + update| \ + upgrade| \ + verify| \ + zfs) + ;; + *) + usage + ;; +esac + +# shellcheck disable=SC2154 +SCRIPTPATH="${bastille_sharedir}/${CMD}.sh" +if [ -f "${SCRIPTPATH}" ]; then + : "${UMASK:=022}" + umask "${UMASK}" + + : "${SH:=sh}" + + if [ -n "${PARAMS}" ]; then + exec "${SH}" "${SCRIPTPATH}" "${PARAMS}" + else + exec "${SH}" "${SCRIPTPATH}" "$@" + fi +else + error_exit "${SCRIPTPATH} not found." +fi From 6f255bd3ba191dfeffb7e771d2da96ba3504c719 Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 10:41:00 -0500 Subject: [PATCH 54/63] bastille: keep alphabetical order for commands --- usr/local/bin/bastille | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/usr/local/bin/bastille b/usr/local/bin/bastille index 12de3d5d..0056287d 100755 --- a/usr/local/bin/bastille +++ b/usr/local/bin/bastille @@ -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). @@ -201,8 +201,8 @@ case "${CMD}" in etcupdate| \ export| \ htop| \ - jcp | \ import| \ + jcp| \ limits| \ list| \ mount| \ @@ -246,4 +246,4 @@ if [ -f "${SCRIPTPATH}" ]; then fi else error_exit "${SCRIPTPATH} not found." -fi \ No newline at end of file +fi From 6f73360cd5436542ac0d89a4408ad3d8ba5b504d Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 10:42:48 -0500 Subject: [PATCH 55/63] bastille: remove unwanted file --- usr/local/bin/bastille.orig | 208 ------------------------------------ 1 file changed, 208 deletions(-) delete mode 100755 usr/local/bin/bastille.orig diff --git a/usr/local/bin/bastille.orig b/usr/local/bin/bastille.orig deleted file mode 100755 index d2449b4a..00000000 --- a/usr/local/bin/bastille.orig +++ /dev/null @@ -1,208 +0,0 @@ -#!/bin/sh -# -# SPDX-License-Identifier: BSD-3-Clause -# -# Copyright (c) 2018-2025, Christer Edwards -# All rights reserved. -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions are met: -# -# * Redistributions of source code must retain the above copyright notice, this -# list of conditions and the following disclaimer. -# -# * Redistributions in binary form must reproduce the above copyright notice, -# this list of conditions and the following disclaimer in the documentation -# and/or other materials provided with the distribution. -# -# * Neither the name of the copyright holder nor the names of its -# contributors may be used to endorse or promote products derived from -# this software without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -PATH=${PATH}:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin - -## check for config existence -bastille_conf_check() { - if [ ! -r "/usr/local/etc/bastille/bastille.conf" ]; then - echo "[INFO] Configuration file not found. Do you want to create it with default values? [y/N]" - read answer - case "${answer}" in - [Nn][Oo]|[Nn]|"") - echo "[INFO] No configuration file has been generated. Exiting." - exit - ;; - [Yy][Ee][Ss]|[Yy]) - cp /usr/local/etc/bastille/bastille.conf.sample /usr/local/etc/bastille/bastille.conf - echo "[INFO] Configuration file has been generated. Continuing with default values" - ;; - *) - echo "[ERROR] Invalid option. Please answer with 'y' or 'N'." - exit 1 - ;; - esac - fi -} - -bastille_conf_check - -## we only load this if conf_check passes -. /usr/local/share/bastille/common.sh -. /usr/local/etc/bastille/bastille.conf - -## bastille_prefix should be 0750 -## this restricts file system access to privileged users -bastille_perms_check() { - if [ -d "${bastille_prefix}" ]; then - BASTILLE_PREFIX_PERMS=$(stat -f "%Op" "${bastille_prefix}") - if [ "${BASTILLE_PREFIX_PERMS}" != 40750 ]; then - error_notify "Insecure permissions on ${bastille_prefix}" - error_exit "Try: chmod 0750 ${bastille_prefix}" - fi - fi -} - -bastille_perms_check - -## version -BASTILLE_VERSION=c6297d7 - -usage() { - cat << EOF -Bastille is an open-source system for automating deployment and management of -containerized applications on FreeBSD. - -Usage: - bastille command TARGET [args] - -Available Commands: - bootstrap Bootstrap a FreeBSD release for container base. - clone Clone an existing container. - cmd Execute arbitrary command on targeted container(s). - config Get or set a config value for the targeted container(s). - console Console into a running container. - convert Convert a Thin container into a Thick container. - cp cp(1) files from host to jail(s). - create Create a new thin container or a thick container if -T|--thick option specified. - destroy Destroy a stopped container or a FreeBSD release. - edit Edit container configuration files (advanced). - etcupdate Update /etc directory to specified release. - 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. - limits Apply resources limits to targeted container(s). See rctl(8). - list List containers (running). - mount Mount a volume inside the targeted container(s). - pkg Manipulate binary packages within targeted container(s). See pkg(8). - rcp cp(1) files from a jail to host. - rdr Redirect host port to container port. - rename Rename a container. - restart Restart a running container. - service Manage services within targeted container(s). - setup Attempt to auto-configure network, firewall and storage on new installs. - start Start a stopped container. - stop Stop a running container. - sysrc Safely edit rc files within targeted container(s). - tags Add or remove tags to targeted container(s). - template Apply file templates to targeted container(s). - top Display and update information about the top(1) cpu processes. - umount Unmount a volume from within the targeted container(s). - update Update container base -pX release. - upgrade Upgrade container release to X.Y-RELEASE. - verify Compare release against a "known good" index. - zfs Manage (get|set) ZFS attributes on targeted container(s). - -Use "bastille -v|--version" for version information. -Use "bastille command -h|--help" for more information about a command. - -EOF - exit 1 -} - -if [ "$#" -lt 1 ]; then - usage -else - CMD="${1}" - shift -fi - -# Handle special-case commands first. -case "${CMD}" in - version|-v|--version) - info "${BASTILLE_VERSION}" - exit 0 - ;; - help|-h|--help) - usage - ;; - bootstrap| \ - clone| \ - cmd| \ - config| \ - console| \ - convert| \ - cp| \ - create| \ - destroy| \ - edit| \ - etcupdate| \ - export| \ - htop| \ - jcp | \ - import| \ - limits| \ - list| \ - mount| \ - network| \ - pkg| \ - rcp| \ - rdr| \ - rename| \ - restart| \ - service| \ - setup| \ - start| \ - stop| \ - sysrc| \ - tags| \ - template| \ - top| \ - umount| \ - update| \ - upgrade| \ - verify| \ - zfs) - ;; - *) - usage - ;; -esac - -# shellcheck disable=SC2154 -SCRIPTPATH="${bastille_sharedir}/${CMD}.sh" -if [ -f "${SCRIPTPATH}" ]; then - : "${UMASK:=022}" - umask "${UMASK}" - - : "${SH:=sh}" - - if [ -n "${PARAMS}" ]; then - exec "${SH}" "${SCRIPTPATH}" "${PARAMS}" - else - exec "${SH}" "${SCRIPTPATH}" "$@" - fi -else - error_exit "${SCRIPTPATH} not found." -fi From 0f04b1be79c24636a546b17c424ec4709d901529 Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 10:45:54 -0500 Subject: [PATCH 56/63] network: Adding SPDX identifier --- usr/local/share/bastille/network.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/usr/local/share/bastille/network.sh b/usr/local/share/bastille/network.sh index 881f29d7..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. # @@ -596,4 +598,4 @@ case "${ACTION}" in *) error_exit "Only [add|remove] are supported." ;; -esac \ No newline at end of file +esac From 4c9947689ea4828d73dc66bf3c42ee9b96f21b34 Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 10:53:26 -0500 Subject: [PATCH 57/63] doc: gettingstarted.rst typos --- docs/chapters/gettingstarted.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst index 86230d79..68ce8130 100644 --- a/docs/chapters/gettingstarted.rst +++ b/docs/chapters/gettingstarted.rst @@ -20,7 +20,7 @@ Next we can create our first jail. Bastille can create a few different types of * Thin jails are the default, and are called thin because they use symlinks to the bootstrapped release. They are lightweight and are created quickly. -* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independant of the release. Created with ``bastille create -T``. +* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independent of the release. Created with ``bastille create -T``. * Clone jails are essentially clones of the bootstrapped release. Changes to the release will affect the clone jail. Created with ``bastille create -C``. @@ -84,4 +84,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 From 2390245a32a79fa34b8f4030bda13cf81057e51f Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 11:19:18 -0500 Subject: [PATCH 58/63] doc: general reformatting to use 80 columns in the text --- docs/chapters/boot-and-priority.rst | 37 ++++--- docs/chapters/configuration.rst | 48 ++++++--- docs/chapters/gcp.rst | 28 +++-- docs/chapters/gettingstarted.rst | 51 +++++---- docs/chapters/migration.rst | 9 +- docs/chapters/networking.rst | 132 ++++++++++++++++-------- docs/chapters/subcommands/bootstrap.rst | 21 ++-- docs/chapters/subcommands/clone.rst | 2 +- docs/chapters/subcommands/console.rst | 5 +- docs/chapters/subcommands/create.rst | 40 ++++--- docs/chapters/subcommands/destroy.rst | 10 +- docs/chapters/subcommands/etcupdate.rst | 8 +- docs/chapters/subcommands/htop.rst | 4 +- docs/chapters/subcommands/limits.rst | 3 +- docs/chapters/subcommands/list.rst | 3 +- docs/chapters/subcommands/mount.rst | 20 ++-- docs/chapters/subcommands/network.rst | 25 ++++- docs/chapters/subcommands/pkg.rst | 6 +- docs/chapters/subcommands/rdr.rst | 10 +- docs/chapters/subcommands/service.rst | 4 +- docs/chapters/subcommands/setup.rst | 4 +- docs/chapters/subcommands/template.rst | 5 +- docs/chapters/subcommands/umount.rst | 3 +- docs/chapters/subcommands/update.rst | 10 +- docs/chapters/subcommands/upgrade.rst | 5 +- docs/chapters/subcommands/verify.rst | 10 +- docs/chapters/subcommands/zfs.rst | 3 +- docs/chapters/targeting.rst | 29 +++--- docs/chapters/template.rst | 69 +++++++------ docs/chapters/upgrading.rst | 71 ++++++++----- docs/chapters/zfs-support.rst | 32 ++++-- docs/copyright.rst | 4 +- 32 files changed, 443 insertions(+), 268 deletions(-) diff --git a/docs/chapters/boot-and-priority.rst b/docs/chapters/boot-and-priority.rst index fff7cb09..713170aa 100644 --- a/docs/chapters/boot-and-priority.rst +++ b/docs/chapters/boot-and-priority.rst @@ -4,20 +4,24 @@ Boot and Priority Boot ---- -The boot setting controls whether a jail will be started on system startup. If you have enabled bastille -with ``sysrc bastille_enable=YES``, all jails with ``boot=on`` will start on system startup. Any jail(s) -with ``boot=off`` will not be started on system startup. +The boot setting controls whether a jail will be started on system startup. If +you have enabled bastille with ``sysrc bastille_enable=YES``, all jails with +``boot=on`` will start on system startup. Any jail(s) with ``boot=off`` will not +be started on system startup. -You can also use ``bastille start --boot TARGET`` to make Bastille respect the boot setting. If ``-b|--boot`` is not -used, the targeted jail(s) will start, regardless of the boot setting. +You can also use ``bastille start --boot TARGET`` to make Bastille respect the +boot setting. If ``-b|--boot`` is not used, the targeted jail(s) will start, +regardless of the boot setting. Jails will still shut down on system shutdown, regardless of this setting. -The ``-b|--boot`` can also be used with the ``stop`` command. Any jails with ``boot=off`` will -not be touched if ``stop`` is called with ``-b|--boot``. Same goes for the ``restart`` command. +The ``-b|--boot`` can also be used with the ``stop`` command. Any jails with +``boot=off`` will not be touched if ``stop`` is called with ``-b|--boot``. Same +goes for the ``restart`` command. -When jails are created with Bastille, the boot setting is set to ``on`` by default. This can be overridden using -the ``--no-boot`` flag. See ``bastille create --no-boot TARGET...``. +When jails are created with Bastille, the boot setting is set to ``on`` by +default. This can be overridden using the ``--no-boot`` flag. See ``bastille +create --no-boot TARGET...``. This value can be changed using ``bastille config TARGET boot [on|off]``. @@ -26,13 +30,16 @@ This value will be shown using ``bastille list all``. Priority -------- -The priority value determines in what order commands are executed if multiple jails are targetted. This also controls -in what order jails are started and stopped on system startup and shutdown. This requires Bastille to be enabled -with ``sysrc bastille_enable=YES``. Jails will start in order starting at the lowest value, and will stop in order starting -at the highest value. So, jails with a priority value of 1 will start first, and stop last. +The priority value determines in what order commands are executed if multiple +jails are targetted. This also controls in what order jails are started and +stopped on system startup and shutdown. This requires Bastille to be enabled +with ``sysrc bastille_enable=YES``. Jails will start in order starting at the +lowest value, and will stop in order starting at the highest value. So, jails +with a priority value of 1 will start first, and stop last. -When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on -creation. See ``bastille create --priority 90 TARGET...``. +When jails are created with Bastille, this value defaults to ``99``, but can be +overridden with ``-p|--priority VALUE`` on creation. See ``bastille create +--priority 90 TARGET...``. This value can be changed using ``bastille config TARGET priority VALUE``. diff --git a/docs/chapters/configuration.rst b/docs/chapters/configuration.rst index 38ef7617..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 should run ``bastille setup``. This will ask if you want to copy the sample config file to the above location. The defaults are sensible for UFS, but -if you want to use ZFS, you will have to change a few options. See the chapter on ZFS Support. +Bastille is configured using a default config file located at +``/usr/local/etc/bastille/bastille.conf``. When first installing bastille, you +should run ``bastille setup``. This will ask if you want to copy the sample +config file to the above location. The defaults are sensible for UFS, but if you +want to use ZFS, you will have to change a few options. See the chapter on ZFS +Support. This is the default `bastille.conf` file. @@ -83,26 +86,45 @@ Notes The options here are fairly self-explanitory, but there are some things to note. -* If you use ZFS, DO NOT create the bastille dataset. You must only create the parent. Bastille must be allowed to create the ``bastille`` child dataset, or you will have issues. So, if you want bastille to live at ``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and ``bastille_zfs_prefix`` to ``data/bastille`` but you should only create ``zroot/data`` before running bastille for the first time. +* If you use ZFS, DO NOT create the bastille dataset. You must only create the + parent. Bastille must be allowed to create the ``bastille`` child dataset, or + you will have issues. So, if you want bastille to live at + ``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and + ``bastille_zfs_prefix`` to ``data/bastille`` but you should only create + ``zroot/data`` before running bastille for the first time. -* Bastille will mount the dataset it creates at ``bastille_prefix`` which defaults to ``/usr/local/bastille``. So if you want to navigate to your jails, you will use the ``bastille_prefix`` as the location because this is where the will be mounted. +* Bastille will mount the dataset it creates at ``bastille_prefix`` which + defaults to ``/usr/local/bastille``. So if you want to navigate to your jails, + you will use the ``bastille_prefix`` as the location because this is where the + will be mounted. Custom Configuration -------------------- -Bastille now supports using a custom config in addition to the default one. This is nice if you have multiple users, or want to store different +Bastille now supports using a custom config in addition to the default one. This +is nice if you have multiple users, or want to store different jails at different locations based on your needs. -The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at ``/usr/local/etc/bastille`` or it will not work. +The customized config file MUST BE PLACED INSIDE THE BASTILLE CONFIG FOLDER at +``/usr/local/etc/bastille`` or it will not work. -Simply copy the default config file and edit it according to your new environment or user. Then, it can be used in a couple of ways. +Simply copy the default config file and edit it according to your new +environment or user. Then, it can be used in a couple of ways. -1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE`` to bootstrap the release using the new config. +1. Run Bastille using ``bastille --config config.conf bootstrap 14.2-RELEASE`` + to bootstrap the release using the new config. -2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export BASTILLE_CONFIG=config.conf``. This config will then always be used when running Bastille with that user. See notes below... +2. As a specific user, export the ``BASTILLE_CONFIG`` variable using ``export + BASTILLE_CONFIG=config.conf``. This config will then always be used when + running Bastille with that user. See notes below... -- Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current session. If you want to persist the export, see documentation for the shell that you use. +- Exporting the ``BASTILLE_CONFIG`` variable will only export it for the current +session. If you want to persist the export, see documentation for the shell that +you use. -- If you use sudo, you will need to run it with ``sudo -E bastille bootstrap...`` to preserve your users environment. This can also be persisted by editing the sudoers file. +- If you use sudo, you will need to run it with ``sudo -E bastille +bootstrap...`` to preserve your users environment. This can also be persisted by +editing the sudoers file. -- If you do set the ``BASTILLE_CONFIG`` variable, you do not need to specify the config file when running Bastille as that specified user. +- If you do set the ``BASTILLE_CONFIG`` variable, you do not need to specify the +config file when running Bastille as that specified user. diff --git a/docs/chapters/gcp.rst b/docs/chapters/gcp.rst index b049337b..e2eb12a5 100644 --- a/docs/chapters/gcp.rst +++ b/docs/chapters/gcp.rst @@ -3,16 +3,17 @@ Bastille VNET on GCP Bastille VNET runs on GCP with a few small tweaks. In summary, they are: -- change MTU setting in jib script -- add an IP address to the bridge interface -- configure host pf to NAT and allow bridge traffic -- set defaultrouter and nameserver in the host +- change MTU setting in jib script - add an IP address to the bridge interface - +configure host pf to NAT and allow bridge traffic - set defaultrouter and +nameserver in the host ## Change MTU in the jib script -GCP uses ``vtnet`` with MTU 1460, which [jib fails on](https://github.com/BastilleBSD/bastille/issues/538). +GCP uses ``vtnet`` with MTU 1460, which [jib fails +on](https://github.com/BastilleBSD/bastille/issues/538). -Apply the below patch to set the correct MTU. You may need to ``cp /usr/share/examples/jails/jib /usr/local/bin/`` first. +Apply the below patch to set the correct MTU. You may need to ``cp +/usr/share/examples/jails/jib /usr/local/bin/`` first. ``patch /usr/local/bin/jib jib.patch`` @@ -39,7 +40,8 @@ Apply the below patch to set the correct MTU. You may need to ``cp /usr/share/ex ## Configure bridge interface -Configure the bridge interface in /etc/rc.conf so it is available in the firewall rules. +Configure the bridge interface in /etc/rc.conf so it is available in the +firewall rules. .. code-block:: shell sysrc cloned_interfaces="bridge0" @@ -49,7 +51,8 @@ Configure the bridge interface in /etc/rc.conf so it is available in the firewal ## Configure host pf -This basic /etc/pf.conf allow incoming packets on the bridge interface, and NATs them through the external interface: +This basic /etc/pf.conf allow incoming packets on the bridge interface, and NATs +them through the external interface: .. code-block:: text ext_if="vtnet0" @@ -68,7 +71,8 @@ This basic /etc/pf.conf allow incoming packets on the bridge interface, and NATs pass in inet proto icmp icmp-type { echoreq } pass in on $bridge_if -Restart the host and make sure everything comes up correctly. You should see the following ifconfig: +Restart the host and make sure everything comes up correctly. You should see the +following ifconfig: .. code-block:: text vtnet0bridge: flags=8843 metric 0 mtu 1460 @@ -83,11 +87,13 @@ Restart the host and make sure everything comes up correctly. You should see the ## Configure router and resolver for new jails -Set the default network gateway for new jails as described in the Networking chapter, and configure a default resolver. +Set the default network gateway for new jails as described in the Networking +chapter, and configure a default resolver. .. code-block:: shell sysrc -f /usr/local/etc/bastille/bastille.conf bastille_network_gateway="192.168.1.1" echo "nameserver 8.8.8.8" > /usr/local/etc/bastille/resolv.conf sysrc -f /usr/local/etc/bastille/bastille.conf bastille_resolv_conf="/usr/local/etc/bastille/resolv.conf" -You can now create a VNET jail with ``bastille create -V myjail 13.2-RELEASE 192.168.1.50/24 vtnet0`` +You can now create a VNET jail with ``bastille create -V myjail 13.2-RELEASE +192.168.1.50/24 vtnet0`` diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst index 68ce8130..4645c7bc 100644 --- a/docs/chapters/gettingstarted.rst +++ b/docs/chapters/gettingstarted.rst @@ -1,30 +1,38 @@ Getting Started =============== -This guide is meant to get you up and running with bastille, and will show you a number -of different options to create and manage your jails. +This guide is meant to get you up and running with bastille, and will show you +a number of different options to create and manage your jails. -The first step is running ``bastille setup`` to try to configure bastille initially, if you didn't during setup. Setup should only be run once. +The first step is running ``bastille setup`` to try to configure bastille +initially, if you didn't during setup. Setup should only be run once. .. code-block:: shell ishmael ~ # bastille setup -Then we need to bootstrap a release for bastille to use. We will use 14.2-RELEASE. +Then we need to bootstrap a release for bastille to use. We will use +14.2-RELEASE. .. code-block:: shell ishmael ~ # bastille bootstrap 14.2-RELEASE -Next we can create our first jail. Bastille can create a few different types of jails. +Next we can create our first jail. Bastille can create a few different types of +jails. -* Thin jails are the default, and are called thin because they use symlinks to the bootstrapped release. They are lightweight and are created quickly. +* Thin jails are the default, and are called thin because they use symlinks to + the bootstrapped release. They are lightweight and are created quickly. -* Thick jails used the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independent of the release. Created with ``bastille create -T``. +* Thick jails used the entire release, which is copied into the jail. The jail + then acts like a full BSD install, completely independent of the release. + Created with ``bastille create -T``. -* Clone jails are essentially clones of the bootstrapped release. Changes to the release will affect the clone jail. Created with ``bastille create -C``. +* Clone jails are essentially clones of the bootstrapped release. Changes to the + release will affect the clone jail. Created with ``bastille create -C``. -* Empty jails are just that, empty. These should be used only if you know what you are doing. Created with ``bastille create -E``. +* Empty jails are just that, empty. These should be used only if you know what + you are doing. Created with ``bastille create -E``. * Linux jails are jails that run linux. Created with ``bastille create -L``. @@ -39,12 +47,13 @@ Classic/Standard Jail ishmael ~ # bastille create nextcloud 14.2-RELEASE 10.1.1.4/24 vtnet0 -This will create a classic jail and add the IP as an alias to the vtnet0 interface. This jail will -use NAT for its outbound traffic. If you want to run a webserver of something similar inside it, you -will have to redirect traffic from the host using ``bastille rdr`` +This will create a classic jail and add the IP as an alias to the vtnet0 +interface. This jail will use NAT for its outbound traffic. If you want to run +a webserver of something similar inside it, you will have to redirect traffic +from the host using ``bastille rdr`` -It the IP is reachable within your local subnet, however, then it is not necessary to redirect the -traffic. It will pass in and out normally. +It the IP is reachable within your local subnet, however, then it is not +necessary to redirect the traffic. It will pass in and out normally. .. code-block:: shell @@ -55,26 +64,28 @@ This will forward traffic from port 80 on the host to port 80 inside the jail. VNET Jail --------- -VNET jails can use either a host interface with ``-V`` or a manually created bridge interface with ``-B``. You can -also optionally set a static MAC for the jail interface with ``-M``. +VNET jails can use either a host interface with ``-V`` or a manually created +bridge interface with ``-B``. You can also optionally set a static MAC for the +jail interface with ``-M``. .. code-block:: shell ishmael ~ # bastille create -BM nextcloud 14.2-RELEASE 192.168.1.50/24 bridge0 -or +or .. code-block:: shell ishmael ~ # bastille create -VM nextcloud 14.2-RELEASE 192.168.1.50/24 vtnet0 -The IP used for VNET jails should be an IP reachable inside your local network. You can also specify 0.0.0.0 or DHCP -to use DHCP. +The IP used for VNET jails should be an IP reachable inside your local network. +You can also specify 0.0.0.0 or DHCP to use DHCP. Linux Jail ---------- -Linux jails are still considered experimental, but they seem to work. First we must bootstrap a linux distro. +Linux jails are still considered experimental, but they seem to work. First we +must bootstrap a linux distro. .. code-block:: shell diff --git a/docs/chapters/migration.rst b/docs/chapters/migration.rst index c904c56a..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 b0652e2b..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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -107,7 +143,8 @@ interface and a free IP on your local network. Shared Interface on IPV6 network (vultr.com) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some ISP's, such as `Vultr `_, 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. @@ -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, @@ -157,9 +194,9 @@ Virtual Network (VNET) (Added in 0.6.x) VNET is supported on FreeBSD 12+ only. -Virtual Network (VNET) creates a private network interface for a container. -This includes a unique hardware address. This is required for VPN, DHCP, and -similar containers. +Virtual Network (VNET) creates a private network interface for a container. This +includes a unique hardware address. This is required for VPN, DHCP, and similar +containers. To create a VNET based container use the ``-V`` option, an IP/netmask and external interface. @@ -188,7 +225,7 @@ host system: .. code-block:: shell ## /etc/devfs.rules (NOT .conf) - + [bastille_vnet=13] add include $devfsrules_hide_all add include $devfsrules_unhide_basic @@ -224,27 +261,36 @@ Below is the definition of what these three parameters are used for and mean: Bridged Network (VNET bridged) ------------------------------ -To use a bridged VNET setup the first thing you have to do is to create a bridge interface on your system. This is done with the ifconfig command and will create a bridged interface named bridge0: +To use a bridged VNET setup the first thing you have to do is to create a bridge +interface on your system. This is done with the ifconfig command and will +create a bridged interface named bridge0: .. code-block:: shell ifconfig bridge create -Then you need to add your system's network interface to the bridge and bring it up (substitute your interface for em0). +Then you need to add your system's network interface to the bridge and bring it +up (substitute your interface for em0). .. code-block:: shell ifconfig bridge0 addm em0 up -Optionally you can rename the interface if you wish to make it obvious that it is for bastille: +Optionally you can rename the interface if you wish to make it obvious that it +is for bastille: .. code-block:: shell ifconfig bridge0 name bastille0bridge -To create a bridged container you use the ``-B`` option, an IP or DHCP, and the bridge interface. +To create a bridged container you use the ``-B`` option, an IP or DHCP, and the +bridge interface. .. code-block:: shell bastille create -B folsom 14.2-RELEASE DHCP bastille0bridge -All the epairs and networking other than the manually created bridge will be created for you automagically. Now if you want this to persist after a reboot then you need to add some lines to your ``/etc/rc.conf`` file. Add the following lines, again, obviously change em0 to whatever your network interface on your system is. +All the epairs and networking other than the manually created bridge will be +created for you automagically. Now if you want this to persist after a reboot +then you need to add some lines to your ``/etc/rc.conf`` file. Add the +following lines, again, obviously change em0 to whatever your network interface +on your system is. .. code-block:: shell cloned_interfaces="bridge0" @@ -293,9 +339,10 @@ Public Network -------------- In this section we describe how to network containers in a public network -such as a cloud hosting provider who only provides you with a single ip address. -(AWS, Digital Ocean, etc) (The exception is vultr.com, which does -provide you with lots of IPV6 addresses and does a great job supporting FreeBSD!) +such as a cloud hosting provider who only provides you with a single ip address. +(AWS, Digital Ocean, etc) (The exception is vultr.com, which does +provide you with lots of IPV6 addresses and does a great job supporting +FreeBSD!) So if you only have a single IP address and if you want to create multiple containers and assign them all unique IP addresses, you'll need to create a new @@ -356,7 +403,8 @@ Create the firewall rules: antispoof for $ext_if inet pass in inet proto tcp from any to any port ssh flags S/SA modulate state -- Make sure to change the ``ext_if`` variable to match your host system interface. +- Make sure to change the ``ext_if`` variable to match your host system +interface. - Make sure to include the last line (``port ssh``) or you'll end up locked out. Note: if you have an existing firewall, the key lines for in/out traffic @@ -405,7 +453,8 @@ This step only needs to be done once in order to prepare the host. local_unbound ------------- -If you are running "local_unbound" on your server, you will probably have issues with DNS resolution. +If you are running "local_unbound" on your server, you will probably have issues +with DNS resolution. To resolve this, add the following configuration to local_unbound: @@ -416,6 +465,7 @@ To resolve this, add the following configuration to local_unbound: access-control: 192.168.0.0/16 allow access-control: 10.17.90.0/24 allow -Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf +Also, change the nameserver to the servers IP instead of 127.0.0.1 inside +/etc/rc.conf Adjust the above "access-control" strings to fit your network. diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst index 641be018..5a6c0fb2 100644 --- a/docs/chapters/subcommands/bootstrap.rst +++ b/docs/chapters/subcommands/bootstrap.rst @@ -1,15 +1,14 @@ bootstrap ========= -The bootstrap sub-command is used to download and extract releases and -templates for use with Bastille containers. A valid release is needed before -containers can be created. Templates are optional but are managed in the same -manner. +The bootstrap sub-command is used to download and extract releases and templates +for use with Bastille containers. A valid release is needed before containers +can be created. Templates are optional but are managed in the same manner. -Note: your mileage may vary with unsupported releases and releases newer -than the host system likely will NOT work at all. Bastille tries to filter for -valid release names. If you find it will not bootstrap a valid release, please -let us know. +Note: your mileage may vary with unsupported releases and releases newer than +the host system likely will NOT work at all. Bastille tries to filter for valid +release names. If you find it will not bootstrap a valid release, please let us +know. In this document we will describe using the ``bootstrap`` sub-command with both releases and templates. We begin with releases. @@ -60,8 +59,8 @@ Tips ^^^^ The ``bootstrap`` sub-command can now take (0.5.20191125+) an optional second -argument of ``update``. If this argument is used, ``bastille update`` will be run -immediately after the bootstrap, effectively bootstrapping and applying +argument of ``update``. If this argument is used, ``bastille update`` will be +run immediately after the bootstrap, effectively bootstrapping and applying security patches and errata in one motion. Notes @@ -126,4 +125,4 @@ begin applying your template. Usage: bastille bootstrap [option(s)] [RELEASE|TEMPLATE] [update|arch] Options: - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/clone.rst b/docs/chapters/subcommands/clone.rst index 0b06c827..50defd8d 100644 --- a/docs/chapters/subcommands/clone.rst +++ b/docs/chapters/subcommands/clone.rst @@ -2,7 +2,7 @@ clone ===== To clone a container and make a duplicate, use the ``bastille clone`` -sub-command.. +sub-command. .. code-block:: shell diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst index ab652581..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,7 +10,7 @@ This sub-command launches a login shell into the container. Default is password- [folsom]: root@folsom:~ # -At this point you are logged in to the container and have full shell access. The +At this point you are logged in to the container and have full shell access. The system is yours to use and/or abuse as you like. Any changes made inside the container are limited to the container. diff --git a/docs/chapters/subcommands/create.rst b/docs/chapters/subcommands/create.rst index c45d0f64..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,31 +23,31 @@ address to the new system. ishmael ~ # bastille create alcatraz 13.2-RELEASE 10.17.89.113/24 -The above code will create a jail with a /24 mask. At the time of this documentation you -can only use CIDR notation, and not use a netmask 255.255.255.0 to accomplish this. +The above code will create a jail with a /24 mask. At the time of this +documentation you can only use CIDR notation, and not use a netmask +255.255.255.0 to accomplish this. I recommend using private (rfc1918) ip address ranges for your container. These ranges include: -- 10.0.0.0/8 -- 172.16.0.0/12 -- 192.168.0.0/16 +- 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 Bastille does its best to validate the submitted ip is valid. This has not been thouroughly tested--I generally use the 10/8 range. -A couple of notes about the created jails. First, MOTD has been disabled inside -of the jails because it does not give information about the jail, but about the host -system. This caused confusion for some users, so we implemented the .hushlogin which -silences the MOTD at login. +A couple of notes about the created jails. First, MOTD has been disabled inside +of the jails because it does not give information about the jail, but about the +host system. This caused confusion for some users, so we implemented the +.hushlogin which silences the MOTD at login. -Also, uname does not work from within a jail. Much like MOTD, it gives you the version -information about the host system instead of the jail. If you need to check the version -of freebsd running on the jail use the freebsd-version command to get accurate information. +Also, uname does not work from within a jail. Much like MOTD, it gives you the +version information about the host system instead of the jail. If you need to +check the version of freebsd running on the jail use the freebsd-version command +to get accurate information. -Bastille can create many different types of jails, along with many different options. See -the below help output. +Bastille can create many different types of jails, along with many different +options. See the below help output. .. code-block:: shell @@ -72,4 +69,3 @@ the below help output. -v | --vlan VLANID Creates the jail with specified VLAN ID (VNET only). -x | --debug Enable debug mode. -Z | --zfs-opts [zfs,options] Comma separated list of ZFS options to create the jail with. This overrides the defaults. - diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst index e7bfc629..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 release cache directory, if you choose to keep it. +Release can be destroyed provided there are no child jails. The `-c|--no-cache` +option will retain the release cache directory, if you choose to keep it. .. code-block:: shell diff --git a/docs/chapters/subcommands/etcupdate.rst b/docs/chapters/subcommands/etcupdate.rst index 2f6c88be..03a71414 100644 --- a/docs/chapters/subcommands/etcupdate.rst +++ b/docs/chapters/subcommands/etcupdate.rst @@ -1,7 +1,8 @@ etcupdate ========= -This command will update the contents of ``/etc`` inside a jail. It should be run after a jail upgrade +This command will update the contents of ``/etc`` inside a jail. It should be +run after a jail upgrade First we need to bootstrap a release for ``etcupdate`` to use. @@ -21,8 +22,9 @@ Next we can use the ``update`` command to apply the update to the jail. ishmael ~ # bastille etcupdate ishmael update 14.1-RELEASE -The output will show you which files were added, updated, changed, deleted, or have conflicts. -To automatically resolve the conflicts, run the ``resolve`` command. +The output will show you which files were added, updated, changed, deleted, or +have conflicts. To automatically resolve the conflicts, run the ``resolve`` +command. .. code-block:: shell diff --git a/docs/chapters/subcommands/htop.rst b/docs/chapters/subcommands/htop.rst index c7f8feba..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/limits.rst b/docs/chapters/subcommands/limits.rst index ea362ef7..015fa149 100644 --- a/docs/chapters/subcommands/limits.rst +++ b/docs/chapters/subcommands/limits.rst @@ -7,7 +7,8 @@ To add a limit, use ``bastille limits TARGET add OPTION VALUE`` To clear the limits from the system, use ``bastille limits TARGET clear`` -To clear the limits, and remove the rctl.conf, use ``bastille limits TARGET reset`` +To clear the limits, and remove the rctl.conf, use ``bastille limits TARGET +reset`` To remove a limit, use ``bastille limits TARGET remove OPTION`` diff --git a/docs/chapters/subcommands/list.rst b/docs/chapters/subcommands/list.rst index e060db24..860647bc 100644 --- a/docs/chapters/subcommands/list.rst +++ b/docs/chapters/subcommands/list.rst @@ -1,7 +1,8 @@ list ==== -List jails, ports, releases, templates, logs, limits, exports and imports managed by bastille. +List jails, ports, releases, templates, logs, limits, exports and imports +managed by bastille. .. code-block:: shell diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst index 180811b2..dd5bf73b 100644 --- a/docs/chapters/subcommands/mount.rst +++ b/docs/chapters/subcommands/mount.rst @@ -9,7 +9,8 @@ Syntax follows standard ``/etc/fstab`` format: Usage: bastille mount TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number] -The ``options`` string can include a comma-separated list of mount options, but must include one of (rw,ro,rq,sw,xx) according to fstab documentation. +The ``options`` string can include a comma-separated list of mount options, but +must include one of (rw,ro,rq,sw,xx) according to fstab documentation. Example: Mount a tmpfs filesystem with options. @@ -31,11 +32,16 @@ Example: Mount a nullfs filesystem [azkaban]: Added: /media/bar /usr/local/bastille/jails/azkaban/root/media/bar nullfs ro 0 0 -Notice the JAIL_PATH format can be /media/foo or simply media/bar. The leading slash / is optional. The HOST_PATH howerver, must be the full path including the leading slash /. +Notice the JAIL_PATH format can be /media/foo or simply media/bar. The leading +slash / is optional. The HOST_PATH howerver, must be the full path including the +leading slash /. It is also possible to mount individual files into a jail as seen below. -Bastille will not mount if a file is already present at the specified mount point. -If the jail file name does not match the host file name, bastille will treat the jail path as a directory, and mount the file underneath as seen in the second example below. +Bastille will not mount if a file is already present at the specified mount +point. +If the jail file name does not match the host file name, bastille will treat the +jail path as a directory, and mount the file underneath as seen in the second +example below. .. code-block:: shell @@ -46,8 +52,10 @@ If the jail file name does not match the host file name, bastille will treat the [azkaban]: Added: /etc/rc.conf usr/local/bastille/jails/azkaban/root/media/bar/rc.conf nullfs ro 0 0 -It is also possible (but not recommended) to have spaces in the directories that are mounted. -It is necessary to escape each space with a backslash \ and enclose the mount point in quotes "" as seen below. +It is also possible (but not recommended) to have spaces in the directories that +are mounted. +It is necessary to escape each space with a backslash \ and enclose the mount +point in quotes "" as seen below. It is possible to do the same for the jail path, but again, not recommemded. .. code-block:: shell diff --git a/docs/chapters/subcommands/network.rst b/docs/chapters/subcommands/network.rst index 2d2a2bc7..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 f8a44e29..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 diff --git a/docs/chapters/subcommands/rdr.rst b/docs/chapters/subcommands/rdr.rst index 03276669..9298b09d 100644 --- a/docs/chapters/subcommands/rdr.rst +++ b/docs/chapters/subcommands/rdr.rst @@ -3,12 +3,12 @@ rdr ``bastille rdr`` allows you to configure dynamic rdr rules for your containers without modifying pf.conf (assuming you are using the ``bastille0`` interface -for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf -as described in the Networking section). +for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf as +described in the Networking section). -Note: you need to be careful if host services are configured to run -on all interfaces as this will include the jail interface - you should -specify the interface they run on in rc.conf (or other config files) +Note: you need to be careful if host services are configured to run on all +interfaces as this will include the jail interface - you should specify the +interface they run on in rc.conf (or other config files) .. code-block:: shell diff --git a/docs/chapters/subcommands/service.rst b/docs/chapters/subcommands/service.rst index 15811d06..458006de 100644 --- a/docs/chapters/subcommands/service.rst +++ b/docs/chapters/subcommands/service.rst @@ -2,8 +2,8 @@ service ======= The ``service`` sub-command allows for managing services within jails. This -allows you to start, stop, restart, and otherwise interact with services -running inside the jail(s). +allows you to start, stop, restart, and otherwise interact with services running +inside the jail(s). .. code-block:: shell diff --git a/docs/chapters/subcommands/setup.rst b/docs/chapters/subcommands/setup.rst index 83062146..76f668b1 100644 --- a/docs/chapters/subcommands/setup.rst +++ b/docs/chapters/subcommands/setup.rst @@ -2,8 +2,8 @@ setup ===== The ``setup`` sub-command attempts to automatically configure a host system for -Bastille containers. This allows you to configure networking, firewall, and storage -options for a Bastille host with one command. +Bastille containers. This allows you to configure networking, firewall, and +storage options for a Bastille host with one command. .. code-block:: shell diff --git a/docs/chapters/subcommands/template.rst b/docs/chapters/subcommands/template.rst index 1c96bbe5..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/umount.rst b/docs/chapters/subcommands/umount.rst index 985d04f8..c65c4a00 100644 --- a/docs/chapters/subcommands/umount.rst +++ b/docs/chapters/subcommands/umount.rst @@ -18,7 +18,8 @@ Syntax requires only the jail path to unmount. Usage: bastille umount TARGET JAIL_PATH -If the directory you are unmounting has spaces, make sure to escape them with a backslash \, and enclose the mount point in quotes "". +If the directory you are unmounting has spaces, make sure to escape them with a +backslash \, and enclose the mount point in quotes "". .. code-block:: shell diff --git a/docs/chapters/subcommands/update.rst b/docs/chapters/subcommands/update.rst index 92900f6c..4f418c87 100644 --- a/docs/chapters/subcommands/update.rst +++ b/docs/chapters/subcommands/update.rst @@ -2,8 +2,8 @@ update ====== The ``update`` command targets a release or a thick jail. Because thin jails are -based on a release, when the release is updated all the thin jails are automatically -updated as well. +based on a release, when the release is updated all the thin jails are +automatically updated as well. If no updates are available, a message will be shown: @@ -38,8 +38,8 @@ The older the release or jail, however, the more updates will be available: To be safe, you may want to restart any jails that have been updated live. -If the jail is a thin jail, an error will be shown. If it is a thick jail, it will be updated just like -the release shown above. +If the jail is a thin jail, an error will be shown. If it is a thick jail, it +will be updated just like the release shown above. .. code-block:: shell @@ -49,4 +49,4 @@ the release shown above. -a | --auto Auto mode. Start/stop jail(s) if required. -f | --force Force update a release. - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst index f7b2042c..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 3f49fbf2..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 diff --git a/docs/chapters/subcommands/zfs.rst b/docs/chapters/subcommands/zfs.rst index 5ca75820..063a4513 100644 --- a/docs/chapters/subcommands/zfs.rst +++ b/docs/chapters/subcommands/zfs.rst @@ -1,7 +1,8 @@ zfs === -Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for targeted jail(s). +Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for +targeted jail(s). .. code-block:: shell diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index e416e980..4073e377 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -4,15 +4,16 @@ Targeting Bastille uses a ``subcommand TARGET ARGS`` syntax, meaning that each command requires a target. Targets are usually containers, but can also be releases. -Targeting a container is done by providing the exact jail name, the JID of the jail, or by typing the -starting few characters of a jail. If more than one matching jail will be found, you will see a message -saying so. +Targeting a container is done by providing the exact jail name, the JID of the +jail, or by typing the starting few characters of a jail. If more than one +matching jail will be found, you will see a message saying so. Targeting a release is done by providing the exact release name. (Note: do not include the ``-pX`` point-release version.) -Bastille includes a pre-defined keyword [ALL|all] to target all running containers. -It is also possible to target multiple jails by grouping them in quotes, as seen below. +Bastille includes a pre-defined keyword [ALL|all] to target all running +containers. It is also possible to target multiple jails by grouping them in +quotes, as seen below. .. code-block:: shell @@ -57,12 +58,12 @@ Examples: Releases ishmael ~ # bastille ... -+-----------+--------------+--------------+-------------------------------------------------------------+ -| command | target | args | description | -+===========+==============+==============+=============================================================+ -| bootstrap | 13.2-RELEASE | --- | bootstrap 13.2-RELEASE release | -+-----------+--------------+--------------+-------------------------------------------------------------+ -| update | 12.4-RELEASE | --- | update 12.4-RELEASE release | -+-----------+--------------+--------------+-------------------------------------------------------------+ -| verify | 12.4-RELEASE | --- | verify 12.4-RELEASE release | -+-----------+--------------+--------------+-------------------------------------------------------------+ ++-----------+--------------+--------------+------------------------------------+ +| command | target | args | description | ++===========+==============+==============+====================================+ +| bootstrap | 13.2-RELEASE | --- | bootstrap 13.2-RELEASE release | ++-----------+--------------+--------------+------------------------------------+ +| update | 12.4-RELEASE | --- | update 12.4-RELEASE release | ++-----------+--------------+--------------+------------------------------------+ +| verify | 12.4-RELEASE | --- | verify 12.4-RELEASE release | ++-----------+--------------+--------------+------------------------------------+ diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index da4d2b7d..417f4105 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -5,11 +5,12 @@ Looking for ready made CI/CD validated `Bastille Templates`_? Bastille supports a templating system allowing you to apply files, pkgs and execute commands inside the containers automatically. -Currently supported template hooks are: ``ARG``, ``CMD``, ``CONFIG``, ``CP``, ``INCLUDE``, -``LIMITS``, ``MOUNT``, ``OVERLAY``, ``PKG``, ``RDR``, ``RENDER``, ``RESTART``, ``SERVICE``, ``SYSRC``. +Currently supported template hooks are: ``ARG``, ``CMD``, ``CONFIG``, ``CP``, +``INCLUDE``, ``LIMITS``, ``MOUNT``, ``OVERLAY``, ``PKG``, ``RDR``, ``RENDER``, +``RESTART``, ``SERVICE``, ``SYSRC``. -Templates are created in ``${bastille_prefix}/templates`` and can leverage any of -the template hooks. +Templates are created in ``${bastille_prefix}/templates`` and can leverage any +of the template hooks. Bastille 0.7.x+ --------------- @@ -59,8 +60,9 @@ Template Hook Descriptions ARG - set an ARG value to be used in the template -ARGS will default to the value set inside the template, but can be changed by including ``--arg ARG=VALUE`` when -running the template. Multiple ARGS can also be specified as seen below. If no ARG value is given, the ``template`` command +ARGS will default to the value set inside the template, but can be changed by +including ``--arg ARG=VALUE`` when running the template. Multiple ARGS can also +be specified as seen below. If no ARG value is given, the ``template`` command will exit. .. code-block:: shell @@ -72,9 +74,11 @@ CMD - run the specified command CONFIG - set the specified property and value -CP/OVERLAY - copy specified files from template directory to specified path inside jail +CP/OVERLAY - copy specified files from template directory to specified path + inside jail -INCLUDE - specify a template to include. Make sure the template is bootstrapped, or you are using the template url +INCLUDE - specify a template to include. Make sure the template is + bootstrapped, or you are using the template url LIMITS - set the specified resource value for the jail @@ -84,7 +88,9 @@ PKG - install specified packages inside jail RDR - redirect specified ports to the jail -RENDER - replace ARG values inside specified files inside the jail. If a directory is specified, ARGS will be replaced in all files underneath +RENDER - replace ARG values inside specified files inside the jail. If a + directory is specified, ARGS will be replaced in all files + underneath RESTART - restart the jail @@ -95,21 +101,21 @@ SYSRC - run `sysrc` inside the jail with specified arguments Special Hook Cases ------------------ -SYSRC requires that NO quotes be used or that quotes (``"``) be escaped -ie; (``\\"``) +SYSRC requires that NO quotes be used or that quotes (``"``) be escaped ie; +(``\\"``) -ARG will always treat an ampersand "\``&``" literally, without the need to escape it. -Escaping it will cause errors. +ARG will always treat an ampersand "\``&``" literally, without the need to +escape it. Escaping it will cause errors. Template Examples ----------------- -Place these uppercase template hook commands into a ``Bastillefile`` in any order -and automate container setup as needed. +Place these uppercase template hook commands into a ``Bastillefile`` in any +order and automate container setup as needed. -In addition to supporting template hooks, Bastille supports overlaying -files into the container. This is done by placing the files in their full path, -using the template directory as "/". +In addition to supporting template hooks, Bastille supports overlaying files +into the container. This is done by placing the files in their full path, using +the template directory as "/". An example here may help. Think of ``bastille/templates/username/template``, our example template, as the root of our filesystem overlay. If you create an @@ -117,18 +123,18 @@ example template, as the root of our filesystem overlay. If you create an can be overlayed into your container. Note: due to the way FreeBSD segregates user-space, the majority of your -overlayed template files will be in ``/usr/local``. The few general -exceptions are the ``/etc/hosts``, ``/etc/resolv.conf``, and -``/etc/rc.conf.local``. +overlayed template files will be in ``/usr/local``. The few general exceptions +are the ``/etc/hosts``, ``/etc/resolv.conf``, and ``/etc/rc.conf.local``. -After populating ``/usr/local`` with custom config files that your container will -use, be sure to include ``/usr`` in the template OVERLAY definition. eg; +After populating ``/usr/local`` with custom config files that your container +will use, be sure to include ``/usr`` in the template OVERLAY definition. eg; .. code-block:: shell echo "CP /usr /" >> /usr/local/bastille/templates/username/template/Bastillefile -The above example ``/usr`` will include anything under ``/usr`` inside the template. +The above example ``/usr`` will include anything under ``/usr`` inside the +template. You do not need to list individual files. Just include the top-level directory name. List these top-level directories one per line. @@ -200,7 +206,13 @@ directory names in the ``bastille/templates`` directory. Using Ports in Templates ------------------------ -Sometimes when you make a template you need special options for a package, or you need a newer version than what is in the pkgs. The solution for these cases, or a case like minecraft server that has NO compiled option, is to use the ports. A working example of this is the minecraft server template in the template repo. The main lines needed to use this is first to mount the ports directory, then compile the port. Below is an example of the minecraft template where this was used. +Sometimes when you make a template you need special options for a package, or +you need a newer version than what is in the pkgs. The solution for these +cases, or a case like minecraft server that has NO compiled option, is to use +the ports. A working example of this is the minecraft server template in the +template repo. The main lines needed to use this is first to mount the ports +directory, then compile the port. Below is an example of the minecraft template +where this was used. .. code-block:: shell @@ -224,8 +236,5 @@ Sometimes when you make a template you need special options for a package, or yo SERVICE minecraft restart RDR tcp 25565 25565 -The MOUNT line mounts the ports directory, then the CMD make line makes the port. This can be modified to use any port in the port tree. - - - - +The MOUNT line mounts the ports directory, then the CMD make line makes the +port. This can be modified to use any port in the port tree. diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index a0fb1f31..a30a718a 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -3,7 +3,10 @@ Upgrading This document outlines updating and upgrading jails hosted by Bastille. -Bastille can "bootstrap" multiple versions of FreeBSD to be used by jails. All jails do not NEED to be the same version (even if they often are), the only requirement here is that the "bootstrapped" versions are less than or equal to the host version of FreeBSD. +Bastille can "bootstrap" multiple versions of FreeBSD to be used by jails. All +jails do not NEED to be the same version (even if they often are), the only +requirement here is that the "bootstrapped" versions are less than or equal to +the host version of FreeBSD. To keep releases updated, use ``bastille update RELEASE`` @@ -13,26 +16,33 @@ To keep thick jails updated, use ``bastille update TARGET`` Minor Release Upgrades ---------------------- -To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the following: +To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the +following: Thick Jails ----------- -1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE +1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to + 13.2-RELEASE 2. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates 3. Reboot the jail ``bastille restart TARGET`` -4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade +4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the + upgrade 5. Upgrade complete! Thin Jails ---------- -1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` +1. Ensure the new release version is bootstrapped and updated to the latest + patch release: ``bastille bootstrap 13.2-RELEASE`` 2. Update the release: ``bastille update 13.2-RELEASE`` 3. Stop the jail(s) that need to be updated. -4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the mount points to 13.2-RELEASE -5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for 13.2-RELEASE -6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents of /etc for 13.2-RELEASE +4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the + mount points to 13.2-RELEASE +5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for + 13.2-RELEASE +6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents + of /etc for 13.2-RELEASE 7. Use ``bastille etcupdate TARGET resolve`` to resolve any conflicts 8. Start the jail(s) 9. Upgrade complete! @@ -41,36 +51,46 @@ Thin Jails Major Release Upgrades ---------------------- -To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the following: +To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the +following: Thick Jails ----------- -1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to 13.2-RELEASE +1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to + 13.2-RELEASE 2. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to apply the updates 3. Reboot the jail ``bastille restart TARGET`` -4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the upgrade -5. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) +4. Use ``bastille upgrade TARGET 13.2-RELEASE update`` to finish applying the + upgrade +5. Force the reinstallation or upgrade of all installed packages (ABI change): + ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) 6. Upgrade complete! Thin Jails ---------- -1. Ensure the new release version is bootstrapped and updated to the latest patch release: ``bastille bootstrap 13.2-RELEASE`` +1. Ensure the new release version is bootstrapped and updated to the latest + patch release: ``bastille bootstrap 13.2-RELEASE`` 2. Update the release: ``bastille update 13.2-RELEASE`` 3. Stop the jail(s) that need to be updated. -4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the mount points to 13.2-RELEASE -5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for 13.2-RELEASE -6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents of /etc for 13.2-RELEASE +4. Use ``bastille upgrade TARGET 13.2-RELEASE`` to automatically change the + mount points to 13.2-RELEASE +5. Use ``bastille etcupdate bootstrap 13.2-RELEASE`` to bootstrap src for + 13.2-RELEASE +6. Use ``bastille etcupdate TARGET update 13.2-RELEASE`` to update the contents + of /etc for 13.2-RELEASE 7. Use ``bastille etcupdate TARGET resolve`` to resolve any conflicts 8. Start the jail(s) -9. Force the reinstallation or upgrade of all installed packages (ABI change): ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) +9. Force the reinstallation or upgrade of all installed packages (ABI change): + ``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``) 10. Upgrade complete! ---------------------------------- Revert Upgrade / Downgrade Process ---------------------------------- -The downgrade process (not usually needed) is similar to the upgrade process only in reverse. +The downgrade process (not usually needed) is similar to the upgrade process +only in reverse. Thick Jails ----------- @@ -80,20 +100,25 @@ Thick jails should not be downgraded and is not supported in general on FreeBSD. Thin Jails ---------- -Not recommended, but you can run ``bastille upgrade TARGET 13.1-RELEASE`` to downgrade a thin jail. -Make sure to run ``bastille etcupdate TARGET update 13.1-RELEASE`` to keep the contents of /etc updated with each release. +Not recommended, but you can run ``bastille upgrade TARGET 13.1-RELEASE`` to +downgrade a thin jail. Make sure to run ``bastille etcupdate TARGET update +13.1-RELEASE`` to keep the contents of /etc updated with each release. -The pkg reinstallation will also need to be repeated after the jail restarts on the previous release. +The pkg reinstallation will also need to be repeated after the jail restarts on +the previous release. ------------ Old Releases ------------ -After upgrading all jails from one release to the next you may find that you now have bootstrapped a release that is no longer used. Once you've decided that you no longer need the option to revert the change you can destroy the old release. +After upgrading all jails from one release to the next you may find that you now +have bootstrapped a release that is no longer used. Once you've decided that you +no longer need the option to revert the change you can destroy the old release. ``bastille list releases`` to list all bootstrapped releases. -``bastille destroy X.Y-RELEASE`` to fully delete the release, including the cache. +``bastille destroy X.Y-RELEASE`` to fully delete the release, including the +cache. ``bastille destroy [-c|--no-cache] X.Y-RELEASE`` to retain the cache directory. diff --git a/docs/chapters/zfs-support.rst b/docs/chapters/zfs-support.rst index 7bf3c763..b00fcf62 100644 --- a/docs/chapters/zfs-support.rst +++ b/docs/chapters/zfs-support.rst @@ -4,14 +4,22 @@ ZFS Support :width: 400 :alt: Alternative text -Bastille 0.4 added initial support for ZFS. ``bastille bootstrap`` and ``bastille create`` will generate ZFS volumes based on settings found in the ``bastille.conf``. This section outlines how to enable and configure Bastille for ZFS. As of Bastille 0.13 you no longer need to do these steps manually. The setup program when you run: +Bastille 0.4 added initial support for ZFS. ``bastille bootstrap`` and +``bastille create`` will generate ZFS volumes based on settings found in the +``bastille.conf``. This section outlines how to enable and configure Bastille +for ZFS. As of Bastille 0.13 you no longer need to do these steps manually. The +setup program when you run: .. code-block:: shell bastille setup -will create the zfs settings for you IF you are running zfs. This section is left in the documents for historical purposes, and so you can understand what the setup program is doing AND so if you need to tweak your settings for some reason. +will create the zfs settings for you IF you are running zfs. This section is +left in the documents for historical purposes, and so you can understand what +the setup program is doing AND so if you need to tweak your settings for some +reason. -Two values are required for Bastille to use ZFS. The default values in the ``bastille.conf`` are NO and empty. Populate these two to enable ZFS. +Two values are required for Bastille to use ZFS. The default values in the +``bastille.conf`` are NO and empty. Populate these two to enable ZFS. .. code-block:: shell @@ -28,11 +36,15 @@ Example ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_enable=YES ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_zpool=ZPOOL_NAME -Replace ``ZPOOL_NAME`` with the zpool you want Bastille to use. Tip: ``zpool list`` and ``zpool status`` will help. -If you get 'no pools available' you are likely not using ZFS and can safely ignore these settings. +Replace ``ZPOOL_NAME`` with the zpool you want Bastille to use. Tip: ``zpool +list`` and ``zpool status`` will help. +If you get 'no pools available' you are likely not using ZFS and can safely +ignore these settings. -By default, bastille will use ``ZPOOL_NAME/bastille`` as its working zfs dataset. If you want it to use a specific dataset -on your pool, set ``bastille_zfs_prefix`` to the dataset you want bastille to use. DO NOT include the pool name. +By default, bastille will use ``ZPOOL_NAME/bastille`` as its working zfs +dataset. If you want it to use a specific dataset +on your pool, set ``bastille_zfs_prefix`` to the dataset you want bastille to +use. DO NOT include the pool name. Example @@ -40,7 +52,9 @@ Example ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_prefix=apps/bastille -The above example will set ``ZPOOL_NAME/apps/bastille`` as the working zfs dataset for bastille. +The above example will set ``ZPOOL_NAME/apps/bastille`` as the working zfs +dataset for bastille. -Bastille will mount the datasets it creates at ``bastille_prefix`` which defaults to ``/usr/local/bastille`` +Bastille will mount the datasets it creates at ``bastille_prefix`` which +defaults to ``/usr/local/bastille`` If this is not desirable, you can change it at the top of the config file. 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. From e93ab798c5a8fe5179b93ceea4a79e5fe4b2b386 Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 11:22:24 -0500 Subject: [PATCH 59/63] doc: gcp, fix list format. --- docs/chapters/gcp.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/chapters/gcp.rst b/docs/chapters/gcp.rst index e2eb12a5..c6fb5e72 100644 --- a/docs/chapters/gcp.rst +++ b/docs/chapters/gcp.rst @@ -3,9 +3,10 @@ Bastille VNET on GCP Bastille VNET runs on GCP with a few small tweaks. In summary, they are: -- change MTU setting in jib script - add an IP address to the bridge interface - -configure host pf to NAT and allow bridge traffic - set defaultrouter and -nameserver in the host +- change MTU setting in jib script +- add an IP address to the bridge interface +- configure host pf to NAT and allow bridge traffic +- set defaultrouter and nameserver in the host ## Change MTU in the jib script From 9a3a39c9b31cc3f970d244a2d25c27289823d55a Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 11:28:35 -0500 Subject: [PATCH 60/63] doc: subcommand index alphabetically --- docs/chapters/subcommands/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 2d3673b4b7c561863b2d80a5afa81c8fc361c4ec Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 11:35:59 -0500 Subject: [PATCH 61/63] setup: removes deprecated option `bastille0` --- usr/local/share/bastille/setup.sh | 5 ----- 1 file changed, 5 deletions(-) diff --git a/usr/local/share/bastille/setup.sh b/usr/local/share/bastille/setup.sh index 6f8ec64c..8cedee2d 100644 --- a/usr/local/share/bastille/setup.sh +++ b/usr/local/share/bastille/setup.sh @@ -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 ;; From 2405750e6b15ce21ac80fa4594ad31ed3c66ce2a Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 11:40:58 -0500 Subject: [PATCH 62/63] shellcheck: keeping comments at 80 columns --- .github/workflows/shellcheck.yml | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) 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 From f2504785013bd28c3838a60d62839589b62f4aea Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Sun, 20 Apr 2025 12:00:38 -0500 Subject: [PATCH 63/63] bastille: Release 0.14.20250420 'easter' release --- README.md | 2 +- docs/chapters/installation.rst | 2 +- docs/conf.py | 4 ++-- usr/local/bin/bastille | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) 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/installation.rst b/docs/chapters/installation.rst index fe6f9288..4f3122da 100644 --- a/docs/chapters/installation.rst +++ b/docs/chapters/installation.rst @@ -4,7 +4,7 @@ Bastille is available in the official FreeBSD ports tree at ``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: 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/usr/local/bin/bastille b/usr/local/bin/bastille index 0056287d..806f8958 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="0.13.20250126" +BASTILLE_VERSION="0.14.20250420" ## check for config existence bastille_conf_check() {