Date: Mon, 15 Jun 2026 22:31:48 +0000 From: Alexander Ziaee <ziaee@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 63927b02bb - main - 15.1: Installation note -> Upgrading note Message-ID: <6a307d54.43ba2.2b377b07@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/doc/commit/?id=63927b02bb470b0702cc85a2afe0bf39750d6671 commit 63927b02bb470b0702cc85a2afe0bf39750d6671 Author: Alexander Ziaee <ziaee@FreeBSD.org> AuthorDate: 2026-06-15 20:11:29 +0000 Commit: Alexander Ziaee <ziaee@FreeBSD.org> CommitDate: 2026-06-15 22:31:07 +0000 15.1: Installation note -> Upgrading note The installation note does not contain installation instructions, and has not since FreeBSD 6.0. Rename it to the upgrading note to avoid confusion with the installation guide. Consolidate all release upgrading information here. Rewrite the introduction to the release note to separate these out more. Remove information that is not needed to introduce this release. The release installation notes do not actually contain instructions on installing FreeBSD, so rename it to the Upgrading Note. Reviewed by: carlavilla (previous), cperciva Discussed with: cperciva, dch, emaste, fuz, michaelo Co-authored-by: Vladlen Popolitov <vladlen@FreeBSD.org> Differential Revision: https://reviews.freebsd.org/D57517 --- website/content/en/releases/15.1R/_index.adoc | 2 +- .../content/en/releases/15.1R/installation.adoc | 90 ------ website/content/en/releases/15.1R/relnotes.adoc | 49 +--- website/content/en/releases/15.1R/upgrading.adoc | 303 +++++++++++++++++++++ 4 files changed, 313 insertions(+), 131 deletions(-) diff --git a/website/content/en/releases/15.1R/_index.adoc b/website/content/en/releases/15.1R/_index.adoc index 8eb581b52b..52106e9ec0 100644 --- a/website/content/en/releases/15.1R/_index.adoc +++ b/website/content/en/releases/15.1R/_index.adoc @@ -23,7 +23,7 @@ can be found at these pages: //link:announce/[FreeBSD {localRel}-RELEASE announcement] + //link:signatures/[FreeBSD {localRel}-RELEASE signed checksum files] + -//link:installation/[FreeBSD {localRel}-RELEASE installation information] + +//link:upgrading/[FreeBSD {localRel}-RELEASE upgrading instructions] + //link:hardware/[FreeBSD {localRel}-RELEASE hardware information] + //link:relnotes/[FreeBSD {localRel}-RELEASE release notes] + //link:errata/[FreeBSD {localRel}-RELEASE errata] + diff --git a/website/content/en/releases/15.1R/installation.adoc b/website/content/en/releases/15.1R/installation.adoc deleted file mode 100644 index 23af2071d9..0000000000 --- a/website/content/en/releases/15.1R/installation.adoc +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "FreeBSD 15.1-RELEASE Installation Instructions" -sidenav: download ---- - -:releaseCurrent: 15.1-RELEASE -:releasePrev: 15.0-RELEASE -:releasePrevLegacy: 14.4-RELEASE -:localRel: 15.1 - -include::shared/en/urls.adoc[] - -= FreeBSD {localRel}-RELEASE Installation Instructions - -== Abstract - -This article gives some brief instructions on installing FreeBSD {releaseCurrent} and upgrading the systems running earlier releases. - -== Table of Contents - -* <<install,Installing FreeBSD>> -* <<upgrade,Upgrading FreeBSD>> - -[[install]] -== Installing FreeBSD - -The link:{handbook}bsdinstall/[Installing FreeBSD] chapter of the FreeBSD Handbook provides more in-depth information about the installation program itself, including a guided walk-through with screenshots. - -[[upgrade]] -== Upgrading FreeBSD - -If you are upgrading from a previous release of FreeBSD, please read the upgrading section in the link:../relnotes[Release Notes] for notable incompatibilities carefully. - -[[upgrade-source]] -== Upgrading from Source - -The procedure for doing a source code based update is described in link:{handbook}cutting-edge/#makeworld[Updating FreeBSD from Source]. - -For Git use the releng/{localRel} branch which will be where any upcoming Security Advisories or Errata Notices will be applied. - -[[upgrade-binary]] -== Upgrading Using "FreeBSD Update" - -The man:freebsd-update[8] utility supports binary upgrades of amd64, arm64, and i386 systems running earlier FreeBSD releases. -Systems running {releasePrevLegacy} or {releasePrev} can upgrade as follows: - -[.screen] ----- -# freebsd-update fetch -# freebsd-update install ----- - -Now the man:freebsd-update[8] utility can fetch bits belonging to {releaseCurrent}. -During this process man:freebsd-update[8] will ask for help in merging configuration files. - -[.screen,subs="verbatim,attributes"] ----- -# freebsd-update upgrade -r {localRel}-RELEASE -# freebsd-update install ----- - -The system must now be rebooted with the newly installed kernel before the non-kernel components are updated. - -[.screen] ----- -# shutdown -r now ----- - -After rebooting, man:freebsd-update[8] needs to be run again to install the new userland components: - -[.screen] ----- -# freebsd-update install ----- - -At this point, users of systems being upgraded from earlier FreeBSD releases will be prompted by man:freebsd-update[8] to rebuild or reinstall all third-party applications (e.g., ports installed from the ports tree or packages installed by man:pkg[8]) due to updates in system libraries. - -After updating installed third-party applications (and again, only if man:freebsd-update[8] printed a message indicating that this was necessary), run man:freebsd-update[8] again so that it can delete the old (no longer used) system libraries: - -[.screen] ----- -# freebsd-update install ----- - -Finally, reboot into a fully {releaseCurrent} system: - -[.screen] ----- -# shutdown -r now ----- diff --git a/website/content/en/releases/15.1R/relnotes.adoc b/website/content/en/releases/15.1R/relnotes.adoc index 87f42e4914..1c05a870be 100644 --- a/website/content/en/releases/15.1R/relnotes.adoc +++ b/website/content/en/releases/15.1R/relnotes.adoc @@ -21,60 +21,29 @@ include::shared/en/urls.adoc[] == Abstract [.abstract-title] -The release notes for FreeBSD {releaseCurrent} contain a summary of the changes made to the FreeBSD base system on the {releaseBranch} development line. -This document lists applicable security advisories that were issued since the last release, as well as significant changes to the FreeBSD kernel and userland. -Some brief remarks on upgrading are also presented. +The release notes for FreeBSD {releaseCurrent} contain a summary of the changes made to the operating system on the {releaseBranch} development line. +This document lists applicable security advisories and errata issued since the last release as well as significant changes to the ecosystem. toc::[] [[intro]] == Introduction -This document contains the release notes for FreeBSD {releaseCurrent}. -It describes recently added, changed, or deleted features of FreeBSD. -It also provides some notes on upgrading from previous versions of FreeBSD. +This document details the changes since FreeBSD {releasePrev}. -The {releaseType} distribution to which these release notes apply represents the latest point along the {releaseBranch} development branch since {releaseBranch} was created. -Information regarding pre-built, binary {releaseType} distributions along this branch can be found at https://www.FreeBSD.org/releases/[]. +For installation instructions, see the link:{handbook}bsdinstall/[Installing FreeBSD] chapter of the FreeBSD Handbook. -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/[]. +For upgrading instructions, see link:../upgrading[FreeBSD {releaseCurrent} Upgrading Instructions]. -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]. +For information on supported hardware, see the link:../hardware[FreeBSD {releaseCurrent} Hardware Compatibility List]. -All users are encouraged to consult the release errata before installing FreeBSD. -The errata document is updated with "late-breaking" information discovered late in the release cycle or after the release. -Typically, it contains information on known bugs, security advisories, and corrections to documentation. -An up-to-date copy of the errata for FreeBSD {releaseCurrent} can be found on the FreeBSD Web site. - -This document describes the most user-visible new or changed features in FreeBSD since {releasePrev}. -In general, changes described here are unique to the {releaseBranch} branch unless specifically marked as MERGED features. - -Typical release note items document recent security advisories issued after {releasePrev}, new drivers or hardware support, new commands or options, major bug fixes, or contributed software upgrades. -They may also list changes to major ports/packages or release engineering practices. -Clearly the release notes cannot list every single change made to FreeBSD between releases; this document focuses primarily on security advisories, user-visible changes, and major architectural improvements. - -[[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. -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#. - -[IMPORTANT] -==== -Upgrading FreeBSD should only be attempted after backing up _all_ data and configuration files. -==== +All readers are encouraged to consult the link:../errata[FreeBSD {releaseCurrent} errata] before installation or upgrading. +The errata document contains information discovered late in the release cycle, such as known bugs, security advisories, or documentation corrections. [[security-errata]] == Security and Errata -This section lists the various Security Advisories and Errata Notices since {releasePrev}. +This section lists the Security Advisories and Errata Notices since {releasePrev}. [[security]] === Security Advisories diff --git a/website/content/en/releases/15.1R/upgrading.adoc b/website/content/en/releases/15.1R/upgrading.adoc new file mode 100644 index 0000000000..d759f1d5e8 --- /dev/null +++ b/website/content/en/releases/15.1R/upgrading.adoc @@ -0,0 +1,303 @@ +--- +title: "FreeBSD 15.1-RELEASE Upgrading Instructions" +sidenav: download +--- + +:releaseCurrent: 15.1-RELEASE +:releasePrev: 15.0-RELEASE +:releasePrevLegacy: 14.4-RELEASE +:localRel: 15.1 + +include::shared/en/urls.adoc[] + += FreeBSD {releaseCurrent} Upgrading Instructions + +== Abstract + +This note details the procedure for upgrading existing installations to FreeBSD {releaseCurrent}. + +[[upgrade]] +== Introduction + +This document explains the procedure for upgrading existing {releasePrevLegacy} or {releasePrev} installations to {releaseCurrent}. +Systems running older releases must be upgraded incrementally to one of these releases before performing this upgrade. + +Before upgrading the operating system, back up _all_ filesystems, read the link:../errata[late-breaking errata] for known issues and workarounds, and the link:../relnotes[release note] for major changes and incompatibilities. + +The procedure for binary upgrades depends on the method used to manage the operating system. +To determine this, run the following command: + +[source,shell] +---- +pkg which /usr/bin/uname +---- + +If `/usr/bin/uname was not installed by a package` is shown, see <<upgrade-fu>> below. + +If a package name is shown, such as `FreeBSD-runtime-15.0`, see <<upgrade-pkg>> below. + +[upgrade-source] +If upgrading via source, see link:{handbook}cutting-edge/#makeworld[FreeBSD Handbook chapter on Updating FreeBSD from Source]. + +[[upgrade-fu]] +== Upgrading with Distribution Sets + +Systems deployed via distribution sets are upgraded via man:freebsd-update[8]. +Systems running {releasePrevLegacy} or {releasePrev} can be upgraded as follows: + +. **Apply all Pending Patches**: ++ +Always fetch and apply all pending patches to the current system before upgrading: ++ +[source,shell] +---- +freebsd-update fetch +freebsd-update install +---- ++ +. **Upgrade the Kernel** ++ +Fetch and install the new kernel: ++ +[source,shell,subs="verbatim,attributes"] +---- +freebsd-update upgrade -r {localRel}-RELEASE +freebsd-update install +---- ++ +During this process man:freebsd-update[8] may ask for help in merging configuration files. ++ +. **Reboot into the new Kernel** ++ +Reboot into the new kernel before installing the new userland: ++ +[source,shell] +---- +shutdown -r +10min "Rebooting for a kernel upgrade" +---- ++ +. **Upgrade the Userland** ++ +After rebooting, run man:freebsd-update[8] again to install the new userland components: ++ +[source,shell] +---- +freebsd-update install +---- ++ +man:freebsd-update[8] may prompt to rebuild or reinstall all third-party software due to changes in system libraries. +Follow those instructions as needed. ++ +[TIP] +==== +If upgrading from {releasePrevLegacy} and reinstalling all third-party software is not possible, install the package:misc/compat14x[] package. +==== ++ +. **Remove Old Files** ++ +Run man:freebsd-update[8] again to remove stale base system files: ++ +[source,shell] +---- +freebsd-update install +---- ++ +. **Upgrade the Boot Loader** ++ +To determine which boot loader to update on your system, run the following command: ++ +[source,shell] +---- +sysctl machdep.bootmethod +---- ++ +Continue to <<upgrade-loader-uefi>> or <<upgrade-loader-bios>> below. + +[[upgrade-pkg]] +== Upgrading with Base System Packages + +Systems deployed with a packaged base system are upgraded via man:pkg[8]. +Systems running {releasePrevLegacy} or {releasePrev} can be upgraded as follows: + +. **Snapshot the Current Installation** ++ +Take a recursive snapshot of the functioning system named with the current date: ++ +[source,shell,subs="verbatim,attributes"] +---- +bectl create -r pre-{localRel} +---- ++ +The boot loader offers a menu to boot from this if the upgrade needs to be rolled back. ++ +. **Upgrade the Package Manager** ++ +[source,shell] +---- +pkg upgrade -yr FreeBSD-ports pkg +---- ++ +. **Upgrade the Base System** ++ +[source,shell] +---- +pkg -oABI=FreeBSD:15:$(uname -p) -oOSVERSION=1501000 upgrade -r FreeBSD-base +---- ++ +After the upgrade, review any messages printed by `pkg(8)`. +Some packages may require additional configuration steps such as running `service <name> setup`. +Follow those instructions as needed. ++ +. **Upgrade Third‑party Kernel Modules** ++ +Third party kernel modules must also be upgraded with the base system: ++ +[source,shell] +---- +pkg upgrade -r FreeBSD-ports-kmods +---- ++ +If the installation is not using these, man:pkg[8] will reply accordingly. ++ +. **Check for Failed Configuration Updates** ++ +If man:pkg[8] is unable to merge configuration file updates, it will install the new configuration as a `.pkgnew` file. +Check for them with the following command: ++ +[source,shell] +---- +find /etc /usr/local/etc -name '*.pkgnew' -ls +---- ++ +If they exist, compare them with the deployed version (e.g., `diff /etc/rc.conf /etc/rc.conf.pkgnew`) and merge any necessary changes. ++ +. **Upgrade the Boot Loader**: ++ +To determine which boot loader to update on your system, run the following command: ++ +[source,shell] +---- +sysctl machdep.bootmethod +---- ++ +Continue to <<upgrade-loader-uefi>> or <<upgrade-loader-bios>> below. + +[[upgrade-loader-uefi]] +== Upgrading the UEFI Boot Loader + +[start=7] +. **Identifying the ESP** ++ +Identify the EFI System Partition (ESP) where the boot loader resides by executing the following command: ++ +[source,shell] +---- +efibootmgr -v +---- ++ +The output should be similar to the following: ++ +[source,shell] +---- + +Boot0000* FreeBSD HD(1,GPT,f859c46d-19ee-4e40-8975-3ad1ab00ac09,0x800,0x82000)/File(\EFI\freebsd\loader.efi) + nda0p1:/EFI/freebsd/loader.efi (null) +---- ++ +The active boot loader entry is preceded with a plus (+) character. +Note the location of the bootloader, in this case `EFI/freebsd/loader.efi` on `nda0p1`, though systems vary. ++ +. **Mounting the ESP** ++ +If the ESP is not already mounted at [.filename]#/boot/efi#, mount the partition listed in the `efibootmgr` output: ++ +[source,shell] +---- +mount_msdosfs /dev/nda0p1 /boot/efi +---- ++ +. **Install the Boot Loader** ++ +On AMD64 systems, upgrade the boot loader in the configured and default positions by executing the following commands: ++ +[source,shell] +---- +cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi +cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi +---- ++ +Note that some installations may not have `freebsd/loader.efi`. ++ +For AArch64 systems, execute the following commands instead: ++ +[source,shell] +---- +cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi +cp /boot/loader.efi /boot/efi/efi/boot/bootaa64.efi +---- ++ +Other architectures vary accordingly; consult man:loader.efi[8] if necessary. ++ +. **Finish** ++ +Reboot after completing the upgrade to FreeBSD {releaseCurrent}: ++ +[source,shell] +---- +shutdown -r +10min "Rebooting for a system upgrade" +---- + +[[upgrade-loader-bios]] +== Upgrading the BIOS Boot Loader + +For systems that boot via BIOS or UEFI CSM 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. + +[start=7] +. **Identify the freebsd-boot Partition** ++ +Identify the `freebsd-boot` device name and partition index by executing the following command: ++ +[source,shell] +---- +gpart show +---- ++ +The output should be similar to the following: ++ +[.screen] +---- + => 34 246162605 ada0 GPT (224G) + 34 1024 1 freebsd-boot (512K) +---- ++ +Note the name (`ada`) and index (`1`) of the `freebsd-boot` partition. ++ +. **Upgrade the Boot Loader** ++ +When using ZFS on BIOS, upgrade the bootcode by running the following command: ++ +[source,shell] +---- +gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 +---- ++ +Where `1` is the index of the `freebsd-boot` partition. ++ +If booting from a storage array, repeat this step for all disks in the pool. ++ +When using UFS on BIOS, execute the following command instead: ++ +[source,shell] +---- +gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0 +---- ++ +. **Finish** ++ +Reboot after completing the upgrade to FreeBSD {releaseCurrent}: ++ +[source,shell] +---- +shutdown -r now +---- +home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?6a307d54.43ba2.2b377b07>