Page MenuHomeFreeBSD
Files F160142651

D57421.id179166.diff
No OneTemporary
Actions

D57421.id179166.diff
View Options

diff --git a/website/content/en/releases/15.1R/installation.adoc b/website/content/en/releases/15.1R/installation.adoc
--- a/website/content/en/releases/15.1R/installation.adoc
+++ b/website/content/en/releases/15.1R/installation.adoc
@@ -82,9 +82,143 @@
# freebsd-update install
----
+[TIP]
+====
+For systems booting in Legacy BIOS (CSM) mode with a GPT partition layout, it is recommended to update the boot loader manually.
+See <<upgrade-boot-loader-bios>> for detailed instructions.
+====
+
Finally, reboot into a fully {releaseCurrent} system:
[.screen]
----
# shutdown -r now
----
+
+[[upgrade-pkgbase]]
+== Upgrading with Base System Packages (pkgbase)
+
+1. **Update `pkg(8)` itself**:
++
+[.screen,subs="verbatim,attributes"]
+....
+# pkg upgrade -yr FreeBSD-ports pkg
+....
+
+2. **Upgrade the base system**.
++
+[.screen,subs="verbatim,attributes"]
+....
+# pkg upgrade -r FreeBSD-base
+....
++
+After the upgrade, review any messages printed by `pkg(8)`. Some base packages may require additional configuration steps (e.g., running `service <name> setup`). Follow those instructions as needed.
+
+3. **Update third‑party kernel modules (kmods)** (if any). Use the same temporary repository:
++
+[.screen,subs="verbatim,attributes"]
+....
+# pkg upgrade -r FreeBSD-ports-kmods
+....
++
+To check whether you have any third‑party kmods installed:
++
+[.screen,subs="verbatim,attributes"]
+....
+# pkg which $(kldstat -v | awk -F '[()]' '/\.ko/ {print $2}')
+....
++
+Modules located in `/boot/kernel/` belong to base system packages (`FreeBSD-kernel-*`).
+Modules located in `/boot/modules/` are third‑party kmods. If no packages with names not starting with `FreeBSD-` appear, you have no third‑party kmods.
+
+4. **Check for configuration file updates** that may have been installed as `.pkgnew` files:
++
+[.screen,subs="verbatim,attributes"]
+....
+# find /etc /usr/local/etc -name '*.pkgnew' -ls
+....
++
+If such files exist, manually compare them with the originals (e.g., `diff /etc/rc.conf /etc/rc.conf.pkgnew`) and merge any necessary changes.
+
+5. **Update the boot loader**. Follow the detailed instructions in <<upgrade-boot-loader>> to update the boot loader for your system (UEFI or Legacy BIOS).
+
+6. **Reboot** to load the new kernel and userland:
++
+[.screen,subs="verbatim,attributes"]
+....
+# shutdown -r now
+....
++
+For more details about base system packages, see man:freebsd-base[7].
+
+[[upgrade-boot-loader]]
+== Update the boot loader
+
+There have been a number of improvements in the boot loaders, and upgrading the boot loader on the boot partition is recommended in most cases, in particular if the system boots via EFI.
+If the root is on a ZFS file system, updating the boot loader is mandatory if the pool is to be upgraded, and the boot loader update must be done first.
+Note that ZFS pool upgrades are not recommended for root file systems in most cases, but updating the boot loader can avoid making the system unbootable if the pool is upgraded in the future.
+The bootstrap update procedure depends on the boot method (EFI or BIOS) and also on the disk partitioning scheme.
+The next several sections address each in turn.
+
+[[upgrade-boot-loader-uefi]]
+=== Update the UEFI boot loader
+
+Notes for systems that boot via EFI, using either binary or source upgrades:
+There are one or more copies of the boot loader on the MS-DOS EFI System Partition (ESP), used by the firmware to boot the kernel.
+The location of the boot loader in use can be determined using the `efibootmgr -v` command.
+The value displayed for `BootCurrent` should be the number of the current boot configuration used to boot the system.
+The corresponding entry of the output should begin with a `+` sign, such as
+
+[.screen,subs="verbatim,attributes"]
+....
+ +Boot0000* FreeBSD HD(1,GPT,f859c46d-19ee-4e40-8975-3ad1ab00ac09,0x800,0x82000)/File(\EFI\freebsd\loader.efi)
+ nda0p1:/EFI/freebsd/loader.efi (null)
+....
+
+The ESP may already be mounted on [.filename]#/boot/efi#.
+Otherwise, the partition may be mounted manually, using the partition listed in the `efibootmgr` output (`nda0p1` in this case):
+[.screen,subs="verbatim,attributes"]
+....
+mount_msdosfs /dev/nda0p1 /boot/efi
+....
+
+See man:loader.efi[8] for another example.
+
+The value in the `File` field in the `efibootmgr -v` output, `\EFI\freebsd\loader.efi` in this case, is the path in MS-DOS format for the boot loader in use on the ESP.
+If the mount point is [.filename]#/boot/efi#, this file will translate to `/boot/efi/efi/freebsd/loader.efi`.
+(Case does not matter on MS-DOSFS file systems; FreeBSD uses lower case.)
+Another common value for `File` would be `\EFI\boot\bootXXX.efi`, where `XXX` is `x64` for amd64, `aa64` for aarch64, or `riscv64` for riscv64; this is the default bootstrap if none is configured.
+Both the configured and default boot loaders should be updated by copying from [.filename]#/boot/loader.efi# to the correct path in [.filename]#/boot/efi#.
+
+[[upgrade-boot-loader-bios]]
+=== Update the Legacy BIOS boot loader
+
+For systems that boot via BIOS and use the GPT partition scheme, bootstrap upgrades are optional unless a ZFS root pool is upgraded (which is discouraged).
+Upgrades are only possible if the `freebsd-boot` partition is at least 180K.
+(512K is now standard.)
+The device name and the partition index can be identified using the command `gpart show`, such as:
+
+[.screen,subs="verbatim,attributes"]
+....
+ => 34 246162605 ada0 GPT (224G)
+ 34 1024 1 freebsd-boot (512K)
+....
+
+When using ZFS, the bootcode can be updated by running the command
+[.screen,subs="verbatim,attributes"]
+....
+gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0
+....
+where `-i 1`
+is the index of the `freebsd-boot` partition (use the actual index shown by `gpart show`).
++
+If updating with a UFS root, the bootcode can be updated by running the command
+[.screen,subs="verbatim,attributes"]
+....
+gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0
+....
+although this should not be necessary.
+Note that the `freebsd-boot` partition size is running up against a hard limit, and this scheme may not be supportable in the future.
+Users of such systems should consider an upgrade to EFI, possibly by carving space from an existing swap partition.
+
+If the system boots via BIOS and uses the MBR partition scheme, or has a GPT `freebsd-boot` partition smaller than 180K, then it is not possible to update the bootcode, and therefore to upgrade the root ZFS storage pool.
diff --git a/website/content/en/releases/15.1R/relnotes.adoc b/website/content/en/releases/15.1R/relnotes.adoc
--- a/website/content/en/releases/15.1R/relnotes.adoc
+++ b/website/content/en/releases/15.1R/relnotes.adoc
@@ -34,14 +34,8 @@
It describes recently added, changed, or deleted features of FreeBSD.
It also provides some notes on upgrading from previous versions of FreeBSD.
-The {releaseType} distribution to which these release notes apply represents the latest point along the {releaseBranch} development branch since {releaseBranch} was created.
+The {releaseType} distribution to which these release notes apply represents the latest point along the {releaseBranch} development branch between {releasePrev} and the future {releaseNext}.
Information regarding pre-built, binary {releaseType} distributions along this branch can be found at https://www.FreeBSD.org/releases/[].
-
-The {releaseType} distribution to which these release notes apply represents a point along the {releaseBranch} development branch between {releasePrev} and the future {releaseNext}.
-Information regarding pre-built, binary {releaseType} distributions along this branch can be found at https://www.FreeBSD.org/releases/[].
-
-This distribution of FreeBSD {releaseCurrent} is a {releaseType} distribution.
-It can be found at https://www.FreeBSD.org/releases/[] or any of its mirrors.
More information on obtaining this (or other) {releaseType} distributions of FreeBSD can be found in the link:{handbook}mirrors[Obtaining FreeBSD appendix] to the link:{handbook}[FreeBSD Handbook].
All users are encouraged to consult the release errata before installing FreeBSD.
@@ -59,17 +53,58 @@
[[upgrade]]
== Upgrading from Previous Releases of FreeBSD
-Binary upgrades between RELEASE versions (and snapshots of the various security branches) are supported using the man:freebsd-update[8] utility.
+[IMPORTANT]
+====
+Upgrading FreeBSD should only be attempted after backing up _all_ data and configuration files.
+====
+
+Upgrading to 15.1 depends on how your base system was installed.
+There are two methods:
+
+* If you installed FreeBSD the traditional way (using the installer or by extracting `base.txz`), use freebsd-update(8) as described in <<upgrade-fu>>.
+* If you installed the base system via `pkg` (pkgbase, a technology preview starting with FreeBSD 15.0), use the `pkg(8)` procedure described in <<upgrade-rc>>.
+
+To determine which method applies to your system, see <<upgrade-detect>>.
+
+[[upgrade-detect]]
+=== Determining Your Base System Type
+
+Run the following command:
+
+[source,shell]
+....
+# pkg which /usr/bin/uname
+....
+
+If the output shows a package name starting with `FreeBSD-` (for example `FreeBSD-runtime-15.0`), your base system is managed by `pkg` (pkgbase).
+If the output says `/usr/bin/uname was not installed by a package`, your system uses the traditional layout (freebsd-update(8) is the appropriate upgrade method).
+
+[[upgrade-fu]]
+=== Upgrading from Distribution Sets
+
+Binary upgrades between snapshots and RELEASE versions are supported using the man:freebsd-update[8] utility.
See the release-specific upgrade procedure, link:../installation/#upgrade-binary[FreeBSD {releaseCurrent} upgrade information], with more details in the FreeBSD handbook link:{handbook}cutting-edge/#freebsdupdate-upgrade[binary upgrade procedure].
This will update unmodified userland utilities, as well as unmodified GENERIC kernels distributed as a part of an official FreeBSD release.
The man:freebsd-update[8] utility requires that the host being upgraded have Internet connectivity.
-Source-based upgrades (those based on recompiling the FreeBSD base system from source code) from previous versions are supported, according to the instructions in [.filename]#/usr/src/UPDATING#.
+[[upgrade-rc]]
+=== Upgrading from Packages
-[IMPORTANT]
-====
-Upgrading FreeBSD should only be attempted after backing up _all_ data and configuration files.
-====
+If your FreeBSD system was installed using base system packages (pkgbase, a technology preview starting with FreeBSD 15.0), upgrades to a new release are performed with `pkg(8)`.
+The full step‑by‑step procedure is described in the installation document:
+
+* link:../installation/#upgrade-pkgbase[Upgrading with Base System Packages (pkgbase)]
+
+Unlike the traditional `freebsd-update(8)` method, the pkgbase upgrade process does not require multiple reboots.
+It also includes updating third‑party kernel modules (`kmods`) and the UEFI boot loader where necessary.
+
+For more details on base system packages, see man:freebsd-base[7].
+
+[[upgrade-mk]]
+=== Upgrading from Source
+
+Source-based upgrades from previous versions are supported via compiling the releng/15.1 branch.
+Refer to the instructions in [.filename]#/usr/src/UPDATING#.
[[security-errata]]
== Security and Errata

File Metadata

Mime Type
text/plain
Expires
Mon, Jun 22, 5:50 PM (3 h, 13 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34147073
Default Alt Text
D57421.id179166.diff (11 KB)

Event Timeline