Page MenuHomeFreeBSD
Files F175037903

D56632.id176452.diff
No OneTemporary
Actions

D56632.id176452.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
@@ -1090,9 +1090,11 @@
[[pkgbase]]
== Updating FreeBSD with packages
-Starting from 14.0-RELEASE, the FreeBSD project has published a set of packages of the base system, using man:pkg[8].
+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 traditionally referred to as _pkgbase_.
Publication of official packages began in link:https://lists.freebsd.org/archives/freebsd-pkgbase/2023-October/000221.html[October 2023].
@@ -1144,6 +1146,8 @@
* Updates passwd and capabilities databases
* Restarts sshd immediately
+For more Information please take a look at the link:https://github.com/FreeBSDFoundation/pkgbasify[README.md] of the project.
+
=== Upgrading a Host using freebsd-base
[WARNING]
@@ -1151,30 +1155,40 @@
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.
+Starting with FreeBSD 15 the FreeBSD-base repository is included in `/etc/pkg/FreeBSD.conf`.
-[source,shell]
+This is disabled by default.
+
+To make adjustments, it is recommended to use configuration files located in `/usr/local/etc/pkg/repos/`.
+
+If this directory does not exist yet, create it.
+
+To enable the FreeBSD-base repository, create or edit the pkg repository configuration file `/usr/local/etc/pkg/repos/FreeBSD.conf`:
+
+[[pgk-base-repo-configuration]]
+[.programlisting]
....
-# mkdir -p /usr/local/etc/pkg/repos/
+FreeBSD-base: {
+ enabled: yes
+}
....
-For using the freebsd-base repository, create a pkg repository configuration file called `FreeBSD-base.conf`:
+To overwrite the defaults set in `/etc/pkg/FreeBSD.conf`, additional content like the url can be set. For example:
-[[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;
+FreeBSD-base: {
+ url: "pkg+https://pkg.FreeBSD.org/${ABI}/base_release_${VERSION_MINOR}",
+ mirror_type: "srv",
+ signature_type: "fingerprints",
+ fingerprints: "/usr/share/keys/pkgbase-${VERSION_MAJOR}",
+ enabled: no
}
....
for more information on specific configuration options see man:pkg.conf[5].
-There are different branches to choose from (by changing the url accordingly):
+There are different branches to choose from (by changing the url accordingly, or overwriting the environment variables ABI and VERSION_MINOR):
[[table-of-packagebase-branches]]
.Base system package Branches
@@ -1204,6 +1218,10 @@
| twice daily – 12:00 and 00:00 UTC
| `pkg+https://pkg.freebsd.org/${ABI}/base_release_3`
+| releng/14.4
+| twice daily – 12:00 and 00:00 UTC
+| `pkg+https://pkg.freebsd.org/${ABI}/base_release_4`
+
| releng/15.0
| twice daily – 12:00 and 00:00 UTC
| `pkg+https://pkg.freebsd.org/${ABI}/base_release_0`
@@ -1217,11 +1235,10 @@
| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly`
|===
-To upgrade the system, change the configuration file according to the desired release, and run:
+To upgrade the patch level of the system run:
[source,shell]
....
-# pkg update -r FreeBSD-base
# pkg upgrade -r FreeBSD-base
....
@@ -1234,29 +1251,38 @@
# shutdown -r now
....
+[[pkgbase-minor-upgrade]]
+==== Minor Upgrades
+When using zfs, using boot environments is a great way to recover from any failures.
+
+Take a look at crossref:cutting-edge[pkgbase-major-upgrade,Major Upgrades] on how to utilize boot environments for upgrading.
+
+Set the environment variable VERSION_MINOR to upgrade to another minor version.
+
+For example to upgrade from 15.0-RELEASE to 15.1-RELEASE, run
+
+[source,shell]
+....
+# env VERSION_MINOR=1 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
+....
+
[[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;
-}
-....
+Use the environment variables for ABI and VERSION_MINOR according to the target version.
+For example to target 15.0 use ABI=FreeBSD:15:amd64 (or whatever architecture is are running) and VERSION_MINOR=0 to get the correct url.
[WARNING]
====
@@ -1267,13 +1293,10 @@
[source,shell]
....
-# pkg -c /mnt/upgrade lock pkg
+# pkg lock pkg
....
-
-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:
[source,shell]
@@ -1281,6 +1304,8 @@
pkg prime-origins | sort -u > /var/tmp/pkg-prime-origins.txt
....
+Always take a look at the link:https://www.freebsd.org/releases/15.0R/relnotes/#upgrade-rc[release notes], because some parts still might change. For example between FreeBSD 14 and 15 the signing keys changed.
+
[[pkgbase-major-zfs]]
===== major upgrade with zfs
Create a boot environment using man:bectl[8] and name it according to the version upgrading to
@@ -1309,7 +1334,7 @@
[source,shell]
....
-# env ABI=FreeBSD:15:amd64 pkg-static -c /mnt/upgrade upgrade -r FreeBSD-base
+# env ABI=FreeBSD:15:amd64 VERSION_MINOR=0 pkg-static -c /mnt/upgrade upgrade -r FreeBSD-base
....
There will be a prompt asking about ignoring the version mismatch looking like this:
@@ -1325,7 +1350,14 @@
Check and confirm that.
-To check if that was successful, chroot into the mountpoint of the boot environment and run `freebsd-version -ku`.
+An experimental major upgrade from FreeBSD 14 to 15 should be followed by installation of package sets (see man:freebsd-base[7]), like `FreeBSD-set-minimal` at least, which is a meta package which includes some base packages required for running a multi-user FreeBSD system.
+
+[source,shell]
+....
+# env ABI=FreeBSD:15:amd64 pkg-static -c /mnt/upgrade install -r FreeBSD-base FreeBSD-set-minimal
+....
+
+To check if the upgrade was successful, chroot into the mountpoint of the boot environment and run `freebsd-version -ku`. The output should show the new Version.
[source,shell]
....
@@ -1357,7 +1389,7 @@
[source,shell]
....
-# env ABI=FreeBSD:15:amd64 pkg-static upgrade -r FreeBSD-base
+# env ABI=FreeBSD:15:amd64 VERSION_MINOR=0 pkg-static upgrade -r FreeBSD-base
....
There will be a prompt to ask about ignoring the version mismatch looking like this:
@@ -1394,9 +1426,9 @@
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
+=== Manually building base packages and publishing it to the local network
-When building custom pkgbase packages clone the FreeBSD source tree:
+When building custom base packages clone the FreeBSD source tree:
[source,shell]
....
@@ -1408,7 +1440,7 @@
[source,shell]
....
-# git checkout releng/14.3
+# git checkout releng/15.0
....
Start the building process, depending on the resources available this could take some while.
@@ -1418,19 +1450,21 @@
[source,shell]
....
-# make -j8 buildworld && make -j8 buildkernel && make -j8 packages
+# make -j8 buildkernel && make -j8 buildworld && make -j8 update-packages
....
+The update-packages make target is copying unchanged packages. This keeps the version number in the packages so only changed packages get upgraded on the hosts.
+
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.
+After building, the packages will get saved into `/usr/obj/usr/src/repo/FreeBSD:15:amd64/15.0p6` 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:
+To publish these packages to the network set up a nginx service and use this location in the http server configuration (usually located in `/usr/local/etc/nginx/nginx.conf`):
[.programlisting]
....
- location /FreeBSD:14:amd64 {
- alias /usr/obj/usr/src/repo/FreeBSD:14:amd64/;
+ location /FreeBSD:15:amd64 {
+ alias /usr/obj/usr/src/repo/FreeBSD:15:amd64/;
autoindex on;
}
....
@@ -1442,12 +1476,24 @@
[.programlisting]
....
upgrade: {
- url = http://ip.of.the.server/FreeBSD:14:amd64/14.3p2
+ url = http://ip.of.the.server/FreeBSD:15:amd64/15.0p6
enabled = yes
}
....
-and use it as written above (but use -r upgrade instead of FreeBSD-base).
+and use it as written above (but use `-r upgrade` instead of `-r FreeBSD-base`).
+
+Optionally create a configuration to use the local repository on the host where the packages are built, if publishing to the network is not needed or to just upgrade the local host.
+
+[.programlisting]
+....
+upgrade {
+ url: "file:///usr/obj/usr/src/repo/FreeBSD:15:amd64/latest/";
+ enabled: yes
+}
+....
+
+Here `latest` is a symlink to the version built last.
[[small-lan]]
== Tracking for Multiple Machines

File Metadata

Mime Type
text/plain
Expires
Thu, Oct 8, 7:52 PM (7 h, 39 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
40439554
Default Alt Text
D56632.id176452.diff (10 KB)

Event Timeline