diff options
Diffstat (limited to 'documentation/content')
| -rw-r--r-- | documentation/content/en/articles/pgpkeys/_index.adoc | 3 | ||||
| -rw-r--r-- | documentation/content/en/books/handbook/cutting-edge/_index.adoc | 278 |
2 files changed, 278 insertions, 3 deletions
diff --git a/documentation/content/en/articles/pgpkeys/_index.adoc b/documentation/content/en/articles/pgpkeys/_index.adoc index 51baa8be03..c082f7feba 100644 --- a/documentation/content/en/articles/pgpkeys/_index.adoc +++ b/documentation/content/en/articles/pgpkeys/_index.adoc @@ -879,6 +879,9 @@ include::{include-path}christos.key[] === `{marino}` include::{include-path}marino.key[] +=== `{emaste}` +include::{include-path}emaste.key[] + === `{cherry}` include::{include-path}cherry.key[] diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc index e787d106ee..e1390faa52 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1087,12 +1087,284 @@ The last step after updating is to restart the computer so all the changes take # 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 a recent Version, 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 tool does not check for this and it is the responsibility of the user to ensure that enough space is available before running the migration. +==== + +man:pkgbasify[8] (or whatever outcome link:https://reviews.freebsd.org/D51594[D51594] or link:https://wiki.freebsd.org/WantedPorts#O-P[port request] will have) 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] +.... +# cd /tmp +# fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkgbasify.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%,20%,70%, options="header"] +|=== +| Branch +| Frequency +| URL + +| main +| twice daily - 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_latest` + +| main +| weekly – Sunday at 12:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_weekly` + +| stable/14 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_latest` + +| stable/14 +| weekly – Sunday at 12:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_weekly` + +| releng/14.2 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_release_2` + +| releng/14.3 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_release_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 executing the following command: + +[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. + +Save a list of your non-base packages in case you need that later: + +[source,shell] +.... +pkg prime-origins | sort -u > /var/tmp/pkg-prime-origins.txt +.... + +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; +} +.... + +The next step will upgrade your system to the specified version. + +[WARNING] +==== +This step might remove non-base packages, which could include your running desktop environment. +Be careful. +==== + +Set the environment variable ABI to upgrade the major version (replace amd64 with your architecture and 15 with your targeted version). + +[source,shell] +.... +# env ABI=FreeBSD:15:amd64 pkg-static upgrade -r FreeBSD-base +.... + +There will be a prompt to ask if you want to ignore the version mismatch looking like this: + +[source,shell] +.... +Newer FreeBSD version for package FreeBSD-zoneinfo: +To ignore this error set IGNORE_OSVERSION=yes +- package: 1500058 +- running userland: 1500000 +Ignore the mismatch and continue? [y/N]: +.... + +Check and confirm that. + +To check if that was successful, 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. + +If you haven't created a boot environment, you might want to consider getting help from link:https://www.freebsd.org/support/[FreeBSD Support]. + +[[build-pkgbase-packages-locally]] +=== Manually building pkgbase and publishing it to the local network + +If you want to start building your own pkgbase packages 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 package: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/upgrade.conf`: + +[.programlisting] +.... +upgrade: { + url = http://ip.of.the.server/FreeBSD:14:amd64/14.3p2 + enabled = yes +} +.... + +and use it as written above (but use -r upgrade instead of FreeBSD-base). + [[small-lan]] == Tracking for Multiple Machines -When multiple machines need to track the same source tree, -it is a waste of disk space, network bandwidth, -and CPU cycles to have each system download the sources and rebuild everything. +When multiple machines need to track the same source tree, it is a waste of disk space, network bandwidth, and CPU cycles to have each system download the sources and rebuild everything. The solution is to have one machine do most of the work, while the rest of the machines mount that work via NFS. This section outlines a method of doing so. For more information about using NFS, refer to crossref:network-servers[network-nfs,"Network File System (NFS)"]. |