Page MenuHomeFreeBSD
Files F163171245

D53534.id166716.diff
No OneTemporary
Actions

D53534.id166716.diff
View Options

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
@@ -1088,35 +1088,43 @@
....
[[pkgbase]]
-== Updating FreeBSD with Base System Packages
+== Updating FreeBSD with 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.
+Starting from 14.0-RELEASE, the FreeBSD project has published a set of packages of the base system, using man:pkg[8].
+The convenience of pkg is no longer limited to the FreeBSD ports collection. man:pkg[8] can be used for FreeBSD itself.
+Base packages, and usage thereof, were tradisionally 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.
+Publication of official packages began in link:https://lists.freebsd.org/archives/freebsd-pkgbase/2023-October/000221.html[October 2023]. Their use with FreeBSD 14 is currently experimental.
-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.
+Starting from 15.0-RELEASE, man:freebsd-base[7] will be supported as a tech preview for:
-[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.
-====
+* installation
+* minor upgrades
+* major upgrades
-Base System Packages replace:
+freebsd-base will eventually 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.
+The current plan is for freebsd-update to work with pkg.
+
+[WARNING]
+====
+The replacement of distribution sets will take some time, until freebsd-base is fully stable
+====
+
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
+=== Converting a Host to use freebsd-base
+
+FreeBSD 14.0-RELEASE or later can be converted to use base packages.
+Earlier versions must be upgraded with freebsd-update before conversion.
-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.
+For conversion, the FreeBSD Foundation-sponsored link:https://github.com/FreeBSDFoundation/pkgbasify[pkgbasify] tool is recommended. Follow the instructions given there.
-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.
+man:freebsd-update[8] will be enhanced to use pkg and pkgbasify.
[WARNING]
====
@@ -1133,19 +1141,11 @@
* 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
+=== Upgrading a Host using freebsd-base
[WARNING]
====
-This is still in development, so please be careful especially when converting an existing system to use pkgbase.
+This is still in development, so please be careful especially when converting an existing system to use freebsd-base.
====
Create a folder for custom pkg repository config files, if there is none present already.
@@ -1155,7 +1155,7 @@
# mkdir -p /usr/local/etc/pkg/repos/
....
-For using the pkgbase repository, create a pkg repository configuration file called `FreeBSD-base.conf`:
+For using the freebsd-base repository, create a pkg repository configuration file called `FreeBSD-base.conf`:
[[pgk-base-repo-configuration]]
[.programlisting]
@@ -1183,27 +1183,35 @@
| main
| twice daily - 12:00 and 00:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_latest`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_latest`
| main
| weekly – Sunday at 12:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_weekly`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly`
| stable/14
| twice daily – 12:00 and 00:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_latest`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_latest`
| stable/14
| weekly – Sunday at 12:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_weekly`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly`
+
+| releng/14.3
+| twice daily – 12:00 and 00:00 UTC
+| `pkg+https://pkg.freebsd.org/${ABI}/base_release_3`
-| releng/14.2
+| releng/15.0
| twice daily – 12:00 and 00:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_release_2`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_release_0`
-| releng/14.3
+| stable/15
| twice daily – 12:00 and 00:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_release_3`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_latest`
+
+| stable/15
+| weekly – Sunday at 12:00 UTC
+| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly`
|===
To upgrade the system, change the configuration file according to the desired release, and run:
@@ -1223,17 +1231,45 @@
# shutdown -r now
....
-==== Performing Major version upgrades
+[[pkgbase-major-upgrade]]
+==== Major Upgrades
+With ZFS, boot environments allow an upgrade to be performed without interrupting running software.
+If the system does not use root-on-ZFS: backup before upgrading.
+
+===== Preparations
+Change `/usr/local/etc/pkg/repos/FreeBSD-base.conf` to target the correct major release like `base_release_0` for 15.0-RELEASE, to look like this:
+
+[WARNING]
+====
+This file might change to be included in RELEASE with a different path.
+====
+
+[.programlisting]
+....
+FreeBSD-base {
+ url = "pkg+https://pkg.freebsd.org/${ABI}/base_release_0";
+ mirror_type = "srv";
+ signature_type = "fingerprints";
+ fingerprints = "/usr/share/keys/pkg";
+ enabled = yes;
+}
+....
-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:
+[WARNING]
+====
+As pkgbase with FreeBSD 14 is experimental, so is a pkgbase major upgrade to 15.
+At the time of this writing in some edge-cases the major upgrade removes pkg and therefore segfaults.
+This is considered a (link:https://github.com/freebsd/pkg/issues/2475[known issue]) for 15.0-RELEASE.
+To work around this issue, lock pkg before upgrading.
[source,shell]
....
-# bectl create 14.2-RELEASE-p4
+# pkg -c /mnt/upgrade lock pkg
....
-Use this boot environment to start the system as it was before the update if something goes wrong.
+An experimental major upgrade from FreeBSD 14, to 15 (or 16.0-CURRENT), should be followed by installation of meta package `FreeBSD-set-minimal`.
+====
+
Save a list of the non-base packages in case they are needed later:
@@ -1242,27 +1278,77 @@
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:
+[[pkgbase-major-zfs]]
+===== major upgrade with zfs
+Create a boot environment using man:bectl[8] and name it according to the version upgrading to
+[source,shell]
+....
+# bectl create 15.0-RELEASE
+....
-[.programlisting]
+Create a directory then mount the new boot environment there to enable working with pkg man:chroot[8] and rootdir.
+
+[source,shell]
....
-FreeBSD-base {
- url = "pkg+https://pkg.freebsd.org/${ABI}/base_latest";
- mirror_type = "srv";
- signature_type = "fingerprints";
- fingerprints = "/usr/share/keys/pkg";
- enabled = yes;
-}
+# mkdir /mnt/upgrade
+# bectl mount 15.0-RELEASE /mnt/upgrade
....
-The next step will upgrade the system to the specified version.
+The next step will upgrade the boot environment 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). Set the pkg-static chroot directory to the boot environment mountpoint.
+
+[source,shell]
+....
+# env ABI=FreeBSD:15:amd64 pkg-static -c /mnt/upgrade upgrade -r FreeBSD-base
+....
+
+There will be a prompt asking 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, chroot into the mountpoint of the boot environment and run `freebsd-version -kru`.
+
+[source,shell]
+....
+# chroot /mnt/upgrade
+# freebsd-version -ku
+# exit
+....
+
+Activate the boot environment temporarily and reboot.
+[source,shell]
+....
+# bectl activate -t 15.0-RELEASE
+# shutdown -r now
+....
+
+If the system does not work as expected: restart the OS, to cease using the temporarily active boot environment.
+The next boot will reuse the pre-upgrade environment.
+
+If the system runs stable after reboot, don't forget to permanently activate this boot environment to prevent accidentally booting the old system.
+
+[source,shell]
+....
+bectl activate 15.0-RELEASE
+....
+
+[[pkgbase-major-non-zfs]]
+===== major upgrade without zfs
Set the environment variable ABI to upgrade the major version (replace amd64 with the architecture and 15 with the targeted version).
[source,shell]
@@ -1283,27 +1369,25 @@
Check and confirm that.
-To check if that was successful, run `freebsd-version -kru`.
+To check if the upgrade was successful, run `freebsd-version -ku`.
Then reboot.
-After upgrading to a new major version, updates and upgrades of installed packages to match the ABI version may be necessary.
-
+===== Post-upgrade tasks
+If pkg was locked during the update as a workaround remove the lock like this:
[source,shell]
....
-# pkg update
-# pkg upgrade
+# pkg unlock pkg
....
-If something broke, go back and activate the backup boot environment created before.
+After upgrading to a new major version, updates and upgrades of installed packages to match the ABI version may be necessary.
[source,shell]
....
-# bectl activate 14.2-RELEASE-p4
+# pkg upgrade
....
-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].
+Consider getting help from link:https://www.freebsd.org/support/[FreeBSD Support] when experiencing issues.
[[build-pkgbase-packages-locally]]
=== Manually building pkgbase and publishing it to the local network

File Metadata

Mime Type
text/plain
Expires
Tue, Jul 21, 5:30 PM (16 m, 37 s)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
35327835
Default Alt Text
D53534.id166716.diff (11 KB)

Event Timeline