Page MenuHomeFreeBSD
Files F144637184

D53534.1775944414.diff
No OneTemporary
Actions

Size
8 KB
Referenced Files
None
Subscribers
None

D53534.1775944414.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
@@ -1096,18 +1096,18 @@
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.
+Starting from 15.0-RELEASE, Base System Packages will be supported as a tech preview to 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:
+Base System Packages is eventually going to 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.
+[WARNING]
+====
+The replacement of distribution sets by Base System Packages will still take some time until this 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.
@@ -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.2
+| releng/14.3
| twice daily – 12:00 and 00:00 UTC
-| `https://pkg.freebsd.org/${ABI}/base_release_2`
+| `pkg+https://pkg.freebsd.org/${ABI}/base_release_3`
-| releng/14.3
+| releng/15.0
+| twice daily – 12:00 and 00:00 UTC
+| `pkg+https://pkg.freebsd.org/${ABI}/base_release_0`
+
+| 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
....
+[[pkgbase-major-upgrade]]
==== Performing Major version upgrades
+When running ZFS, boot environments are an easy option to upgrade the system without interrupting running software and then upgrade into the upgraded system.
+When not running ZFS, consider backing up the system before upgrading to a newer version.
-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:
+===== 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;
+}
+....
+
+[WARNING]
+====
+Upgrading from 14 to 15 with pkgbase is not officially supported (because pkgbase was not officially supported in 14)! FreeBSD 15 is the first FreeBSD with pkgbase as a technical preview.
+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.
+After upgrading from 14 to 15 please consider to install a package set like `FreeBSD-set-minimal`.
+====
+
Save a list of the non-base packages in case they are needed later:
@@ -1242,20 +1278,23 @@
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 and mount the just created boot environment into that folder to enable working with pkg chroot 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]
====
@@ -1263,6 +1302,53 @@
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 boot environment fails to start, simply reboot and the system will boot back into the previously used boot 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,26 @@
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 update
+# 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
Sat, Apr 11, 9:53 PM (5 h, 43 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
28326640
Default Alt Text
D53534.1775944414.diff (8 KB)

Event Timeline