Page MenuHomeFreeBSD
Files F134728834

D51279.id158424.diff
No OneTemporary
Actions

D51279.id158424.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
@@ -1087,6 +1087,273 @@
# 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
+link:https://man.freebsd.org/cgi/man.cgi?query=pkg&sektion=8&manpath=freebsd-ports[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 line.
+
+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 freebsd-update tool will only be supported on the earlier 13 and 14 lineage 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 link:https://man.freebsd.org/cgi/man.cgi?query=bsdinstall&sektion=8&manpath=freebsd-release[bsdinstall(8)]
+
+* link:https://man.freebsd.org/cgi/man.cgi?query=freebsd-update&sektion=8&manpath=freebsd-release[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 14.0-RELEASE, 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 you may need up to 5GiB additional free space during this migration, to download, unpack, and relocate any conflicting files. This space check is your responsibility, and the pkgbasify tool will not check for it.
+====
+
+pkgbasify performs 6 main tasks:
+
+* If on ZFS, make a backup boot environment, to allow easily rolling back if required
+* Creates the new package repository config files
+* Upgrades existing system components such as base, kernel, lib32, debug
+* Merges merges existing and new config files
+* Updates passwd and capabilities databases
+* Restarts sshd immediately
+
+[source,shell]
+....
+### TODO this should be in ports or base, not via fetch rando url
+cd /tmp
+fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkbasify.lua
+chmod +x pkgbasify.lua
+./pkgbasify.lua
+... scrolling intensifies ...
+....
+
+=== Upgrading a Host using PkgBase
+
+[WARNING]
+====
+This is still in development, so please be careful especially when converting an existing system to use PkgBase.
+====
+
+If you don't already have a folder for custom pkg repository config files, create one
+[source,shell]
+....
+mkdir -p /usr/local/etc/pkg/repos/
+....
+
+For using the pkgbase repository, you should create a pkg repository configuration file `FreeBSD-base.conf`
+
+[[pgk-base-repo-configuration]]
+[source,shell]
+....
+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 link:https://man.freebsd.org/cgi/man.cgi?pkg.conf(5)[pkg.conf(5)].
+
+There are different branches to choose from (by changing the url accordingly):
+[WARNING]
+====
+ToDo: add explenation to what kmod is
+====
+
+[[table-of-packagebase-branches]]
+.PkgBase Branches
+[cols="10%,10%,40%,40%, options="header"]
+|===
+| Branch
+| Frequency
+| URL
+| kmods
+
+| main
+| twice daily - 12:00 and 00:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_latest`
+| `https://pkg.freebsd.org/${ABI}/kmods_latest`
+
+| main
+| weekly – Sunday at 12:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_weekly`
+| n.a.
+
+| stable/14
+| twice daily – 12:00 and 00:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_latest`
+| `https://pkg.freebsd.org/${ABI}/kmods_latest`
+
+| stable/14
+| weekly – Sunday at 12:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_weekly`
+| n.a.
+
+| releng/14.1
+| twice daily – 12:00 and 00:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_release_1`
+| n.a.
+
+| releng/14.2
+| twice daily – 12:00 and 00:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_release_2`
+| `https://pkg.freebsd.org/${ABI}/kmods_latest_2`
+
+| releng/14.3
+| twice daily – 12:00 and 00:00 UTC
+| `https://pkg.freebsd.org/${ABI}/base_release_3`
+| `https://pkg.freebsd.org/${ABI}/kmods_latest_3`
+|===
+
+To upgrade the System, change the configuration file according to the release you would like to use, 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
+[source,shell]
+....
+shutdown -r now
+....
+
+==== Performing Major version upgrades
+If you are running ZFS you should consider creating a boot environment before upgrading to a newer version.
+To create a new boot environment using the link:https://man.freebsd.org/cgi/man.cgi?bectl(8)[bectl(8)] tool run:
+[source,shell]
+....
+bectl create 15.0-CURRENT
+....
+It is recommended to make the changes inside the boot environment so you can roll back if something goes wrong.
+To go inside the boot environment mount it and chroot into it.
+[source,shell]
+....
+mkdir -p /tmp/bootenv
+bectl mount 15.0-CURRENT /tmp/bootenv
+chroot /tmp/bootenv
+....
+
+
+Change `/usr/local/etc/pkg/repos/FreeBSD-base.conf` to target the correct major release like `base_latest`, so it looks like:
+[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;
+}
+....
+
+To upgrade the majer version you need to supply the environment variable ABI:
+
+[source,shell]
+....
+env ABI=FreeBSD:15:amd64 pkg-static update -r FreeBSD-upgrade
+env ABI=FreeBSD:15:amd64 pkg-static upgrade -r FreeBSD-upgrade
+....
+
+To check if that was successfull, you can run `freebsd-version -kru`.
+
+If you created the boot environment, you now can exit this boot environment and activate it for next boot.
+
+[source,shell]
+....
+exit
+bectl activate -t 15.0-CURRENT
+....
+
+Then reboot.
+
+After upgrading to a new major version, you should probably update and upgrade your packages to match the ABI version.
+
+[source,shell]
+....
+pkg update
+pkg upgrade
+....
+
+If everything works, you can permanently activate the boot environment.
+
+[source,shell]
+....
+bectl activate 15.0-CURRENT
+....
+
+[[build-pkgbase-packets-locally]]
+=== Building PkgBase on your own and publish it to the local network
+To start building your own packagebase packets you need to 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 you would like 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.
+You should set the parallel processes according to your cpu core count.
+This example is written for 8 core CPU:
+[source,shell]
+....
+make -j8 buildworld && make -j8 buildkernel && make -j8 packages
+....
+
+If you are building this frequently, you should probably look into using ccache.
+
+After building, the packages will get saved into `/usr/obj/usr/src/repo/FreeBSD:14:amd64/14.3p1` or something like that, depending on the version you build.
+
+To publish these packages to the Network you could set up a nginx service and use this location in your http server configuration:
+[source,config]
+....
+ location /FreeBSD:14:amd64 {
+ alias /usr/obj/usr/src/repo/FreeBSD:14:amd64/;
+ autoindex on;
+ }
+....
+And reload the nginx service.
+
+If you are not using https, you could simly just use a small configuration file on your clients to target the pkgbase version you just built by editing `/usr/local/etc/pkg/repos/FreeBSD-base.conf`
+[source,shell]
+....
+freebsd-upgrade: {
+ url = http://ip.of.your.server/FreeBSD:14:amd64/14.3p1
+ enabled = yes
+}
+....
+and use it as written above.
+
+Based on link:https://wiki.freebsd.org/PkgBase[Wiki - PkgBase]
+
[[small-lan]]
== Tracking for Multiple Machines

File Metadata

Mime Type
text/plain
Expires
Wed, Nov 5, 5:46 AM (14 h, 27 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
24780705
Default Alt Text
D51279.id158424.diff (9 KB)

Event Timeline