From 3fb721b2968dd39c4bb0562fab09a3093121faf1 Mon Sep 17 00:00:00 2001 From: Juan David Hurtado G Date: Tue, 8 Jul 2025 22:40:28 -0500 Subject: [PATCH] doc: reformat and reflow documentation for consistent 80-column text --- docs/chapters/centralized-assets.rst | 50 +++++------ docs/chapters/comparing.rst | 10 ++- docs/chapters/gettingstarted.rst | 10 ++- docs/chapters/jail-startup-configuration.rst | 82 +++++++++++------- docs/chapters/migration.rst | 67 ++++++++------- docs/chapters/networking.rst | 90 +++++++++++--------- docs/chapters/subcommands/convert.rst | 5 +- docs/chapters/subcommands/limits.rst | 27 +++--- docs/chapters/subcommands/list.rst | 13 +-- docs/chapters/subcommands/rdr.rst | 4 +- docs/chapters/subcommands/setup.rst | 47 +++++----- docs/chapters/targeting.rst | 25 +++--- docs/chapters/template.rst | 23 ++--- docs/chapters/zfs-support.rst | 51 ++++++----- 14 files changed, 280 insertions(+), 224 deletions(-) diff --git a/docs/chapters/centralized-assets.rst b/docs/chapters/centralized-assets.rst index e00df421..9c650b50 100644 --- a/docs/chapters/centralized-assets.rst +++ b/docs/chapters/centralized-assets.rst @@ -1,20 +1,21 @@ Centralized Assets ================== -Sometimes it is preferable to share applications, libraries, packages or even directories -and files across multiple jails. +Sometimes it is preferable to share applications, libraries, packages or even +directories and files across multiple jails. -Or perhaps we just want to avoid all the time it takes to create a jail, and manully configure -it with the packages we normally use. +Or perhaps we just want to avoid all the time it takes to create a jail, and +manually configure it with the packages we normally use. Bastille offers a number of ways to do the above. Templates --------- -A template is a predefined file containing instructions to execute on a targeted jail. This -is one of the easiest ways to create a repeatable environment for your Bastille jails. Simply -create your template, the execute it on as many jails as you prefer. +A template is a predefined file containing instructions to execute on a targeted +jail. This is one of the easiest ways to create a repeatable environment for your +Bastille jails. Simply create your template, the execute it on as many jails as +you prefer. .. code-block:: shell @@ -25,12 +26,12 @@ See the chapter on templates for details on how to create your own templates. Mounting -------- -On of the fastest ways to share directories and files across multiple jails is with -the ``bastille mount`` command. +On of the fastest ways to share directories and files across multiple jails is +with the ``bastille mount`` command. The following command will mount ``/my/host/directory`` into ``jail1`` and ``jail2`` -at ``/my/jail/directory`` with read and write access. To mount with read only access, -simply use ``ro`` instead of ``rw`` as the option. +at ``/my/jail/directory`` with read and write access. To mount with read only +access, simply use ``ro`` instead of ``rw`` as the option. .. code-block:: shell @@ -39,8 +40,8 @@ simply use ``ro`` instead of ``rw`` as the option. Cloning ------- -Bastille allows you to create a full duplicate of your jail using ``bastille clone``. To clone -your jail, use the following command. +Bastille allows you to create duplicate of your jail using ``bastille clone``. +To clone your jail, use the following command. .. code-block:: shell @@ -51,29 +52,30 @@ This will create an exact duplicate of ``myjail`` at ``mynewjail``. Custom Releases --------------- -Bastille allows creating custom releases from jails, then using those releases to create -more jails. +Bastille allows creating custom releases from jails, then using those releases to +create more jails. -To start, we must first create our jail. Make sure it is a thick jail, as this process will -not work with any other jail types. +To start, we must first create our jail. Make sure it is a thick jail, as this +process will not work with any other jail types. .. code-block:: shell ishmael ~ # bastille create -T myjail 14.2-RELEASE 10.0.0.1 -Once the jail is up and running, configure it to your liking, then run the following commmand -to create a custom release based on your jail. +Once the jail is up and running, configure it to your liking, then run the +following commmand to create a custom release based on your jail. .. code-block:: shell ishmael ~ # bastille convert myjail myrelease -Once this process completes, you will be able to run the following command to create a jail -based off your newly created release. +Once this process completes, you will be able to run the following command to +create a jail based off your newly created release. -Please note that using this approach is experimental. It will be up to the end user to keep -track of which official FreeBSD release their custom release is based on. The ``osrelease`` -config variable will be set to your custom release name inside the ``jail.conf`` file. +Please note that using this approach is experimental. It will be up to the end +user to keep track of which official FreeBSD release their custom release is +based on. The ``osrelease`` config variable will be set to your custom release +name inside the ``jail.conf`` file. .. code-block:: shell diff --git a/docs/chapters/comparing.rst b/docs/chapters/comparing.rst index 18972389..91aa8eff 100644 --- a/docs/chapters/comparing.rst +++ b/docs/chapters/comparing.rst @@ -112,11 +112,13 @@ as a list of popular managers and their status on each option. | Support | | | | | | +--------------+-------------+--------------+-----------+-----------+-----------+ -We do our best to stay true and honest as to what other jail managers do and don't do. +We do our best to stay true and honest as to what other jail managers do and +don't do. If you see an error, you can open a PR on the BastillBSD github repo. -We also realize that each jail manger does certain things better than other, and perhaps -certain things worse. Some do this, others do that. They are all different, and each user -should choose the one they want to use based on their needs. +We also realize that each jail manger does certain things better than other, and +perhaps certain things worse. Some do this, others do that. They are all +different, and each user should choose the one they want to use based on their +needs. Thanks for using BastilleBSD! diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst index b00811d6..5a9b5e2f 100644 --- a/docs/chapters/gettingstarted.rst +++ b/docs/chapters/gettingstarted.rst @@ -12,10 +12,11 @@ will attempt to configure the networking, storage, and firewall on your system for use with Bastille. By default the setup command will configure a loopback interface, storage (ZFS if -enabled, otherwise UFS) and the pf firewall if you run it as below without any options. +enabled, otherwise UFS) and the pf firewall if you run it as below without any +options. -Alternatively, you can run the ``setup`` command with any of the supported options to -configure the selected option by itself. +Alternatively, you can run the ``setup`` command with any of the supported +options to configure the selected option by itself. To see a list of available options and switches, see the ``setup`` subcommand. @@ -103,7 +104,8 @@ Linux Jail ^^^^^^^^^^ Linux jails are still considered experimental, but they seem to work. First we -must bootstrap a linux distro (Linux distros are bootstrapped with the Debian tool debootstrap). +must bootstrap a linux distro (Linux distros are bootstrapped with the Debian +tool debootstrap). .. code-block:: shell diff --git a/docs/chapters/jail-startup-configuration.rst b/docs/chapters/jail-startup-configuration.rst index 83a49dfe..42cf2a04 100644 --- a/docs/chapters/jail-startup-configuration.rst +++ b/docs/chapters/jail-startup-configuration.rst @@ -1,33 +1,39 @@ Jail Startup Configuration ========================== -Bastille can start jails on system startup, and stop them on system shutdown. To enable this functionality, we -must first enable Bastille as a service using ``sysrc bastille_enable=YES``. Once you reboot your host, all jails -with ``boot=on`` will be started when the host boots. +Bastille can start jails on system startup, and stop them on system shutdown. +To enable this functionality, we must first enable Bastille as a service using +``sysrc bastille_enable=YES``. Once you reboot your host, all jails with +``boot=on`` will be started when the host boots. -If you have certain jails that must be started before other jails, you can use the priority option. Jails will start -in order starting at the lowest value, and will stop in order starting at the highest value. So, jails with a priority -value of 1 will start first, and stop last. +If you have certain jails that must be started before other jails, you can use +the priority option. Jails will start in order starting at the lowest value, and +will stop in order starting at the highest value. So, jails with a priority value +of 1 will start first, and stop last. See the chapter on targeting for more info. Boot ---- -The boot setting controls whether a jail will be started on system startup. If you have enabled bastille -with ``sysrc bastille_enable=YES``, all jails with ``boot=on`` will start on system startup. Any jail(s) -with ``boot=off`` will not be started on system startup. +The boot setting controls whether a jail will be started on system startup. If +you have enabled bastille with ``sysrc bastille_enable=YES``, all jails with +``boot=on`` will start on system startup. Any jail(s) with ``boot=off`` will not +be started on system startup. -By default, when jails are created with Bastille, the boot setting is set to ``on`` by default. This can be overridden using -the ``--no-boot`` flag. See ``bastille create --no-boot TARGET...``. +By default, when jails are created with Bastille, the boot setting is set to ``on`` +by default. This can be overridden using the ``--no-boot`` flag. +See ``bastille create --no-boot TARGET...``. -You can also use ``bastille start --boot TARGET`` to make Bastille respect the boot setting. If ``-b|--boot`` is not -used, the targeted jail(s) will start, regardless of the boot setting. +You can also use ``bastille start --boot TARGET`` to make Bastille respect the +boot setting. If ``-b|--boot`` is not used, the targeted jail(s) will start, +regardless of the boot setting. Jails will still shut down on system shutdown, regardless of this setting. -The ``-b|--boot`` can also be used with the ``stop`` command. Any jails with ``boot=off`` will -not be touched if ``stop`` is called with ``-b|--boot``. Same goes for the ``restart`` command. +The ``-b|--boot`` can also be used with the ``stop`` command. Any jails with +``boot=off`` will not be touched if ``stop`` is called with ``-b|--boot``. Same +goes for the ``restart`` command. This value can be changed using ``bastille config TARGET set boot [on|off]``. @@ -36,39 +42,49 @@ This value will be shown using ``bastille list all``. Depend ------ -Bastille supports configuring jails to depend on each other when started and stopped. If jail1 "depends" on jail2, then -jail2 will be started if it is not running when ``bastille start jail1`` is called. Any jail that jail1 "depends" on will -first be verified running (started if stopped) before jail1 is started. +Bastille supports configuring jails to depend on each other when started and +stopped. If jail1 "depends" on jail2, then jail2 will be started if it is not +running when ``bastille start jail1`` is called. Any jail that jail1 "depends" +on will first be verified running (started if stopped) before jail1 is started. -For example, I have 3 jails called nginx, mariadb and nextcloud. I want to ensure that nginx and mariadb are running before -nextcloud is started. +For example, I have 3 jails called nginx, mariadb and nextcloud. I want to +ensure that nginx and mariadb are running before nextcloud is started. -First we must add both jails to nextcloud's depend property with ``bastille config nextcloud set depend "mariadb nginx"``. -Then, when we start nextcloud with ``bastille start nextcloud`` it will verify that nginx and mariadb are running (start if stopped) before -starting nextcloud. +First we must add both jails to nextcloud's depend property with +``bastille config nextcloud set depend "mariadb nginx"``. +Then, when we start nextcloud with ``bastille start nextcloud`` it will verify +that nginx and mariadb are running (start if stopped) before starting nextcloud. -When stopping a jail, any jail that "depends" on it will first be stopped. For example, if we run ``bastille stop nginx``, then -nextcloud will first be stopped because it "depends" on nginx. +When stopping a jail, any jail that "depends" on it will first be stopped. +For example, if we run ``bastille stop nginx``, then nextcloud will first be +stopped because it "depends" on nginx. -Note that if we do a ``bastille restart nginx``, however, nextcloud will be stopped, because it "depends" on nginx, but will not be started again, because the jail we just restarted, nginx, does not depend on nextcloud. +Note that if we do a ``bastille restart nginx``, however, nextcloud will be +stopped, because it "depends" on nginx, but will not be started again, because +the jail we just restarted, nginx, does not depend on nextcloud. Parallel Startup ---------------- -Bastille supports starting, stopping and restarting jails in parallel mode using the ``rc`` service script. To enable this functionality, set +Bastille supports starting, stopping and restarting jails in parallel mode using +the ``rc`` service script. To enable this functionality, set ``bastille_parallel_limit`` to a numeric value. -For example, if you run ``sysrc bastille_parallel_limit=4``, then Bastille will start 4 -jails at a time on system startup, as well as stop or restart 4 jails at a time when ``service bastille...`` is called. +For example, if you run ``sysrc bastille_parallel_limit=4``, then Bastille will +start 4 jails at a time on system startup, as well as stop or restart 4 jails at +a time when ``service bastille...`` is called. This value is set to 1 by default, to only start/stop/restart jails one at a time. Startup Delay ------------- -Sometimes it is necessary to let a jail start fully before continuing to the next jail. +Sometimes it is necessary to let a jail start fully before continuing to the +next jail. -We can do this with another sysrc value called ``bastille_startup_delay``. Setting ``bastille_startup_delay=5`` will -tell Bastille to wait 5 seconds between starting each jail. +We can do this with another sysrc value called ``bastille_startup_delay``. +Setting ``bastille_startup_delay=5`` will tell Bastille to wait 5 seconds between +starting each jail. -You can also use ``bastille start -d|--delay 5 all`` or ``bastille restart -d|--delay 5 all`` to achieve the same thing. +You can also use ``bastille start -d|--delay 5 all`` or +``bastille restart -d|--delay 5 all`` to achieve the same thing. diff --git a/docs/chapters/migration.rst b/docs/chapters/migration.rst index e7037720..5055bb9a 100644 --- a/docs/chapters/migration.rst +++ b/docs/chapters/migration.rst @@ -9,54 +9,61 @@ Bastille supports migrations to a remote system using the ``migrate`` subcommand Prerequisites ^^^^^^^^^^^^^ -There are a couple of things that need to be in place before running the ``migrate`` command. +There are a couple of things that need to be in place before running the +``migrate`` command. -First, you must have bastille configured both locally and remotely to use the same filesystem -configuration. ZFS on both, or UFS on both. +First, you must have bastille configured both locally and remotely to use the +same filesystem configuration. ZFS on both, or UFS on both. -Second, you must create a user on the remote system that will be used to migrate the jail. The user -must be able to log in via SSH using either key-based authentication, or password based authentication. -The user also needs ``sudo`` permissions on the remote system. This user should then be given as the -``USER`` arg in the ``migrate`` command. +Second, you must create a user on the remote system that will be used to migrate +the jail. The user must be able to log in via SSH using either key-based +authentication, or password based authentication. +The user also needs ``sudo`` permissions on the remote system. This user should +then be given as the ``USER`` arg in the ``migrate`` command. -If you don't want to use ``sudo``, we support using ``doas`` as the super-user command. Simply set ``--doas`` as -one of the options when running the ``migrate`` command. +If you don't want to use ``sudo``, we support using ``doas`` as the super-user +command. Simply set ``--doas`` as one of the options when running the ``migrate`` command. -If you are using key-based auth, the keys should be stored in the default location at ``$HOME/.ssh/id_rsa``, -where ``$HOME`` is the users home directory. This is the default location for ssh keys, and where Bastille -will try to load them from. +If you are using key-based auth, the keys should be stored in the default +location at ``$HOME/.ssh/id_rsa``, where ``$HOME`` is the users home directory. +This is the default location for ssh keys, and where Bastille will try to load +them from. -If you want to use password based authentication, simply run ``bastille migrate -p TARGET USER@HOST``. This -will prompt you to enter the password for the remote system, which Bastille will then use during the migration +If you want to use password based authentication, simply run +``bastille migrate -p TARGET USER@HOST``. This will prompt you to enter the +password for the remote system, which Bastille will then use during the migration process. Migration ^^^^^^^^^ To migrate a jail (or multiple jails) we can simply run -``bastille migrate TARGET USER@HOST``. This will export the jail(s), send them to the -remote system, and import them. +``bastille migrate TARGET USER@HOST``. This will export the jail(s), send them +to the remote system, and import them. -The ``migrate`` sub-command includes the ``-a|--auto`` option, which will auto-stop the old jail, -migrate it, and attempt to start the migrated jail on the remote system after importing it. See the -warning below about auto-starting the migrated jail. +The ``migrate`` sub-command includes the ``-a|--auto`` option, which will +auto-stop the old jail, migrate it, and attempt to start the migrated jail on +the remote system after importing it. See the warning below about auto-starting +the migrated jail. -WARNING: Every system is unique, has different interfaces, bridges, and network configurations. -It is possible, with the right configuration, for jails to start and work normally. But for some -systems, it will be necessary to edit the ``jail.conf`` file of the migrated jail to get it working -properly. +WARNING: Every system is unique, has different interfaces, bridges, and network +configurations. It is possible, with the right configuration, for jails to start +and work normally. But for some systems, it will be necessary to edit the +``jail.conf`` file of the migrated jail to get it working properly. -Using ``-l|--live`` mode (ZFS only) will leave the local jail running, and the remote jail stopped. +Using ``-l|--live`` mode (ZFS only) will leave the local jail running, and the +remote jail stopped. Using ``-a|--auto`` mode will stop the local jail, and start the remote jail. -Using the ``-l|--live`` and ``-a|--auto`` options together will migrate the jail while it is running, -then stop the local jail, and start the remote jail. +Using the ``-l|--live`` and ``-a|--auto`` options together will migrate the jail +while it is running, then stop the local jail, and start the remote jail. -You can optionally set ``-d|--destroy`` to have Bastille destroy the old jail on completion. +You can optionally set ``-d|--destroy`` to have Bastille destroy the old jail on +completion. -You can also set ``-b|--backup`` to retain the archives remotely. They will be copied into -``${bastille_backupsdir}``. +You can also set ``-b|--backup`` to retain the archives remotely. They will be +copied into ``${bastille_backupsdir}``. iocage ------ @@ -89,7 +96,7 @@ Import the iocage backup file (use zip file name) bastille import jailname_$(date +%F).zip Bastille will attempt to configure your interface and IP from the -``config.json`` file, but if you have issues you can configure it manully. +``config.json`` file, but if you have issues you can configure it manually. .. code-block:: shell diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index e78f10a6..7f260990 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -13,10 +13,10 @@ different types of jail network configurations. whatever your interface is called. This will be used for the host/jail epairs. Bastille will create/destroy these epairs as the jail is started/stopped. -* Bridged VNET mode: For bridged VNET jails (``-B``) you must manually create a bridge - interface to attach your jail to. Bastille will then create and attach the - host/jail epairs to this interface when the jail starts, and remove them when - it stops. +* Bridged VNET mode: For bridged VNET jails (``-B``) you must manually create a + bridge interface to attach your jail to. Bastille will then create and attach + the host/jail epairs to this interface when the jail starts, and remove them\ + when it stops. * Alias mode: For classic/standard jails that use an IP that is accessible within your local subnet (alias mode) Bastille will add the IP to the @@ -24,10 +24,10 @@ different types of jail network configurations. * NAT mode: For classic/standard jails that use an IP not reachable in your local subnet, Bastille will add the IP to the specified interface as an alias, and - additionally, add it to the pf firewall table (if available) to allow the jail outbound - access. If you do not specify an interface, Bastille will assume you have run - the ``bastille setup`` command and will attempt to use ``bastille0`` (which - is created using the setup command) as its interface. If you have not run + additionally, add it to the pf firewall table (if available) to allow the jail + outbound access. If you do not specify an interface, Bastille will assume you + have run the ``bastille setup`` command and will attempt to use ``bastille0`` + (which is created using the setup command) as its interface. If you have not run ``bastille setup`` and do not specify an interface, Bastille will error. * Inherit mode: For classic/standard jails that are set to ``inherit`` or @@ -38,9 +38,9 @@ different types of jail network configurations. bastille will simply set ``ip4`` to ``ip_hostname`` inside the jail config. The jail will then function according the jail(8) documentation. -You cannot use ``-V|--vnet`` with any interface that is already a member of another -bridge. For example, if you create a bridge, and assign ``vtnet0`` as a member, you -will not be able to use ``vtnet0`` with ``-V|--vnet``. +You cannot use ``-V|--vnet`` with any interface that is already a member of +another bridge. For example, if you create a bridge, and assign ``vtnet0`` as a +member, you will not be able to use ``vtnet0`` with ``-V|--vnet``. IP Address Options ------------------ @@ -95,8 +95,9 @@ For the ``inherit`` and ``ip_hostname`` options, you can also specify Shared Interface ---------------- -This scenario works best when you have just one computer, or a home or small office network -that is separated from the rest of the internet by a router. So you are free to use +This scenario works best when you have just one computer, or a home or small +office network that is separated from the rest of the internet by a router. So +you are free to use `private IP addresses `_. @@ -118,9 +119,10 @@ reach services at that address. This method is the simplest. All you need to know is the name of your network interface and a free IP on your local network. -We can also run ``bastille setup shared`` to configure our primary interface as a default -interface for Bastille to use. Once we have run the command and chosen our interface, it will -not be necessary to specify an interface in our create command. +We can also run ``bastille setup shared`` to configure our primary interface as +a default interface for Bastille to use. Once we have run the command and chosen +our interface, it will not be necessary to specify an interface in our create +command. .. code-block:: shell @@ -128,8 +130,8 @@ not be necessary to specify an interface in our create command. This will automatically use the interface we selected during the setup command. -Note that we cannot use the ``shared`` option together with the ``loopback`` option. Configuring -one using the ``bastille setup`` command will disable the other. +Note that we cannot use the ``shared`` option together with the ``loopback`` +option. Configuring one using the ``bastille setup`` command will disable the other. Shared Interface on IPV6 network (vultr.com) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -259,8 +261,8 @@ bridge, use the ``-B`` option, an IP/netmask and external bridge. bastille create -B azkaban 13.2-RELEASE 192.168.1.50/24 bridge0 -Bastille will automagically create the needed interface(s), attach it to the specified -bridge and connect/disconnect containers as they are started and stopped. +Bastille will automagically create the needed interface(s), attach it to the +specified bridge and connect/disconnect containers as they are started and stopped. The bridge needs to be created/enabled before creating and starting the jail. Below are the steps to creating a bridge for this purpose. @@ -309,21 +311,23 @@ on your system is. VLAN Configuration ------------------ -Bastille supports VLANs to some extent when creating jails. When creating a jail, use -the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set the proper -variables inside the jails `rc.conf` to add the jail to the specified VLAN. When using this method, -the interface being assigned must carry tagged VLAN packets, e.g. you can bridge a VLAN trunk to -the jail and in the jail you then can access all VLANs. But be careful: This may have -security implications. +Bastille supports VLANs to some extent when creating jails. When creating a jail, +use the ``--vlan ID`` options to specify a VLAN ID for your jail. This will set +the proper variables inside the jails `rc.conf` to add the jail to the specified +VLAN. When using this method, the interface being assigned must carry tagged VLAN +packets, e.g. you can bridge a VLAN trunk to the jail and in the jail you then can +access all VLANs. But be careful: This may have security implications. -You cannot use the ``-V|--vnet`` options with interfaces that have dots (.) in the name, which is the -standard way of naming a VLAN interface. This is due to the limitations -of the JIB script that Bastille uses to manage VNET jails. +You cannot use the ``-V|--vnet`` options with interfaces that have dots (.) in the +name, which is the standard way of naming a VLAN interface. This is due to the +limitations of the JIB script that Bastille uses to manage VNET jails. -You can however use ``-B|--bridge`` with VLAN interfaces (even with dots in the name). -Using this method you create bridge interfaces in ``rc.conf`` and only add VLANs that are needed -for the jail. The jail only has access to these VLANs and not to the whole trunk. -Below is an ``rc.conf`` snippet that was provided by a user who has such a configuration. +You can however use ``-B|--bridge`` with VLAN interfaces (even with dots in the +name). Using this method you create bridge interfaces in ``rc.conf`` and only +add VLANs that are needed for the jail. The jail only has access to these VLANs +and not to the whole trunk. +Below is an ``rc.conf`` snippet that was provided by a user who has such a +configuration. .. code-block:: shell @@ -397,11 +401,13 @@ To enable netgraph, run `bastille setup netgraph`. This will load and persist th required kernel modules. Once netgraph is configured, any VNET jails you create will be managed with netgraph. -Note that you should only enable netgraph on a new system. Bastille is set up to use either -`netgraph` or `if_bridge` as the VNET management, and uses `if_bridge` as the default, as it -always has. The `netgraph` option is new, and should only be used with new systems. +Note that you should only enable netgraph on a new system. Bastille is set up to +use either `netgraph` or `if_bridge` as the VNET management, and uses `if_bridge` +as the default, as it always has. The `netgraph` option is new, and should only +be used with new systems. -This value is set with the `bastille_network_vnet_type` option inside the config file. +This value is set with the `bastille_network_vnet_type` option inside the config +file. loopback (bastille0) ^^^^^^^^^^^^^^^^^^^^ @@ -423,9 +429,9 @@ traffic out of containers and can selectively redirect traffic into containers based on connection ports (ie; 80, 443, etc.) To set up the loopback address automatically, we can simply run ``bastille setup``. -This will configure the storage, pf firewall, and loopback addresses for us. To set -these up individually, we can run ``bastille setup storage``, ``bastille setup firewall``, -and ``bastille setup loopback`` respectively. +This will configure the storage, pf firewall, and loopback addresses for us. +To set these up individually, we can run ``bastille setup storage``, +``bastille setup firewall``, and ``bastille setup loopback`` respectively. Alternatively, you can do it all manually, as shown below. @@ -512,8 +518,8 @@ ssh session and continue. This step only needs to be done once in order to prepare the host. -Note that we cannot use the ``loopback`` option together with the ``shared`` option. Configuring -one using the ``bastille setup`` command will disable the other. +Note that we cannot use the ``loopback`` option together with the ``shared`` +option. Configuring one using the ``bastille setup`` command will disable the other. local_unbound ------------- diff --git a/docs/chapters/subcommands/convert.rst b/docs/chapters/subcommands/convert.rst index a21ebc91..8d589c6c 100644 --- a/docs/chapters/subcommands/convert.rst +++ b/docs/chapters/subcommands/convert.rst @@ -18,7 +18,8 @@ RELEASE as args. ishmael ~ # bastille convert azkaban myrelease -This release can then be used to create a thick jail using the ``--no-validate`` flag. +This release can then be used to create a thick jail using the ``--no-validate`` +flag. .. code-block:: shell @@ -33,4 +34,4 @@ This release can then be used to create a thick jail using the ``--no-validate`` -a | --auto Auto mode. Start/stop jail(s) if required. -y | --yes Do not prompt. Just convert. - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/limits.rst b/docs/chapters/subcommands/limits.rst index d0d255aa..6d9c14b1 100644 --- a/docs/chapters/subcommands/limits.rst +++ b/docs/chapters/subcommands/limits.rst @@ -11,29 +11,30 @@ To add a limit, use ``bastille limits TARGET add OPTION VALUE``. To clear the limits from the system, use ``bastille limits TARGET clear``. To clear the limits, and remove the rctl.conf, so that limits will not be loaded -on a restart, use ``bastille limits TARGET reset``. This removes the ``rctl.conf`` file, -and removes any active limits from the system. +on a restart, use ``bastille limits TARGET reset``. This removes the ``rctl.conf`` +file, and removes any active limits from the system. To remove a limit, use ``bastille limits TARGET remove OPTION``. This file can be edited manually using ``bastille edit TARGET rctl.conf``. -Supported actions are ``add``, ``remove``, ``clear``, ``reset``, ``list``, ``show``, and -``stats``. +Supported actions are ``add``, ``remove``, ``clear``, ``reset``, ``list``, +``show``, and ``stats``. cpuset ------ -Bastille supports limiting CPUs using ``cpuset``. To limit a jail to a specific CPU, use -``bastille limits TARGET cpu 2,3,4``` where the value (2,3,4) is a comma-separated list of CPUs on -your system. Bastille will validate the CPUs, and error if they are not available to be used. +Bastille supports limiting CPUs using ``cpuset``. To limit a jail to a specific +CPU, use ``bastille limits TARGET cpu 2,3,4``` where the value (2,3,4) is a +comma-separated list of CPUs on your system. Bastille will validate the CPUs, and +error if they are not available to be used. -To adjust the CPU limits, run ``bastille limits TARGET cpu 1,2,3`` again with a new set of CPU -values. This will overwrite the ``cpuset.conf`` file. This will restrict the targetted jail(s) to -the specified CPUs. +To adjust the CPU limits, run ``bastille limits TARGET cpu 1,2,3`` again with a +new set of CPU values. This will overwrite the ``cpuset.conf`` file. This will +restrict the targetted jail(s) to the specified CPUs. -CPU limits are cleared when the jail is stopped, and loaded again on jail start, providing the CPU -values are present in ``cpuset.conf`` inside the jail directory. +CPU limits are cleared when the jail is stopped, and loaded again on jail start, +providing the CPU values are present in ``cpuset.conf`` inside the jail directory. Supported actions are ``add``, ``remove``, ``reset``, ``list`` and ``show``. @@ -51,4 +52,4 @@ This file can be edited manually using ``bastille edit TARGET cpuset.conf``. -a | --auto Auto mode. Start/stop jail(s) if required. -l | --log Enable logging for the specified rule (rctl only). - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/list.rst b/docs/chapters/subcommands/list.rst index 96678bd4..e79df0eb 100644 --- a/docs/chapters/subcommands/list.rst +++ b/docs/chapters/subcommands/list.rst @@ -1,13 +1,14 @@ list ==== -List jails, ports, releases, templates, logs, limits, exports and imports and much more -managed by bastille. See the ``help`` output below. +List jails, ports, releases, templates, logs, limits, exports and imports and +much more managed by bastille. See the ``help`` output below. -Using `bastille list` without args will print all jails with the info we feel is most important. +Using `bastille list` without args will print all jails with the info we feel is +most important. -Most options can be printed in JSON format by including the ``-j|--json`` flag. Use ``-p|--pretty`` -to print in columns instead of rows. +Most options can be printed in JSON format by including the ``-j|--json`` flag. +Use ``-p|--pretty`` to print in columns instead of rows. .. code-block:: shell @@ -21,4 +22,4 @@ to print in columns instead of rows. -p | --pretty Print JSON in columns. -s | --sort VALUE Print info in VALUE order. -u | --up List running jails only. - -x | --debug Enable debug mode. \ No newline at end of file + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/rdr.rst b/docs/chapters/subcommands/rdr.rst index ea1d15cb..3874d63f 100644 --- a/docs/chapters/subcommands/rdr.rst +++ b/docs/chapters/subcommands/rdr.rst @@ -68,8 +68,8 @@ The options can be used together, as seen above. If you have multiple interfaces assigned to your jail, ``bastille rdr`` will only redirect using the default one. -It is also possible to specify a pf table as the source, providing it exists. Simply use the table -name instead of an IP address or subnet. +It is also possible to specify a pf table as the source, providing it exists. +Simply use the table name instead of an IP address or subnet. .. code-block:: shell diff --git a/docs/chapters/subcommands/setup.rst b/docs/chapters/subcommands/setup.rst index 96a927cc..92fee0da 100644 --- a/docs/chapters/subcommands/setup.rst +++ b/docs/chapters/subcommands/setup.rst @@ -25,38 +25,41 @@ Below is a list of available options that can be used with the ``setup`` command -y | --yes Assume always yes on prompts. -x | --debug Enable debug mode. -The ``loopback`` option will configure a loopback interface called ``bastille0`` that -will be used as a default when not specifying an interface with the ``create`` command. +The ``loopback`` option will configure a loopback interface called ``bastille0`` +that will be used as a default when not specifying an interface with the +``create`` command. -The ``shared`` option will configure the interface you choose to also be used as the default -when not specifying an interface with the ``create`` command. +The ``shared`` option will configure the interface you choose to also be used as +the default when not specifying an interface with the ``create`` command. -Please note. You CANNOT run both a loopback and a shared interface with Bastille. Only one -should be configured. If you configure one, it will disable the other. +Please note. You CANNOT run both a loopback and a shared interface with Bastille. +Only one should be configured. If you configure one, it will disable the other. -The ``loopback`` option is the default, and is enough for most use cases. It is simply an ``lo`` interface -that jails will get linked to on creation. It is not attached to any specific interface. This is the simplest -networking option. The ``loopback`` and ``shared`` options are only for cases where the ``interface`` -is not specified during the ``create`` command. If an interface is specified, these options have no effect. -Instead, the specified interface will be used. +The ``loopback`` option is the default, and is enough for most use cases. It is +simply an ``lo`` interface that jails will get linked to on creation. It is not +attached to any specific interface. This is the simplest networking option. The +``loopback`` and ``shared`` options are only for cases where the ``interface`` +is not specified during the ``create`` command. If an interface is specified, +these options have no effect. Instead, the specified interface will be used. -The ``shared`` option is for cases where you want an actual interface to use with bastille as -opposed to a loopback. Jails will be linked to the shared interface on creation. +The ``shared`` option is for cases where you want an actual interface to use with +Bastille as opposed to a loopback. Jails will be linked to the shared interface +on creation. -The ``pf|firewall`` option will configure the pf firewall by enabling the service and creating the -default ``pf.conf`` file. Once this is done, you can use the ``rdr`` command to forward traffic into -a jail. +The ``pf|firewall`` option will configure the pf firewall by enabling the service +and creating the default ``pf.conf`` file. Once this is done, you can use the +``rdr`` command to forward traffic into a jail. -The ``storage`` option will attempt to configure a pool and dataset for Bastille, but only -if ZFS in enabled on your system. Otherwise it will use UFS. +The ``storage`` option will attempt to configure a pool and dataset for Bastille, +but only if ZFS in enabled on your system. Otherwise it will use UFS. The ``vnet`` option will configure your system for use with VNET ``-V`` jails. -The ``bridge`` options will attempt to configure a bridge interface for use with bridged VNET -``-B`` jails. +The ``bridge`` options will attempt to configure a bridge interface for use with +bridged VNET ``-B`` jails. -Running ``bastille setup`` without any options will attempt to auto-configure the ``filesystem``, ``loopback``, ``firewall`` and -``storage`` options. +Running ``bastille setup`` without any options will attempt to auto-configure the +``filesystem``, ``loopback``, ``firewall`` and ``storage`` options. .. code-block:: shell diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index faf7abd4..3f01e419 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -22,14 +22,18 @@ quotes, as seen below. Priority -------- -The priority value determines in what order commands are executed if multiple jails are targetted, including the ALL target. +The priority value determines in what order commands are executed if multiple +jails are targetted, including the ALL target. -It also controls in what order jails are started and stopped on system startup and shutdown. This requires Bastille to be enabled -with ``sysrc bastille_enable=YES``. Jails will start in order starting at the lowest value, and will stop in order starting -at the highest value. So, jails with a priority value of 1 will start first, and stop last. +It also controls in what order jails are started and stopped on system startup +and shutdown. This requires Bastille to be enabled with ``sysrc bastille_enable=YES``. +Jails will start in order starting at the lowest value, and will stop in order +starting at the highest value. So, jails with a priority value of 1 will start +first, and stop last. -When jails are created with Bastille, this value defaults to ``99``, but can be overridden with ``-p|--priority VALUE`` on -creation. See ``bastille create --priority 90 TARGET...``. +When jails are created with Bastille, this value defaults to ``99``, but can be +overridden with ``-p|--priority VALUE`` on creation. +See ``bastille create --priority 90 TARGET...``. This value can be changed using ``bastille config TARGET set priority VALUE``. @@ -38,14 +42,15 @@ This value will be shown using ``bastille list all``. Parallel Mode ------------- -Any command that supports multiple targets, also supports parallel mode. This means that -Bastille will run the command on multiple jails at a single time, depending on the value -given. +Any command that supports multiple targets, also supports parallel mode. This +means that Bastille will run the command on multiple jails at a single time, +depending on the value given. To use parallel mode, run ``bastille -p 4 pkg ALL update``, for example, to start updating packages in all jails, 4 processes at a time. -Note that the ``-p`` option should follow the main ``bastille`` command, and not the sub-command. +Note that the ``-p`` option should follow the main ``bastille`` command, and not +the sub-command. Examples: Containers -------------------- diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index edd9b5f5..6be4cd4f 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -65,15 +65,15 @@ Template Hook Descriptions ARGS will default to the value set inside the template, but can be changed by including ``--arg ARG=VALUE`` when running the template. -Multiple ARGS can also be specified as seen below. If no ARG value is given, Bastille -will show a warning, but continue on with the rest of the template. +Multiple ARGS can also be specified as seen below. If no ARG value is given, +Bastille will show a warning, but continue on with the rest of the template. .. code-block:: shell ishmael ~ # bastille template azkaban sample/template --arg ARG=VALUE --arg ARG1=VALUE -The ``ARG`` hook has a wide range of functionality, including passing KEY=VALUE pairs -to any templates called with the ``INCLUDE`` hook. See the following example... +The ``ARG`` hook has a wide range of functionality, including passing KEY=VALUE +pairs to any templates called with the ``INCLUDE`` hook. See the following example... .. code-block:: shell @@ -82,14 +82,15 @@ to any templates called with the ``INCLUDE`` hook. See the following example... INCLUDE other/template --arg JAIL=${JAIL} --arg IP=${IP} -If the above template is called with ``--arg JAIL=myjail --arg IP=10.3.3.3``, these values will -be passed along to ``other/template`` as well, with the matching variable. So ``${JAIL}`` will be -``myjail`` and ``${IP}`` will be ``10.3.3.3``. +If the above template is called with ``--arg JAIL=myjail --arg IP=10.3.3.3``, +these values will be passed along to ``other/template`` as well, with the +matching variable. So ``${JAIL}`` will be ``myjail`` and ``${IP}`` will be +``10.3.3.3``. -The ARG hook has three values that are built in, and will differ for every jail. The values -are ``JAIL_NAME``, ``JAIL_IP``, and ``JAIL_IP6``. These can be used inside any template without -setting the values at the top of the Bastillefile. The values are automatically retrieved from -the targeted jails configuration. +The ARG hook has three values that are built in, and will differ for every jail. +The values are ``JAIL_NAME``, ``JAIL_IP``, and ``JAIL_IP6``. These can be used +inside any template without setting the values at the top of the Bastillefile. +The values are automatically retrieved from the targeted jails configuration. ``CMD`` - run the specified command diff --git a/docs/chapters/zfs-support.rst b/docs/chapters/zfs-support.rst index d6a6b70a..ca6046c4 100644 --- a/docs/chapters/zfs-support.rst +++ b/docs/chapters/zfs-support.rst @@ -63,46 +63,55 @@ If this is not desirable, you can change it at the top of the config file. Altroot ------- -If a ZFS pool has been imported using ``-R`` (altroot), your system will automatically add whatever the ``altroot`` is to -any ``zfs mount`` commands. Bastille supports using an ``altroot``, and there should be no issues using this feature. +If a ZFS pool has been imported using ``-R`` (altroot), your system will +automatically add whatever the ``altroot`` is to any ``zfs mount`` commands. +Bastille supports using an ``altroot``, and there should be no issues using this feature. -One thing to note though, is that you MUST NOT include your ``altroot`` path in the ``bastille_prefix``. For example, if -you imported your pool with ``zpool import -R /mnt poolname``, and you wish for your jails to live at ``/mnt/poolname/bastille`` -then ``bastille_prefix`` should be set to ``/poolname/bastille`` without the ``/mnt`` part. +One thing to note though, is that you MUST NOT include your ``altroot`` path in +the ``bastille_prefix``. For example, if you imported your pool with +``zpool import -R /mnt poolname``, and you wish for your jails to live at +``/mnt/poolname/bastille`` then ``bastille_prefix`` should be set to +``/poolname/bastille`` without the ``/mnt`` part. -If you do accidentally add the ``/mnt`` part, your datasets will be mounted at ``/mnt/mnt/poolname/bastille`` and Bastille will -throw all kinds of errors due to not finding the proper paths. +If you do accidentally add the ``/mnt`` part, your datasets will be mounted at +``/mnt/mnt/poolname/bastille`` and Bastille will throw all kinds of errors due +to not finding the proper paths. Jailing a Dataset ----------------- -It is possible to "jail" a dataset. This means mounting a datset into a jail, and being -able to fully manage it from within the jail. +It is possible to "jail" a dataset. This means mounting a datset into a jail, +and being able to fully manage it from within the jail. -To add a dataset to a jail, we can run ``bastille zfs TARGET jail pool/dataset /path/inside/jail``. -This will mount ``pool/dataset`` into the jail at ``/path/inside/jail`` when the jail is started, and -unmount and unjail it when the jail is stopped. +To add a dataset to a jail, we can run +``bastille zfs TARGET jail pool/dataset /path/inside/jail``. +This will mount ``pool/dataset`` into the jail at ``/path/inside/jail`` when the +jail is started, and unmount and unjail it when the jail is stopped. -You can manually change the path where the dataset will be mounted by ``bastille edit TARGET zfs.conf`` and -adjusting the path after you have added it, bearing in mind the warning below. +You can manually change the path where the dataset will be mounted by +``bastille edit TARGET zfs.conf`` and adjusting the path after you have added it, +bearing in mind the warning below. -WARNING: Adding or removing datasets to the ``zfs.conf`` file can result in permission errors with your jail. It is -important that the jail is first stopped before attempting to manually configure this file. The format inside -the file is simple. +WARNING: Adding or removing datasets to the ``zfs.conf`` file can result in +permission errors with your jail. It is important that the jail is first stopped +before attempting to manually configure this file. The format inside the file is +simple. .. code-block:: shell pool/dataset /path/in/jail pool/other/dataset /other/path/in/jail -To remove a dataset from being jailed, we can run ``bastille zfs TARGET unjail pool/dataset``. +To remove a dataset from being jailed, we can run +``bastille zfs TARGET unjail pool/dataset``. Template Approach ^^^^^^^^^^^^^^^^^ -While it is possible to "jail" a dataset using a template, it is a bit more "hacky" than the above apporach. -Below is a template that you can use that will add the necessary bits to the ``jail.conf`` file to "jail" a -dataset. +While it is possible to "jail" a dataset using a template, it is a bit more +"hacky" than the above apporach. +Below is a template that you can use that will add the necessary bits to the +``jail.conf`` file to "jail" a dataset. .. code-block:: shell