diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index d94bf27d7..8b78b5dbb 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -120,6 +120,10 @@ container interfaces as they are started and stopped. These interface names match the pattern `eXb_bastilleX`. Internally to the containers these interfaces are presented as `vnet0`. +If you do not specify a subnet mask, you might have issues with jail to jail +networking, especially VLAN to VLAN. We recommend always adding a subnet to +VNET jail IPs when creating them to avoid these issues. + VNET also requires a custom devfs ruleset. Create the file as needed on the host system: @@ -305,3 +309,21 @@ At this point you'll likely be disconnected from the host. Reconnect the 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. + +To resolve this, add the following configuration to local_unbound: + +.. code-block:: shell + + server: + interface: 0.0.0.0 + access-control: 192.168.0.0/16 allow + access-control: 10.17.90.0/24 allow + +Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf + +Adjust the above "access-control" strings to fit your network. diff --git a/docs/chapters/subcommands/etcupdate.rst b/docs/chapters/subcommands/etcupdate.rst new file mode 100644 index 000000000..cec9a4113 --- /dev/null +++ b/docs/chapters/subcommands/etcupdate.rst @@ -0,0 +1,46 @@ +========= +etcupdate +========= + +This command will update the contents of `/etc` inside a jail. It should be run after a jail upgrade + +First we need to bootstrap a release for `etcupdate` to use. + +.. code-block:: shell + + ishmael ~ # bastille etcupdate bootstrap 14.1-RELEASE + bastille_bootstrap_archives: base -> src + /usr/local/bastille/cache/14.1-RELEASE/MANIFES 1046 B 1134 kBps 00s + /usr/local/bastille/cache/14.1-RELEASE/src.txz 205 MB 2711 kBps 01m18s + bastille_bootstrap_archives: src -> base + Building tarball, please wait... + Etcupdate bootstrap complete: 14.1-RELEASE + +Next we can use the `update` command to apply the update to the jail. + +.. code-block:: shell + + ishmael ~ # bastille etcupdate ishmael update 14.1-RELEASE + +The output will show you which files were added, updated, changed, deleted, or have conflicts. +To automatically resolve the conflicts, run the `resolve` command. + +.. code-block:: shell + + ishmael ~ # bastille etcupdate ishmael resolve + +To show only the differences between the releases, use the `diff` command. + +.. code-block:: shell + + ishmael ~ # bastille etcupdate ishmael diff 14.1-RELEASE + +.. code-block:: shell + + ishmael ~ # bastille etcupdate help + Usage: bastille etcupdate [option(s)] [bootstrap|TARGET] [diff|resolve|update RELEASE] + Options: + + -d | --dry-run Show output, but do not apply. + -f | --force Force a re-bootstrap of a RELEASE. + -x | --debug Enable debug mode. diff --git a/docs/chapters/subcommands/update.rst b/docs/chapters/subcommands/update.rst index 4beef6557..e1a6bae47 100644 --- a/docs/chapters/subcommands/update.rst +++ b/docs/chapters/subcommands/update.rst @@ -2,8 +2,8 @@ update ====== -The `update` command targets a release instead of a container. Because every container is -based on a release, when the release is updated all the containers are automatically +The `update` command targets a release or a thick jail. Because thin jails are +based on a release, when the release is updated all the thin jails are automatically updated as well. If no updates are available, a message will be shown: @@ -20,8 +20,7 @@ If no updates are available, a message will be shown: No updates needed to update system to 11.4-RELEASE-p4. No updates are available to install. - -The older the release, however, the more updates will be available: +The older the release or jail, however, the more updates will be available: .. code-block:: shell @@ -38,4 +37,7 @@ The older the release, however, the more updates will be available: The following files will be added as part of updating to 13.2-RELEASE-p4: ...[snip]... -To be safe, you may want to restart any containers that have been updated live. +To be safe, you may want to restart any jails that have been updated live. + +If the jail is a thin jail, an error will be shown. If it is a thick jail, it will be updated just like +the release shown above. diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst new file mode 100644 index 000000000..bbff8af46 --- /dev/null +++ b/docs/chapters/subcommands/upgrade.rst @@ -0,0 +1,16 @@ +======= +upgrade +======= + +The `upgrade` command targets a thick or thin jail. Thin jails will be updated by changing the +release mount point that it is based on. Thick jails will be upgraded normally. + +.. code-block:: shell + + ishmael ~ # bastille upgrade help + Usage: bastille upgrade [option(s)] TARGET [NEWRELEASE|install] + Options: + + -a | --auto Auto mode. Start/stop jail(s) if required. + -f | --force Force upgrade a jail. + -x | --debug Enable debug mode. diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index e3a7d5f1a..0c45bead5 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -6,8 +6,8 @@ Looking for ready made CI/CD validated `Bastille Templates`_? Bastille supports a templating system allowing you to apply files, pkgs and execute commands inside the containers automatically. -Currently supported template hooks are: `CMD`, `CP`, `INCLUDE`, `LIMITS`, `MOUNT`, -`PKG`, `RDR`, `SERVICE`, `SYSRC`. +Currently supported template hooks are: `ARG`, `CMD`, `CONFIG`, `CP`, `INCLUDE`, +`LIMITS`, `MOUNT`, `OVERLAY`, `PKG`, `RDR`, `RENDER`, `RESTART`, `SERVICE`, `SYSRC`. Templates are created in `${bastille_prefix}/templates` and can leverage any of the template hooks. @@ -23,27 +23,75 @@ template hook commands. Template Automation Hooks ------------------------- -+---------+-------------------+-----------------------------------------+ -| HOOK | format | example | -+=========+===================+=========================================+ -| CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh | -+---------+-------------------+-----------------------------------------+ -| CP | path(s) | etc root usr (one per line) | -+---------+-------------------+-----------------------------------------+ -| INCLUDE | template path/URL | http?://TEMPLATE_URL or project/path | -+---------+-------------------+-----------------------------------------+ -| LIMITS | resource value | memoryuse 1G | -+---------+-------------------+-----------------------------------------+ -| MOUNT | fstab syntax | /host/path container/path nullfs ro 0 0 | -+---------+-------------------+-----------------------------------------+ -| PKG | port/pkg name(s) | vim-console zsh git-lite tree htop | -+---------+-------------------+-----------------------------------------+ -| RDR | tcp port port | tcp 2200 22 (hostport jailport) | -+---------+-------------------+-----------------------------------------+ -| SERVICE | service command | 'nginx start' OR 'postfix reload' | -+---------+-------------------+-----------------------------------------+ -| SYSRC | sysrc command(s) | nginx_enable=YES | -+---------+-------------------+-----------------------------------------+ ++-------------+---------------------+-----------------------------------------+ +| HOOK | format | example | ++=============+=====================+=========================================+ +| ARG | ARG=VALUE | MINECRAFT_MEMX="1024M" | ++-------------+---------------------+-----------------------------------------+ +| CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh | ++-------------+---------------------+-----------------------------------------+ +| CONFIG | set property value | set allow.mlock 1 | ++-------------+---------------------+-----------------------------------------+ +| CP/OVERLAY | path(s) | etc root usr (one per line) | ++-------------+---------------------+-----------------------------------------+ +| INCLUDE | template path/URL | http?://TEMPLATE_URL or project/path | ++-------------+---------------------+-----------------------------------------+ +| LIMITS | resource value | memoryuse 1G | ++-------------+---------------------+-----------------------------------------+ +| MOUNT | fstab syntax | /host/path container/path nullfs ro 0 0 | ++-------------+---------------------+-----------------------------------------+ +| OVERLAY | path(s) | etc root usr (one per line) | ++-------------+---------------------+-----------------------------------------+ +| PKG | port/pkg name(s) | vim-console zsh git-lite tree htop | ++-------------+---------------------+-----------------------------------------+ +| RDR | tcp port port | tcp 2200 22 (hostport jailport) | ++-------------+---------------------+-----------------------------------------+ +| RENDER | /path/file.txt | /usr/local/etc/gitea/conf/app.ini | ++-------------+---------------------+-----------------------------------------+ +| RESTART | | (restart jail) | ++-------------+---------------------+-----------------------------------------+ +| SERVICE | service command | 'nginx start' OR 'postfix reload' | ++-------------+---------------------+-----------------------------------------+ +| SYSRC | sysrc command(s) | nginx_enable=YES | ++-------------+---------------------+-----------------------------------------+ + +Template Hook Descriptions +-------------------------- + +ARG - set an ARG value to be used in the template + +ARGS will default to the value set inside the template, but can be changed by including `--arg ARG=VALUE` when +running the template. Multiple ARGS can also be specified as seen below. If no ARG value is given, the template +will show a warning, but will still continue. + +.. code-block:: shell + + ishmael ~ # bastille template azkaban sample/template --arg ARG=VALUE --arg ARG1=VALUE + + +CMD - run the specified command + +CONFIG - set the specified property and value + +CP/OVERLAY - copy specified files from template directory to specified path inside jail + +INCLUDE - specify a template to include. Make sure the template is bootstrapped, or you are using the template url + +LIMITS - set the specified resource value for the jail + +MOUNT - mount specified files/directories inside the jail + +PKG - install specified packages inside jail + +RDR - redirect specified ports to the jail + +RENDER - replace ARG values inside specified files inside the jail. If a directory is specified, ARGS will be replaced in all files underneath + +RESTART - restart the jail + +SERVICE - run `service` command inside the jail with specified arguments + +SYSRC - run `sysrc` inside the jail with specified arguments Special Hook Cases ------------------ @@ -54,6 +102,9 @@ ie; (`\\"`) ARG will always treat an ampersand "\&" literally, without the need to escape it. Escaping it will cause errors. +Template Examples +----------------- + Place these uppercase template hook commands into a `Bastillefile` in any order and automate container setup as needed. diff --git a/docs/chapters/upgrading.rst b/docs/chapters/upgrading.rst index b059fa0d0..1d9161eb6 100644 --- a/docs/chapters/upgrading.rst +++ b/docs/chapters/upgrading.rst @@ -5,31 +5,88 @@ This document outlines upgrading jails hosted using Bastille. Bastille can "bootstrap" multiple versions of FreeBSD to be used by jails. All jails do not NEED to be the same version (even if they often are), the only requirement here is that the "bootstrapped" versions are less than or equal to the host version of FreeBSD. +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: -1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE update` -2. stop the jail(s) that need to be updated. -3. use `bastille edit TARGET fstab` to manually update the jail mounts from 13.1 to 13.2 release path. -4. start the jail(s) that were edited -5. upgrade complete! +Thick Jails +=========== + +1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` +2. update the release: `bastille update 13.2-RELEASE` +3. use `bastille upgrade TARGET 13.2-RELEASE` to upgrade the jail to 13.2-RELEASE +4. use `bastille upgrade TARGET 13.2-RELEASE update` to apply the updates +5. reboot the jail `bastille restart TARGET` +6. use `bastille upgrade TARGET 13.2-RELEASE update` to finish applying the upgrade +7. upgrade complete! + +Thin Jails +========== + +1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` +2. update the release: `bastille update 13.2-RELEASE` +3. stop the jail(s) that need to be updated. +4. use `bastille upgrade TARGET 13.2-RELEASE` to automatically change the mount points to 13.2-RELEASE +5. use `bastille etcupdate bootstrap 13.2-RELEASE` to bootstrap src for 13.2-RELEASE +6. use `bastille etcupdate TARGET update 13.2-RELEASE` to update the contents of /etc for 13.2-RELEASE +7. use `bastille etcupdate TARGET reslove` to resolve any conflicts +8. start the jail(s) +8. upgrade complete! + +====================== +Major Release Upgrades +====================== To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the following: -1. ensure the new version is bootstrapped and update to the latest patch release: `bastille bootstrap 13.2-RELEASE update` -2. stop the jail(s) that need to be updated. -3. use `bastille edit TARGET fstab` to manually update the jail mounts from 12.4 to 13.2 release path. -4. start the jail(s) that were edited -5. Force the reinstallation or upgrade of all installed packages (ABI change): `pkg upgrade -f` within each jail (or `bastille pkg ALL upgrade -f`) -6. restart the affected jail(s) -7. upgrade complete! +Thick Jails +=========== + +1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` +2. update the release: `bastille update 13.2-RELEASE` +3. use `bastille upgrade TARGET 13.2-RELEASE` to upgrade the jail to 13.2-RELEASE +4. use `bastille upgrade TARGET 13.2-RELEASE update` to apply the updates +5. reboot the jail `bastille restart TARGET` +6. use `bastille upgrade TARGET 13.2-RELEASE update` to finish applying the upgrade +7. force the reinstallation or upgrade of all installed packages (ABI change): `pkg upgrade -f` within each jail (or `bastille pkg ALL upgrade -f`) +8. upgrade complete! + +Thin Jails +========== + +1. ensure the new release version is bootstrapped and updated to the latest patch release: `bastille bootstrap 13.2-RELEASE` +2. update the release: `bastille update 13.2-RELEASE` +3. stop the jail(s) that need to be updated. +4. use `bastille upgrade TARGET 13.2-RELEASE` to automatically change the mount points to 13.2-RELEASE +5. use `bastille etcupdate bootstrap 13.2-RELEASE` to bootstrap src for 13.2-RELEASE +6. use `bastille etcupdate TARGET update 13.2-RELEASE` to update the contents of /etc for 13.2-RELEASE +7. use `bastille etcupdate TARGET reslove` to resolve any conflicts +8. start the jail(s) +9. force the reinstallation or upgrade of all installed packages (ABI change): `pkg upgrade -f` within each jail (or `bastille pkg ALL upgrade -f`) +10. upgrade complete! Revert Upgrade / Downgrade Process ---------------------------------- The downgrade process (not usually needed) is similar to the upgrade process only in reverse. -If you did a minor upgrade changing the release path from 13.1 to 13.2, stop the jail and revert that change. Downgrade complete. +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. -If you did a major upgrade changing the release path from 12.4 to 13.2, stop the jail and revert that change. The pkg reinstallation will also need to be repeated after the jail restarts on the previous release. +The pkg reinstallation will also need to be repeated after the jail restarts on the previous release. Old Releases ---------------------------------- @@ -40,4 +97,4 @@ After upgrading all jails from one release to the next you may find that you now `bastille destroy X.Y-RELEASE` to fully delete the release. -`bastille destroy force X.Y-RELEASE` to delete the cache directory as well. +`bastille destroy [-f|--force] X.Y-RELEASE` to delete the cache directory as well. diff --git a/usr/local/share/bastille/etcupdate.sh b/usr/local/share/bastille/etcupdate.sh index 1f0979be2..2f625d413 100644 --- a/usr/local/share/bastille/etcupdate.sh +++ b/usr/local/share/bastille/etcupdate.sh @@ -46,7 +46,7 @@ EOF bootstrap_etc_release() { local _release="${1}" local _current="$(sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives | awk -F': ' '{print $2}')" - if ! ls -A "${bastille_releasesdir}/${_release}/usr/src" 2>/dev/null; then + if [ -z "$(ls -A "${bastille_releasesdir}/${_release}/usr/src")" ]; then sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives=src if ! bastille bootstrap "${_release}" > /dev/null; then sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives="${_current}" diff --git a/usr/local/share/bastille/templates/default/base/Bastillefile b/usr/local/share/bastille/templates/default/base/Bastillefile index 7418fba64..ad8984469 100644 --- a/usr/local/share/bastille/templates/default/base/Bastillefile +++ b/usr/local/share/bastille/templates/default/base/Bastillefile @@ -1,6 +1,9 @@ ARG HOST_RESOLV_CONF=/etc/resolv.conf CMD touch /etc/rc.conf +CMD touch /etc/periodic.conf +CMD sysrc -f /etc/periodic.conf daily_status_world_kernel="NO" + SYSRC syslogd_flags="-ss" SYSRC sendmail_enable="NO" SYSRC sendmail_submit_enable="NO"