diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1087,6 +1087,244 @@ # shutdown -r now .... + +[[pkgbase]] +== Updating FreeBSD with Base System Packages + +Starting from 14.0-RELEASE, the FreeBSD project has published a set of packages of the kernel and base system, using man:pkg[8]. These can be used in the same convenient way that users are used to, for adding and upgrading ported software, but for the kernel and userland itself. The packages, and usage thereof, +are often referred to as pkgbase. + +Packages have been available since link:https://lists.freebsd.org/archives/freebsd-pkgbase/2023-October/000221.html[October 2023], considered experimental for FreeBSD's 14 Release. + +Starting from 15.0-RELEASE, Base System packages will be the default and officially supported way to both install new FreeBSD instances, and also to update and upgrade between minor and major releases. + +[NOTE] +==== +From 15.0-RELEASE onwards, the long-running man:freebsd-update[8] tool will only be supported on the earlier 13 and 14 release branches. +==== + +Base System Packages replace: + +* tarball distribution sets, such as `base.txz` or `kernel.txz`, which are historically used for installation of the OS with man:bsdinstall[8] +* man:freebsd-update[8] for updates to the OS. + +Base System packages complement crossref:cutting-edge[makeworld,"building and installing from source"], which is still available for those who wish to build their own custom kernels or userland. It is also possible to build custom base system packages from local sources, as well as just relying on officially provided packages. + +=== Converting a Host to use pkgbase + +Systems installed with FreeBSD 14.0-RELEASE or later can be converted to use Base System packages. For earlier versions, it is recommended to first upgrade to 14.0-RELEASE, and then convert. + +The FreeBSD Foundation has sponsored development of a tool called link:https://github.com/FreeBSDFoundation/pkgbasify[pkgbasify], which for most users, will be the easiest and safest way to convert systems to use Base System packages. + +[WARNING] +==== +Note that this migration requires up to 5GiB additional free space, to download, unpack, and relocate any conflicting files. The pkgbasify does not check for this and it is the responsibility of the user to ensure that enough space is available before running the migration. +==== + +pkgbasify performs 6 main tasks: + +* Creates a backup boot environment (ZFS only) with man:bectl[8] +* Creates the new package repository config files +* Upgrades existing system components such as base, kernel, lib32, debug +* Merges existing and new config files +* Updates passwd and capabilities databases +* Restarts sshd immediately + +[source,shell] +.... +### TODO this should be in ports or base, not via fetch rando url +# cd /tmp +# fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkbasify.lua +# chmod +x pkgbasify.lua +# ./pkgbasify.lua +.... + +=== Upgrading a Host using pkgbase + +[WARNING] +==== +This is still in development, so please be careful especially when converting an existing system to use pkgbase. +==== + +Create a folder for custom pkg repository config files, if there is none present already. +[source,shell] +.... +# mkdir -p /usr/local/etc/pkg/repos/ +.... + +For using the pkgbase repository, create a pkg repository configuration file called `FreeBSD-base.conf`: + +[[pgk-base-repo-configuration]] +[.programlisting] +.... +FreeBSD-base { + url = "pkg+https://pkg.freebsd.org/${ABI}/base_release_${VERSION_MINOR}"; + mirror_type = "srv"; + signature_type = "fingerprints"; + fingerprints = "/usr/share/keys/pkg"; + enabled = yes; +} +.... + +for more Information on specific configuration options see man:pkg.conf[5]. + +There are different branches to choose from (by changing the url accordingly): + +[[table-of-packagebase-branches]] +.Base system package Branches +[cols="10%,10%,40%,40%, options="header"] +|=== +| Branch +| Frequency +| URL +| kmods + +| main +| twice daily - 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_latest` +| `https://pkg.freebsd.org/${ABI}/kmods_latest` + +| main +| weekly – Sunday at 12:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_weekly` +| n.a. + +| stable/14 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_latest` +| `https://pkg.freebsd.org/${ABI}/kmods_latest` + +| stable/14 +| weekly – Sunday at 12:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_weekly` +| n.a. + +| releng/14.1 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_release_1` +| n.a. + +| releng/14.2 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_release_2` +| `https://pkg.freebsd.org/${ABI}/kmods_latest_2` + +| releng/14.3 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_release_3` +| `https://pkg.freebsd.org/${ABI}/kmods_latest_3` +|=== + +To upgrade the System, change the configuration file according to the desired release, and run: +[source,shell] +.... +# pkg update -r FreeBSD-base +# pkg upgrade -r FreeBSD-base +.... + +check, if these packages are correct and accept the changes. + +Reboot the OS +[source,shell] +.... +# shutdown -r now +.... + +==== Performing Major version upgrades +When running ZFS, consider creating a boot environment before upgrading to a newer version. +To create a new boot environment using the man:bectl[8] tool run: +[source,shell] +.... +# bectl create 14.2-RELEASE-p4 +.... +Use this boot environment to start the system as it was before the update if something goes wrong. + +Change `/usr/local/etc/pkg/repos/FreeBSD-base.conf` to target the correct major release like `base_latest`, so it looks like: +[.programlisting] +.... +FreeBSD-base { + url = "pkg+https://pkg.freebsd.org/${ABI}/base_latest"; + mirror_type = "srv"; + signature_type = "fingerprints"; + fingerprints = "/usr/share/keys/pkg"; + enabled = yes; +} +.... + +Set the environment variable ABI to upgrade the major version. + +[source,shell] +.... +# env ABI=FreeBSD:15:amd64 pkg-static upgrade -r FreeBSD-base +.... + +To check if that was successfull, run `freebsd-version -kru`. + +Then reboot. + +After upgrading to a new major version, updates and upgrades of installed packages to match the ABI version may be necessary. + +[source,shell] +.... +# pkg update +# pkg upgrade +.... + +If something broke, go back and activate the backup boot environment created before. + +[source,shell] +.... +# bectl activate 14.2-RELEASE-p4 +.... +Reboot, and the system will be back to the state before upgrading. + +[[build-pkgbase-packets-locally]] +=== Manually building pkgbase and publishing it to the local network +To start building custom pkgbase packets clone the FreeBSD source tree +[source,shell] +.... +# cd /usr/src +# git clone https://github.com/freebsd/freebsd-src.git /usr/src +.... + +Check out the branch for the release to build packages for +[source,shell] +.... +# git checkout releng/14.3 +.... + +Start the building process, depending on the resources available this could take some while. +Set the parallel processes according to the cpu core count. +This example is written for an 8 core CPU: +[source,shell] +.... +# make -j8 buildworld && make -j8 buildkernel && make -j8 packages +.... + +When building frequently, consider using devel/ccache to speed up subsequent builds from the cache. + +After building, the packages will get saved into `/usr/obj/usr/src/repo/FreeBSD:14:amd64/14.3p2` or something like that, depending on the version build. + +To publish these packages to the network set up a nginx service and use this location in the http server configuration: +[.programlisting] +.... + location /FreeBSD:14:amd64 { + alias /usr/obj/usr/src/repo/FreeBSD:14:amd64/; + autoindex on; + } +.... +And reload the nginx service. + +When not using https, use a small configuration file on the clients to target the pkgbase version just built by editing `/usr/local/etc/pkg/repos/FreeBSD-base.conf` +[.programlisting] +.... +freebsd-upgrade: { + url = http://ip.of.the.server/FreeBSD:14:amd64/14.3p2 + enabled = yes +} +.... +and use it as written above. + [[small-lan]] == Tracking for Multiple Machines