pkgbase: add docs

docs/chapters/pkgbase.rst

@@ -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.

docs/chapters/subcommands/bootstrap.rst

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

usr/local/share/bastille/bootstrap.sh

@@ -208,9 +208,7 @@ bootstrap_directories() {
 
 bootstrap_pkgbase_release() {
 
-    local mirror_type="srv"
     local abi="${PLATFORM_OS}:${MAJOR_VERSION}:${HW_MACHINE_ARCH}"
-    local signature_type="fingerprints"
     local fingerprints="${bastille_releasesdir}/${RELEASE}/usr/share/keys/pkg"
     local host_fingerprintsdir="/usr/share/keys/pkg"
     local release_fingerprintsdir="${bastille_releasesdir}/${RELEASE}/usr/share/keys"

usr/local/share/bastille/etcupdate.sh

@@ -43,84 +43,124 @@ EOF
     exit 1
 }
 
+bootstrap_etc_release_pkgbase() {
+
+    local release="${1}"
+    local release_dir="${bastille_releasesdir}/${release}"
+    local abi="FreeBSD:${MAJOR_VERSION}:${HW_MACHINE_ARCH}"
+    local fingerprints="${release_dir}/usr/share/keys/pkg"
+    if [ "${FREEBSD_BRANCH}" = "release" ]; then
+        local repo_name="FreeBSD-base-release-${MINOR_VERSION}"
+    elif [ "${FREEBSD_BRANCH}" = "current" ]; then
+        local repo_name="FreeBSD-base-latest"
+    fi
+    local repo_dir="${bastille_sharedir}/pkgbase"
+
+    if [ -d "${release_dir}" ]; then
+        # Update repo (pkgbase)
+        if ! pkg --rootdir "${release_dir}" \
+                 --repo-conf-dir "${repo_dir}" \
+                  -o IGNORE_OSVERSION="yes" \
+                  -o ABI="${abi}" \
+                  -o ASSUME_ALWAYS_YES="yes" \
+                  -o FINGERPRINTS="${fingerprints}" \
+                  update -r "${repo_name}"; then
+            error_exit "[ERROR]: Failed to update pkg repo: ${repo_name}"
+        fi
+        # Install FreeBSD-set-src
+        if ! pkg --rootdir "${release_dir}" \
+                 --repo-conf-dir "${repo_dir}" \
+                  -o IGNORE_OSVERSION="yes" \
+                  -o ABI="${abi}" \
+                  -o ASSUME_ALWAYS_YES="yes" \
+                  -o FINGERPRINTS="${fingerprints}" \
+                  install -r "${repo_name}" \
+                  freebsd-set-src; then
+            error_exit "[ERROR]: Failed to install package set: FreeBSD-set-src"
+        fi
+    else
+        error_exit "[ERROR]: Release not found: ${release}"
+    fi
+}
+
 bootstrap_etc_release() {
 
-    local _release="${1}"
+    local release="${1}"
-    local _current="$(sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives | awk -F': ' '{print $2}')"
+    local current="$(sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives | awk -F': ' '{print $2}')"
 
-    if [ ! -f "${bastille_cachedir}/${_release}/src.txz" ]; then
+    if [ ! -f "${bastille_cachedir}/${release}/src.txz" ]; then
-        sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives=src
+        sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives="src"
-        if ! bastille bootstrap "${_release}" > /dev/null; then
+        if ! bastille bootstrap "${release}" > /dev/null; then
-            sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives="${_current}"
+            sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives="${current}"
-            error_exit "[ERROR]: Failed to bootstrap etcupdate: ${_release}"
+            error_exit "[ERROR]: Failed to bootstrap etcupdate: ${release}"
         else
-            sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives="${_current}"
+            sysrc -f /usr/local/etc/bastille/bastille.conf bastille_bootstrap_archives="${current}"
         fi
     fi
 }
 
 bootstrap_etc_tarball() {
 
-    local _release="${1}"
+    local release="${1}"
 
-    if [ ! -f ${bastille_cachedir}/${_release}.tbz2 ]; then
+    if [ ! -f ${bastille_cachedir}/${release}.tbz2 ]; then
         info "\nBuilding tarball, please wait..."
-        if ! etcupdate build -d /tmp/etcupdate -s ${bastille_releasesdir}/${_release}/usr/src ${bastille_cachedir}/${_release}.tbz2; then
+        if ! etcupdate build -d /tmp/etcupdate -s ${bastille_releasesdir}/${release}/usr/src ${bastille_cachedir}/${release}.tbz2; then
-            error_exit "[ERROR]: Failed to build etcupdate tarball \"${_release}.tbz2\""
+            error_exit "[ERROR]: Failed to build etcupdate tarball \"${release}.tbz2\""
         else
-            info "\nEtcupdate bootstrap complete: ${_release}"
+            info "\nEtcupdate bootstrap complete: ${release}"
         fi
-    elif [ -f ${bastille_cachedir}/${_release}.tbz2 ] && [ "${FORCE}" -eq 1 ]; then
+    elif [ -f ${bastille_cachedir}/${release}.tbz2 ] && [ "${FORCE}" -eq 1 ]; then
-        rm -f "${bastille_cachedir}/${_release}.tbz2"
+        rm -f "${bastille_cachedir}/${release}.tbz2"
         info "\nBuilding tarball, please wait..."
-        if ! etcupdate build -d /tmp/etcupdate -s ${bastille_releasesdir}/${_release}/usr/src ${bastille_cachedir}/${_release}.tbz2; then
+        if ! etcupdate build -d /tmp/etcupdate -s ${bastille_releasesdir}/${release}/usr/src ${bastille_cachedir}/${release}.tbz2; then
-            error_exit "[ERROR]: Failed to build etcupdate tarball: ${_release}.tbz2"
+            error_exit "[ERROR]: Failed to build etcupdate tarball: ${release}.tbz2"
         else
-            info "\nEtcupdate bootstrap complete: ${_release}"
+            info "\nEtcupdate bootstrap complete: ${release}"
         fi
     else
-        info "\nEtcupdate release has already been prepared for application: ${_release}"
+        info "\nEtcupdate release has already been prepared for application: ${release}"
     fi
 }
 
 diff_review() {
 
-    local _jail="${1}"
+    local jail="${1}"
 
     if [ "${DRY_RUN}" -eq 1 ]; then
         error_exit "[ERROR]: diff mode does not support [-d|--dryrun]"
     fi
 
     echo "Running: etcupdate --diff mode"
-    etcupdate diff -D "${bastille_jailsdir}/${_jail}/root"
+    etcupdate diff -D "${bastille_jailsdir}/${jail}/root"
 }
 
 resolve_conflicts() {
 
-    local _jail="${1}"
+    local jail="${1}"
 
     if [ "${DRY_RUN}" -eq 1 ]; then
         error_exit "[ERROR]: resolve mode does not support [-d|--dryrun]"
     fi
 
     echo "Running: etcupdate resolve"
-    etcupdate resolve -D "${bastille_jailsdir}/${_jail}/root"
+    etcupdate resolve -D "${bastille_jailsdir}/${jail}/root"
 }
 
 update_jail_etc() {
 
-    local _jail="${1}"
+    local jail="${1}"
-    local _release="${2}"
+    local release="${2}"
 
-    if [ ! -f ${bastille_cachedir}/${_release}.tbz2 ]; then
+    if [ ! -f ${bastille_cachedir}/${release}.tbz2 ]; then
         error_exit "[ERROR]: Please run 'bastille etcupdate bootstrap RELEASE' first."
     fi
     if [ "${DRY_RUN}" -eq 1 ]; then
         echo "Running: etcupdate update --dry-run"
-        etcupdate -n -D "${bastille_jailsdir}/${_jail}/root" -t ${bastille_cachedir}/${_release}.tbz2
+        etcupdate -n -D "${bastille_jailsdir}/${jail}/root" -t ${bastille_cachedir}/${release}.tbz2
     else
         echo "Running: etcupdate update"
-        etcupdate -D "${bastille_jailsdir}/${_jail}/root" -t ${bastille_cachedir}/${_release}.tbz2
+        etcupdate -D "${bastille_jailsdir}/${jail}/root" -t ${bastille_cachedir}/${release}.tbz2
     fi
 }
 
@@ -173,9 +213,28 @@ while [ "$#" -gt 0 ]; do
                 usage
             else
                 RELEASE="${2}"
+                # Validate PKGBASE or non-PKGBASE
+                HW_MACHINE_ARCH=$(sysctl hw.machine_arch | awk '{ print $2 }')
+                MINOR_VERSION=$(echo ${RELEASE} | sed -E 's/^[0-9]+\.([0-9]+)-.*$/\1/')
+                MAJOR_VERSION=$(echo ${RELEASE} | grep -Eo '^[0-9]+')
+                if echo "${NEW_RELEASE}" | grep -oq "\-CURRENT"; then
+                    FREEBSD_BRANCH="current"
+                else
+                    FREEBSD_BRANCH="release"
+                fi
                 info "\nAttempting to bootstrap etcupdate release: ${RELEASE}..."
+                if [ "${MAJOR_VERSION}" -ge 16 ] || pkg -r "${bastille_releasesdir}/${RELEASE}" -N 2>/dev/null; then
+                    PKGBASE=1
+                else
+                    PKGBASE=0
+                fi
+                if [ "${PKGBASE}" -eq 1 ]; then
+                    bootstrap_etc_release_pkgbase "${RELEASE}"
+                    bootstrap_etc_tarball "${RELEASE}"
+                else
                     bootstrap_etc_release "${RELEASE}"
                     bootstrap_etc_tarball "${RELEASE}"
+                fi
                 shift "$#"
             fi
             ;;
@@ -212,5 +271,3 @@ while [ "$#" -gt 0 ]; do
             ;;
     esac
 done
-
-echo