diff options
Diffstat (limited to 'documentation/content/en/books/handbook/cutting-edge/_index.adoc')
| -rw-r--r-- | documentation/content/en/books/handbook/cutting-edge/_index.adoc | 483 |
1 files changed, 422 insertions, 61 deletions
diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc index 2dc1343ef9..04f7e9d37d 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1,13 +1,14 @@ --- -title: Chapter 24. Updating and Upgrading FreeBSD +title: Chapter 26. Updating and Upgrading FreeBSD part: Part III. System Administration prev: books/handbook/l10n next: books/handbook/dtrace description: Information about how to keep a FreeBSD system up-to-date with freebsd-update or Git, how to rebuild and reinstall the entire base system, etc tags: ["updating", "upgrading", "documentation", "FreeBSD-STABLE", "FreeBSD-CURRENT", "Security Patches"] showBookMenu: true -weight: 28 -path: "/books/handbook/" +weight: 30 +params: + path: "/books/handbook/cutting-edge/" --- [[updating-upgrading]] @@ -18,7 +19,7 @@ path: "/books/handbook/" :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 24 +:sectnumoffset: 26 :partnums: :source-highlighter: rouge :experimental: @@ -57,7 +58,7 @@ However, even official releases are often updated with security and other critic Regardless of the version used, FreeBSD provides all the necessary tools to keep the system updated, and allows for easy upgrades between versions. This chapter describes how to track the development system and the basic tools for keeping a FreeBSD system up-to-date. -After reading this chapter, you will know: +Read this chapter to learn: * How to keep a FreeBSD system up-to-date with freebsd-update or Git. * How to compare the state of an installed system against a known pristine copy. @@ -65,7 +66,7 @@ After reading this chapter, you will know: * The difference between the two development branches: FreeBSD-STABLE and FreeBSD-CURRENT. * How to rebuild and reinstall the entire base system. -Before reading this chapter, you should: +Before reading this chapter: * Properly set up the network connection (crossref:advanced-networking[advanced-networking,Advanced Networking]). * Know how to install additional third-party software (crossref:ports[ports,Installing Applications: Packages and Ports]). @@ -146,10 +147,9 @@ MergeChanges /etc/ /var/named/etc/ /boot/device.hints .... List of directories with configuration files that `freebsd-update` should attempt to merge. -The file merge process is a series of man:diff[1] patches similar to man:mergemaster[8], but with fewer options. +The file merge process is a series of man:diff[1] patches. Merges are either accepted, open an editor, or cause `freebsd-update` to abort. When in doubt, backup [.filename]#/etc# and just accept the merges. -See man:mergemaster[8] for more information about `mergemaster`. [.programlisting] .... @@ -173,6 +173,8 @@ In cases where the user is doing a version upgrade, this location should have at When this option is set to `yes`, `freebsd-update` will assume that the `Components` list is complete and will not attempt to make changes outside of the list. Effectively, `freebsd-update` will attempt to update every file which belongs to the `Components` list. +Refer to man:freebsd-update.conf[5] for more details. + [[freebsdupdate-security-patches]] === Applying Security Patches @@ -180,7 +182,7 @@ The process of applying FreeBSD security patches has been simplified, allowing a More information about FreeBSD security advisories can be found in crossref:security[security-advisories,"FreeBSD Security Advisories"]. FreeBSD security patches may be downloaded and installed using the following commands. -The first command will determine if any outstanding patches are available, and if so, will list the files that will be modifed if the patches are applied. +The first command will determine if any outstanding patches are available, and if so, will list the files that will be modified if the patches are applied. The second command will apply the patches. [source,shell] @@ -228,7 +230,7 @@ The man:uname[1] command may be used to verify its installation. ==== Always keep a copy of the [.filename]#GENERIC# kernel in [.filename]#/boot/GENERIC#. It will be helpful in diagnosing a variety of problems and in performing version upgrades. -Refer to <<freebsd-update-custom-kernel-9x>> for instructions on how to get a copy of the [.filename]#GENERIC# kernel. +Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x, Custom Kernels with FreeBSD 9.X and Later] for instructions on how to get a copy of the [.filename]#GENERIC# kernel. ==== Unless the default configuration in [.filename]#/etc/freebsd-update.conf# has been changed, @@ -243,23 +245,55 @@ Rebuilding a custom kernel, even if nothing else changed, allows `uname` to accu This is particularly helpful when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one. [[freebsdupdate-upgrade]] -=== Performing Major and Minor Version Upgrades +=== Performing Minor and Major Version Upgrades + +Upgrades from one minor version of FreeBSD to another are called _minor version_ upgrades. An example: + +- FreeBSD 13.1 to 13.2. + +_Major version_ upgrades increase the major version number. An example: + +- FreeBSD 13.2 to 14.0. + +Both types of upgrade can be performed by providing `freebsd-update` with a release version target. + +[WARNING] +==== +After each new `RELEASE`, FreeBSD package build servers will, for a limited period, *not* use the newer version of the operating system. +This provides continuity for the many users who do not upgrade immediately after a release announcement. +For example: + +* packages for users of 13.1 and 13.2 will be built on a server running 13.1, until 13.1 reaches end of life + +-- and, critically: + +* a kernel module that is built on 13.1 might *not* be suitable for 13.2. + +So, with any minor or major OS upgrade, if the package requirements include any kernel module: -Upgrades from one minor version of FreeBSD to another, like from FreeBSD 9.0 to FreeBSD 9.1, are called _minor version_ upgrades. -_Major version_ upgrades occur when FreeBSD is upgraded from one major version to another, like from FreeBSD 9.X to FreeBSD 10.X. -Both types of upgrades can be performed by providing `freebsd-update` with a release version target. +* *be prepared to build the module from source*. + +==== [NOTE] ==== If the system is running a custom kernel, make sure that a copy of the [.filename]#GENERIC# kernel exists in [.filename]#/boot/GENERIC# before starting the upgrade. -Refer to <<freebsd-update-custom-kernel-9x>> for instructions on how to get a copy of the [.filename]#GENERIC# kernel. +Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x, Custom Kernels with FreeBSD 9.X and Later] for instructions on how to get a copy of the [.filename]#GENERIC# kernel. ==== -The following command, when run on a FreeBSD 9.0 system, will upgrade it to FreeBSD 9.1: +Before upgrading to a new version, ensure the existing FreeBSD installation is up to date with respect to security and errata patches: [source,shell] .... -# freebsd-update -r 9.1-RELEASE upgrade +# freebsd-update fetch +# freebsd-update install +.... + +The following command, when run on a FreeBSD 13.1 system, will upgrade it to FreeBSD 13.2: + +[source,shell] +.... +# freebsd-update -r 13.2-RELEASE upgrade .... After the command has been received, `freebsd-update` will evaluate the configuration file and current system in an attempt to gather the information necessary to perform the upgrade. @@ -269,7 +303,7 @@ For example: [source,shell] .... Looking up update.FreeBSD.org mirrors... 1 mirrors found. -Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done. +Fetching metadata signature for 13.1-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. @@ -294,7 +328,7 @@ When using a custom kernel, the above step will produce a warning similar to the [source,shell] .... WARNING: This system is running a "MYKERNEL" kernel, which is not a -kernel configuration distributed as part of FreeBSD 9.0-RELEASE. +kernel configuration distributed as part of FreeBSD 13.1-RELEASE. This kernel will not be updated: you MUST update the kernel manually before running "/usr/sbin/freebsd-update install" .... @@ -365,7 +399,8 @@ Depending upon whether any library version numbers were bumped, there may only b ==== The upgrade is now complete. -If this was a major version upgrade, reinstall all ports and packages as described in <<freebsdupdate-portsrebuild>>. +If this was a major version upgrade, reinstall all ports and packages as +described in crossref:cutting-edge[freebsdupdate-portsrebuild, Upgrading Packages After a Major Version Upgrade]. [[freebsd-update-custom-kernel-9x]] ==== Custom Kernels with FreeBSD 9.X and Later @@ -380,8 +415,8 @@ If physical access to the system is available, a copy of the `GENERIC` kernel ca [source,shell] .... -# mount /cdrom -# cd /cdrom/usr/freebsd-dist +# mount /media +# cd /media/usr/freebsd-dist # tar -C/ -xvf kernel.txz boot/kernel/kernel .... @@ -417,7 +452,7 @@ The forced upgrade can be accomplished by performing: # pkg-static upgrade -f .... -A rebuild of all installed applications can be accomplished with this command: +A rebuild of all applications installed from the ports collection can be accomplished with this command: [source,shell] .... @@ -571,7 +606,8 @@ In order to track changes to the whole source tree, not just the changes to Free . Synchronize with the FreeBSD-CURRENT sources. Typically, `git` is used to check out the -CURRENT code from the `main` branch of the FreeBSD Git repository (see crossref:mirrors[git,“Using Git”] for details). . Due to the size of the repository, some users choose to only synchronize the sections of source that interest them or which they are contributing patches to. However, users that plan to compile the operating system from source must download _all_ of FreeBSD-CURRENT, not just selected portions. + -Before compiling FreeBSD-CURRENT, read [.filename]#/usr/src/Makefile# very carefully and follow the instructions in <<makeworld>>. +Before compiling FreeBSD-CURRENT, read [.filename]#/usr/src/Makefile# very +carefully and follow the instructions in crossref:cutting-edge[makeworld, Updating FreeBSD from Source]. Read the {freebsd-current} and [.filename]#/usr/src/UPDATING# to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. . Be active! FreeBSD-CURRENT users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are always welcome. @@ -604,8 +640,10 @@ In order to track changes for the whole source tree, subscribe to {dev-commits-s . To install a new FreeBSD-STABLE system, install the most recent FreeBSD-STABLE release from the crossref:mirrors[mirrors,FreeBSD mirror sites] or use a monthly snapshot built from FreeBSD-STABLE. Refer to link:https://www.FreeBSD.org/snapshots/[www.freebsd.org/snapshots] for more information about snapshots. + To compile or upgrade an existing FreeBSD system to FreeBSD-STABLE, use `git` to check out the source for the desired branch. -Branch names, such as `stable/9`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng]. -. Before compiling or upgrading to FreeBSD-STABLE , read [.filename]#/usr/src/Makefile# carefully and follow the instructions in <<makeworld>>. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. +Branch names, such as `stable/13`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng]. +. Before compiling or upgrading to FreeBSD-STABLE , read + [.filename]#/usr/src/Makefile# carefully and follow the instructions in + crossref:cutting-edge[makeworld, Updating FreeBSD from Source]. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. [[translate-n-number]] === The N-number @@ -614,9 +652,10 @@ FreeBSD provides version information compiled into the kernel. man:uname[1] retrieves this information, for example: [source,shell] .... -% uname -a +% uname -v FreeBSD 14.0-CURRENT #112 main-n247514-031260d64c18: Tue Jun 22 20:43:19 MDT 2021 fred@machine:/usr/home/fred/obj/usr/home/fred/git/head/amd64.amd64/sys/FRED .... +The final field gives information regarding the kernel name, the person that built it, and the location that it was compiled in. Looking at the 4th field, it is made up of several parts: [source,shell] .... @@ -648,8 +687,8 @@ For example: Usually this number is not all that important. However, when bug fixes are committed, this number makes it easy to quickly determine whether the fix is present in the currently running system. Developers will often refer to the hash of the commit (or provide a URL which has that hash), but not the n-number since the hash is the easily visible identifier for a change while the n-number is not. -Security advisories and errata notices will also note an n-number, which can be directly compared against your system. -When you need to use shallow Git clones, you cannot compare n-numbers reliably as the `git rev-list` command counts all the revisions in the repository which a shallow clone omits. +Security advisories and errata notices will also note an n-number, which can be directly compared against the system. +When shallow Git clones are used, n-numbers cannot be compared reliably, as the git rev-list command counts all revisions in the repository, which a shallow clone omits. [[makeworld]] == Updating FreeBSD from Source @@ -665,13 +704,29 @@ The build process takes longer to update a system than just installing binary up This is a quick reference for the typical steps used to update FreeBSD by building from source. Later sections describe the process in more detail. +[WARNING] +==== +When switching from man:mergemaster[8] to man:etcupdate[8], the first run might merge changes incorrectly generating spurious conflicts. +To prevent this, perform the following steps *before* updating sources and building the new world: + +[source,shell] +.... +# etcupdate extract <.> +# etcupdate diff <.> +.... + +<.> Bootstrap the database of stock [.filename]#/etc# files; for more information see man:etcupdate[8]. + +<.> Check the diff after bootstrapping. Trim any local changes that are no longer needed to reduce the chance of conflicts in future updates. +==== + [.procedure] ==== * Update and Build + [source,shell] .... -# git pull /usr/src <.> +# git -C /usr/src pull <.> check /usr/src/UPDATING <.> # cd /usr/src <.> # make -j4 buildworld <.> @@ -684,7 +739,8 @@ check /usr/src/UPDATING <.> # shutdown -r now <.> .... -<.> Get the latest version of the source. See <<updating-src-obtaining-src>> for more information on obtaining and updating source. +<.> Get the latest version of the source. See +crossref:cutting-edge[updating-src-obtaining-src, Updating the Source] for more information on obtaining and updating source. <.> Check [.filename]#/usr/src/UPDATING# for any manual steps required before or after building from source. @@ -732,7 +788,7 @@ This indicates that [.filename]#/usr/src/# is under version control and can be u [[synching]] [source,shell] .... -# git pull /usr/src +# git -C /usr/src pull .... The update process can take some time if the directory has not been updated recently. @@ -740,16 +796,17 @@ After it finishes, the source code is up to date and the build process described [NOTE] ==== -*Obtaining the Source:* + +Obtaining the source: If the output says `fatal: not a git repository`, the files there are missing or were installed with a different method. A new checkout of the source is required. +==== [[updating-src-obtaining-src-repopath]] .FreeBSD Versions and Repository Branches [cols="10%,10%,80%", options="header"] |=== -| uname -r Output +| uname ‑r Output | Repository Path | Description @@ -775,21 +832,21 @@ Determine which version of FreeBSD is being used with man:uname[1]: [source,shell] .... # uname -r -10.3-RELEASE +13.2-RELEASE .... -Based on <<updating-src-obtaining-src-repopath>>, the source used to update `10.3-RELEASE` has a repository path of `releng/10.3`. That path is used when checking out the source: +Based on crossref:cutting-edge[updating-src-obtaining-src-repopath,FreeBSD Versions and Repository Branches], the source used to update `13.2-RELEASE` has a repository path of `releng/13.2`. +That path is used when checking out the source: [source,shell] .... # mv /usr/src /usr/src.bak <.> -# git clone --branch releng/10.3 https://git.FreeBSD.org/src.git /usr/src <.> +# git clone --branch releng/13.2 https://git.FreeBSD.org/src.git /usr/src <.> .... <.> Move the old directory out of the way. If there are no local modifications in this directory, it can be deleted. -<.> The path from <<updating-src-obtaining-src-repopath>> is added to the repository URL. The third parameter is the destination directory for the source code on the local system. -==== +<.> The path from crossref:cutting-edge[updating-src-obtaining-src-repopath,FreeBSD Versions and Repository Branches] is added to the repository URL. The third parameter is the destination directory for the source code on the local system. [[updating-src-building]] === Building from Source @@ -933,7 +990,7 @@ Any modified configuration files are merged with the new versions, outdated libr man:etcupdate[8] is a tool for managing updates to files that are not updated as part of an installworld such as files located in [.filename]#/etc/#. It manages updates by doing a three-way merge of changes made to these files against the local versions. -It is also designed to minimize the amount of user intervention, in contrast to man:mergemaster[8]'s interactive prompts. +man:etcupdate[8] is designed to minimize the amount of user intervention. [NOTE] ==== @@ -966,26 +1023,11 @@ To prevent this, perform the following steps *before* updating sources and build # etcupdate diff <.> .... -<.> Bootstrap the database of stock [.filename]#/etc# files, for more information see man:etcupdate[8]. +<.> Bootstrap the database of stock [.filename]#/etc# files; for more information see man:etcupdate[8]. <.> Check the diff after bootstrapping. Trim any local changes that are no longer needed to reduce the chance of conflicts in future updates. ==== -[[updating-src-completing-merge-mergemaster]] -==== Merging Configuration Files with man:mergemaster[8] - -man:mergemaster[8] provides a way to merge changes that have been made to system configuration files with new versions of those files. -man:mergemaster[8] is an alternative to the preferred man:etcupdate[8] -With `-Ui`, man:mergemaster[8] automatically updates files that have not been user-modified and installs new files that are not already present: - -[source,shell] -.... -# mergemaster -Ui -.... - -If a file must be manually merged, an interactive display allows the user to choose which portions of the files are kept. -See man:mergemaster[8] for more information. - [[updating-src-completing-check-old]] ==== Checking for Outdated Files and Libraries @@ -1045,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 the non-base packages in case they are needed 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 the system to the specified version. + +[WARNING] +==== +This step might remove non-base packages, which could include the running desktop environment. +Be careful. +==== + +Set the environment variable ABI to upgrade the major version (replace amd64 with the architecture and 15 with the targeted version). + +[source,shell] +.... +# env ABI=FreeBSD:15:amd64 pkg-static upgrade -r FreeBSD-base +.... + +There will be a prompt to ask about ignoring 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 no boot environment was created before, 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 + +When building custom 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)"]. @@ -1073,11 +1387,12 @@ Also, each build machine should have its kernel name set with `KERNCONF` in [.fi and the build machine should list them all in its `KERNCONF`, listing its own kernel first. The build machine must have the kernel configuration files for each machine in its [.filename]#/usr/src/sys/arch/conf#. -On the build machine, build the kernel and world as described in <<makeworld>>, +On the build machine, build the kernel and world as described in +crossref:cutting-edge[makeworld, Updating FreeBSD from Source], but do not install anything on the build machine. Instead, install the built kernel on the test machine. On the test machine, mount [.filename]#/usr/src# and [.filename]#/usr/obj# via NFS. -Then, run `shutdown now` to go to single-user mode in order to install the new kernel and world and run `mergemaster` as usual. +Then, run `shutdown now` to go to single-user mode in order to install the new kernel and world and run `etcupdate` as usual. When done, reboot to return to normal multi-user operations. After verifying that everything on the test machine is working properly, @@ -1090,3 +1405,49 @@ set `DISTDIR` to a common shared directory that is writable by whichever user `r Each machine should set `WRKDIRPREFIX` to a local build directory, if ports are to be built locally. Alternately, if the build system is to build and distribute packages to the machines in the build set, set `PACKAGES` on the build system to a directory similar to `DISTDIR`. + +[[building-on-non-freebsd-hosts]] +== Building on non-FreeBSD Hosts + +Historically, building required a FreeBSD host. +Nowadays, FreeBSD can be built on Linux and macOS. + +To build on a non-FreeBSD host, the `tools/build/make.py` script is recommended. +This script acts as a wrapper around `bmake`, which is the make implementation used by FreeBSD. +It ensures that the necessary tooling, including the actual FreeBSD's man:make[1], is bootstrapped and that the build environment is properly configured. +In particular, it sets the external toolchain variables, such as `XCC`, `XLD`, and others. +Additionally, the script can pass any additional command arguments, such as `-j 4` for parallel builds or specific make targets, to `bmake`. + +[NOTE] +==== +A recent version of `bmake` can be used instead of the `tools/build/make.py` script as well. +In that case, however, required environment variables need to be set manually (the easiest way to obtain a list of them is by running `tools/build/make.py --debug`). +==== + +Otherwise, the list of prerequisites for building FreeBSD is rather short. +In fact, it boils down to installing a couple of dependencies. + +On macOS, the only dependency is LLVM. +The necessary dependencies can be installed with package manager (e.g., link:https://brew.sh/[Homebrew]): + +[source,shell] +.... +brew install llvm +.... + +On a Linux distributions, install link:https://clang.llvm.org/[Clang] version 10.0 or newer and the headers for libarchive and libbz2 (often packaged as libarchive-dev and libbz2-dev). + +Once the dependencies are installed, the host should be able to build FreeBSD. + +For example, the following `tools/build/make.py` invocation builds the world: + +[source,shell] +.... +MAKEOBJDIRPREFIX=/tmp/obj tools/build/make.py -j 8 TARGET=arm64 TARGET_ARCH=aarch64 buildworld +.... + +It builds the world for target `aarch64:arm64` on 8 CPUs and uses [.filename]#/tmp/obj# for object files. +Note that the variables `MAKEOBJDIRPREFIX`, `TARGET`, and `TARGET_ARCH` are mandatory when building on non-FreeBSD hosts. +Also, make sure to create the object directory pointed to by the `MAKEOBJDIRPREFIX` environment variable. + +Refer to man:arch[7] and man:build[7] for more details. |