xref: /freebsd/UPDATING (revision 4410e857965edef0e3be42ae323356ec08d2aaad)
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
3020230113:
31	LinuxKPI pci.h changes may require out-of-tree drivers to be recompiled.
32	Bump _FreeBSD_version to 1400078 to be able to detect this change.
33
3420221212:
35	llvm-objump is now always installed as objdump.  Previously there was
36	no /usr/bin/objdump unless the WITH_LLVM_BINUTILS knob was used.
37
38	Some LLVM objdump options have a different output format compared to
39	GNU objdump; readelf is available for inspecting ELF files, and GNU
40	objdump is available from the devel/binutils port or package.
41
4220221205:
43	dma(8) has replaced sendmail(8) as the default mta.  For people willing
44	to reenable sendmail(8):
45
46	$ cp /usr/share/examples/sendmail/mailer.conf /etc/mail/mailer.conf
47
48	and add sendmail_enable="YES" to rc.conf.
49
5020221204:
51	hw.bus.disable_failed_devices has changed from 'false' to 'true' by
52	default. Now if newbus succeeds in probing a device, but fails to attach
53	the device, we'll disable the device. In the past, we'd keep retrying
54	the device on each new driver loaded. To get that behavior now, one
55	needs to use devctl to re-enable the device, and reprobe it (or set
56	the sysctl/tunable hw.bus.disable_failed_devices=false).
57
58	NOTE: This was reverted 20221205 due to unexpected compatibility issues
59
6020221122:
61	pf no longer accepts 'scrub fragment crop' or 'scrub fragment drop-ovl'.
62	These configurations are no longer automatically reinterpreted as
63	'scrub fragment reassemble'.
64
6520221121:
66	The WITHOUT_CLANG_IS_CC option has been removed.  When Clang is enabled
67	it is always installed as /usr/bin/cc (and c++, cpp).
68
6920221026:
70	Some programs have been moved into separate packages. It is recommended
71	for pkgbase users to do:
72
73	pkg install FreeBSD-dhclient FreeBSD-geom FreeBSD-resolvconf \
74	  FreeBSD-devd FreeBSD-devmatch
75
76	after upgrading to restore all the component that were previously
77	installed.
78
7920220610:
80	LinuxKPI pm.h changes require an update to the latest drm-kmod version
81	before re-compiling to avoid errors.
82
8320211230:
84	The macros provided for the manipulation of CPU sets (e.g. CPU_AND)
85	have been modified to take 2 source arguments instead of only 1.
86	Externally maintained sources that use these macros will have to
87	be adapted. The FreeBSD version has been bumped to 1400046 to
88	reflect this change.
89
9020211214:
91	A number of the kernel include files are able to be included by
92	themselves.  A test has been added to buildworld to enforce this.
93
9420211209:
95	Remove mips as a recognized target. This starts the decommissioning of
96	mips support in FreeBSD. mips related items will be removed wholesale in
97	the coming days and weeks.
98
99	This broke the NO_CLEAN build for some people. Either do a clean build
100	or touch
101		lib/clang/include/llvm/Config/Targets.def
102		lib/clang/include/llvm/Config/AsmParsers.def
103		lib/clang/include/llvm/Config/Disassemblers.def
104		lib/clang/include/llvm/Config/AsmPrinters.def
105	before the build to force everything to rebuild that needs to.
106
10720211202:
108	Unbound support for RFC8375: The special-use domain 'home.arpa' is
109	by default blocked. To unblock it use a local-zone nodefault
110	statement in unbound.conf:
111		local-zone: "home.arpa." nodefault
112
113	Or use another type of local-zone to override with your choice.
114
115	The reason for this is discussed in Section 6.1 of RFC8375:
116	Because 'home.arpa.' is not globally scoped and cannot be secured
117	using DNSSEC based on the root domain's trust anchor, there is no way
118	to tell, using a standard DNS query, in which homenet scope an answer
119	belongs.  Consequently, users may experience surprising results with
120	such names when roaming to different homenets.
121
12220211110:
123	Commit b8d60729deef changed the TCP congestion control framework so
124	that any of the included congestion control modules could be
125	the single module built into the kernel. Previously newreno
126	was automatically built in through direct reference. As of
127	this commit you are required to declare at least one congestion
128	control module (e.g. 'options CC_NEWRENO') and to also declare a
129	default using the CC_DEFAULT option (e.g. options CC_DEFAULT="newreno\").
130	The GENERIC configuration includes CC_NEWRENO and defines newreno
131	as the default. If no congestion control option is built into the
132	kernel and you are including networking, the kernel compile will
133	fail. Also if no default is declared the kernel compile will fail.
134
13520211118:
136	Mips has been removed from universe builds. It will be removed from the
137	tree shortly.
138
13920211106:
140	Commit f0c9847a6c47 changed the arguments for VOP_ALLOCATE.
141	The NFS modules must be rebuilt from sources and any out
142	of tree file systems that implement their own VOP_ALLOCATE
143	may need to be modified.
144
14520211022:
146	The synchronous PPP kernel driver sppp(4) has been removed.
147	The cp(4) and ce(4) drivers are now always compiled with netgraph(4)
148	support, formerly enabled by NETGRAPH_CRONYX option.
149
15020211020:
151	sh(1) is now the default shell for the root user.  To force root to use
152	the csh shell, please run the following command as root:
153
154	# chsh -s csh
155
15620211004:
157	Ncurses distribution has been split between libtinfow and libncurses
158	with libncurses.so becoming a linker (ld) script to seamlessly link
159	to libtinfow as needed. Bump _FreeBSD_version to 1400035 to reflect
160	this change.
161
16220210923:
163	As of commit 8160a0f62be6, the dummynet module no longer depends on the
164	ipfw module. Dummynet can now be used by pf as well as ipfw. As such
165	users who relied on this dependency may need to include ipfw in the
166	list of modules to load on their systems.
167
16820210922:
169	As of commit 903873ce1560, the mixer(8) utility has got a slightly
170	new syntax. Please refer to the mixer(8) manual page for more
171	information. The old mixer utility can be installed from ports:
172	audio/freebsd-13-mixer
173
17420210911:
175	As of commit 55089ef4f8bb, the global variable nfs_maxcopyrange has
176	been deleted from the nfscommon.ko.  As such, nfsd.ko must be built
177	from up to date sources to avoid an undefined reference when
178	being loaded.
179
18020210817:
181	As of commit 62ca9fc1ad56 OpenSSL no longer enables kernel TLS
182	by default.  Users can enable kernel TLS via the "KTLS" SSL
183	option.  This can be enabled globally by using a custom
184	OpenSSL config file via OPENSSL_CONF or via an
185	application-specific configuration option for applications
186	which permit setting SSL options via SSL_CONF_cmd(3).
187
18820210811:
189	Commit 3ad1e1c1ce20 changed the internal KAPI between the NFS
190	modules. Therefore, all need to be rebuilt from sources.
191
19220210730:
193	Commit b69019c14cd8 removes pf's DIOCGETSTATESNV ioctl.
194	As of be70c7a50d32 it is no longer used by userspace, but it does mean
195	users may not be able to enumerate pf states if they update the kernel
196	past b69019c14cd8 without first updating userspace past be70c7a50d32.
197
19820210729:
199	As of commit 01ad0c007964 if_bridge member interfaces can no longer
200	change their MTU. Changing the MTU of the bridge itself will change the
201	MTU on all member interfaces instead.
202
20320210716:
204	Commit ee29e6f31111 changed the internal KAPI between the nfscommon
205	and nfsd modules. Therefore, both need to be rebuilt from sources.
206	Bump __FreeBSD_version to 1400026 for this KAPI change.
207
20820210715:
209	The 20210707 awk update brought in a change in behavior. This has
210	been corrected as of d4d252c49976. Between these dates, if you
211	installed a new awk binary, you may not be able to build a new
212	kernel because the change in behavior affected the genoffset
213	script used to build the kernel. If you did update, the fix is
214	to update your sources past the above hash and do
215		% cd usr.bin/awk
216		% make clean all
217		% sudo -E make install
218	to enable building kernels again.
219
22020210708:
221	Commit 1e0a518d6548 changed the internal KAPI between the NFS
222	modules. They all need to be rebuilt from sources.  I did not
223	bump __FreeBSD_version, since it was bumped recently.
224
22520210707:
226	awk has been updated to the latest one-true-awk version 20210215.
227	This contains a number of minor bug fixes.
228
22920210624:
230	The NFSv4 client now uses the highest minor version of NFSv4
231	supported by the NFSv4 server by default instead of minor version 0,
232	for NFSv4 mounts.
233	The "minorversion" mount option may be used to override this default.
234
23520210618:
236	Bump __FreeBSD_version to 1400024 for LinuxKPI changes.
237	Most notably netdev.h can change now as the (last) dependencies
238	(mlx4/ofed) are now using struct ifnet directly, but also for PCI
239	additions and others.
240
24120210618:
242	The directory "blacklisted" under /usr/share/certs/ has been
243	renamed to "untrusted".
244
24520210611:
246	svnlite has been removed from base. Should you need svn for any reason
247	please install the svn package or port.
248
24920210611:
250	Commit e1a907a25cfa changed the internal KAPI between the krpc
251	and nfsserver.  As such, both modules must be rebuilt from
252	sources.  Bump __FreeBSD_version to 1400022.
253
25420210610:
255	The an(4) driver has been removed from FreeBSD.
256
25720210608:
258	The vendor/openzfs branch was renamed to vendor/openzfs/legacy to
259	start tracking OpenZFS upstream more closely. Please see
260https://lists.freebsd.org/archives/freebsd-current/2021-June/000153.html
261	for details on how to correct any errors that might result. The
262	short version is that you need to remove the old branch locally:
263	    git update-ref -d refs/remotes/freebsd/vendor/openzfs
264	(assuming your upstream origin is named 'freebsd').
265
26620210525:
267	Commits 17accc08ae15 and de102f870501 add new files to LinuxKPI
268	which break drm-kmod.  In addition various other additions where
269	committed. Bump __FreeBSD_version to 1400015 to be able to
270	detect this.
271
27220210513:
273	Commit ca179c4d74f2 changed the package in which the OpenSSL
274	libraries and utilities are packaged.
275	It is recommended for pkgbase user to do:
276	pkg install -f FreeBSD-openssl
277	before pkg upgrade otherwise some dependencies might not be met
278	and pkg will stop working as libssl will not be present anymore
279	on the system.
280
28120210426:
282	Commit 875977314881 changed the internal KAPI between
283	the nfsd and nfscommon modules.  As such these modules
284	need to be rebuilt from sources.
285	Without this patch in your NFSv4.1/4.2 server, enabling
286	delegations by setting vfs.nfsd.issue_delegations non-zero
287	is not recommended.
288
28920210411:
290	Commit 7763814fc9c2 changed the internal KAPI between
291	the krpc and NFS.  As such, the krpc, nfscommon and
292	nfscl modules must all be rebuilt from sources.
293	Without this patch, NFSv4.1/4.2 mounts should not
294	be done with the nfscbd(8) daemon running, to avoid
295	needing a working back channel for server->client RPCs.
296
29720210330:
298	Commit 01ae8969a9ee fixed the NFSv4.1/4.2 server so that it
299	handles binding of the back channel as required by RFC5661.
300	Until this patch is in your server, avoid use of the "nconnects"
301	mount option for Linux NFSv4.1/4.2 mounts.
302
30320210225:
304	For 64-bit architectures the base system is now built with Position
305	Independent Executable (PIE) support enabled by default.  It may be
306	disabled using the WITHOUT_PIE knob.  A clean build is required.
307
30820210128:
309	Various LinuxKPI functionality was added which conflicts with DRM.
310	Please update your drm-kmod port to after the __FreeBSD_version 1400003
311	update.
312
31320210108:
314	PC Card attachments for all devices have been removed. In the case of
315	wi and cmx, the entire drivers were removed because they were only
316	PC Card devices. FreeBSD_version 1300134 should be used for this
317	since it was bumped so recently.
318
31920210107:
320	Transport-independent parts of HID support have been split off the USB
321	code in to separate subsystem.  Kernel configs which include one of
322	ums, ukbd, uhid, atp, wsp, wmt, uaudio, ugold or ucycom drivers should
323	be updated with adding of "device hid" line.
324
32520210105:
326	ncurses installation has been modified to only keep the widechar
327	enabled version.  Incremental build is broken for that change, so it
328	requires a clean build.
329
33020201223:
331	The FreeBSD project has migrated from Subversion to Git. Temporary
332	instructions can be found at
333	https://github.com/bsdimp/freebsd-git-docs/blob/main/src-cvt.md
334	and other documents in that repo.
335
33620201216:
337	The services database has been updated to cover more of the basic
338	services expected in a modern system. The database is big enough
339	that it will cause issues in mergemaster in Releases previous to
340	12.2 and 11.3, or in very old current systems from before r358154.
341
34220201215:
343	Obsolete in-tree GDB 6.1.1 has been removed.  GDB (including kgdb)
344	may be installed from ports or packages.
345
34620201124:
347	ping6 has been merged into ping.  It can now be called as "ping -6".
348	See ping(8) for details.
349
35020201108:
351	Default value of net.add_addr_allfibs has been changed to 0.
352	If you have multi-fib configuration and rely on existence of all
353	interface routes in every fib, you need to set the above sysctl to 1.
354
35520201030:
356	The internal pre-processor in the calendar(1) program has been
357	extended to support more C pre-processor commands (e.g. #ifdef, #else,
358	and #undef) and to detect unbalanced conditional statements.
359	Error messages have been extended to include the filename and line
360	number if processing stops to help fixing malformed data files.
361
36220201026:
363	All the data files for the calendar(1) program, except calendar.freebsd,
364	have been moved to the deskutils/calendar-data port, much like the
365	jewish calendar entries were moved to deskutils/hebcal years ago. After
366	make delete-old-files, you need to install it to retain full
367	functionality. calendar(1) will issue a reminder for files it can't
368	find.
369
37020200923:
371	LINT files are no longer generated. We now include the relevant NOTES
372	files. Note: This may cause conflicts with updating in some cases.
373	        find sys -name LINT\* -delete
374	is suggested across this commit	to remove the generated	LINT files.
375
376	If you have tried to update with generated files there, the svn
377	command you want to un-auger the tree is
378		cd sys/amd64/conf
379		svn revert -R .
380	and then do the above find from the top level. Substitute 'amd64'
381	above with where the error message indicates a conflict.
382
38320200824:
384	OpenZFS support has been integrated. Do not upgrade root pools until
385	the loader is updated to support zstd. Furthermore, we caution against
386	'zpool upgrade' for the next few weeks. The change should be transparent
387	unless you  want to use new features.
388
389	Not all "NO_CLEAN" build scenarios work across these changes. Many
390	scenarios have been tested and fixed, but rebuilding kernels without
391	rebuilding world may fail.
392
393	The ZFS cache file has moved from /boot to /etc to match the OpenZFS
394	upstream default. A fallback to /boot has been added for mountroot.
395
396	Pool auto import behavior at boot has been moved from the kernel module
397	to an explicit "zpool import -a" in one of the rc scripts enabled by
398	zfs_enable=YES. This means your non-root zpools won't auto import until
399	you upgrade your /etc/rc.d files.
400
40120200824:
402	The resume code now notifies devd with the 'kernel' system
403	rather than the old 'kern' subsystem to be consistent with
404	other use. The old notification will be created as well, but
405	will be removed prior to FreeBSD 14.0.
406
40720200821:
408	r362275 changed the internal API between the kernel RPC and the
409	NFS modules. As such, all the modules must be recompiled from
410	sources.
411
41220200817:
413	r364330 modified the internal API used between the NFS modules.
414	As such, all the NFS modules must be re-compiled from sources.
415
41620200816:
417	Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have
418	been upgraded to 11.0.0.  Please see the 20141231 entry below for
419	information about prerequisites and upgrading, if you are not already
420	using clang 3.5.0 or higher.
421
42220200810:
423	r364092 modified the internal ABI used between the kernel NFS
424	modules.  As such, all of these modules need to be rebuilt
425	from sources, so a version bump was done.
426
42720200807:
428	Makefile.inc has been updated to work around the issue documented in
429	20200729. It was a case where the optimization of using symbolic links
430	to point to binaries created a situation where we'd run new binaries
431	with old libraries starting midway through the installworld process.
432
43320200729:
434	r363679 has redefined some undefined behavior in regcomp(3); notably,
435	extraneous escapes of most ordinary characters will no longer be
436	accepted.  An exp-run has identified all of the problems with this in
437	ports, but other non-ports software may need extra escapes removed to
438	continue to function.
439
440	Because of this change, installworld may encounter the following error
441	from rtld: Undefined symbol "regcomp@FBSD_1.6" -- It is imperative that
442	you do not halt installworld. Instead, let it run to completion (whether
443	successful or not) and run installworld once more.
444
44520200627:
446	A new implementation of bc and dc has been imported in r362681. This
447	implementation corrects non-conformant behavior of the previous bc
448	and adds GNU bc compatible options. It offers a number of extensions,
449	is much faster on large values, and has support for message catalogs
450	(a number of languages are already supported, contributions of further
451	languages welcome). The option WITHOUT_GH_BC can be used to build the
452	world with the previous versions of bc and dc.
453
45420200625:
455	r362639 changed the internal API used between the NFS kernel modules.
456	As such, they all need to be rebuilt from sources.
457
45820200613:
459	r362158 changed the arguments for VFS_CHECKEXP().  As such, any
460	out of tree file systems need to be modified and rebuilt.
461	Also, any file systems that are modules must be rebuilt.
462
46320200604:
464	read(2) of a directory fd is now rejected by default.  root may
465	re-enable it for system root only on non-ZFS filesystems with the
466	security.bsd.allow_read_dir sysctl(8) MIB if
467	security.bsd.suser_enabled=1.
468
469	It may be advised to setup aliases for grep to default to `-d skip` if
470	commonly non-recursively grepping a list that includes directories and
471	the potential for the resulting stderr output is not tolerable.  Example
472	aliases are now installed, commented out, in /root/.cshrc and
473	/root/.shrc.
474
47520200523:
476	Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have
477	been upgraded to 10.0.1.  Please see the 20141231 entry below for
478	information about prerequisites and upgrading, if you are not already
479	using clang 3.5.0 or higher.
480
48120200512:
482	Support for obsolete compilers has been removed from the build system.
483	Clang 6 and GCC 6.4 are the minimum supported versions.
484
48520200424:
486	closefrom(2) has been moved under COMPAT12, and replaced in libc with a
487	stub that calls close_range(2).  If using a custom kernel configuration,
488	you may want to ensure that the COMPAT_FREEBSD12 option is included, as
489	a slightly older -CURRENT userland and older FreeBSD userlands may not
490	be functional without closefrom(2).
491
49220200414:
493	Upstream DTS from Linux 5.6 was merged and they now have the SID
494	and THS (Secure ID controller and THermal Sensor) node present.
495	The DTB overlays have now been removed from the tree for the H3/H5 and
496	A64 SoCs and the aw_sid and aw_thermal driver have been updated to
497	deal with upstream DTS. If you are using those overlays you need to
498	remove them from loader.conf and update the DTBs on the FAT partition.
499
50020200310:
501	Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have
502	been upgraded to 10.0.0.  Please see the 20141231 entry below for
503	information about prerequisites and upgrading, if you are not already
504	using clang 3.5.0 or higher.
505
50620200309:
507	The amd(8) automount daemon has been removed from the source tree.
508	As of FreeBSD 10.1 autofs(5) is the preferred tool for automounting.
509	amd is still available in the sysutils/am-utils port.
510
51120200301:
512	Removed brooktree driver (bktr.4) from the tree.
513
51420200229:
515	The WITH_GPL_DTC option has been removed.  The BSD-licenced device tree
516	compiler in usr.bin/dtc is used on all architectures which use dtc, and
517	the GPL dtc is available (if needed) from the sysutils/dtc port.
518
51920200229:
520	The WITHOUT_LLVM_LIBUNWIND option has been removed.  LLVM's libunwind
521	is used by all supported CPU architectures.
522
52320200229:
524	GCC 4.2.1 has been removed from the tree.  The WITH_GCC,
525	WITH_GCC_BOOTSTRAP, and WITH_GNUCXX options are no longer available.
526	Users who wish to build FreeBSD with GCC must use the external toolchain
527	ports or packages.
528
52920200220:
530	ncurses has been updated to a newer version (6.2-20200215). Given the ABI
531	has changed, users will have to rebuild all the ports that are linked to
532	ncurses.
533
53420200217:
535	The size of struct vnet and the magic cookie have changed.
536	Users need to recompile libkvm and all modules using VIMAGE
537	together with their new kernel.
538
53920200212:
540	Defining the long deprecated NO_CTF, NO_DEBUG_FILES, NO_INSTALLLIB,
541	NO_MAN, NO_PROFILE, and NO_WARNS variables is now an error.  Update
542	your Makefiles and scripts to define MK_<var>=no instead as required.
543
544	One exception to this is that program or library Makefiles should
545	define MAN to empty rather than setting MK_MAN=no.
546
54720200108:
548	Clang/LLVM is now the default compiler and LLD the default
549	linker for riscv64.
550
55120200107:
552	make universe no longer uses GCC 4.2.1 on any architectures.
553	Architectures not supported by in-tree Clang/LLVM require an
554	external toolchain package.
555
55620200104:
557	GCC 4.2.1 is now not built by default, as part of the GCC 4.2.1
558	retirement plan.  Specifically, the GCC, GCC_BOOTSTRAP, and GNUCXX
559	options default to off for all supported CPU architectures.  As a
560	short-term transition aid they may be enabled via WITH_* options.
561	GCC 4.2.1 is expected to be removed from the tree on 2020-03-31.
562
56320200102:
564	Support for armv5 has been disconnected and is being removed. The
565	machine combination MACHINE=arm MACHINE_ARCH=arm is no longer valid.
566	You must now use a MACHINE_ARCH of armv6 or armv7. The default
567	MACHINE_ARCH for MACHINE=arm is now armv7.
568
56920191226:
570	Clang/LLVM is now the default compiler for all powerpc architectures.
571	LLD is now the default linker for powerpc64.  The change for powerpc64
572	also includes a change to the ELFv2 ABI, incompatible with the existing
573	ABI.
574
57520191226:
576	Kernel-loadable random(4) modules are no longer unloadable.
577
57820191222:
579	Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have
580	been upgraded to 9.0.1.  Please see the 20141231 entry below for
581	information about prerequisites and upgrading, if you are not already
582	using clang 3.5.0 or higher.
583
58420191212:
585	r355677 has modified the internal interface used between the
586	NFS modules in the kernel. As such, they must all be upgraded
587	simultaneously. I will do a version bump for this.
588
58920191205:
590	The root certificates of the Mozilla CA Certificate Store have been
591	imported into the base system and can be managed with the certctl(8)
592	utility.  If you have installed the security/ca_root_nss port or package
593	with the ETCSYMLINK option (the default), be advised that there may be
594	differences between those included in the port and those included in
595	base due to differences in nss branch used as well as general update
596	frequency.  Note also that certctl(8) cannot manage certs in the
597	format used by the security/ca_root_nss port.
598
59920191120:
600	The amd(8) automount daemon has been disabled by default, and will be
601	removed in the future.  As of FreeBSD 10.1 the autofs(5) is available
602	for automounting.
603
60420191107:
605	The nctgpio and wbwd drivers have been moved to the superio bus.
606	If you have one of these drivers in a kernel configuration, then
607	you should add device superio to it.  If you use one of these drivers
608	as a module and you compile a custom set of modules, then you should
609	add superio to the set.
610
61120191021:
612	KPIs for network drivers to access interface addresses have changed.
613	Users need to recompile NIC driver modules together with kernel.
614
61520191021:
616	The net.link.tap.user_open sysctl no longer prevents user opening of
617	already created /dev/tapNN devices.  Access is still controlled by
618	node permissions, just like tun devices.  The net.link.tap.user_open
619	sysctl is now used only to allow users to perform devfs cloning of
620	tap devices, and the subsequent open may not succeed if the user is not
621	in the appropriate group.  This sysctl may be deprecated/removed
622	completely in the future.
623
62420191009:
625	mips, powerpc, and sparc64 are no longer built as part of
626	universe / tinderbox unless MAKE_OBSOLETE_GCC is defined. If
627	not defined, mips, powerpc, and sparc64 builds will look for
628	the xtoolchain binaries and if installed use them for universe
629	builds. As llvm 9.0 becomes vetted for these architectures, they
630	will be removed from the list.
631
63220191009:
633	Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have
634	been upgraded to 9.0.0.  Please see the 20141231 entry below for
635	information about prerequisites and upgrading, if you are not already
636	using clang 3.5.0 or higher.
637
63820191003:
639	The hpt27xx, hptmv, hptnr, and hptrr drivers have been removed from
640	GENERIC.  They are available as modules and can be loaded by adding
641	to /boot/loader.conf hpt27xx_load="YES", hptmv_load="YES",
642	hptnr_load="YES", or hptrr_load="YES", respectively.
643
64420190913:
645	ntpd no longer by default locks its pages in memory, allowing them
646	to be paged out by the kernel. Use rlimit memlock to restore
647	historic BSD behaviour. For example, add "rlimit memlock 32"
648	to ntp.conf to lock up to 32 MB of ntpd address space in memory.
649
65020190823:
651	Several of ping6's options have been renamed for better consistency
652	with ping.  If you use any of -ARWXaghmrtwx, you must update your
653	scripts.  See ping6(8) for details.
654
65520190727:
656	The vfs.fusefs.sync_unmount and vfs.fusefs.init_backgrounded sysctls
657	and the "-o sync_unmount" and "-o init_backgrounded" mount options have
658	been removed from mount_fusefs(8).  You can safely remove them from
659	your scripts, because they had no effect.
660
661	The vfs.fusefs.fix_broken_io, vfs.fusefs.sync_resize,
662	vfs.fusefs.refresh_size, vfs.fusefs.mmap_enable,
663	vfs.fusefs.reclaim_revoked, and vfs.fusefs.data_cache_invalidate
664	sysctls have been removed.  If you felt the need to set any of them to
665	a non-default value, please tell asomers@FreeBSD.org why.
666
66720190713:
668	Default permissions on the /var/account/acct file (and copies of it
669	rotated by periodic daily scripts) are changed from 0644 to 0640
670	because the file contains sensitive information that should not be
671	world-readable.  If the /var/account directory must be created by
672	rc.d/accounting, the mode used is now 0750.  Admins who use the
673	accounting feature are encouraged to change the mode of an existing
674	/var/account directory to 0750 or 0700.
675
67620190620:
677	Entropy collection and the /dev/random device are no longer optional
678	components.  The "device random" option has been removed.
679	Implementations of distilling algorithms can still be made loadable
680	with "options RANDOM_LOADABLE" (e.g., random_fortuna.ko).
681
68220190612:
683	Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have
684	been upgraded to 8.0.1.  Please see the 20141231 entry below for
685	information about prerequisites and upgrading, if you are not already
686	using clang 3.5.0 or higher.
687
68820190608:
689	A fix was applied to i386 kernel modules to avoid panics with
690	dpcpu or vnet.  Users need to recompile i386 kernel modules
691	having pcpu or vnet sections or they will refuse to load.
692
69320190513:
694	User-wired pages now have their own counter,
695	vm.stats.vm.v_user_wire_count.  The vm.max_wired sysctl was renamed
696	to vm.max_user_wired and changed from an unsigned int to an unsigned
697	long.  bhyve VMs wired with the -S are now subject to the user
698	wiring limit; the vm.max_user_wired sysctl may need to be tuned to
699	avoid running into the limit.
700
70120190507:
702	The IPSEC option has been removed from GENERIC.  Users requiring
703	ipsec(4) must now load the ipsec(4) kernel module.
704
70520190507:
706	The tap(4) driver has been folded into tun(4), and the module has been
707	renamed to tuntap.  You should update any kld_list="if_tap" or
708	kld_list="if_tun" entries in /etc/rc.conf, if_tap_load="YES" or
709	if_tun_load="YES" entries in /boot/loader.conf to load the if_tuntap
710	module instead, and "device tap" or "device tun" entries in kernel
711	config files to select the tuntap device instead.
712
71320190418:
714	The following knobs have been added related to tradeoffs between
715	safe use of the random device and availability in the absence of
716	entropy:
717
718	kern.random.initial_seeding.bypass_before_seeding: tunable; set
719	non-zero to bypass the random device prior to seeding, or zero to
720	block random requests until the random device is initially seeded.
721	For now, set to 1 (unsafe) by default to restore pre-r346250 boot
722	availability properties.
723
724	kern.random.initial_seeding.read_random_bypassed_before_seeding:
725	read-only diagnostic sysctl that is set when bypass is enabled and
726	read_random(9) is bypassed, to enable programmatic handling of this
727	initial condition, if desired.
728
729	kern.random.initial_seeding.arc4random_bypassed_before_seeding:
730	Similar to the above, but for arc4random(9) initial seeding.
731
732	kern.random.initial_seeding.disable_bypass_warnings: tunable; set
733	non-zero to disable warnings in dmesg when the same conditions are
734	met as for the diagnostic sysctls above.  Defaults to zero, i.e.,
735	produce warnings in dmesg when the conditions are met.
736
73720190416:
738	The loadable random module KPI has changed; the random_infra_init()
739	routine now requires a 3rd function pointer for a bool (*)(void)
740	method that returns true if the random device is seeded (and
741	therefore unblocked).
742
74320190404:
744	r345895 reverts r320698. This implies that an nfsuserd(8) daemon
745	built from head sources between r320757 (July 6, 2017) and
746	r338192 (Aug. 22, 2018) will not work unless the "-use-udpsock"
747	is added to the command line.
748	nfsuserd daemons built from head sources that are post-r338192 are
749	not affected and should continue to work.
750
75120190320:
752	The fuse(4) module has been renamed to fusefs(4) for consistency with
753	other filesystems.  You should update any kld_load="fuse" entries in
754	/etc/rc.conf, fuse_load="YES" entries in /boot/loader.conf, and
755	"options FUSE" entries in kernel config files.
756
75720190304:
758	Clang, llvm, lld, lldb, compiler-rt and libc++ have been upgraded to
759	8.0.0.  Please see the 20141231 entry below for information about
760	prerequisites and upgrading, if you are not already using clang 3.5.0
761	or higher.
762
76320190226:
764	geom_uzip(4) depends on the new module xz.  If geom_uzip is statically
765	compiled into your custom kernel, add 'device xz' statement to the
766	kernel config.
767
76820190219:
769	drm and drm2 have been removed from the tree. Please see
770	https://wiki.freebsd.org/Graphics for the latest information on
771	migrating to the drm ports.
772
77320190131:
774	Iflib is no longer unconditionally compiled into the kernel.  Drivers
775	using iflib and statically compiled into the kernel, now require
776	the 'device iflib' config option.  For the same drivers loaded as
777	modules on kernels not having 'device iflib', the iflib.ko module
778	is loaded automatically.
779
78020190125:
781	The IEEE80211_AMPDU_AGE and AH_SUPPORT_AR5416 kernel configuration
782	options no longer exist since r343219 and r343427 respectively;
783	nothing uses them, so they should be just removed from custom
784	kernel config files.
785
78620181230:
787	r342635 changes the way efibootmgr(8) works by requiring users to add
788	the -b (bootnum) parameter for commands where the bootnum was previously
789	specified with each option. For example 'efibootmgr -B 0001' is now
790	'efibootmgr -B -b 0001'.
791
79220181220:
793	r342286 modifies the NFSv4 server so that it obeys vfs.nfsd.nfs_privport
794	in the same as it is applied to NFSv2 and 3.  This implies that NFSv4
795	servers that have vfs.nfsd.nfs_privport set will only allow mounts
796	from clients using a reserved port. Since both the FreeBSD and Linux
797	NFSv4 clients use reserved ports by default, this should not affect
798	most NFSv4 mounts.
799
80020181219:
801	The XLP config has been removed. We can't support 64-bit atomics in this
802	kernel because it is running in 32-bit mode. XLP users must transition
803	to running a 64-bit kernel (XLP64 or XLPN32).
804
805	The mips GXEMUL support has been removed from FreeBSD. MALTA* + qemu is
806	the preferred emulator today and we don't need two different ones.
807
808	The old sibyte / swarm / Broadcom BCM1250 support has been
809	removed from the mips port.
810
81120181211:
812	Clang, llvm, lld, lldb, compiler-rt and libc++ have been upgraded to
813	7.0.1.  Please see the 20141231 entry below for information about
814	prerequisites and upgrading, if you are not already using clang 3.5.0
815	or higher.
816
81720181211:
818	Remove the timed and netdate programs from the base tree.  Setting
819	the time with these daemons has been obsolete for over a decade.
820
82120181126:
822	On amd64, arm64 and armv7 (architectures that install LLVM's ld.lld
823	linker as /usr/bin/ld) GNU ld is no longer installed as ld.bfd, as
824	it produces broken binaries when ifuncs are in use.  Users needing
825	GNU ld should install the binutils port or package.
826
82720181123:
828	The BSD crtbegin and crtend code has been enabled by default. It has
829	had extensive testing on amd64, arm64, and i386. It can be disabled
830	by building a world with -DWITHOUT_BSD_CRTBEGIN.
831
83220181115:
833	The set of CTM commands (ctm, ctm_smail, ctm_rmail, ctm_dequeue)
834	has been converted to a port (misc/ctm) and will be removed from
835	FreeBSD-13.  It is available as a package (ctm) for all supported
836	FreeBSD versions.
837
83820181110:
839	The default newsyslog.conf(5) file has been changed to only include
840	files in /etc/newsyslog.conf.d/ and /usr/local/etc/newsyslog.conf.d/ if
841	the filenames end in '.conf' and do not begin with a '.'.
842
843	You should check the configuration files in these two directories match
844	this naming convention. You can verify which configuration files are
845	being included using the command:
846		$ newsyslog -Nrv
847
84820181015:
849	Ports for the DRM modules have been simplified. Now, amd64 users should
850	just install the drm-kmod port. All others should install
851	drm-legacy-kmod.
852
853	Graphics hardware that's newer than about 2010 usually works with
854	drm-kmod.  For hardware older than 2013, however, some users will need
855	to use drm-legacy-kmod if drm-kmod doesn't work for them. Hardware older
856	than 2008 usually only works in drm-legacy-kmod. The graphics team can
857	only commit to hardware made since 2013 due to the complexity of the
858	market and difficulty to test all the older cards effectively. If you
859	have hardware supported by drm-kmod, you are strongly encouraged to use
860	that as you will get better support.
861
862	Other than KPI chasing, drm-legacy-kmod will not be updated. As outlined
863	elsewhere, the drm and drm2 modules will be eliminated from the src base
864	soon (with a limited exception for arm). Please update to the package
865	asap and report any issues to x11@freebsd.org.
866
867	Generally, anybody using the drm*-kmod packages should add
868	WITHOUT_DRM_MODULE=t and WITHOUT_DRM2_MODULE=t to avoid nasty
869	cross-threading surprises, especially with automatic driver
870	loading from X11 startup. These will become the defaults in 13-current
871	shortly.
872
87320181012:
874	The ixlv(4) driver has been renamed to iavf(4).  As a consequence,
875	custom kernel and module loading configuration files must be updated
876	accordingly.  Moreover, interfaces previous presented as ixlvN to the
877	system are now exposed as iavfN and network configuration files must
878	be adjusted as necessary.
879
88020181009:
881	OpenSSL has been updated to version 1.1.1.  This update included
882	additional various API changes throughout the base system.  It is
883	important to rebuild third-party software after upgrading.  The value
884	of __FreeBSD_version has been bumped accordingly.
885
88620181006:
887	The legacy DRM modules and drivers have now been added to the loader's
888	module blacklist, in favor of loading them with kld_list in rc.conf(5).
889	The module blacklist may be overridden with the loader.conf(5)
890	'module_blacklist' variable, but loading them via rc.conf(5) is strongly
891	encouraged.
892
89320181002:
894	The cam(4) based nda(4) driver will be used over nvd(4) by default on
895	powerpc64. You may set 'options NVME_USE_NVD=1' in your kernel conf or
896	loader tunable 'hw.nvme.use_nvd=1' if you wish to use the existing
897	driver.  Make sure to edit /boot/etc/kboot.conf and fstab to use the
898	nda device name.
899
90020180913:
901	Reproducible build mode is now on by default, in preparation for
902	FreeBSD 12.0.  This eliminates build metadata such as the user,
903	host, and time from the kernel (and uname), unless the working tree
904	corresponds to a modified checkout from a version control system.
905	The previous behavior can be obtained by setting the /etc/src.conf
906	knob WITHOUT_REPRODUCIBLE_BUILD.
907
90820180826:
909	The Yarrow CSPRNG has been removed from the kernel as it has not been
910	supported by its designers since at least 2003. Fortuna has been the
911	default since FreeBSD-11.
912
91320180822:
914	devctl freeze/thaw have gone into the tree, the rc scripts have been
915	updated to use them and devmatch has been changed.  You should update
916	kernel, userland and rc scripts all at the same time.
917
91820180818:
919	The default interpreter has been switched from 4th to Lua.
920	LOADER_DEFAULT_INTERP, documented in build(7), will override the default
921	interpreter.  If you have custom FORTH code you will need to set
922	LOADER_DEFAULT_INTERP=4th (valid values are 4th, lua or simp) in
923	src.conf for the build.  This will create default hard links between
924	loader and loader_4th instead of loader and loader_lua, the new default.
925	If you are using UEFI it will create the proper hard link to loader.efi.
926
927	bhyve uses userboot.so. It remains 4th-only until some issues are solved
928	regarding coexisting with multiple versions of FreeBSD are resolved.
929
93020180815:
931	ls(1) now respects the COLORTERM environment variable used in other
932	systems and software to indicate that a colored terminal is both
933	supported and desired.  If ls(1) is suddenly emitting colors, they may
934	be disabled again by either removing the unwanted COLORTERM from your
935	environment, or using `ls --color=never`.  The ls(1) specific CLICOLOR
936	may not be observed in a future release.
937
93820180808:
939	The default pager for most commands has been changed to "less".  To
940	restore the old behavior, set PAGER="more" and MANPAGER="more -s" in
941	your environment.
942
94320180731:
944	The jedec_ts(4) driver has been removed. A superset of its functionality
945	is available in the jedec_dimm(4) driver, and the manpage for that
946	driver includes migration instructions. If you have "device jedec_ts"
947	in your kernel configuration file, it must be removed.
948
94920180730:
950	amd64/GENERIC now has EFI runtime services, EFIRT, enabled by default.
951	This should have no effect if the kernel is booted via BIOS/legacy boot.
952	EFIRT may be disabled via a loader tunable, efi.rt.disabled, if a system
953	has a buggy firmware that prevents a successful boot due to use of
954	runtime services.
955
95620180727:
957	Atmel AT91RM9200 and AT91SAM9, Cavium CNS 11xx and XScale
958	support has been removed from the tree. These ports were
959	obsolete and/or known to be broken for many years.
960
96120180723:
962	loader.efi has been augmented to participate more fully in the
963	UEFI boot manager protocol. loader.efi will now look at the
964	BootXXXX environment variable to determine if a specific kernel
965	or root partition was specified. XXXX is derived from BootCurrent.
966	efibootmgr(8) manages these standard UEFI variables.
967
96820180720:
969	zfsloader's functionality has now been folded into loader.
970	zfsloader is no longer necessary once you've updated your
971	boot blocks. For a transition period, we will install a
972	hardlink for zfsloader to loader to allow a smooth transition
973	until the boot blocks can be updated (hard link because old
974	zfs boot blocks don't understand symlinks).
975
97620180719:
977	ARM64 now have efifb support, if you want to have serial console
978	on your arm64 board when an screen is connected and the bootloader
979	setup a frame buffer for us to use, just add :
980	boot_serial=YES
981	boot_multicons=YES
982	in /boot/loader.conf
983	For Raspberry Pi 3 (RPI) users, this is needed even if you don't have
984	an screen connected as the firmware will setup a frame buffer are that
985	u-boot will expose as an EFI frame buffer.
986
98720180719:
988	New uid:gid added, ntpd:ntpd (123:123).  Be sure to run mergemaster
989	or take steps to update /etc/passwd before doing installworld on
990	existing systems.  Do not skip the "mergemaster -Fp" step before
991	installworld, as described in the update procedures near the bottom
992	of this document.  Also, rc.d/ntpd now starts ntpd(8) as user ntpd
993	if the new mac_ntpd(4) policy is available, unless ntpd_flags or
994	the ntp config file contain options that change file/dir locations.
995	When such options (e.g., "statsdir" or "crypto") are used, ntpd can
996	still be run as non-root by setting ntpd_user=ntpd in rc.conf, after
997	taking steps to ensure that all required files/dirs are accessible
998	by the ntpd user.
999
100020180717:
1001	Big endian arm support has been removed.
1002
100320180711:
1004	The static environment setup in kernel configs is no longer mutually
1005	exclusive with the loader(8) environment by default.  In order to
1006	restore the previous default behavior of disabling the loader(8)
1007	environment if a static environment is present, you must specify
1008	loader_env.disabled=1 in the static environment.
1009
101020180705:
1011	The ABI of syscalls used by management tools like sockstat and
1012	netstat has been broken to allow 32-bit binaries to work on
1013	64-bit kernels without modification.  These programs will need
1014	to match the kernel in order to function.  External programs may
1015	require minor modifications to accommodate a change of type in
1016	structures from pointers to 64-bit virtual addresses.
1017
101820180702:
1019	On i386 and amd64 atomics are now inlined. Out of tree modules using
1020	atomics will need to be rebuilt.
1021
102220180701:
1023	The '%I' format in the kern.corefile sysctl limits the number of
1024	core files that a process can generate to the number stored in the
1025	debug.ncores sysctl. The '%I' format is replaced by the single digit
1026	index. Previously, if all indexes were taken the kernel would overwrite
1027	only a core file with the highest index in a filename.
1028	Currently the system will create a new core file if there is a free
1029	index or if all slots are taken it will overwrite the oldest one.
1030
103120180630:
1032	Clang, llvm, lld, lldb, compiler-rt and libc++ have been upgraded to
1033	6.0.1.  Please see the 20141231 entry below for information about
1034	prerequisites and upgrading, if you are not already using clang 3.5.0
1035	or higher.
1036
103720180628:
1038	r335753 introduced a new quoting method. However, etc/devd/devmatch.conf
1039	needed to be changed to work with it. This change was made with r335763
1040	and requires a mergemaster / etcupdate / etc to update the installed
1041	file.
1042
104320180612:
1044	r334930 changed the interface between the NFS modules, so they all
1045	need to be rebuilt.  r335018 did a __FreeBSD_version bump for this.
1046
104720180530:
1048	As of r334391 lld is the default amd64 system linker; it is installed
1049	as /usr/bin/ld.  Kernel build workarounds (see 20180510 entry) are no
1050	longer necessary.
1051
105220180530:
1053	The kernel / userland interface for devinfo changed, so you'll
1054	need a new kernel and userland as a pair for it to work (rebuilding
1055	lib/libdevinfo is all that's required). devinfo and devmatch will
1056	not work, but everything else will when there's a mismatch.
1057
105820180523:
1059	The on-disk format for hwpmc callchain records has changed to include
1060	threadid corresponding to a given record. This changes the field offsets
1061	and thus requires that libpmcstat be rebuilt before using a kernel
1062	later than r334108.
1063
106420180517:
1065	The vxge(4) driver has been removed.  This driver was introduced into
1066	HEAD one week before the Exar left the Ethernet market and is not
1067	known to be used.  If you have device vxge in your kernel config file
1068	it must be removed.
1069
107020180510:
1071	The amd64 kernel now requires a ld that supports ifunc to produce a
1072	working kernel, either lld or a newer binutils. lld is built by default
1073	on amd64, and the 'buildkernel' target uses it automatically. However,
1074	it is not the default linker, so building the kernel the traditional
1075	way requires LD=ld.lld on the command line (or LD=/usr/local/bin/ld for
1076	binutils port/package). lld will soon be default, and this requirement
1077	will go away.
1078
1079	NOTE: As of r334391 lld is the default system linker on amd64, and no
1080	workaround is necessary.
1081
108220180508:
1083	The nxge(4) driver has been removed.  This driver was for PCI-X 10g
1084	cards made by s2io/Neterion.  The company was acquired by Exar and
1085	no longer sells or supports Ethernet products.  If you have device
1086	nxge in your kernel config file it must be removed.
1087
108820180504:
1089	The tz database (tzdb) has been updated to 2018e.  This version more
1090	correctly models time stamps in time zones with negative DST such as
1091	Europe/Dublin (from 1971 on), Europe/Prague (1946/7), and
1092	Africa/Windhoek (1994/2017).  This does not affect the UT offsets, only
1093	time zone abbreviations and the tm_isdst flag.
1094
109520180502:
1096	The ixgb(4) driver has been removed.  This driver was for an early and
1097	uncommon legacy PCI 10GbE for a single ASIC, Intel 82597EX. Intel
1098	quickly shifted to the long lived ixgbe family.  If you have device
1099	ixgb in your kernel config file it must be removed.
1100
110120180501:
1102	The lmc(4) driver has been removed.  This was a WAN interface
1103	card that was already reportedly rare in 2003, and had an ambiguous
1104	license.  If you have device lmc in your kernel config file it must
1105	be removed.
1106
110720180413:
1108	Support for Arcnet networks has been removed.  If you have device
1109	arcnet or device cm in your kernel config file they must be
1110	removed.
1111
111220180411:
1113	Support for FDDI networks has been removed.  If you have device
1114	fddi or device fpa in your kernel config file they must be
1115	removed.
1116
111720180406:
1118	In addition to supporting RFC 3164 formatted messages, the
1119	syslogd(8) service is now capable of parsing RFC 5424 formatted
1120	log messages. The main benefit of using RFC 5424 is that clients
1121	may now send log messages with timestamps containing year numbers,
1122	microseconds and time zone offsets.
1123
1124	Similarly, the syslog(3) C library function has been altered to
1125	send RFC 5424 formatted messages to the local system logging
1126	daemon. On systems using syslogd(8), this change should have no
1127	negative impact, as long as syslogd(8) and the C library are
1128	updated at the same time. On systems using a different system
1129	logging daemon, it may be necessary to make configuration
1130	adjustments, depending on the software used.
1131
1132	When using syslog-ng, add the 'syslog-protocol' flag to local
1133	input sources to enable parsing of RFC 5424 formatted messages:
1134
1135		source src {
1136			unix-dgram("/var/run/log" flags(syslog-protocol));
1137		}
1138
1139	When using rsyslog, disable the 'SysSock.UseSpecialParser' option
1140	of the 'imuxsock' module to let messages be processed by the
1141	regular RFC 3164/5424 parsing pipeline:
1142
1143		module(load="imuxsock" SysSock.UseSpecialParser="off")
1144
1145	Do note that these changes only affect communication between local
1146	applications and syslogd(8). The format that syslogd(8) uses to
1147	store messages on disk or forward messages to other systems
1148	remains unchanged. syslogd(8) still uses RFC 3164 for these
1149	purposes. Options to customize this behaviour will be added in the
1150	future. Utilities that process log files stored in /var/log are
1151	thus expected to continue to function as before.
1152
1153	__FreeBSD_version has been incremented to 1200061 to denote this
1154	change.
1155
115620180328:
1157	Support for token ring networks has been removed. If you
1158	have "device token" in your kernel config you should remove
1159	it. No device drivers supported token ring.
1160
116120180323:
1162	makefs was modified to be able to tag ISO9660 El Torito boot catalog
1163	entries as EFI instead of overloading the i386 tag as done previously.
1164	The amd64 mkisoimages.sh script used to build amd64 ISO images for
1165	release was updated to use this. This may mean that makefs must be
1166	updated before "make cdrom" can be run in the release directory. This
1167	should be as simple as:
1168
1169		$ cd $SRCDIR/usr.sbin/makefs
1170		$ make depend all install
1171
117220180212:
1173	FreeBSD boot loader enhanced with Lua scripting. It's purely opt-in for
1174	now by building WITH_LOADER_LUA and WITHOUT_FORTH in /etc/src.conf.
1175	Co-existence for the transition period will come shortly. Booting is a
1176	complex environment and test coverage for Lua-enabled loaders has been
1177	thin, so it would be prudent to assume it might not work and make
1178	provisions for backup boot methods.
1179
118020180211:
1181	devmatch functionality has been turned on in devd. It will automatically
1182	load drivers for unattached devices. This may cause unexpected drivers
1183	to be loaded. Please report any problems to current@ and
1184	imp@freebsd.org.
1185
118620180114:
1187	Clang, llvm, lld, lldb, compiler-rt and libc++ have been upgraded to
1188	6.0.0.  Please see the 20141231 entry below for information about
1189	prerequisites and upgrading, if you are not already using clang 3.5.0
1190	or higher.
1191
119220180110:
1193	LLVM's lld linker is now used as the FreeBSD/amd64 bootstrap linker.
1194	This means it is used to link the kernel and userland libraries and
1195	executables, but is not yet installed as /usr/bin/ld by default.
1196
1197	To revert to ld.bfd as the bootstrap linker, in /etc/src.conf set
1198	WITHOUT_LLD_BOOTSTRAP=yes
1199
120020180110:
1201	On i386, pmtimer has been removed. Its functionality has been folded
1202	into apm. It was a no-op on ACPI in current for a while now (but was
1203	still needed on i386 in FreeBSD 11 and earlier). Users may need to
1204	remove it from kernel config files.
1205
120620180104:
1207	The use of RSS hash from the network card aka flowid has been
1208	disabled by default for lagg(4) as it's currently incompatible with
1209	the lacp and loadbalance protocols.
1210
1211	This can be re-enabled by setting the following in loader.conf:
1212	net.link.lagg.default_use_flowid="1"
1213
121420180102:
1215	The SW_WATCHDOG option is no longer necessary to enable the
1216	hardclock-based software watchdog if no hardware watchdog is
1217	configured. As before, SW_WATCHDOG will cause the software
1218	watchdog to be enabled even if a hardware watchdog is configured.
1219
122020171215:
1221	r326887 fixes the issue described in the 20171214 UPDATING entry.
1222	r326888 flips the switch back to building GELI support always.
1223
122420171214:
1225	r362593 broke ZFS + GELI support for reasons unknown. However,
1226	it also broke ZFS support generally, so GELI has been turned off
1227	by default as the lesser evil in r326857. If you boot off ZFS and/or
1228	GELI, it might not be a good time to update.
1229
123020171125:
1231	PowerPC users must update loader(8) by rebuilding world before
1232	installing a new kernel, as the protocol connecting them has
1233	changed. Without the update, loader metadata will not be passed
1234	successfully to the kernel and users will have to enter their
1235	root partition at the kernel mountroot prompt to continue booting.
1236	Newer versions of loader can boot old kernels without issue.
1237
123820171110:
1239	The LOADER_FIREWIRE_SUPPORT build variable has been renamed to
1240	WITH/OUT_LOADER_FIREWIRE. LOADER_{NO_,}GELI_SUPPORT has been renamed
1241	to WITH/OUT_LOADER_GELI.
1242
124320171106:
1244	The naive and non-compliant support of posix_fallocate(2) in ZFS
1245	has been removed as of r325320.  The system call now returns EINVAL
1246	when used on a ZFS file.  Although the new behavior complies with the
1247	standard, some consumers are not prepared to cope with it.
1248	One known victim is lld prior to r325420.
1249
125020171102:
1251	Building in a FreeBSD src checkout will automatically create object
1252	directories now rather than store files in the current directory if
1253	'make obj' was not ran.  Calling 'make obj' is no longer necessary.
1254	This feature can be disabled by setting WITHOUT_AUTO_OBJ=yes in
1255	/etc/src-env.conf (not /etc/src.conf), or passing the option in the
1256	environment.
1257
125820171101:
1259	The default MAKEOBJDIR has changed from /usr/obj/<srcdir> for native
1260	builds, and /usr/obj/<arch>/<srcdir> for cross-builds, to a unified
1261	/usr/obj/<srcdir>/<arch>.  This behavior can be changed to the old
1262	format by setting WITHOUT_UNIFIED_OBJDIR=yes in /etc/src-env.conf,
1263	the environment, or with -DWITHOUT_UNIFIED_OBJDIR when building.
1264	The UNIFIED_OBJDIR option is a transitional feature that will be
1265	removed for 12.0 release; please migrate to the new format for any
1266	tools by looking up the OBJDIR used by 'make -V .OBJDIR' means rather
1267	than hardcoding paths.
1268
126920171028:
1270	The native-xtools target no longer installs the files by default to the
1271	OBJDIR.  Use the native-xtools-install target with a DESTDIR to install
1272	to ${DESTDIR}/${NXTP} where NXTP defaults to /nxb-bin.
1273
127420171021:
1275	As part of the boot loader infrastructure cleanup, LOADER_*_SUPPORT
1276	options are changing from controlling the build if defined / undefined
1277	to controlling the build with explicit 'yes' or 'no' values. They will
1278	shift to WITH/WITHOUT options to match other options in the system.
1279
128020171010:
1281	libstand has turned into a private library for sys/boot use only.
1282	It is no longer supported as a public interface outside of sys/boot.
1283
128420171005:
1285	The arm port has split armv6 into armv6 and armv7. armv7 is now
1286	a valid TARGET_ARCH/MACHINE_ARCH setting. If you have an armv7 system
1287	and are running a kernel from before r324363, you will need to add
1288	MACHINE_ARCH=armv7 to 'make buildworld' to do a native build.
1289
129020171003:
1291	When building multiple kernels using KERNCONF, non-existent KERNCONF
1292	files will produce an error and buildkernel will fail. Previously
1293	missing KERNCONF files silently failed giving no indication as to
1294	why, only to subsequently discover during installkernel that the
1295	desired kernel was never built in the first place.
1296
129720170912:
1298	The default serial number format for CTL LUNs has changed.  This will
1299	affect users who use /dev/diskid/* device nodes, or whose FibreChannel
1300	or iSCSI clients care about their LUNs' serial numbers.  Users who
1301	require serial number stability should hardcode serial numbers in
1302	/etc/ctl.conf .
1303
130420170912:
1305	For 32-bit arm compiled for hard-float support, soft-floating point
1306	binaries now always get their shared libraries from
1307	LD_SOFT_LIBRARY_PATH (in the past, this was only used if
1308	/usr/libsoft also existed). Only users with a hard-float ld.so, but
1309	soft-float everything else should be affected.
1310
131120170826:
1312	The geli password typed at boot is now hidden.  To restore the previous
1313	behavior, see geli(8) for configuration options.
1314
131520170825:
1316	Move PMTUD blackhole counters to TCPSTATS and remove them from bare
1317	sysctl values.  Minor nit, but requires a rebuild of both world/kernel
1318	to complete.
1319
132020170814:
1321	"make check" behavior (made in ^/head@r295380) has been changed to
1322	execute from a limited sandbox, as opposed to executing from
1323	${TESTSDIR}.
1324
1325	Behavioral changes:
1326	- The "beforecheck" and "aftercheck" targets are now specified.
1327	- ${CHECKDIR} (added in commit noted above) has been removed.
1328	- Legacy behavior can be enabled by setting
1329	  WITHOUT_MAKE_CHECK_USE_SANDBOX in src.conf(5) or the environment.
1330
1331	If the limited sandbox mode is enabled, "make check" will execute
1332	"make distribution", then install, execute the tests, and clean up the
1333	sandbox if successful.
1334
1335	The "make distribution" and "make install" targets are typically run as
1336	root to set appropriate permissions and ownership at installation time.
1337	The end-user should set "WITH_INSTALL_AS_USER" in src.conf(5) or the
1338	environment if executing "make check" with limited sandbox mode using
1339	an unprivileged user.
1340
134120170808:
1342	Since the switch to GPT disk labels, fsck for UFS/FFS has been
1343	unable to automatically find alternate superblocks. As of r322297,
1344	the information needed to find alternate superblocks has been
1345	moved to the end of the area reserved for the boot block.
1346	Filesystems created with a newfs of this vintage or later
1347	will create the recovery information. If you have a filesystem
1348	created prior to this change and wish to have a recovery block
1349	created for your filesystem, you can do so by running fsck in
1350	foreground mode (i.e., do not use the -p or -y options). As it
1351	starts, fsck will ask ``SAVE DATA TO FIND ALTERNATE SUPERBLOCKS''
1352	to which you should answer yes.
1353
135420170728:
1355	As of r321665, an NFSv4 server configuration that services
1356	Kerberos mounts or clients that do not support the uid/gid in
1357	owner/owner_group string capability, must explicitly enable
1358	the nfsuserd daemon by adding nfsuserd_enable="YES" to the
1359	machine's /etc/rc.conf file.
1360
136120170722:
1362	Clang, llvm, lldb, compiler-rt and libc++ have been upgraded to 5.0.0.
1363	Please see the 20141231 entry below for information about prerequisites
1364	and upgrading, if you are not already using clang 3.5.0 or higher.
1365
136620170701:
1367	WITHOUT_RCMDS is now the default. Set WITH_RCMDS if you need the
1368	r-commands (rlogin, rsh, etc.) to be built with the base system.
1369
137020170625:
1371	The FreeBSD/powerpc platform now uses a 64-bit type for time_t.  This is
1372	a very major ABI incompatible change, so users of FreeBSD/powerpc must
1373	be careful when performing source upgrades.  It is best to run
1374	'make installworld' from an alternate root system, either a live
1375	CD/memory stick, or a temporary root partition.  Additionally, all ports
1376	must be recompiled.  powerpc64 is largely unaffected, except in the case
1377	of 32-bit compatibility.  All 32-bit binaries will be affected.
1378
137920170623:
1380	Forward compatibility for the "ino64" project have been committed. This
1381	will allow most new binaries to run on older kernels in a limited
1382	fashion.  This prevents many of the common foot-shooting actions in the
1383	upgrade as well as the limited ability to roll back the kernel across
1384	the ino64 upgrade. Complicated use cases may not work properly, though
1385	enough simpler ones work to allow recovery in most situations.
1386
138720170620:
1388	Switch back to the BSDL dtc (Device Tree Compiler). Set WITH_GPL_DTC
1389	if you require the GPL compiler.
1390
139120170618:
1392	The internal ABI used for communication between the NFS kernel modules
1393	was changed by r320085, so __FreeBSD_version was bumped to
1394	ensure all the NFS related modules are updated together.
1395
139620170617:
1397	The ABI of struct event was changed by extending the data
1398	member to 64bit and adding ext fields.  For upgrade, same
1399	precautions as for the entry 20170523 "ino64" must be
1400	followed.
1401
140220170531:
1403	The GNU roff toolchain has been removed from base. To render manpages
1404	which are not supported by mandoc(1), man(1) can fallback on GNU roff
1405	from ports (and recommends to install it).
1406	To render roff(7) documents, consider using GNU roff from ports or the
1407	heirloom doctools roff toolchain from ports via pkg install groff or
1408	via pkg install heirloom-doctools.
1409
141020170524:
1411	The ath(4) and ath_hal(4) modules now build piecemeal to allow for
1412	smaller runtime footprint builds.  This is useful for embedded systems
1413	which only require one chipset support.
1414
1415	If you load it as a module, make sure this is in /boot/loader.conf:
1416
1417	if_ath_load="YES"
1418
1419	This will load the HAL, all chip/RF backends and if_ath_pci.
1420	If you have if_ath_pci in /boot/loader.conf, ensure it is after
1421	if_ath or it will not load any HAL chipset support.
1422
1423	If you want to selectively load things (eg on cheaper ARM/MIPS
1424	platforms where RAM is at a premium) you should:
1425
1426	* load ath_hal
1427	* load the chip modules in question
1428	* load ath_rate, ath_dfs
1429	* load ath_main
1430	* load if_ath_pci and/or if_ath_ahb depending upon your particular
1431	  bus bind type - this is where probe/attach is done.
1432
1433	For further comments/feedback, poke adrian@ .
1434
143520170523:
1436	The "ino64" 64-bit inode project has been committed, which extends
1437	a number of types to 64 bits.  Upgrading in place requires care and
1438	adherence to the documented upgrade procedure.
1439
1440	If using a custom kernel configuration ensure that the
1441	COMPAT_FREEBSD11 option is included (as during the upgrade the
1442	system will be running the ino64 kernel with the existing world).
1443
1444	For the safest in-place upgrade begin by removing previous build
1445	artifacts via "rm -rf /usr/obj/*".  Then, carefully follow the full
1446	procedure documented below under the heading "To rebuild everything and
1447	install it on the current system."  Specifically, a reboot is required
1448	after installing the new kernel before installing world. While an
1449	installworld normally works by accident from multiuser after rebooting
1450	the proper kernel, there are many cases where this will fail across this
1451	upgrade and installworld from single user is required.
1452
145320170424:
1454	The NATM framework including the en(4), fatm(4), hatm(4), and
1455	patm(4) devices has been removed.  Consumers should plan a
1456	migration before the end-of-life date for FreeBSD 11.
1457
145820170420:
1459	GNU diff has been replaced by a BSD licensed diff. Some features of GNU
1460	diff has not been implemented, if those are needed a newer version of
1461	GNU diff is available via the diffutils package under the gdiff name.
1462
146320170413:
1464	As of r316810 for ipfilter, keep frags is no longer assumed when
1465	keep state is specified in a rule. r316810 aligns ipfilter with
1466	documentation in man pages separating keep frags from keep state.
1467	This allows keep state to be specified without forcing keep frags
1468	and allows keep frags to be specified independently of keep state.
1469	To maintain previous behaviour, also specify keep frags with
1470	keep state (as documented in ipf.conf.5).
1471
147220170407:
1473	arm64 builds now use the base system LLD 4.0.0 linker by default,
1474	instead of requiring that the aarch64-binutils port or package be
1475	installed. To continue using aarch64-binutils, set
1476	CROSS_BINUTILS_PREFIX=/usr/local/aarch64-freebsd/bin .
1477
147820170405:
1479	The UDP optimization in entry 20160818 that added the sysctl
1480	net.inet.udp.require_l2_bcast has been reverted.  L2 broadcast
1481	packets will no longer be treated as L3 broadcast packets.
1482
148320170331:
1484	Binds and sends to the loopback addresses, IPv6 and IPv4, will now
1485	use any explicitly assigned loopback address available in the jail
1486	instead of using the first assigned address of the jail.
1487
148820170329:
1489	The ctl.ko module no longer implements the iSCSI target frontend:
1490	cfiscsi.ko does instead.
1491
1492	If building cfiscsi.ko as a kernel module, the module can be loaded
1493	via one of the following methods:
1494	- `cfiscsi_load="YES"` in loader.conf(5).
1495	- Add `cfiscsi` to `$kld_list` in rc.conf(5).
1496	- ctladm(8)/ctld(8), when compiled with iSCSI support
1497	  (`WITH_ISCSI=yes` in src.conf(5))
1498
1499	Please see cfiscsi(4) for more details.
1500
150120170316:
1502	The mmcsd.ko module now additionally depends on geom_flashmap.ko.
1503	Also, mmc.ko and mmcsd.ko need to be a matching pair built from the
1504	same source (previously, the dependency of mmcsd.ko on mmc.ko was
1505	missing, but mmcsd.ko now will refuse to load if it is incompatible
1506	with mmc.ko).
1507
150820170315:
1509	The syntax of ipfw(8) named states was changed to avoid ambiguity.
1510	If you have used named states in the firewall rules, you need to modify
1511	them after installworld and before rebooting. Now named states must
1512	be prefixed with colon.
1513
151420170311:
1515	The old drm (sys/dev/drm/) drivers for i915 and radeon have been
1516	removed as the userland we provide cannot use them. The KMS version
1517	(sys/dev/drm2) supports the same hardware.
1518
151920170302:
1520	Clang, llvm, lldb, compiler-rt and libc++ have been upgraded to 4.0.0.
1521	Please see the 20141231 entry below for information about prerequisites
1522	and upgrading, if you are not already using clang 3.5.0 or higher.
1523
152420170221:
1525	The code that provides support for ZFS .zfs/ directory functionality
1526	has been reimplemented.  It's not possible now to create a snapshot
1527	by mkdir under .zfs/snapshot/.  That should be the only user visible
1528	change.
1529
153020170216:
1531	EISA bus support has been removed. The WITH_EISA option is no longer
1532	valid.
1533
153420170215:
1535	MCA bus support has been removed.
1536
153720170127:
1538	The WITH_LLD_AS_LD / WITHOUT_LLD_AS_LD build knobs have been renamed
1539	WITH_LLD_IS_LD / WITHOUT_LLD_IS_LD, for consistency with CLANG_IS_CC.
1540
154120170112:
1542	The EM_MULTIQUEUE kernel configuration option is deprecated now that
1543	the em(4) driver conforms to iflib specifications.
1544
154520170109:
1546	The igb(4), em(4) and lem(4) ethernet drivers are now implemented via
1547	IFLIB.  If you have a custom kernel configuration that excludes em(4)
1548	but you use igb(4), you need to re-add em(4) to your custom
1549	configuration.
1550
155120161217:
1552	Clang, llvm, lldb, compiler-rt and libc++ have been upgraded to 3.9.1.
1553	Please see the 20141231 entry below for information about prerequisites
1554	and upgrading, if you are not already using clang 3.5.0 or higher.
1555
155620161124:
1557	Clang, llvm, lldb, compiler-rt and libc++ have been upgraded to 3.9.0.
1558	Please see the 20141231 entry below for information about prerequisites
1559	and upgrading, if you are not already using clang 3.5.0 or higher.
1560
156120161119:
1562	The layout of the pmap structure has changed for powerpc to put the pmap
1563	statistics at the front for all CPU variations.  libkvm(3) and all tools
1564	that link against it need to be recompiled.
1565
156620161030:
1567	isl(4) and cyapa(4) drivers now require a new driver,
1568	chromebook_platform(4), to work properly on Chromebook-class hardware.
1569	On other types of hardware the drivers may need to be configured using
1570	device hints.  Please see the corresponding manual pages for details.
1571
157220161017:
1573	The urtwn(4) driver was merged into rtwn(4) and now consists of
1574	rtwn(4) main module + rtwn_usb(4) and rtwn_pci(4) bus-specific
1575	parts.
1576	Also, firmware for RTL8188CE was renamed due to possible name
1577	conflict (rtwnrtl8192cU(B) -> rtwnrtl8192cE(B))
1578
157920161015:
1580	GNU rcs has been removed from base.  It is available as packages:
1581	- rcs: Latest GPLv3 GNU rcs version.
1582	- rcs57: Copy of the latest version of GNU rcs (GPLv2) before it was
1583	removed from base.
1584
158520161008:
1586	Use of the cc_cdg, cc_chd, cc_hd, or cc_vegas congestion control
1587	modules now requires that the kernel configuration contain the
1588	TCP_HHOOK option. (This option is included in the GENERIC kernel.)
1589
159020161003:
1591	The WITHOUT_ELFCOPY_AS_OBJCOPY src.conf(5) knob has been retired.
1592	ELF Tool Chain's elfcopy is always installed as /usr/bin/objcopy.
1593
159420160924:
1595	Relocatable object files with the extension of .So have been renamed
1596	to use an extension of .pico instead.  The purpose of this change is
1597	to avoid a name clash with shared libraries on case-insensitive file
1598	systems.  On those file systems, foo.So is the same file as foo.so.
1599
160020160918:
1601	GNU rcs has been turned off by default.  It can (temporarily) be built
1602	again by adding WITH_RCS knob in src.conf.
1603	Otherwise, GNU rcs is available from packages:
1604	- rcs: Latest GPLv3 GNU rcs version.
1605	- rcs57: Copy of the latest version of GNU rcs (GPLv2) from base.
1606
160720160918:
1608	The backup_uses_rcs functionality has been removed from rc.subr.
1609
161020160908:
1611	The queue(3) debugging macro, QUEUE_MACRO_DEBUG, has been split into
1612	two separate components, QUEUE_MACRO_DEBUG_TRACE and
1613	QUEUE_MACRO_DEBUG_TRASH.  Define both for the original
1614	QUEUE_MACRO_DEBUG behavior.
1615
161620160824:
1617	r304787 changed some ioctl interfaces between the iSCSI userspace
1618	programs and the kernel.  ctladm, ctld, iscsictl, and iscsid must be
1619	rebuilt to work with new kernels.  __FreeBSD_version has been bumped
1620	to 1200005.
1621
162220160818:
1623	The UDP receive code has been updated to only treat incoming UDP
1624	packets that were addressed to an L2 broadcast address as L3
1625	broadcast packets.  It is not expected that this will affect any
1626	standards-conforming UDP application.  The new behaviour can be
1627	disabled by setting the sysctl net.inet.udp.require_l2_bcast to
1628	0.
1629
163020160818:
1631	Remove the openbsd_poll system call.
1632	__FreeBSD_version has been bumped because of this.
1633
163420160708:
1635	The stable/11 branch has been created from head@r302406.
1636
1637After branch N is created, entries older than the N-2 branch point are removed
1638from this file. After stable/14 is branched and current becomes FreeBSD 15,
1639entries older than stable/12 branch point will be removed from current's
1640UPDATING file.
1641
1642COMMON ITEMS:
1643
1644	General Notes
1645	-------------
1646	Sometimes, obscure build problems are the result of environment
1647	poisoning.  This can happen because the make utility reads its
1648	environment when searching for values for global variables.  To run
1649	your build attempts in an "environmental clean room", prefix all make
1650	commands with 'env -i '.  See the env(1) manual page for more details.
1651	Occasionally a build failure will occur with "make -j" due to a race
1652	condition.  If this happens try building again without -j, and please
1653	report a bug if it happens consistently.
1654
1655	When upgrading from one major version to another it is generally best to
1656	upgrade to the latest code in the currently installed branch first, then
1657	do an upgrade to the new branch. This is the best-tested upgrade path,
1658	and has the highest probability of being successful.  Please try this
1659	approach if you encounter problems with a major version upgrade.  Since
1660	the stable 4.x branch point, one has generally been able to upgrade from
1661	anywhere in the most recent stable branch to head / current (or even the
1662	last couple of stable branches). See the top of this file when there's
1663	an exception.
1664
1665	The update process will emit an error on an attempt to perform a build
1666	or install from a FreeBSD version below the earliest supported version.
1667	When updating from an older version the update should be performed one
1668	major release at a time, including running `make delete-old` at each
1669	step.
1670
1671	When upgrading a live system, having a root shell around before
1672	installing anything can help undo problems. Not having a root shell
1673	around can lead to problems if pam has changed too much from your
1674	starting point to allow continued authentication after the upgrade.
1675
1676	This file should be read as a log of events. When a later event changes
1677	information of a prior event, the prior event should not be deleted.
1678	Instead, a pointer to the entry with the new information should be
1679	placed in the old entry. Readers of this file should also sanity check
1680	older entries before relying on them blindly. Authors of new entries
1681	should write them with this in mind.
1682
1683	ZFS notes
1684	---------
1685	When upgrading the boot ZFS pool to a new version (via zpool upgrade),
1686	always follow these three steps:
1687
1688	1) recompile and reinstall the ZFS boot loader and boot block
1689	(this is part of "make buildworld" and "make installworld")
1690
1691	2) update the ZFS boot block on your boot drive (only required when
1692	doing a zpool upgrade):
1693
1694	When booting on x86 via BIOS, use the following to update the ZFS boot
1695	block on the freebsd-boot partition of a GPT partitioned drive ada0:
1696		gpart bootcode -p /boot/gptzfsboot -i $N ada0
1697	The value $N will typically be 1.  For EFI booting, see EFI notes.
1698
1699	3) zpool upgrade the root pool. New bootblocks will work with old
1700	pools, but not vice versa, so they need to be updated before any
1701	zpool upgrade.
1702
1703	Non-boot pools do not need these updates.
1704
1705	EFI notes
1706	---------
1707
1708	There are two locations the boot loader can be installed into. The
1709	current location (and the default) is \efi\freebsd\loader.efi and using
1710	efibootmgr(8) to configure it. The old location, that must be used on
1711	deficient systems that don't honor efibootmgr(8) protocols, is the
1712	fallback location of \EFI\BOOT\BOOTxxx.EFI. Generally, you will copy
1713	/boot/loader.efi to this location, but on systems installed a long time
1714	ago the ESP may be too small and /boot/boot1.efi may be needed unless
1715	the ESP has been expanded in the meantime.
1716
1717	Recent systems will have the ESP mounted on /boot/efi, but older ones
1718	may not have it mounted at all, or mounted in a different
1719	location. Older arm SD images with MBR used /boot/msdos as the
1720	mountpoint. The ESP is a MSDOS filesystem.
1721
1722	The EFI boot loader rarely needs to be updated. For ZFS booting,
1723	however, you must update loader.efi before you do 'zpool upgrade' the
1724	root zpool, otherwise the old loader.efi may reject the upgraded zpool
1725	since it does not automatically understand some new features.
1726
1727	See loader.efi(8) and uefi(8) for more details.
1728
1729	To build a kernel
1730	-----------------
1731	If you are updating from a prior version of FreeBSD (even one just
1732	a few days old), you should follow this procedure.  It is the most
1733	failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
1734
1735	make kernel-toolchain
1736	make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
1737	make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
1738
1739	To test a kernel once
1740	---------------------
1741	If you just want to boot a kernel once (because you are not sure
1742	if it works, or if you want to boot a known bad kernel to provide
1743	debugging information) run
1744	make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
1745	nextboot -k testkernel
1746
1747	To rebuild everything and install it on the current system.
1748	-----------------------------------------------------------
1749	# Note: sometimes if you are running current you gotta do more than
1750	# is listed here if you are upgrading from a really old current.
1751
1752	<make sure you have good level 0 dumps>
1753	make buildworld
1754	make buildkernel KERNCONF=YOUR_KERNEL_HERE
1755	make installkernel KERNCONF=YOUR_KERNEL_HERE
1756							[1]
1757	<reboot in single user>				[3]
1758	etcupdate -p					[5]
1759	make installworld
1760	etcupdate -B					[4]
1761	make delete-old					[6]
1762	<reboot>
1763
1764	To cross-install current onto a separate partition
1765	--------------------------------------------------
1766	# In this approach we use a separate partition to hold
1767	# current's root, 'usr', and 'var' directories.   A partition
1768	# holding "/", "/usr" and "/var" should be about 2GB in
1769	# size.
1770
1771	<make sure you have good level 0 dumps>
1772	<boot into -stable>
1773	make buildworld
1774	make buildkernel KERNCONF=YOUR_KERNEL_HERE
1775	<maybe newfs current's root partition>
1776	<mount current's root partition on directory ${CURRENT_ROOT}>
1777	make installworld DESTDIR=${CURRENT_ROOT} -DDB_FROM_SRC
1778	make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
1779	make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
1780	cp /etc/fstab ${CURRENT_ROOT}/etc/fstab 		   # if newfs'd
1781	<edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
1782	<reboot into current>
1783	<do a "native" rebuild/install as described in the previous section>
1784	<maybe install compatibility libraries from ports/misc/compat*>
1785	<reboot>
1786
1787
1788	To upgrade in-place from stable to current
1789	----------------------------------------------
1790	<make sure you have good level 0 dumps>
1791	make buildworld					[9]
1792	make buildkernel KERNCONF=YOUR_KERNEL_HERE	[8]
1793	make installkernel KERNCONF=YOUR_KERNEL_HERE
1794							[1]
1795	<reboot in single user>				[3]
1796	etcupdate -p					[5]
1797	make installworld
1798	etcupdate -B					[4]
1799	make delete-old					[6]
1800	<reboot>
1801
1802	Make sure that you've read the UPDATING file to understand the
1803	tweaks to various things you need.  At this point in the life
1804	cycle of current, things change often and you are on your own
1805	to cope.  The defaults can also change, so please read ALL of
1806	the UPDATING entries.
1807
1808	Also, if you are tracking -current, you must be subscribed to
1809	freebsd-current@freebsd.org.  Make sure that before you update
1810	your sources that you have read and understood all the recent
1811	messages there.  If in doubt, please track -stable which has
1812	much fewer pitfalls.
1813
1814	[1] If you have third party modules, such as vmware, you should disable
1815	them at this point so they don't crash your system on
1816	reboot. Alternatively, you should rebuild all the modules you have in
1817	your system and install them as well.  If you are running -current, you
1818	should seriously consider placing all sources to all the modules for
1819	your system (or symlinks to them) in /usr/local/sys/modules so this
1820	happens automatically. If all your modules come from ports, then adding
1821	the port origin directories to PORTS_MODULES instead is also automatic
1822	and effective, eg:
1823	     PORTS_MODULES+=x11/nvidia-driver
1824
1825	[3] From the bootblocks, boot -s, and then do
1826		fsck -p
1827		mount -u /
1828		mount -a
1829		sh /etc/rc.d/zfs start	# mount zfs filesystem, if needed
1830		cd src			# full path to source
1831		adjkerntz -i		# if CMOS is wall time
1832	Also, when doing a major release upgrade, it is required that you boot
1833	into single user mode to do the installworld.
1834
1835	[4] Note: This step is non-optional.  Failure to do this step
1836	can result in a significant reduction in the functionality of the
1837	system.  Attempting to do it by hand is not recommended and those
1838	that pursue this avenue should read this file carefully, as well
1839	as the archives of freebsd-current and freebsd-hackers mailing lists
1840	for potential gotchas.  See etcupdate(8) for more information.
1841
1842	[5] Usually this step is a no-op.  However, from time to time
1843	you may need to do this if you get unknown user in the following
1844	step.
1845
1846	[6] This only deletes old files and directories. Old libraries
1847	can be deleted by "make delete-old-libs", but you have to make
1848	sure that no program is using those libraries anymore.
1849
1850	[8] The new kernel must be able to run existing binaries used by an
1851	installworld.  When upgrading across major versions, the new kernel's
1852	configuration must include the correct COMPAT_FREEBSD<n> option for
1853	existing binaries (e.g. COMPAT_FREEBSD11 to run 11.x binaries).  Failure
1854	to do so may leave you with a system that is hard to boot to recover. A
1855	GENERIC kernel will include suitable compatibility options to run
1856	binaries from older branches.  Note that the ability to run binaries
1857	from unsupported branches is not guaranteed.
1858
1859	Make sure that you merge any new devices from GENERIC since the
1860	last time you updated your kernel config file. Options also
1861	change over time, so you may need to adjust your custom kernels
1862	for these as well.
1863
1864	[9] If CPUTYPE is defined in your /etc/make.conf, make sure to use the
1865	"?=" instead of the "=" assignment operator, so that buildworld can
1866	override the CPUTYPE if it needs to.
1867
1868	MAKEOBJDIRPREFIX must be defined in an environment variable, and
1869	not on the command line, or in /etc/make.conf.  buildworld will
1870	warn if it is improperly defined.
1871FORMAT:
1872
1873This file contains a list, in reverse chronological order, of major
1874breakages in tracking -current.  It is not guaranteed to be a complete
1875list of such breakages, and only contains entries since September 23, 2011.
1876If you need to see UPDATING entries from before that date, you will need
1877to fetch an UPDATING file from an older FreeBSD release.
1878
1879Copyright information:
1880
1881Copyright 1998-2009 M. Warner Losh <imp@FreeBSD.org>
1882
1883Redistribution, publication, translation and use, with or without
1884modification, in full or in part, in any form or format of this
1885document are permitted without further permission from the author.
1886
1887THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
1888IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1889WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1890DISCLAIMED.  IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
1891INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1892(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1893SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1894HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1895STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
1896IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1897POSSIBILITY OF SUCH DAMAGE.
1898
1899Contact Warner Losh if you have any questions about your use of
1900this document.
1901
1902$FreeBSD$
1903