xref: /freebsd/UPDATING (revision f93d92f43d984c1d927c7c12d06ae1497d12deea)
1Updating Information for FreeBSD current users.
2
3This file is maintained and copyrighted by M. Warner Losh <imp@freebsd.org>.
4See end of file for further details.  For commonly done items, please see the
5COMMON ITEMS: section later in the file.  These instructions assume that you
6basically know what you are doing.  If not, then please consult the FreeBSD
7handbook:
8
9    https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld
10
11Items affecting the ports and packages system can be found in
12/usr/ports/UPDATING.  Please read that file before updating system packages
13and/or ports.
14
15NOTE TO PEOPLE WHO THINK THAT FreeBSD 14.x IS SLOW:
16	FreeBSD 14.x has many debugging features turned on, in both the kernel
17	and userland.  These features attempt to detect incorrect use of
18	system primitives, and encourage loud failure through extra sanity
19	checking and fail stop semantics.  They also substantially impact
20	system performance.  If you want to do performance measurement,
21	benchmarking, and optimization, you'll want to turn them off.  This
22	includes various WITNESS- related kernel options, INVARIANTS, malloc
23	debugging flags in userland, and various verbose features in the
24	kernel.  Many developers choose to disable these features on build
25	machines to maximize performance.  (To completely disable malloc
26	debugging, define WITH_MALLOC_PRODUCTION in /etc/src.conf and rebuild
27	world, or to merely disable the most expensive debugging functionality
28	at runtime, run "ln -s 'abort:false,junk:false' /etc/malloc.conf".)
29
3020221121:
31	The WITHOUT_CLANG_IS_CC option has been removed.  When Clang is enabled
32	it is always installed as /usr/bin/cc (and c++, cpp).
33
3420221026:
35	Some programs have been moved into separate packages. It is recommended
36	for pkgbase users to do:
37
38	pkg install FreeBSD-dhclient FreeBSD-geom FreeBSD-resolvconf \
39	  FreeBSD-devd FreeBSD-devmatch
40
41	after upgrading to restore all the component that were previously
42	installed.
43
4420220610:
45	LinuxKPI pm.h changes require an update to the latest drm-kmod version
46	before re-compiling to avoid errors.
47
4820211230:
49	The macros provided for the manipulation of CPU sets (e.g. CPU_AND)
50	have been modified to take 2 source arguments instead of only 1.
51	Externally maintained sources that use these macros will have to
52	be adapted. The FreeBSD version has been bumped to 1400046 to
53	reflect this change.
54
5520211214:
56	A number of the kernel include files are able to be included by
57	themselves.  A test has been added to buildworld to enforce this.
58
5920211209:
60	Remove mips as a recognized target. This starts the decommissioning of
61	mips support in FreeBSD. mips related items will be removed wholesale in
62	the coming days and weeks.
63
64	This broke the NO_CLEAN build for some people. Either do a clean build
65	or touch
66		lib/clang/include/llvm/Config/Targets.def
67		lib/clang/include/llvm/Config/AsmParsers.def
68		lib/clang/include/llvm/Config/Disassemblers.def
69		lib/clang/include/llvm/Config/AsmPrinters.def
70	before the build to force everything to rebuild that needs to.
71
7220211202:
73	Unbound support for RFC8375: The special-use domain 'home.arpa' is
74	by default blocked. To unblock it use a local-zone nodefault
75	statement in unbound.conf:
76		local-zone: "home.arpa." nodefault
77
78	Or use another type of local-zone to override with your choice.
79
80	The reason for this is discussed in Section 6.1 of RFC8375:
81	Because 'home.arpa.' is not globally scoped and cannot be secured
82	using DNSSEC based on the root domain's trust anchor, there is no way
83	to tell, using a standard DNS query, in which homenet scope an answer
84	belongs.  Consequently, users may experience surprising results with
85	such names when roaming to different homenets.
86
8720211110:
88	Commit b8d60729deef changed the TCP congestion control framework so
89	that any of the included congestion control modules could be
90	the single module built into the kernel. Previously newreno
91	was automatically built in through direct reference. As of
92	this commit you are required to declare at least one congestion
93	control module (e.g. 'options CC_NEWRENO') and to also declare a
94	default using the CC_DEFAULT option (e.g. options CC_DEFAULT="newreno\").
95	The GENERIC configuration includes CC_NEWRENO and defines newreno
96	as the default. If no congestion control option is built into the
97	kernel and you are including networking, the kernel compile will
98	fail. Also if no default is declared the kernel compile will fail.
99
10020211118:
101	Mips has been removed from universe builds. It will be removed from the
102	tree shortly.
103
10420211106:
105	Commit f0c9847a6c47 changed the arguments for VOP_ALLOCATE.
106	The NFS modules must be rebuilt from sources and any out
107	of tree file systems that implement their own VOP_ALLOCATE
108	may need to be modified.
109
11020211022:
111	The synchronous PPP kernel driver sppp(4) has been removed.
112	The cp(4) and ce(4) drivers are now always compiled with netgraph(4)
113	support, formerly enabled by NETGRAPH_CRONYX option.
114
11520211020:
116	sh(1) is now the default shell for the root user.  To force root to use
117	the csh shell, please run the following command as root:
118
119	# chsh -s csh
120
12120211004:
122	Ncurses distribution has been split between libtinfow and libncurses
123	with libncurses.so becoming a linker (ld) script to seamlessly link
124	to libtinfow as needed. Bump _FreeBSD_version to 1400035 to reflect
125	this change.
126
12720210923:
128	As of commit 8160a0f62be6, the dummynet module no longer depends on the
129	ipfw module. Dummynet can now be used by pf as well as ipfw. As such
130	users who relied on this dependency may need to include ipfw in the
131	list of modules to load on their systems.
132
13320210922:
134	As of commit 903873ce1560, the mixer(8) utility has got a slightly
135	new syntax. Please refer to the mixer(8) manual page for more
136	information. The old mixer utility can be installed from ports:
137	audio/freebsd-13-mixer
138
13920210911:
140	As of commit 55089ef4f8bb, the global variable nfs_maxcopyrange has
141	been deleted from the nfscommon.ko.  As such, nfsd.ko must be built
142	from up to date sources to avoid an undefined reference when
143	being loaded.
144
14520210817:
146	As of commit 62ca9fc1ad56 OpenSSL no longer enables kernel TLS
147	by default.  Users can enable kernel TLS via the "KTLS" SSL
148	option.  This can be enabled globally by using a custom
149	OpenSSL config file via OPENSSL_CONF or via an
150	application-specific configuration option for applications
151	which permit setting SSL options via SSL_CONF_cmd(3).
152
15320210811:
154	Commit 3ad1e1c1ce20 changed the internal KAPI between the NFS
155	modules. Therefore, all need to be rebuilt from sources.
156
15720210730:
158	Commit b69019c14cd8 removes pf's DIOCGETSTATESNV ioctl.
159	As of be70c7a50d32 it is no longer used by userspace, but it does mean
160	users may not be able to enumerate pf states if they update the kernel
161	past b69019c14cd8 without first updating userspace past be70c7a50d32.
162
16320210729:
164	As of commit 01ad0c007964 if_bridge member interfaces can no longer
165	change their MTU. Changing the MTU of the bridge itself will change the
166	MTU on all member interfaces instead.
167
16820210716:
169	Commit ee29e6f31111 changed the internal KAPI between the nfscommon
170	and nfsd modules. Therefore, both need to be rebuilt from sources.
171	Bump __FreeBSD_version to 1400026 for this KAPI change.
172
17320210715:
174	The 20210707 awk update brought in a change in behavior. This has
175	been corrected as of d4d252c49976. Between these dates, if you
176	installed a new awk binary, you may not be able to build a new
177	kernel because the change in behavior affected the genoffset
178	script used to build the kernel. If you did update, the fix is
179	to update your sources past the above hash and do
180		% cd usr.bin/awk
181		% make clean all
182		% sudo -E make install
183	to enable building kernels again.
184
18520210708:
186	Commit 1e0a518d6548 changed the internal KAPI between the NFS
187	modules. They all need to be rebuilt from sources.  I did not
188	bump __FreeBSD_version, since it was bumped recently.
189
19020210707:
191	awk has been updated to the latest one-true-awk version 20210215.
192	This contains a number of minor bug fixes.
193
19420210624:
195	The NFSv4 client now uses the highest minor version of NFSv4
196	supported by the NFSv4 server by default instead of minor version 0,
197	for NFSv4 mounts.
198	The "minorversion" mount option may be used to override this default.
199
20020210618:
201	Bump __FreeBSD_version to 1400024 for LinuxKPI changes.
202	Most notably netdev.h can change now as the (last) dependencies
203	(mlx4/ofed) are now using struct ifnet directly, but also for PCI
204	additions and others.
205
20620210618:
207	The directory "blacklisted" under /usr/share/certs/ has been
208	renamed to "untrusted".
209
21020210611:
211	svnlite has been removed from base. Should you need svn for any reason
212	please install the svn package or port.
213
21420210611:
215	Commit e1a907a25cfa changed the internal KAPI between the krpc
216	and nfsserver.  As such, both modules must be rebuilt from
217	sources.  Bump __FreeBSD_version to 1400022.
218
21920210610:
220	The an(4) driver has been removed from FreeBSD.
221
22220210608:
223	The vendor/openzfs branch was renamed to vendor/openzfs/legacy to
224	start tracking OpenZFS upstream more closely. Please see
225https://lists.freebsd.org/archives/freebsd-current/2021-June/000153.html
226	for details on how to correct any errors that might result. The
227	short version is that you need to remove the old branch locally:
228	    git update-ref -d refs/remotes/freebsd/vendor/openzfs
229	(assuming your upstream origin is named 'freebsd').
230
23120210525:
232	Commits 17accc08ae15 and de102f870501 add new files to LinuxKPI
233	which break drm-kmod.  In addition various other additions where
234	committed. Bump __FreeBSD_version to 1400015 to be able to
235	detect this.
236
23720210513:
238	Commit ca179c4d74f2 changed the package in which the OpenSSL
239	libraries and utilities are packaged.
240	It is recommended for pkgbase user to do:
241	pkg install -f FreeBSD-openssl
242	before pkg upgrade otherwise some dependencies might not be met
243	and pkg will stop working as libssl will not be present anymore
244	on the system.
245
24620210426:
247	Commit 875977314881 changed the internal KAPI between
248	the nfsd and nfscommon modules.  As such these modules
249	need to be rebuilt from sources.
250	Without this patch in your NFSv4.1/4.2 server, enabling
251	delegations by setting vfs.nfsd.issue_delegations non-zero
252	is not recommended.
253
25420210411:
255	Commit 7763814fc9c2 changed the internal KAPI between
256	the krpc and NFS.  As such, the krpc, nfscommon and
257	nfscl modules must all be rebuilt from sources.
258	Without this patch, NFSv4.1/4.2 mounts should not
259	be done with the nfscbd(8) daemon running, to avoid
260	needing a working back channel for server->client RPCs.
261
26220210330:
263	Commit 01ae8969a9ee fixed the NFSv4.1/4.2 server so that it
264	handles binding of the back channel as required by RFC5661.
265	Until this patch is in your server, avoid use of the "nconnects"
266	mount option for Linux NFSv4.1/4.2 mounts.
267
26820210225:
269	For 64-bit architectures the base system is now built with Position
270	Independent Executable (PIE) support enabled by default.  It may be
271	disabled using the WITHOUT_PIE knob.  A clean build is required.
272
27320210128:
274	Various LinuxKPI functionality was added which conflicts with DRM.
275	Please update your drm-kmod port to after the __FreeBSD_version 1400003
276	update.
277
278COMMON ITEMS:
279
280	General Notes
281	-------------
282	Sometimes, obscure build problems are the result of environment
283	poisoning.  This can happen because the make utility reads its
284	environment when searching for values for global variables.  To run
285	your build attempts in an "environmental clean room", prefix all make
286	commands with 'env -i '.  See the env(1) manual page for more details.
287	Occasionally a build failure will occur with "make -j" due to a race
288	condition.  If this happens try building again without -j, and please
289	report a bug if it happens consistently.
290
291	When upgrading from one major version to another it is generally best to
292	upgrade to the latest code in the currently installed branch first, then
293	do an upgrade to the new branch. This is the best-tested upgrade path,
294	and has the highest probability of being successful.  Please try this
295	approach if you encounter problems with a major version upgrade.  Since
296	the stable 4.x branch point, one has generally been able to upgrade from
297	anywhere in the most recent stable branch to head / current (or even the
298	last couple of stable branches). See the top of this file when there's
299	an exception.
300
301	The update process will emit an error on an attempt to perform a build
302	or install from a FreeBSD version below the earliest supported version.
303	When updating from an older version the update should be performed one
304	major release at a time, including running `make delete-old` at each
305	step.
306
307	When upgrading a live system, having a root shell around before
308	installing anything can help undo problems. Not having a root shell
309	around can lead to problems if pam has changed too much from your
310	starting point to allow continued authentication after the upgrade.
311
312	This file should be read as a log of events. When a later event changes
313	information of a prior event, the prior event should not be deleted.
314	Instead, a pointer to the entry with the new information should be
315	placed in the old entry. Readers of this file should also sanity check
316	older entries before relying on them blindly. Authors of new entries
317	should write them with this in mind.
318
319	ZFS notes
320	---------
321	When upgrading the boot ZFS pool to a new version, always follow
322	these two steps:
323
324	1.) recompile and reinstall the ZFS boot loader and boot block
325	(this is part of "make buildworld" and "make installworld")
326
327	2.) update the ZFS boot block on your boot drive
328
329	The following example updates the ZFS boot block on the
330	freebsd-boot partition of a GPT partitioned drive ada0:
331	"gpart bootcode -p /boot/gptzfsboot -i $N ada0"
332	The value $N will typically be 1 (if booting from BIOS) or 2 (if
333	booting from EFI).
334
335	Non-boot pools do not need these updates.
336
337	To build a kernel
338	-----------------
339	If you are updating from a prior version of FreeBSD (even one just
340	a few days old), you should follow this procedure.  It is the most
341	failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
342
343	make kernel-toolchain
344	make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
345	make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
346
347	To test a kernel once
348	---------------------
349	If you just want to boot a kernel once (because you are not sure
350	if it works, or if you want to boot a known bad kernel to provide
351	debugging information) run
352	make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
353	nextboot -k testkernel
354
355	To rebuild everything and install it on the current system.
356	-----------------------------------------------------------
357	# Note: sometimes if you are running current you gotta do more than
358	# is listed here if you are upgrading from a really old current.
359
360	<make sure you have good level 0 dumps>
361	make buildworld
362	make buildkernel KERNCONF=YOUR_KERNEL_HERE
363	make installkernel KERNCONF=YOUR_KERNEL_HERE
364							[1]
365	<reboot in single user>				[3]
366	etcupdate -p					[5]
367	make installworld
368	etcupdate -B					[4]
369	make delete-old					[6]
370	<reboot>
371
372	To cross-install current onto a separate partition
373	--------------------------------------------------
374	# In this approach we use a separate partition to hold
375	# current's root, 'usr', and 'var' directories.   A partition
376	# holding "/", "/usr" and "/var" should be about 2GB in
377	# size.
378
379	<make sure you have good level 0 dumps>
380	<boot into -stable>
381	make buildworld
382	make buildkernel KERNCONF=YOUR_KERNEL_HERE
383	<maybe newfs current's root partition>
384	<mount current's root partition on directory ${CURRENT_ROOT}>
385	make installworld DESTDIR=${CURRENT_ROOT} -DDB_FROM_SRC
386	make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
387	make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
388	cp /etc/fstab ${CURRENT_ROOT}/etc/fstab 		   # if newfs'd
389	<edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
390	<reboot into current>
391	<do a "native" rebuild/install as described in the previous section>
392	<maybe install compatibility libraries from ports/misc/compat*>
393	<reboot>
394
395
396	To upgrade in-place from stable to current
397	----------------------------------------------
398	<make sure you have good level 0 dumps>
399	make buildworld					[9]
400	make buildkernel KERNCONF=YOUR_KERNEL_HERE	[8]
401	make installkernel KERNCONF=YOUR_KERNEL_HERE
402							[1]
403	<reboot in single user>				[3]
404	etcupdate -p					[5]
405	make installworld
406	etcupdate -B					[4]
407	make delete-old					[6]
408	<reboot>
409
410	Make sure that you've read the UPDATING file to understand the
411	tweaks to various things you need.  At this point in the life
412	cycle of current, things change often and you are on your own
413	to cope.  The defaults can also change, so please read ALL of
414	the UPDATING entries.
415
416	Also, if you are tracking -current, you must be subscribed to
417	freebsd-current@freebsd.org.  Make sure that before you update
418	your sources that you have read and understood all the recent
419	messages there.  If in doubt, please track -stable which has
420	much fewer pitfalls.
421
422	[1] If you have third party modules, such as vmware, you should disable
423	them at this point so they don't crash your system on
424	reboot. Alternatively, you should rebuild all the modules you have in
425	your system and install them as well.  If you are running -current, you
426	should seriously consider placing all sources to all the modules for
427	your system (or symlinks to them) in /usr/local/sys/modules so this
428	happens automatically. If all your modules come from ports, then adding
429	the port origin directories to PORTS_MODULES instead is also automatic
430	and effective, eg:
431	     PORTS_MODULES+=x11/nvidia-driver
432
433	[3] From the bootblocks, boot -s, and then do
434		fsck -p
435		mount -u /
436		mount -a
437		sh /etc/rc.d/zfs start	# mount zfs filesystem, if needed
438		cd src			# full path to source
439		adjkerntz -i		# if CMOS is wall time
440	Also, when doing a major release upgrade, it is required that you boot
441	into single user mode to do the installworld.
442
443	[4] Note: This step is non-optional.  Failure to do this step
444	can result in a significant reduction in the functionality of the
445	system.  Attempting to do it by hand is not recommended and those
446	that pursue this avenue should read this file carefully, as well
447	as the archives of freebsd-current and freebsd-hackers mailing lists
448	for potential gotchas.  See etcupdate(8) for more information.
449
450	[5] Usually this step is a no-op.  However, from time to time
451	you may need to do this if you get unknown user in the following
452	step.
453
454	[6] This only deletes old files and directories. Old libraries
455	can be deleted by "make delete-old-libs", but you have to make
456	sure that no program is using those libraries anymore.
457
458	[8] The new kernel must be able to run existing binaries used by an
459	installworld.  When upgrading across major versions, the new kernel's
460	configuration must include the correct COMPAT_FREEBSD<n> option for
461	existing binaries (e.g. COMPAT_FREEBSD11 to run 11.x binaries).  Failure
462	to do so may leave you with a system that is hard to boot to recover. A
463	GENERIC kernel will include suitable compatibility options to run
464	binaries from older branches.  Note that the ability to run binaries
465	from unsupported branches is not guaranteed.
466
467	Make sure that you merge any new devices from GENERIC since the
468	last time you updated your kernel config file. Options also
469	change over time, so you may need to adjust your custom kernels
470	for these as well.
471
472	[9] If CPUTYPE is defined in your /etc/make.conf, make sure to use the
473	"?=" instead of the "=" assignment operator, so that buildworld can
474	override the CPUTYPE if it needs to.
475
476	MAKEOBJDIRPREFIX must be defined in an environment variable, and
477	not on the command line, or in /etc/make.conf.  buildworld will
478	warn if it is improperly defined.
479FORMAT:
480
481This file contains a list, in reverse chronological order, of major
482breakages in tracking -current.  It is not guaranteed to be a complete
483list of such breakages, and only contains entries since September 23, 2011.
484If you need to see UPDATING entries from before that date, you will need
485to fetch an UPDATING file from an older FreeBSD release.
486
487Copyright information:
488
489Copyright 1998-2009 M. Warner Losh <imp@FreeBSD.org>
490
491Redistribution, publication, translation and use, with or without
492modification, in full or in part, in any form or format of this
493document are permitted without further permission from the author.
494
495THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
496IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
497WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
498DISCLAIMED.  IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
499INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
500(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
501SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
502HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
503STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
504IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
505POSSIBILITY OF SUCH DAMAGE.
506
507Contact Warner Losh if you have any questions about your use of
508this document.
509
510$FreeBSD$
511