From b7331ad80f5589023d2a246bcbabd90cff420275 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 11:20:52 -0700 Subject: [PATCH 01/50] docs: Add getting started and fix minor bugs --- docs/chapters/upgrading.rst | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index e78ff9a4..0ae3fc0c 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -9,14 +9,14 @@ To keep releases updated, use `bastille update RELEASE` To keep thick jails updated, use `bastille update TARGET` -====================== +---------------------- Minor Release Upgrades -====================== +---------------------- To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the following: 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` @@ -27,7 +27,7 @@ Thick Jails 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` @@ -39,14 +39,14 @@ Thin Jails 8. start the jail(s) 8. upgrade complete! -====================== +---------------------- Major Release Upgrades -====================== +---------------------- To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the following: Thick Jails -=========== +----------- 1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` 2. update the release: `bastille update 13.2-RELEASE` @@ -58,7 +58,7 @@ Thick Jails 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` @@ -71,25 +71,28 @@ Thin Jails 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. Thick Jails -=========== +----------- 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. 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. From ba6d2fbd10f826d0ebae79ac3a25f12eb327d4ac Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 11:51:30 -0700 Subject: [PATCH 02/50] docs: Add gettingstarted --- docs/chapters/gettingstarted.rst | 88 ++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/chapters/gettingstarted.rst diff --git a/docs/chapters/gettingstarted.rst b/docs/chapters/gettingstarted.rst new file mode 100644 index 00000000..6a5d053c --- /dev/null +++ b/docs/chapters/gettingstarted.rst @@ -0,0 +1,88 @@ +=============== +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. + +.. code-block:: shell + + ishmael ~ # bastille setup + +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. + +* 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`. + +* Clone jails are essentially clones of the bootstrapped release. Changes to the release will affect the clone jail. Created with `-C`. + +* Empty jails are just that, empty. These should be used only if you know what you are doing. Created with `-E`. + +* Linux jails are jails that run linux. Created with `-L`. + +Only clone, thin, and thick jails can be created with `-V` `-B` and `-M`. + +We will focus on thin jails for the guide. + +Classic/Standard Jail +--------------------- + +.. code-block:: shell + + 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` + +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 + + ishmael ~ # bastille rdr nextcloud tcp 80 80 + +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`. + +.. code-block:: shell + + ishmael ~ # bastille create -BM nextcloud 14.2-RELEASE 192.168.1.50/24 bridge0 + +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. + +Linux Jail +---------- + +Linux jails are still considered experimental, but they seem to work. First we must bootstrap a linux distro. + +.. code-block:: shell + + ishmael ~ # bastille bootstrap bionic + +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 From 82f1648f6bfaeee3128896844f61685da39c1746 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 11:55:36 -0700 Subject: [PATCH 03/50] docs: Clean up migration chapter --- docs/chapters/migration.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/chapters/migration.rst b/docs/chapters/migration.rst index f297558b..5e5c4c76 100644 --- a/docs/chapters/migration.rst +++ b/docs/chapters/migration.rst @@ -1,3 +1,10 @@ +========= +Migration +========= + +iocage +------ + Stop the running jail and export it: .. code-block:: shell @@ -11,7 +18,7 @@ Move the backup files (.zip and .sha256) into Bastille backup dir (default: /usr mv /iocage/images/jailname_$(date +%F).* /usr/local/bastille/backups/ -for remote systems you could use rsync: +for remote systems you can use rsync: .. code-block:: shell @@ -24,13 +31,11 @@ Import the iocage backup file (use zip file name) bastille import jailname_$(date +%F).zip -Set your new ip address and interface: +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 - vim /usr/local/bastille/jails/jailname/jail.conf - interface = bastille0; - ip4.addr = "192.168.0.1"; + bastille edit jailname + ip4.addr = bastille0|192.168.0.1/24; - -You can use you 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. From 075ddd90199b199b03600ca50bf7cc8c8d333e67 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 11:58:06 -0700 Subject: [PATCH 04/50] Update usage.rst --- docs/chapters/usage.rst | 79 ++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 37 deletions(-) diff --git a/docs/chapters/usage.rst b/docs/chapters/usage.rst index 9cad2220..e21d659d 100644 --- a/docs/chapters/usage.rst +++ b/docs/chapters/usage.rst @@ -1,3 +1,4 @@ +===== Usage ===== @@ -7,43 +8,47 @@ Usage Bastille is an open-source system for automating deployment and management of containerized applications on FreeBSD. - Usage: - bastille command TARGET [args] + Usage: + bastille command TARGET [args] - Available Commands: - bootstrap Bootstrap a FreeBSD release for container base. - cmd Execute arbitrary command on targeted container(s). - clone Clone an existing container. - 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 targeted container(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). - export Exports a specified container. - help Help about any command. - htop Interactive process viewer (requires htop). - 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). - rdr Redirect host port to container port. - rename Rename a container. - restart Restart a running container. - service Manage services within targeted container(s). - start Start a stopped container. - stop Stop a running container. - sysrc Safely edit rc files within 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). + 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 or container to host or targeted container(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). + export Exports a specified container. + 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). + 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. + Use "bastille -v|--version" for version information. + Use "bastille command -h|--help" for more information about a command. From 45dc812a7c69420f597d313aac322f7b62e34792 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 12:42:14 -0700 Subject: [PATCH 05/50] Update index.rst --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index ca300cd0..ff3d0103 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ https://docs.bastillebsd.org. :caption: Contents: chapters/installation + chapters/gettingstarted chapters/upgrading chapters/networking chapters/usage From 02fb0fd3da669a2b5c391083c97507e417bb6f11 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 12:44:30 -0700 Subject: [PATCH 06/50] Update installation.rst --- docs/chapters/installation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index 1596813b..c083919f 100644 --- a/docs/chapters/installation.rst +++ b/docs/chapters/installation.rst @@ -1,7 +1,7 @@ Installation ============ Bastille is available in the official FreeBSD ports tree at -`sysutils/bastille`. Binary packages available in `quarterly` and `latest` +`sysutils/bastille`. Binary packages are available in `quarterly` and `latest` repositories. Current version is `0.13.20250126`. @@ -12,7 +12,7 @@ To install from the FreeBSD package repository: * latest repository will match recent ports -PKG +pkg --- .. code-block:: shell @@ -34,7 +34,7 @@ ports sysrc bastille_rcorder=YES -GIT +git --- .. code-block:: shell From 2427266803e16bd7899aeffa519b91cb7aa4b6d7 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 12:56:20 -0700 Subject: [PATCH 07/50] docs: Add template to sub-commands --- docs/chapters/subcommands/template.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/chapters/subcommands/template.rst diff --git a/docs/chapters/subcommands/template.rst b/docs/chapters/subcommands/template.rst new file mode 100644 index 00000000..425b928c --- /dev/null +++ b/docs/chapters/subcommands/template.rst @@ -0,0 +1,22 @@ +template +======== + +Run preconfigured template files inside targeted jail(s). + +.. code-block:: shell + + 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 +hooks. See the chapter called Template for a list of supported hooks. + +.. code-block:: shell + + ishmael ~ # bastille template help + Usage: bastille template [option(s)] TARGET [--convert|project/template] + + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -x | --debug Enable debug mode. From 2121d7812495a20926fb37aa7ab4227ead0a245a Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 12:58:35 -0700 Subject: [PATCH 08/50] docs: Add missing subcommands to index --- docs/chapters/subcommands/index.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/index.rst b/docs/chapters/subcommands/index.rst index 5f860768..d241ca5a 100644 --- a/docs/chapters/subcommands/index.rst +++ b/docs/chapters/subcommands/index.rst @@ -6,19 +6,25 @@ Bastille sub-commands :caption: Contents: bootstrap - cmd clone + cmd + config console convert cp create destroy edit + etcupdate export htop import + jcp + limits + list mount pkg + rcp rdr rename restart @@ -33,3 +39,4 @@ Bastille sub-commands update upgrade verify + zfs From b828d74fef6b00c10c966a58058fe900261b9850 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:04:05 -0700 Subject: [PATCH 09/50] Update bootstrap.rst --- docs/chapters/subcommands/bootstrap.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst index 11462009..39a3606b 100644 --- a/docs/chapters/subcommands/bootstrap.rst +++ b/docs/chapters/subcommands/bootstrap.rst @@ -1,4 +1,3 @@ -========= bootstrap ========= @@ -15,12 +14,11 @@ let us know. In this document we will describe using the `bootstrap` sub-command with both releases and templates. We begin with releases. - Releases -======== +-------- Example -------- +^^^^^^^ To `bootstrap` a FreeBSD release, run the bootstrap sub-command with the release version as the argument. @@ -44,7 +42,7 @@ download the base.txz. These files are verified (sha256 via MANIFEST file) before they are extracted for use. EOL Releases ------------- +^^^^^^^^^^^^ It is sometimes necessary to run end-of-life releases for testing or legacy application support. By default Bastille will only install supported releases @@ -59,7 +57,7 @@ By overriding the BASTILLE_URL_FREEBSD variable you can now bootstrap archived 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 @@ -67,7 +65,7 @@ immediately after the bootstrap, effectively bootstrapping and applying security patches and errata in one motion. Notes ------ +^^^^^ 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 @@ -85,7 +83,7 @@ mileage may vary; let me know what happens. Templates -========= +--------- Bastille aims to integrate container automation into the platform while maintaining a simple, uncomplicated design. Templates are git repositories with @@ -94,7 +92,7 @@ automation definitions for packages, services, file overlays, etc. To download one of these templates see the example below. Example -------- +^^^^^^^ .. code-block:: shell @@ -103,13 +101,13 @@ Example ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/python3 Tips ----- +^^^^ See the documentation on templates for more information on how they work and how you can create or customize your own. Templates are a powerful part of Bastille and facilitate full container automation. 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. From 6073b57235188ced0265a57834959755c08c151c Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:04:26 -0700 Subject: [PATCH 10/50] Update clone.rst --- docs/chapters/subcommands/clone.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/clone.rst b/docs/chapters/subcommands/clone.rst index 27821e44..c433f3ca 100644 --- a/docs/chapters/subcommands/clone.rst +++ b/docs/chapters/subcommands/clone.rst @@ -1,4 +1,3 @@ -===== clone ===== From e73be7894e33593b5e717e45dc3c2d915de7c01e Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:04:41 -0700 Subject: [PATCH 11/50] Update cmd.rst --- docs/chapters/subcommands/cmd.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/cmd.rst b/docs/chapters/subcommands/cmd.rst index fe2f9903..d6b95e01 100644 --- a/docs/chapters/subcommands/cmd.rst +++ b/docs/chapters/subcommands/cmd.rst @@ -1,4 +1,3 @@ -=== cmd === From 39808cd258ee61fbfbcc67069c37028acbf3a56a Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:04:59 -0700 Subject: [PATCH 12/50] Update config.rst --- docs/chapters/subcommands/config.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/chapters/subcommands/config.rst b/docs/chapters/subcommands/config.rst index bea9008d..c25dfc0e 100644 --- a/docs/chapters/subcommands/config.rst +++ b/docs/chapters/subcommands/config.rst @@ -1,6 +1,5 @@ -======= config -======= +====== Get or set properties for targeted jail(s). From 0e6c70b793d8118548ff98c595f6814110d91c8d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:05:32 -0700 Subject: [PATCH 13/50] Update console.rst --- docs/chapters/subcommands/console.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst index 264a87b5..d25e1a3b 100644 --- a/docs/chapters/subcommands/console.rst +++ b/docs/chapters/subcommands/console.rst @@ -1,4 +1,3 @@ -======= console ======= @@ -10,17 +9,6 @@ This sub-command launches a login shell into the container. Default is password- [folsom]: root@folsom:~ # -TARGET can also be a running jails JID value. - -.. code-block:: shell - - ishmael ~ # bastille list - JID IP Address Hostname Path - 1 10.1.2.3 ishmael /usr/local/bastille/jails/ishmael/root - ishmael ~ # bastille console 1 - [ishmael]: - root@ishmael:~ # - 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. From b2448abcde31b983a22be1df295e170c3aa1cbd1 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:05:50 -0700 Subject: [PATCH 14/50] Update convert.rst --- docs/chapters/subcommands/convert.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/convert.rst b/docs/chapters/subcommands/convert.rst index 32e5f5d4..b2f35093 100644 --- a/docs/chapters/subcommands/convert.rst +++ b/docs/chapters/subcommands/convert.rst @@ -1,4 +1,3 @@ -======= convert ======= From 728bbc03191d035eab0aa16a5e09e571d65e7969 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:06:06 -0700 Subject: [PATCH 15/50] Update cp.rst --- docs/chapters/subcommands/cp.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/cp.rst b/docs/chapters/subcommands/cp.rst index 57b610b9..5496e526 100644 --- a/docs/chapters/subcommands/cp.rst +++ b/docs/chapters/subcommands/cp.rst @@ -1,4 +1,3 @@ -== cp == From a706fc03d7ab510cb67260486f7af2ff700285fa Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:06:47 -0700 Subject: [PATCH 16/50] Update create.rst --- docs/chapters/subcommands/create.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/chapters/subcommands/create.rst b/docs/chapters/subcommands/create.rst index fd3b9c5d..adab8667 100644 --- a/docs/chapters/subcommands/create.rst +++ b/docs/chapters/subcommands/create.rst @@ -1,4 +1,3 @@ -====== create ====== @@ -30,7 +29,6 @@ address to the new system. 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: From f87998e4f4867346beb3f9c418b780a4905635a7 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:07:17 -0700 Subject: [PATCH 17/50] Update destroy.rst --- docs/chapters/subcommands/destroy.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst index 2ef18414..e3e49133 100644 --- a/docs/chapters/subcommands/destroy.rst +++ b/docs/chapters/subcommands/destroy.rst @@ -1,4 +1,3 @@ -======= destroy ======= From a59eee51228b81b41e2e2515e89b192b15dd598a Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:07:30 -0700 Subject: [PATCH 18/50] Update edit.rst --- docs/chapters/subcommands/edit.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/edit.rst b/docs/chapters/subcommands/edit.rst index 618fbad6..a29f5f6c 100644 --- a/docs/chapters/subcommands/edit.rst +++ b/docs/chapters/subcommands/edit.rst @@ -1,4 +1,3 @@ -==== edit ==== From 367889948e088429a3e6192a90d134bf21530268 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:07:47 -0700 Subject: [PATCH 19/50] Update etcupdate.rst --- docs/chapters/subcommands/etcupdate.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/etcupdate.rst b/docs/chapters/subcommands/etcupdate.rst index cec9a411..4d21f3f2 100644 --- a/docs/chapters/subcommands/etcupdate.rst +++ b/docs/chapters/subcommands/etcupdate.rst @@ -1,4 +1,3 @@ -========= etcupdate ========= From 8ff01aca2546f51862c7dc2335ec7132f907cee6 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:08:12 -0700 Subject: [PATCH 20/50] Update export.rst --- docs/chapters/subcommands/export.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/export.rst b/docs/chapters/subcommands/export.rst index 3fb2b5ff..a49e93f8 100644 --- a/docs/chapters/subcommands/export.rst +++ b/docs/chapters/subcommands/export.rst @@ -1,4 +1,3 @@ -====== export ====== From f55612ac7d8aa4e4f5cea174cd55bb5e4a7b976f Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:08:30 -0700 Subject: [PATCH 21/50] Update htop.rst --- docs/chapters/subcommands/htop.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/chapters/subcommands/htop.rst b/docs/chapters/subcommands/htop.rst index 1fcb8bdb..800fe726 100644 --- a/docs/chapters/subcommands/htop.rst +++ b/docs/chapters/subcommands/htop.rst @@ -1,11 +1,9 @@ -==== htop ==== This command runs `htop` in the targeted jail. Requires htop to be installed in the jail. - .. image:: ../../images/htop.png :align: center :alt: bastille htop container From 7927fb9e25891ea327df067741cbdcfc13e9be3f Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:09:36 -0700 Subject: [PATCH 22/50] Update import.rst --- docs/chapters/subcommands/import.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/chapters/subcommands/import.rst b/docs/chapters/subcommands/import.rst index be14e880..85100f01 100644 --- a/docs/chapters/subcommands/import.rst +++ b/docs/chapters/subcommands/import.rst @@ -1,4 +1,3 @@ -====== import ====== @@ -11,6 +10,8 @@ Import a container backup image or archive. The import sub-command supports both UFS and ZFS storage. ZFS based containers 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 file [option] + Usage: bastille import [option(s)] file [RELEASE] From 5ee33c7265e413c02c3b72a9e1b20cf4ecc3690a Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:09:53 -0700 Subject: [PATCH 23/50] Update jcp.rst --- docs/chapters/subcommands/jcp.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/jcp.rst b/docs/chapters/subcommands/jcp.rst index 6dca3c3d..6035d370 100644 --- a/docs/chapters/subcommands/jcp.rst +++ b/docs/chapters/subcommands/jcp.rst @@ -1,4 +1,3 @@ -=== jcp === From 55a3e10651652cda6ef7ec5ffcc410e3a609cd74 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:10:09 -0700 Subject: [PATCH 24/50] Update limits.rst --- docs/chapters/subcommands/limits.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/limits.rst b/docs/chapters/subcommands/limits.rst index b48caf70..7aee8be4 100644 --- a/docs/chapters/subcommands/limits.rst +++ b/docs/chapters/subcommands/limits.rst @@ -1,4 +1,3 @@ -====== limits ====== From b8432a4d4f0ffd0683c00fd223c0a617b6e9eca3 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:10:25 -0700 Subject: [PATCH 25/50] Update list.rst --- docs/chapters/subcommands/list.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/list.rst b/docs/chapters/subcommands/list.rst index 14fb46e0..82b78f12 100644 --- a/docs/chapters/subcommands/list.rst +++ b/docs/chapters/subcommands/list.rst @@ -1,4 +1,3 @@ -==== list ==== From 192bcb75c138ad0b208283813043c02707384174 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:10:41 -0700 Subject: [PATCH 26/50] Update mount.rst --- docs/chapters/subcommands/mount.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst index 2f37f47b..c3e643c3 100644 --- a/docs/chapters/subcommands/mount.rst +++ b/docs/chapters/subcommands/mount.rst @@ -1,4 +1,3 @@ -===== mount ===== From 15635da6c152526f964f0f4e4816d12cba2540ca Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:10:58 -0700 Subject: [PATCH 27/50] Update pkg.rst --- docs/chapters/subcommands/pkg.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/pkg.rst b/docs/chapters/subcommands/pkg.rst index 3a098669..bd999227 100644 --- a/docs/chapters/subcommands/pkg.rst +++ b/docs/chapters/subcommands/pkg.rst @@ -1,4 +1,3 @@ -=== pkg === From 3ebe3784807938678cffcc2a57f1830bd107a458 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:11:11 -0700 Subject: [PATCH 28/50] Update rcp.rst --- docs/chapters/subcommands/rcp.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/rcp.rst b/docs/chapters/subcommands/rcp.rst index fd4ab86f..c01bcc90 100644 --- a/docs/chapters/subcommands/rcp.rst +++ b/docs/chapters/subcommands/rcp.rst @@ -1,4 +1,3 @@ -=== rcp === From 6b4eb50b5a4223fe3a5b1e5e6520c0e3aaf94f69 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:13:09 -0700 Subject: [PATCH 29/50] Update rdr.rst --- docs/chapters/subcommands/rdr.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/chapters/subcommands/rdr.rst b/docs/chapters/subcommands/rdr.rst index 262f83b8..e5ca6bc2 100644 --- a/docs/chapters/subcommands/rdr.rst +++ b/docs/chapters/subcommands/rdr.rst @@ -1,4 +1,3 @@ -=== rdr === @@ -12,16 +11,6 @@ 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 - - # bastille rdr --help - Usage: bastille rdr TARGET [option(s)] [clear|reset|list|(tcp|udp host_port jail_port [log ['(' logopts ')'] ] )] - Options: - - -i | --interface [interface] Set the interface to create the rdr rule on. Useful if you have multiple interfaces. - -s | --source [source ip] Limit rdr to a source IP. Useful to only allow access from a certian IP or subnet. - -d | --destination [destination ip] Limit rdr to a destination IP. Useful if you have multiple IPs on one interface. - -t | --type [ipv4|ipv6] Specify IP type. Must be used if -s or -d are used. Defaults to both. - -x | --debug Enable debug mode. # bastille rdr dev1 tcp 2001 22 [jail1]: @@ -78,3 +67,16 @@ 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. + +.. code-block:: shell + + # bastille rdr --help + Usage: bastille rdr TARGET [option(s)] [clear|reset|list|(tcp|udp host_port jail_port [log ['(' logopts ')'] ] )] + + Options: + + -i | --interface [interface] Set the interface to create the rdr rule on. Useful if you have multiple interfaces. + -s | --source [source ip] Limit rdr to a source IP. Useful to only allow access from a certian IP or subnet. + -d | --destination [destination ip] Limit rdr to a destination IP. Useful if you have multiple IPs on one interface. + -t | --type [ipv4|ipv6] Specify IP type. Must be used if -s or -d are used. Defaults to both. + -x | --debug Enable debug mode. From ed3723396ce99bf37449bfbc9ae99b5d7f2ed571 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:13:23 -0700 Subject: [PATCH 30/50] Update rename.rst --- docs/chapters/subcommands/rename.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/rename.rst b/docs/chapters/subcommands/rename.rst index a36110b1..ccd812a7 100644 --- a/docs/chapters/subcommands/rename.rst +++ b/docs/chapters/subcommands/rename.rst @@ -1,4 +1,3 @@ -====== rename ====== From 7a83c7cb0dbbc01acbcba0cfc1eccd3bcfc1975f Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:13:38 -0700 Subject: [PATCH 31/50] Update restart.rst --- docs/chapters/subcommands/restart.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/restart.rst b/docs/chapters/subcommands/restart.rst index 8948fb7a..2f6bf52a 100644 --- a/docs/chapters/subcommands/restart.rst +++ b/docs/chapters/subcommands/restart.rst @@ -1,4 +1,3 @@ -======= restart ======= From 353dfcd0b7c723363b2d0313ecb0b9a08bf0039d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:13:53 -0700 Subject: [PATCH 32/50] Update service.rst --- docs/chapters/subcommands/service.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/service.rst b/docs/chapters/subcommands/service.rst index 72ab8f3e..1f67a045 100644 --- a/docs/chapters/subcommands/service.rst +++ b/docs/chapters/subcommands/service.rst @@ -1,4 +1,3 @@ -======= service ======= From 7faf8bdc23132e2b67b4ddbd7be88b0cfe595c2c Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:14:07 -0700 Subject: [PATCH 33/50] Update setup.rst --- docs/chapters/subcommands/setup.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/setup.rst b/docs/chapters/subcommands/setup.rst index cf5ddfbc..3ae38efc 100644 --- a/docs/chapters/subcommands/setup.rst +++ b/docs/chapters/subcommands/setup.rst @@ -1,4 +1,3 @@ -===== setup ===== From 41bda189000f88db2ea276251e383d03f5587e76 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:14:51 -0700 Subject: [PATCH 34/50] Update setup.rst --- docs/chapters/subcommands/setup.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/chapters/subcommands/setup.rst b/docs/chapters/subcommands/setup.rst index 3ae38efc..39a2a09f 100644 --- a/docs/chapters/subcommands/setup.rst +++ b/docs/chapters/subcommands/setup.rst @@ -13,3 +13,8 @@ options for a Bastille host with one command. ishmael ~ # bastille setup zfs ## only configure ZFS storage ishmael ~ # bastille setup vnet ## only configure VNET bridge ishmael ~ # bastille setup ## configure all of the above + +.. code-block:: shell + + ishmael ~ # bastille setup help + Usage: bastille setup [pf|network|zfs|vnet] From eac162dd32a06a0ba67ab3863c734793617db875 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:15:50 -0700 Subject: [PATCH 35/50] Update start.rst --- docs/chapters/subcommands/start.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/start.rst b/docs/chapters/subcommands/start.rst index 9057a707..6f1ddfc6 100644 --- a/docs/chapters/subcommands/start.rst +++ b/docs/chapters/subcommands/start.rst @@ -1,4 +1,3 @@ -===== start ===== @@ -9,3 +8,12 @@ To start a container you can use the `bastille start` command. ishmael ~ # bastille start folsom [folsom]: folsom: created + +.. code-block:: shell + + ishmael ~ # bastille start help + Usage: bastille start [option(s)] TARGET + Options: + + -v | --verbose Print every action on jail start. + -x | --debug Enable debug mode. From a02ccf43371770407b0d6df7630cbfe7e7a91dab Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:16:21 -0700 Subject: [PATCH 36/50] Update stop.rst --- docs/chapters/subcommands/stop.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/stop.rst b/docs/chapters/subcommands/stop.rst index 3ee7e507..4642d035 100644 --- a/docs/chapters/subcommands/stop.rst +++ b/docs/chapters/subcommands/stop.rst @@ -1,4 +1,3 @@ -==== stop ==== @@ -9,3 +8,12 @@ To stop a container you can use the `bastille stop` command. ishmael ~ # bastille stop folsom [folsom]: folsom: removed + +.. code-block:: shell + + ishmael ~ # bastille stop help + Usage: bastille stop [option(s)] TARGET + Options: + + -v | --verbose Print every action on jail stop. + -x | --debug Enable debug mode. From e98bb482bf6ec7559758501fe1e3641e043c878d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:16:34 -0700 Subject: [PATCH 37/50] Update sysrc.rst --- docs/chapters/subcommands/sysrc.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/sysrc.rst b/docs/chapters/subcommands/sysrc.rst index 1e6fb8c1..9aa21871 100644 --- a/docs/chapters/subcommands/sysrc.rst +++ b/docs/chapters/subcommands/sysrc.rst @@ -1,4 +1,3 @@ -===== sysrc ===== From 4bc130947af51aa9890d2fb4eadbd8d0f3994e2d Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:16:46 -0700 Subject: [PATCH 38/50] Update tags.rst --- docs/chapters/subcommands/tags.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/tags.rst b/docs/chapters/subcommands/tags.rst index 93a39955..96adf7da 100644 --- a/docs/chapters/subcommands/tags.rst +++ b/docs/chapters/subcommands/tags.rst @@ -1,4 +1,3 @@ -==== tags ==== From e13a0fdf873a020c9a703ffeab80b865eca7cf93 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:18:10 -0700 Subject: [PATCH 39/50] Update top.rst --- docs/chapters/subcommands/top.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/top.rst b/docs/chapters/subcommands/top.rst index 77e7f831..3e65815d 100644 --- a/docs/chapters/subcommands/top.rst +++ b/docs/chapters/subcommands/top.rst @@ -1,4 +1,3 @@ -=== top === @@ -8,3 +7,12 @@ This command runs `top` in the targeted jail. .. image:: ../../images/top.png :align: center :alt: bastille top container + +.. code-block:: shell + + ishmael ~ # bastille top help + Usage: bastille top [options(s)] TARGET + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -x | --debug Enable debug mode. From 870a1d376d852ab71819b23e2128364d5e645ce3 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:18:29 -0700 Subject: [PATCH 40/50] Update htop.rst --- docs/chapters/subcommands/htop.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/chapters/subcommands/htop.rst b/docs/chapters/subcommands/htop.rst index 800fe726..1215ffad 100644 --- a/docs/chapters/subcommands/htop.rst +++ b/docs/chapters/subcommands/htop.rst @@ -7,3 +7,12 @@ Requires htop to be installed in the jail. .. image:: ../../images/htop.png :align: center :alt: bastille htop container + +..code-block:: shell + + ishmael ~ # bastille htop help + Usage: bastille htop [options(s)] TARGET + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -x | --debug Enable debug mode. From 3200140eb90d87c5159d9d6829807ae0b88dd336 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:18:38 -0700 Subject: [PATCH 41/50] Update htop.rst --- docs/chapters/subcommands/htop.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/chapters/subcommands/htop.rst b/docs/chapters/subcommands/htop.rst index 1215ffad..eef6ef56 100644 --- a/docs/chapters/subcommands/htop.rst +++ b/docs/chapters/subcommands/htop.rst @@ -8,7 +8,7 @@ Requires htop to be installed in the jail. :align: center :alt: bastille htop container -..code-block:: shell +.. code-block:: shell ishmael ~ # bastille htop help Usage: bastille htop [options(s)] TARGET From 310346caa021ba6c53e69cd0b4291efded038119 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:18:52 -0700 Subject: [PATCH 42/50] Update umount.rst --- docs/chapters/subcommands/umount.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/umount.rst b/docs/chapters/subcommands/umount.rst index 2dbfdafa..849d4f53 100644 --- a/docs/chapters/subcommands/umount.rst +++ b/docs/chapters/subcommands/umount.rst @@ -1,4 +1,3 @@ -====== umount ====== From 91d6c668a9822b7002404431d6dcd75e9b41a3d9 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:19:03 -0700 Subject: [PATCH 43/50] Update update.rst --- docs/chapters/subcommands/update.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/update.rst b/docs/chapters/subcommands/update.rst index e1a6bae4..259813fa 100644 --- a/docs/chapters/subcommands/update.rst +++ b/docs/chapters/subcommands/update.rst @@ -1,4 +1,3 @@ -====== update ====== From de636d3e5791d95d29ae21e7c02e456223813eb7 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:19:16 -0700 Subject: [PATCH 44/50] Update upgrade.rst --- docs/chapters/subcommands/upgrade.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst index bbff8af4..daebb503 100644 --- a/docs/chapters/subcommands/upgrade.rst +++ b/docs/chapters/subcommands/upgrade.rst @@ -1,4 +1,3 @@ -======= upgrade ======= From 935e4424ec2311f5400baa09af8b83149c57c260 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:19:31 -0700 Subject: [PATCH 45/50] Update verify.rst --- docs/chapters/subcommands/verify.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/verify.rst b/docs/chapters/subcommands/verify.rst index de2b85ad..fe5b3cd7 100644 --- a/docs/chapters/subcommands/verify.rst +++ b/docs/chapters/subcommands/verify.rst @@ -1,4 +1,3 @@ -====== verify ====== From b08286bfa1ded6cd7e9a86eb2ef5dd7ece58ae6f Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:19:46 -0700 Subject: [PATCH 46/50] Update zfs.rst --- docs/chapters/subcommands/zfs.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/subcommands/zfs.rst b/docs/chapters/subcommands/zfs.rst index f010d16f..d2388f1d 100644 --- a/docs/chapters/subcommands/zfs.rst +++ b/docs/chapters/subcommands/zfs.rst @@ -1,4 +1,3 @@ -=== zfs === From b4f75a47dbe67cb4255381a1e7ba2dff62f57204 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:24:46 -0700 Subject: [PATCH 47/50] Update networking.rst --- docs/chapters/networking.rst | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 48d0e4a9..701fb05b 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -1,5 +1,8 @@ -Network Basics - IP Address -=========================== +Networking +========== + +IP Address Options +------------------ Bastille includes a number of IP options. @@ -32,8 +35,9 @@ 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. -Network Requirements -==================== +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 @@ -59,7 +63,8 @@ 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 -================================================ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + If you have just one computer, or a home or small office network, where you are separated from the rest of the internet by a router. So you are free to use `private IP addresses @@ -83,7 +88,8 @@ 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. Shared Interface on IPV6 network (vultr.com) -============================================ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + 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. @@ -130,7 +136,8 @@ use `wget`/`curl`/`fetch` to test the connectivity. 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. @@ -198,7 +205,8 @@ Below is the definition of what these three parameters are used for and mean: interface, set to 0 to disable it. -**Regarding Routes** +Regarding Routes +---------------- 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 @@ -222,7 +230,8 @@ This config change will apply the defined gateway to any new containers. Existing containers will need to be manually updated. 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. @@ -235,7 +244,8 @@ bridge and connect / disconnect containers as they are started and stopped. The bridge needs to be created/enabled before creating and starting the jail. 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 @@ -247,6 +257,7 @@ network. loopback (bastille0) -------------------- + 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 @@ -280,7 +291,8 @@ Second, enable the firewall: Create the firewall rules: /etc/pf.conf ------------- +^^^^^^^^^^^^ + .. code-block:: shell ext_if="vtnet0" @@ -345,7 +357,7 @@ ssh session and continue. 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. From c605d8c71195dd605637da956f9f21f2fc5b0b7f Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:26:20 -0700 Subject: [PATCH 48/50] Update template.rst --- docs/chapters/template.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index 0c45bead..a2a317cf 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -1,4 +1,3 @@ -======== Template ======== Looking for ready made CI/CD validated `Bastille Templates`_? From 07106c5889b69703c5ba3ea5a5a3c7de2be15a6e Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:47:15 -0700 Subject: [PATCH 49/50] docs: Clarify what the host does in different network scenarios --- docs/chapters/networking.rst | 45 +++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 701fb05b..520b936e 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -12,29 +12,46 @@ Bastille includes a number of IP options. The IP address specified above can be any of the following options. -1. 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. -2. 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`. -3. 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. -4. 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. -5. 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. -6. 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. +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. + +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. + +* 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. + +* 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. + Network Scenarios ----------------- From 870a8aff16759750ad0a5066b330eb2f745bc149 Mon Sep 17 00:00:00 2001 From: tschettervictor <85497460+tschettervictor@users.noreply.github.com> Date: Sat, 1 Mar 2025 13:53:38 -0700 Subject: [PATCH 50/50] Update export.rst --- docs/chapters/subcommands/export.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/chapters/subcommands/export.rst b/docs/chapters/subcommands/export.rst index a49e93f8..848c1026 100644 --- a/docs/chapters/subcommands/export.rst +++ b/docs/chapters/subcommands/export.rst @@ -15,16 +15,16 @@ can be exported only when the jail is not running. .. code-block:: shell - Usage: bastille export | option(s) | TARGET | PATH + Usage: bastille export [option(s)] TARGET PATH Available options are: .. code-block:: shell - --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. - --tgz -- Export a jail using simple .tgz compressed archive instead. - --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. + --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. + --tgz Export a jail using simple .tgz compressed archive instead. + --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.