freebsd-src/UPDATING

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$