Mirrors/BastilleBSD_bastille
1
0
Fork 1
mirror of https://github.com/BastilleBSD/bastille.git synced 2025-12-11 01:19:52 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1272 from BastilleBSD/pkgbase

Browse Source
This commit is contained in:
tschettervictor
2025-11-09 12:06:22 -07:00
committed by GitHub
parent 1d0d2150a5 d1ea15002b
commit e99cc7b75b
15 changed files with 810 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/chapters/comparing.rst
View File

@@ -19,7 +19,7 @@ as a list of popular managers and their status on each option.
| | | | Rust | | Python |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Dep | None | C | Rust | None | Python |
| endencies | | | | | |
|endencies | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Jail | vnet, | clone, | thick | basejail | clone, |
| Types | bridged | copy, | | | basejail, |
@@ -33,16 +33,15 @@ as a list of popular managers and their status on each option.
| Jail | Yes | Yes | Yes | No | Yes |
| Dependency | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Impo | Yes | Yes | Yes | Yes | Yes |
| rt/Export | | | | | |
| Import/ | Yes | Yes | Yes | Yes | Yes |
| Export | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Boot | Yes | Yes | No | Yes using | Yes |
| Order | | | | 'rcorder' | |
| Priorities | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Linux | Yes | Yes | No | No | Yes |
| c | | | | | |
| ontainers | | | | | |
| Containers | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Automation | Templates | Makejail, | Flavours, | Flavours | Plugins |
| | | Initscripts, | Images | | |
@@ -90,6 +89,9 @@ as a list of popular managers and their status on each option.
| | | jails & | | | |
| | | NAT) | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| PkgBase | Yes | Yes | No | No | No |
| Support | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+
| Multi-target | Yes | No | No | No | No |
| Commands | | | | | |
+--------------+-------------+--------------+-----------+-----------+-----------+

18
docs/chapters/configuration.rst
View File

@@ -41,6 +41,24 @@ This is the default `bastille.conf` file.
## bastille_bootstrap_archives="base lib32 ports src test"
bastille_bootstrap_archives="base" ## default: "base"
## pkgbase package sets (used for FreeBSD 15+)
## Any set with [-dbg] can be installed with debugging
## symbols by adding '-dbg' to the package set
## base[-dbg] - Base system
## base-jail[-dbg] - Base system for jails
## devel[-dbg] - Development tools
## kernels[-dbg] - Base system kernels
## lib32[-dbg] - 32-bit compatability libraries
## minimal[-dbg] - Basic multi-user system
## minimal-jail[-dbg] - Basic multi-user jail system
## optional[-dbg] - Optional base system software
## optional-jail[-dbg] - Optional base system software for jails
## src - System source code
## tests - System test suite
## Whitespace separated list:
## bastille_pkgbase_packages="base-jail lib32-dbg src"
bastille_pkgbase_packages="base-jail" ## default: "base-jail"
## default timezone
bastille_tzdata="" ## default: empty to use host's time zone

61
docs/chapters/pkgbase.rst Normal file
View File

@@ -0,0 +1,61 @@
Pkgbase
=======
Pkgbase is the new method for managing the base system on a FreeBSD host
or jail. It is considered experimental for 15.0-RELEASE, but will be
made the default for version 16.0-RELEASE and above.
Bootstrap
---------
To bootstrap a release using pkgbase, run ``bastille bootstrap --pkgbase RELEASE``.
For version 14, it is not supported. For version 15 it is optional, but
for version 16 and above, it is the default method of bootstrapping a release.
Update
------
To update a release created with pkgbase, simply run ``bastille update RELEASE`` as
you would with legacy releases.
To update a thick jail, run ``bastille update TARGET`` as you would with legacy
releases.
To update a thin jail, you must update the release that it is based on.
Upgrade
-------
Upgrading is not supported for releases. See ``bastille bootstrap RELEASE`` to
bootstrap the required release.
Upgrading is supported for both thin and thick jails. Thin jails will have their
mount points adjusted, and you will need to run ``bastille etcupdate`` on them
when upgrading from a major release to a newer major release. For example,
15.0-RELEASE to 16.0-RELEASE.
Converting to Pkgbase
---------------------
Thick jails that are running legacy releases will have to be converted to pkgbase
before attempting to upgrade to 16.0-RELEASE. This can be done in two ways.
1. Enter the jail, fetch the ``pkgbasify`` script, and run it.
.. code-block:: shell
fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkgbasify.lua
chmod +x pkgbasify.lua
./pkgbasify.lua
2. Fetch the ``pkgbasify`` script and run it from the host using ``--rootdir``.
.. code-block:: shell
fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkgbasify.lua
chmod +x pkgbasify.lua
./pkgbasify.lua --rootdir /usr/local/bastille/jails/TARGET/root
Converting a release to pkgbase can be done the same way, but we recommend simply destroying
and re-bootstrapping it using pkgbase. This will not work if you are running thin jails
based on the release in question. In such a case, follow step 2 above.

1
docs/chapters/subcommands/bootstrap.rst
View File

@@ -126,4 +126,5 @@ begin applying your template.
Options:
-p | --pkgbase Bootstrap using pkgbase (15.0-RELEASE and above).
-x | --debug Enable debug mode.

119
docs/chapters/upgrading.rst
View File

@@ -12,15 +12,14 @@ To keep releases updated, use ``bastille update RELEASE``
To keep thick jails updated, use ``bastille update TARGET``
----------------------
Minor Release Upgrades
----------------------
Minor Release Upgrades - Legacy
-------------------------------
To upgrade Bastille jails for a minor release (ie; 13.1→13.2) you can do the
To upgrade Bastille jails for a minor release (ie; 13.1 > 13.2) you can do the
following:
Thick Jails
-----------
^^^^^^^^^^^
1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to
13.2-RELEASE
@@ -31,7 +30,7 @@ Thick Jails
5. Upgrade complete!
Thin Jails
----------
^^^^^^^^^^
1. Ensure the new release version is bootstrapped: ``bastille bootstrap 13.2-RELEASE``
2. Update the release (optional): ``bastille update 13.2-RELEASE``
@@ -40,15 +39,14 @@ Thin Jails
5. Start the jail(s)
6. Upgrade complete!
----------------------
Major Release Upgrades
----------------------
Major Release Upgrades - Legacy
-------------------------------
To upgrade Bastille jails for a major release (ie; 12.4→13.2) you can do the
To upgrade Bastille jails for a major release (ie; 12.4 > 13.2) you can do the
following:
Thick Jails
-----------
^^^^^^^^^^^
1. Use ``bastille upgrade TARGET 13.2-RELEASE`` to upgrade the jail to
13.2-RELEASE
@@ -61,12 +59,11 @@ Thick Jails
6. Upgrade complete!
Thin Jails
----------
^^^^^^^^^^
1. Ensure the new release version is bootstrapped and updated to the latest
patch release: ``bastille bootstrap 13.2-RELEASE``
1. Ensure the new release version is bootstrapped: ``bastille bootstrap 13.2-RELEASE``
2. Update the release: ``bastille update 13.2-RELEASE``
3. Stop the jail(s) that are bound to the release being updated.
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
@@ -79,28 +76,102 @@ Thin Jails
``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
10. Upgrade complete!
----------------------------------
Minor Release Upgrades - Pkgbase
--------------------------------
To upgrade Bastille jails for a minor release (ie; 15.1 > 15.2) you can do the
following:
Thick Jails
^^^^^^^^^^^
1. Use ``bastille upgrade TARGET 15.2-RELEASE`` to upgrade the jail to
15.2-RELEASE
2. Reboot the jail ``bastille restart TARGET``
3. Upgrade complete!
Thin Jails
^^^^^^^^^^
1. Ensure the new release version is bootstrapped: ``bastille bootstrap --pkgbase 15.2-RELEASE``
2. Update the release (optional): ``bastille update 15.2-RELEASE``
3. Stop the jail(s) that need to be updated.
4. Use ``bastille upgrade TARGET 15.2-RELEASE`` to automatically change the mount points to 15.2-RELEASE
5. Start the jail(s)
6. Upgrade complete!
Major Release Upgrades - Pkgbase
--------------------------------
To upgrade Bastille jails for a major release (ie; 15.5 > 16.0) you can do the
following:
Thick Jails
^^^^^^^^^^^
1. Use ``bastille upgrade TARGET 16.0-RELEASE`` to upgrade the jail to
16.0-RELEASE
2. Reboot the jail ``bastille restart TARGET``
3. Force the reinstallation or upgrade of all installed packages (ABI change):
``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
4. Upgrade complete!
Thin Jails
^^^^^^^^^^
1. Ensure the new release version is bootstrapped: ``bastille bootstrap 16.0-RELEASE``
2. Update the release: ``bastille update 16.0-RELEASE``
3. Stop the jail(s) that need to be updated.
4. Use ``bastille upgrade TARGET 16.0-RELEASE`` to automatically change the
mount points to 16.0-RELEASE
5. Use ``bastille etcupdate bootstrap 16.0-RELEASE`` to bootstrap src for
16.0-RELEASE
6. Use ``bastille etcupdate TARGET update 16.0-RELEASE`` to update the contents
of /etc for 16.0-RELEASE
7. Use ``bastille etcupdate TARGET resolve`` to resolve any conflicts
8. Start the jail(s)
9. Force the reinstallation or upgrade of all installed packages (ABI change):
``pkg upgrade -f`` within each jail (or ``bastille pkg ALL upgrade -f``)
10. Upgrade complete!
Updating
--------
To keep jails updated with the latest security patches and base,
use the ``bastille update`` command.
Thick Jails
^^^^^^^^^^^
Use ``bastille update TARGET`` to update the jail with the latest
patches and security updates.
Thin Jails
^^^^^^^^^^
Use ``bastille update RELEASE`` to update the release that any thin jails
are based on with the latest patches and security updates.
Revert Upgrade / Downgrade Process
----------------------------------
The downgrade process (not usually needed) is similar to the upgrade 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 pkg re-installation will also need to be repeated after the jail restarts on
the previous release.
------------
Old Releases
------------
@@ -108,10 +179,10 @@ After upgrading all jails from one release to the next you may find that you now
have bootstrapped a release that is no longer used. Once you've decided that you
no longer need the option to revert the change you can destroy the old release.
``bastille list releases`` to list all bootstrapped releases.
``bastille destroy X.Y-RELEASE`` to fully delete the release, including the
cache.
cache (cache is not used with pkgbase).
``bastille destroy [-c|--no-cache] X.Y-RELEASE`` to retain the cache directory.
``bastille destroy [-c|--no-cache] X.Y-RELEASE`` to retain the cache directory
(not supported when using pkgbase).

2
docs/chapters/usage.rst
View File

@@ -35,7 +35,7 @@ Usage
rcp cp(1) files from a jail to host.
rdr Redirect host port to jail port.
rename Rename a jail.
restart Restart a running jail.
restart Restart a jail.
service Manage services within targeted jail(s).
setup Attempt to auto-configure network, firewall and storage and more...
start Start a stopped jail.

1
docs/index.rst
View File

@@ -27,6 +27,7 @@ https://docs.bastillebsd.org.
chapters/zfs-support
chapters/gcp
chapters/migration
chapters/pkgbase
copyright