Updating Information for FreeBSD current users.
This file is maintained and copyrighted by M. Warner Losh <imp@freebsd.org>.
See end of file for further details. For commonly done items, please see the
COMMON ITEMS: section later in the file. These instructions assume that you
basically know what you are doing. If not, then please consult the FreeBSD
handbook:
https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld
Items affecting the ports and packages system can be found in
/usr/ports/UPDATING. Please read that file before updating system packages
and/or ports.
NOTE TO PEOPLE WHO THINK THAT FreeBSD 14.x IS SLOW:
FreeBSD 14.x has many debugging features turned on, in both the kernel
and userland. These features attempt to detect incorrect use of
system primitives, and encourage loud failure through extra sanity
checking and fail stop semantics. They also substantially impact
system performance. If you want to do performance measurement,
benchmarking, and optimization, you'll want to turn them off. This
includes various WITNESS- related kernel options, INVARIANTS, malloc
debugging flags in userland, and various verbose features in the
kernel. Many developers choose to disable these features on build
machines to maximize performance. (To completely disable malloc
debugging, define WITH_MALLOC_PRODUCTION in /etc/src.conf and rebuild
world, or to merely disable the most expensive debugging functionality
at runtime, run "ln -s 'abort:false,junk:false' /etc/malloc.conf".)
20221121:
The WITHOUT_CLANG_IS_CC option has been removed. When Clang is enabled
it is always installed as /usr/bin/cc (and c++, cpp).
20221026:
Some programs have been moved into separate packages. It is recommended
for pkgbase users to do:
pkg install FreeBSD-dhclient FreeBSD-geom FreeBSD-resolvconf \
FreeBSD-devd FreeBSD-devmatch
after upgrading to restore all the component that were previously
installed.
20220610:
LinuxKPI pm.h changes require an update to the latest drm-kmod version
before re-compiling to avoid errors.
20211230:
The macros provided for the manipulation of CPU sets (e.g. CPU_AND)
have been modified to take 2 source arguments instead of only 1.
Externally maintained sources that use these macros will have to
be adapted. The FreeBSD version has been bumped to 1400046 to
reflect this change.
20211214:
A number of the kernel include files are able to be included by
themselves. A test has been added to buildworld to enforce this.
20211209:
Remove mips as a recognized target. This starts the decommissioning of
mips support in FreeBSD. mips related items will be removed wholesale in
the coming days and weeks.
This broke the NO_CLEAN build for some people. Either do a clean build
or touch
lib/clang/include/llvm/Config/Targets.def
lib/clang/include/llvm/Config/AsmParsers.def
lib/clang/include/llvm/Config/Disassemblers.def
lib/clang/include/llvm/Config/AsmPrinters.def
before the build to force everything to rebuild that needs to.
20211202:
Unbound support for RFC8375: The special-use domain 'home.arpa' is
by default blocked. To unblock it use a local-zone nodefault
statement in unbound.conf:
local-zone: "home.arpa." nodefault
Or use another type of local-zone to override with your choice.
The reason for this is discussed in Section 6.1 of RFC8375:
Because 'home.arpa.' is not globally scoped and cannot be secured
using DNSSEC based on the root domain's trust anchor, there is no way
to tell, using a standard DNS query, in which homenet scope an answer
belongs. Consequently, users may experience surprising results with
such names when roaming to different homenets.
20211110:
Commit b8d60729deef changed the TCP congestion control framework so
that any of the included congestion control modules could be
the single module built into the kernel. Previously newreno
was automatically built in through direct reference. As of
this commit you are required to declare at least one congestion
control module (e.g. 'options CC_NEWRENO') and to also declare a
default using the CC_DEFAULT option (e.g. options CC_DEFAULT="newreno\").
The GENERIC configuration includes CC_NEWRENO and defines newreno
as the default. If no congestion control option is built into the
kernel and you are including networking, the kernel compile will
fail. Also if no default is declared the kernel compile will fail.
20211118:
Mips has been removed from universe builds. It will be removed from the
tree shortly.
20211106:
Commit f0c9847a6c47 changed the arguments for VOP_ALLOCATE.
The NFS modules must be rebuilt from sources and any out
of tree file systems that implement their own VOP_ALLOCATE
may need to be modified.
20211022:
The synchronous PPP kernel driver sppp(4) has been removed.
The cp(4) and ce(4) drivers are now always compiled with netgraph(4)
support, formerly enabled by NETGRAPH_CRONYX option.
20211020:
sh(1) is now the default shell for the root user. To force root to use
the csh shell, please run the following command as root:
# chsh -s csh
20211004:
Ncurses distribution has been split between libtinfow and libncurses
with libncurses.so becoming a linker (ld) script to seamlessly link
to libtinfow as needed. Bump _FreeBSD_version to 1400035 to reflect
this change.
20210923:
As of commit 8160a0f62be6, the dummynet module no longer depends on the
ipfw module. Dummynet can now be used by pf as well as ipfw. As such
users who relied on this dependency may need to include ipfw in the
list of modules to load on their systems.
20210922:
As of commit 903873ce1560, the mixer(8) utility has got a slightly
new syntax. Please refer to the mixer(8) manual page for more
information. The old mixer utility can be installed from ports:
audio/freebsd-13-mixer
20210911:
As of commit 55089ef4f8bb, the global variable nfs_maxcopyrange has
been deleted from the nfscommon.ko. As such, nfsd.ko must be built
from up to date sources to avoid an undefined reference when
being loaded.
20210817:
As of commit 62ca9fc1ad56 OpenSSL no longer enables kernel TLS
by default. Users can enable kernel TLS via the "KTLS" SSL
option. This can be enabled globally by using a custom
OpenSSL config file via OPENSSL_CONF or via an
application-specific configuration option for applications
which permit setting SSL options via SSL_CONF_cmd(3).
20210811:
Commit 3ad1e1c1ce20 changed the internal KAPI between the NFS
modules. Therefore, all need to be rebuilt from sources.
20210730:
Commit b69019c14cd8 removes pf's DIOCGETSTATESNV ioctl.
As of be70c7a50d32 it is no longer used by userspace, but it does mean
users may not be able to enumerate pf states if they update the kernel
past b69019c14cd8 without first updating userspace past be70c7a50d32.
20210729:
As of commit 01ad0c007964 if_bridge member interfaces can no longer
change their MTU. Changing the MTU of the bridge itself will change the
MTU on all member interfaces instead.
20210716:
Commit ee29e6f31111 changed the internal KAPI between the nfscommon
and nfsd modules. Therefore, both need to be rebuilt from sources.
Bump __FreeBSD_version to 1400026 for this KAPI change.
20210715:
The 20210707 awk update brought in a change in behavior. This has
been corrected as of d4d252c49976. Between these dates, if you
installed a new awk binary, you may not be able to build a new
kernel because the change in behavior affected the genoffset
script used to build the kernel. If you did update, the fix is
to update your sources past the above hash and do
% cd usr.bin/awk
% make clean all
% sudo -E make install
to enable building kernels again.
20210708:
Commit 1e0a518d6548 changed the internal KAPI between the NFS
modules. They all need to be rebuilt from sources. I did not
bump __FreeBSD_version, since it was bumped recently.
20210707:
awk has been updated to the latest one-true-awk version 20210215.
This contains a number of minor bug fixes.
20210624:
The NFSv4 client now uses the highest minor version of NFSv4
supported by the NFSv4 server by default instead of minor version 0,
for NFSv4 mounts.
The "minorversion" mount option may be used to override this default.
20210618:
Bump __FreeBSD_version to 1400024 for LinuxKPI changes.
Most notably netdev.h can change now as the (last) dependencies
(mlx4/ofed) are now using struct ifnet directly, but also for PCI
additions and others.
20210618:
The directory "blacklisted" under /usr/share/certs/ has been
renamed to "untrusted".
20210611:
svnlite has been removed from base. Should you need svn for any reason
please install the svn package or port.
20210611:
Commit e1a907a25cfa changed the internal KAPI between the krpc
and nfsserver. As such, both modules must be rebuilt from
sources. Bump __FreeBSD_version to 1400022.
20210610:
The an(4) driver has been removed from FreeBSD.
20210608:
The vendor/openzfs branch was renamed to vendor/openzfs/legacy to
start tracking OpenZFS upstream more closely. Please see
https://lists.freebsd.org/archives/freebsd-current/2021-June/000153.html
for details on how to correct any errors that might result. The
short version is that you need to remove the old branch locally:
git update-ref -d refs/remotes/freebsd/vendor/openzfs
(assuming your upstream origin is named 'freebsd').
20210525:
Commits 17accc08ae15 and de102f870501 add new files to LinuxKPI
which break drm-kmod. In addition various other additions where
committed. Bump __FreeBSD_version to 1400015 to be able to
detect this.
20210513:
Commit ca179c4d74f2 changed the package in which the OpenSSL
libraries and utilities are packaged.
It is recommended for pkgbase user to do:
pkg install -f FreeBSD-openssl
before pkg upgrade otherwise some dependencies might not be met
and pkg will stop working as libssl will not be present anymore
on the system.
20210426:
Commit 875977314881 changed the internal KAPI between
the nfsd and nfscommon modules. As such these modules
need to be rebuilt from sources.
Without this patch in your NFSv4.1/4.2 server, enabling
delegations by setting vfs.nfsd.issue_delegations non-zero
is not recommended.
20210411:
Commit 7763814fc9c2 changed the internal KAPI between
the krpc and NFS. As such, the krpc, nfscommon and
nfscl modules must all be rebuilt from sources.
Without this patch, NFSv4.1/4.2 mounts should not
be done with the nfscbd(8) daemon running, to avoid
needing a working back channel for server->client RPCs.
20210330:
Commit 01ae8969a9ee fixed the NFSv4.1/4.2 server so that it
handles binding of the back channel as required by RFC5661.
Until this patch is in your server, avoid use of the "nconnects"
mount option for Linux NFSv4.1/4.2 mounts.
20210225:
For 64-bit architectures the base system is now built with Position
Independent Executable (PIE) support enabled by default. It may be
disabled using the WITHOUT_PIE knob. A clean build is required.
20210128:
Various LinuxKPI functionality was added which conflicts with DRM.
Please update your drm-kmod port to after the __FreeBSD_version 1400003
update.
COMMON ITEMS:
General Notes
-------------
Sometimes, obscure build problems are the result of environment
poisoning. This can happen because the make utility reads its
environment when searching for values for global variables. To run
your build attempts in an "environmental clean room", prefix all make
commands with 'env -i '. See the env(1) manual page for more details.
Occasionally a build failure will occur with "make -j" due to a race
condition. If this happens try building again without -j, and please
report a bug if it happens consistently.
When upgrading from one major version to another it is generally best to
upgrade to the latest code in the currently installed branch first, then
do an upgrade to the new branch. This is the best-tested upgrade path,
and has the highest probability of being successful. Please try this
approach if you encounter problems with a major version upgrade. Since
the stable 4.x branch point, one has generally been able to upgrade from
anywhere in the most recent stable branch to head / current (or even the
last couple of stable branches). See the top of this file when there's
an exception.
The update process will emit an error on an attempt to perform a build
or install from a FreeBSD version below the earliest supported version.
When updating from an older version the update should be performed one
major release at a time, including running `make delete-old` at each
step.
When upgrading a live system, having a root shell around before
installing anything can help undo problems. Not having a root shell
around can lead to problems if pam has changed too much from your
starting point to allow continued authentication after the upgrade.
This file should be read as a log of events. When a later event changes
information of a prior event, the prior event should not be deleted.
Instead, a pointer to the entry with the new information should be
placed in the old entry. Readers of this file should also sanity check
older entries before relying on them blindly. Authors of new entries
should write them with this in mind.
ZFS notes
---------
When upgrading the boot ZFS pool to a new version, always follow
these two steps:
1.) recompile and reinstall the ZFS boot loader and boot block
(this is part of "make buildworld" and "make installworld")
2.) update the ZFS boot block on your boot drive
The following example updates the ZFS boot block on the
freebsd-boot partition of a GPT partitioned drive ada0:
"gpart bootcode -p /boot/gptzfsboot -i $N ada0"
The value $N will typically be 1 (if booting from BIOS) or 2 (if
booting from EFI).
Non-boot pools do not need these updates.
To build a kernel
-----------------
If you are updating from a prior version of FreeBSD (even one just
a few days old), you should follow this procedure. It is the most
failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
make kernel-toolchain
make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
To test a kernel once
---------------------
If you just want to boot a kernel once (because you are not sure
if it works, or if you want to boot a known bad kernel to provide
debugging information) run
make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
nextboot -k testkernel
To rebuild everything and install it on the current system.
-----------------------------------------------------------
# Note: sometimes if you are running current you gotta do more than
# is listed here if you are upgrading from a really old current.
<make sure you have good level 0 dumps>
make buildworld
make buildkernel KERNCONF=YOUR_KERNEL_HERE
make installkernel KERNCONF=YOUR_KERNEL_HERE
[1]
<reboot in single user> [3]
etcupdate -p [5]
make installworld
etcupdate -B [4]
make delete-old [6]
<reboot>
To cross-install current onto a separate partition
--------------------------------------------------
# In this approach we use a separate partition to hold
# current's root, 'usr', and 'var' directories. A partition
# holding "/", "/usr" and "/var" should be about 2GB in
# size.
<make sure you have good level 0 dumps>
<boot into -stable>
make buildworld
make buildkernel KERNCONF=YOUR_KERNEL_HERE
<maybe newfs current's root partition>
<mount current's root partition on directory ${CURRENT_ROOT}>
make installworld DESTDIR=${CURRENT_ROOT} -DDB_FROM_SRC
make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
cp /etc/fstab ${CURRENT_ROOT}/etc/fstab # if newfs'd
<edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
<reboot into current>
<do a "native" rebuild/install as described in the previous section>
<maybe install compatibility libraries from ports/misc/compat*>
<reboot>
To upgrade in-place from stable to current
----------------------------------------------
<make sure you have good level 0 dumps>
make buildworld [9]
make buildkernel KERNCONF=YOUR_KERNEL_HERE [8]
make installkernel KERNCONF=YOUR_KERNEL_HERE
[1]
<reboot in single user> [3]
etcupdate -p [5]
make installworld
etcupdate -B [4]
make delete-old [6]
<reboot>
Make sure that you've read the UPDATING file to understand the
tweaks to various things you need. At this point in the life
cycle of current, things change often and you are on your own
to cope. The defaults can also change, so please read ALL of
the UPDATING entries.
Also, if you are tracking -current, you must be subscribed to
freebsd-current@freebsd.org. Make sure that before you update
your sources that you have read and understood all the recent
messages there. If in doubt, please track -stable which has
much fewer pitfalls.
[1] If you have third party modules, such as vmware, you should disable
them at this point so they don't crash your system on
reboot. Alternatively, you should rebuild all the modules you have in
your system and install them as well. If you are running -current, you
should seriously consider placing all sources to all the modules for
your system (or symlinks to them) in /usr/local/sys/modules so this
happens automatically. If all your modules come from ports, then adding
the port origin directories to PORTS_MODULES instead is also automatic
and effective, eg:
PORTS_MODULES+=x11/nvidia-driver
[3] From the bootblocks, boot -s, and then do
fsck -p
mount -u /
mount -a
sh /etc/rc.d/zfs start # mount zfs filesystem, if needed
cd src # full path to source
adjkerntz -i # if CMOS is wall time
Also, when doing a major release upgrade, it is required that you boot
into single user mode to do the installworld.
[4] Note: This step is non-optional. Failure to do this step
can result in a significant reduction in the functionality of the
system. Attempting to do it by hand is not recommended and those
that pursue this avenue should read this file carefully, as well
as the archives of freebsd-current and freebsd-hackers mailing lists
for potential gotchas. See etcupdate(8) for more information.
[5] Usually this step is a no-op. However, from time to time
you may need to do this if you get unknown user in the following
step.
[6] This only deletes old files and directories. Old libraries
can be deleted by "make delete-old-libs", but you have to make
sure that no program is using those libraries anymore.
[8] The new kernel must be able to run existing binaries used by an
installworld. When upgrading across major versions, the new kernel's
configuration must include the correct COMPAT_FREEBSD<n> option for
existing binaries (e.g. COMPAT_FREEBSD11 to run 11.x binaries). Failure
to do so may leave you with a system that is hard to boot to recover. A
GENERIC kernel will include suitable compatibility options to run
binaries from older branches. Note that the ability to run binaries
from unsupported branches is not guaranteed.
Make sure that you merge any new devices from GENERIC since the
last time you updated your kernel config file. Options also
change over time, so you may need to adjust your custom kernels
for these as well.
[9] If CPUTYPE is defined in your /etc/make.conf, make sure to use the
"?=" instead of the "=" assignment operator, so that buildworld can
override the CPUTYPE if it needs to.
MAKEOBJDIRPREFIX must be defined in an environment variable, and
not on the command line, or in /etc/make.conf. buildworld will
warn if it is improperly defined.
FORMAT:
This file contains a list, in reverse chronological order, of major
breakages in tracking -current. It is not guaranteed to be a complete
list of such breakages, and only contains entries since September 23, 2011.
If you need to see UPDATING entries from before that date, you will need
to fetch an UPDATING file from an older FreeBSD release.
Copyright information:
Copyright 1998-2009 M. Warner Losh <imp@FreeBSD.org>
Redistribution, publication, translation and use, with or without
modification, in full or in part, in any form or format of this
document are permitted without further permission from the author.
THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Contact Warner Losh if you have any questions about your use of
this document.
$FreeBSD$