xref: /freebsd/UPDATING (revision 4a5216a6dc0c3ce4cf5f2d3ee8af0c3ff3402c4f)
1Updating Information for FreeBSD current users
2
3This file is maintained and copyrighted by M. Warner Losh
4<imp@village.org>.  See end of file for further details.  For commonly
5done items, please see the COMMON ITEMS: section later in the file.
6
7Items affecting the ports and packages system can be found in
8/usr/ports/UPDATING.  Please read that file before running
9portupgrade.
10
11NOTE TO PEOPLE WHO THINK THAT FreeBSD 8.x IS SLOW:
12	FreeBSD 8.x has many debugging features turned on, in
13	both the kernel and userland.  These features attempt to detect
14	incorrect use of system primitives, and encourage loud failure
15	through extra sanity checking and fail stop semantics.  They
16	also substantially impact system performance.  If you want to
17	do performance measurement, benchmarking, and optimization,
18	you'll want to turn them off.  This includes various WITNESS-
19	related kernel options, INVARIANTS, malloc debugging flags
20	in userland, and various verbose features in the kernel.  Many
21	developers choose to disable these features on build machines
22	to maximize performance.  (To disable malloc debugging, run
23	ln -s aj /etc/malloc.conf.)
24
2520081009:
26	The uhci, ohci, ehci and slhci USB Host controller drivers have
27	been put into separate modules. If you load the usb module
28	separately through loader.conf you will need to load the
29	appropriate *hci module as well. E.g. for a UHCI-based USB 2.0
30	controller add the following to loader.conf:
31
32		uhci_load="YES"
33		ehci_load="YES"
34
3520081009:
36	The ABI used by the PMC toolset has changed.  Please keep
37	userland (libpmc(3)) and the kernel module (hwpmc(4)) in
38	sync.
39
4020080820:
41	The TTY subsystem of the kernel has been replaced by a new
42	implementation, which provides better scalability and an
43	improved driver model. Most common drivers have been migrated to
44	the new TTY subsystem, while others have not. The following
45	drivers have not yet been ported to the new TTY layer:
46
47	PCI/ISA:
48		cy, digi, rc, rp, sio
49
50	USB:
51		ubser, ucycom
52
53	Line disciplines:
54		ng_h4, ng_tty, ppp, sl, snp
55
56	Adding these drivers to your kernel configuration file shall
57	cause compilation to fail.
58
5920080818:
60	ntpd has been upgraded to 4.2.4p5.
61
6220080801:
63	OpenSSH has been upgraded to 5.1p1.
64
65	For many years, FreeBSD's version of OpenSSH preferred DSA
66	over RSA for host and user authentication keys.  With this
67	upgrade, we've switched to the vendor's default of RSA over
68	DSA.  This may cause upgraded clients to warn about unknown
69	host keys even for previously known hosts.  Users should
70	follow the usual procedure for verifying host keys before
71	accepting the RSA key.
72
73	This can be circumvented by setting the "HostKeyAlgorithms"
74	option to "ssh-dss,ssh-rsa" in ~/.ssh/config or on the ssh
75	command line.
76
77	Please note that the sequence of keys offered for
78	authentication has been changed as well.  You may want to
79	specify IdentityFile in a different order to revert this
80	behavior.
81
8220080713:
83	The sio(4) driver has been removed from the i386 and amd64
84	kernel configuration files. This means uart(4) is now the
85	default serial port driver on those platforms as well.
86
87	To prevent collisions with the sio(4) driver, the uart(4) driver
88	uses different names for its device nodes. This means the
89	onboard serial port will now most likely be called "ttyu0"
90	instead of "ttyd0". You may need to reconfigure applications to
91	use the new device names.
92
93	When using the serial port as a boot console, be sure to update
94	/boot/device.hints and /etc/ttys before booting the new kernel.
95	If you forget to do so, you can still manually specify the hints
96	at the loader prompt:
97
98		set hint.uart.0.at="isa"
99		set hint.uart.0.port="0x3F8"
100		set hint.uart.0.flags="0x10"
101		set hint.uart.0.irq="4"
102		boot -s
103
10420080609:
105	The gpt(8) utility has been removed. Use gpart(8) to partition
106	disks instead.
107
10820080603:
109	The version that Linuxulator emulates was changed from 2.4.2
110	to 2.6.16. If you experience any problems with Linux binaries
111	please try to set sysctl compat.linux.osrelease to 2.4.2 and
112	if it fixes the problem contact emulation mailing list.
113
11420080525:
115	ISDN4BSD (I4B) was removed from the src tree. You may need to
116	update a your kernel configuration and remove relevant entries.
117
11820080509:
119	I have checked in code to support multiple routing tables.
120	See the man pages setfib(1) and setfib(2).
121	This is a hopefully backwards compatible version,
122	but to make use of it you need to compile your kernel
123	with options ROUTETABLES=2 (or more up to 16).
124
12520080420:
126	The 802.11 wireless support was redone to enable multi-bss
127	operation on devices that are capable.  The underlying device
128	is no longer used directly but instead wlanX devices are
129	cloned with ifconfig.  This requires changes to rc.conf files.
130	For example, change:
131		ifconfig_ath0="WPA DHCP"
132	to
133		wlans_ath0=wlan0
134		ifconfig_wlan0="WPA DHCP"
135	see rc.conf(5) for more details.  In addition, mergemaster of
136	/etc/rc.d is highly recommended.  Simultaneous update of userland
137	and kernel wouldn't hurt either.
138
139	As part of the multi-bss changes the wlan_scan_ap and wlan_scan_sta
140	modules were merged into the base wlan module.  All references
141	to these modules (e.g. in kernel config files) must be removed.
142
14320080408:
144	psm(4) has gained write(2) support in native operation level.
145	Arbitrary commands can be written to /dev/psm%d and status can
146	be read back from it.  Therefore, an application is responsible
147	for status validation and error recovery.  It is a no-op in
148	other operation levels.
149
15020080312:
151	Support for KSE threading has been removed from the kernel.  To
152	run legacy applications linked against KSE libmap.conf may
153	be used.  The following libmap.conf may be used to ensure
154	compatibility with any prior release:
155
156	libpthread.so.1 libthr.so.1
157	libpthread.so.2 libthr.so.2
158	libkse.so.3 libthr.so.3
159
16020080301:
161	The layout of struct vmspace has changed. This affects libkvm
162	and any executables that link against libkvm and use the
163	kvm_getprocs() function. In particular, but not exclusively,
164	it affects ps(1), fstat(1), pkill(1), systat(1), top(1) and w(1).
165	The effects are minimal, but it's advisable to upgrade world
166	nonetheless.
167
16820080229:
169	The latest em driver no longer has support in it for the
170	82575 adapter, this is now moved to the igb driver. The
171	split was done to make new features that are incompatible
172	with older hardware easier to do.
173
17420080220:
175	The new geom_lvm(4) geom class has been renamed to geom_linux_lvm(4),
176	likewise the kernel option is now GEOM_LINUX_LVM.
177
17820080211:
179	The default NFS mount mode has changed from UDP to TCP for
180	increased reliability.  If you rely on (insecurely) NFS
181	mounting across a firewall you may need to update your
182	firewall rules.
183
18420080208:
185	Belatedly note the addition of m_collapse for compacting
186	mbuf chains.
187
18820080126:
189	The fts(3) structures have been changed to use adequate
190	integer types for their members and so to be able to cope
191	with huge file trees.  The old fts(3) ABI is preserved
192	through symbol versioning in libc, so third-party binaries
193	using fts(3) should still work, although they will not take
194	advantage of the extended types.  At the same time, some
195	third-party software might fail to build after this change
196	due to unportable assumptions made in its source code about
197	fts(3) structure members.  Such software should be fixed
198	by its vendor or, in the worst case, in the ports tree.
199	FreeBSD_version 800015 marks this change for the unlikely
200	case that a portable fix is impossible.
201
20220080123:
203	To upgrade to -current after this date, you must be running
204	FreeBSD not older than 6.0-RELEASE.  Upgrading to -current
205	from 5.x now requires a stop over at RELENG_6 or RELENG_7 systems.
206
20720071128:
208	The ADAPTIVE_GIANT kernel option has been retired because its
209	functionality is the default now.
210
21120071118:
212	The AT keyboard emulation of sunkbd(4) has been turned on
213	by default. In order to make the special symbols of the Sun
214	keyboards driven by sunkbd(4) work under X these now have
215	to be configured the same way as Sun USB keyboards driven
216	by ukbd(4) (which also does AT keyboard emulation), f.e.:
217
218	Option	"XkbLayout" "us"
219	Option	"XkbRules" "xorg"
220	Option	"XkbSymbols" "pc(pc105)+sun_vndr/usb(sun_usb)+us"
221
22220071024:
223	It has been decided that it is desirable to provide ABI
224	backwards compatibility to the FreeBSD 4/5/6 versions of the
225	PCIOCGETCONF, PCIOCREAD and PCIOCWRITE IOCTLs, which was
226	broken with the introduction of PCI domain support (see the
227	20070930 entry). Unfortunately, this required the ABI of
228	PCIOCGETCONF to be broken again in order to be able to
229	provide backwards compatibility to the old version of that
230	IOCTL. Thus consumers of PCIOCGETCONF have to be recompiled
231	again. As for prominent ports this affects neither pciutils
232	nor xorg-server this time, the hal port needs to be rebuilt
233	however.
234
23520071020:
236	The misnamed kthread_create() and friends have been renamed
237	to kproc_create() etc. Many of the callers already
238	used kproc_start()..
239	I will return kthread_create() and friends in a while
240	with implementations that actually create threads, not procs.
241	Renaming corresponds with version 800002.
242
24320071010:
244	RELENG_7 branched.
245
24620071009:
247	Setting WITHOUT_LIBPTHREAD now means WITHOUT_LIBKSE and
248	WITHOUT_LIBTHR are set.
249
25020070930:
251	The PCI code has been made aware of PCI domains. This means that
252	the location strings as used by pciconf(8) etc are now in the
253	following format: pci<domain>:<bus>:<device>[:<function>]. It
254	also means that consumers of <sys/pciio.h> potentially need to
255	be recompiled; this includes the hal and xorg-server ports.
256
25720070928:
258        The caching daemon (cached) was renamed to nscd. nscd.conf
259        configuration file should be used instead of cached.conf and
260        nscd_enable, nscd_pidfile and nscd_flags options should be used
261        instead of cached_enable, cached_pidfile and cached_flags in
262        rc.conf.
263
26420070921:
265	The getfacl(1) utility now prints owning user and group name
266	instead of owning uid and gid in the three line comment header.
267	This is the same behavior as getfacl(1) on Solaris and Linux.
268
26920070704:
270        The new IPsec code is now compiled in using the IPSEC option.  The
271	IPSEC option now requires "device crypto" be defined in your kernel
272	configuration.  The FAST_IPSEC kernel option is now deprecated.
273
27420070702:
275	The packet filter (pf) code has been updated to OpenBSD 4.1 Please
276	note the changed syntax - keep state is now on by default.  Also
277	note the fact that ftp-proxy(8) has been changed from bottom up and
278	has been moved from libexec to usr/sbin.  Changes in the ALTQ
279	handling also affect users of IPFW's ALTQ capabilities.
280
28120070701:
282	Remove KAME IPsec in favor of FAST_IPSEC, which is now the
283	only IPsec supported by FreeBSD.  The new IPsec stack
284	supports both IPv4 and IPv6. The kernel option will change
285	after the code changes have settled in.  For now the kernel
286	option IPSEC is deprecated and FAST_IPSEC is the only option, that
287	will change after some settling time.
288
28920070701:
290	The wicontrol(8) utility has been removed from the base system. wi(4)
291	cards should be configured using ifconfig(8), see the man page for more
292	information.
293
29420070612:
295	The i386/amd64 GENERIC kernel now defaults to the nfe(4) driver
296	instead of the nve(4) driver. Please update your configuration
297	accordingly.
298
29920070612:
300	By default, /etc/rc.d/sendmail no longer rebuilds the aliases
301	database if it is missing or older than the aliases file.  If
302	desired, set the new rc.conf option sendmail_rebuild_aliases
303	to "YES" to restore that functionality.
304
30520070612:
306	The IPv4 multicast socket code has been considerably modified, and
307	moved to the file sys/netinet/in_mcast.c. Initial support for the
308	RFC 3678 Source-Specific Multicast Socket API has been added to
309	the IPv4 network stack.
310
311	Strict multicast and broadcast reception is now the default for
312	UDP/IPv4 sockets; the net.inet.udp.strict_mcast_mship sysctl variable
313	has now been removed.
314
315	The RFC 1724 hack for interface selection has been removed; the use
316	of the Linux-derived ip_mreqn structure with IP_MULTICAST_IF has
317	been added to replace it. Consumers such as routed will soon be
318	updated to reflect this.
319
320	These changes affect users who are running routed(8) or rdisc(8)
321	from the FreeBSD base system on point-to-point or unnumbered
322	interfaces.
323
32420070610:
325	The net80211 layer has changed significantly and all wireless
326	drivers that depend on it need to be recompiled.  Further these
327	changes require that any program that interacts with the wireless
328	support in the kernel be recompiled; this includes: ifconfig,
329	wpa_supplicant, hostapd, and wlanstats.  Users must also, for
330	the moment, kldload the wlan_scan_sta and/or wlan_scan_ap modules
331	if they use modules for wireless support.  These modules implement
332	scanning support for station and ap modes, respectively.  Failure
333	to load the appropriate module before marking a wireless interface
334	up will result in a message to the console and the device not
335	operating properly.
336
33720070610:
338	The pam_nologin(8) module ceases to provide an authentication
339	function and starts providing an account management function.
340	Consequent changes to /etc/pam.d should be brought in using
341	mergemaster(8).  Third-party files in /usr/local/etc/pam.d may
342	need manual editing as follows.  Locate this line (or similar):
343
344		auth	required	pam_nologin.so	no_warn
345
346	and change it according to this example:
347
348		account	required	pam_nologin.so	no_warn
349
350	That is, the first word needs to be changed from "auth" to
351	"account".  The new line can be moved to the account section
352	within the file for clarity.  Not updating pam.conf(5) files
353	will result in nologin(5) ignored by the respective services.
354
35520070529:
356	The ether_ioctl() function has been synchronized with ioctl(2)
357	and ifnet.if_ioctl.  Due to that, the size of one of its arguments
358	has changed on 64-bit architectures.  All kernel modules using
359	ether_ioctl() need to be rebuilt on such architectures.
360
36120070516:
362	Improved INCLUDE_CONFIG_FILE support has been introduced to the
363	config(8) utility. In order to take advantage of this new
364	functionality, you are expected to recompile and install
365	src/usr.sbin/config. If you don't rebuild config(8), and your
366	kernel configuration depends on INCLUDE_CONFIG_FILE, the kernel
367	build will be broken because of a missing "kernconfstring"
368	symbol.
369
37020070513:
371	Symbol versioning is enabled by default.  To disable it, use
372	option WITHOUT_SYMVER.  It is not advisable to attempt to
373	disable symbol versioning once it is enabled; your installworld
374	will break because a symbol version-less libc will get installed
375	before the install tools.  As a result, the old install tools,
376	which previously had symbol dependencies to FBSD_1.0, will fail
377	because the freshly installed libc will not have them.
378
379	The default threading library (providing "libpthread") has been
380	changed to libthr.  If you wish to have libkse as your default,
381	use option DEFAULT_THREAD_LIB=libkse for the buildworld.
382
38320070423:
384	The ABI breakage in sendmail(8)'s libmilter has been repaired
385	so it is no longer necessary to recompile mail filters (aka,
386	milters).  If you recompiled mail filters after the 20070408
387	note, it is not necessary to recompile them again.
388
38920070417:
390	The new trunk(4) driver has been renamed to lagg(4) as it better
391	reflects its purpose. ifconfig will need to be recompiled.
392
39320070408:
394	sendmail(8) has been updated to version 8.14.1.  Mail filters
395	(aka, milters) compiled against the libmilter included in the
396	base operating system should be recompiled.
397
39820070302:
399	Firmwares for ipw(4) and iwi(4) are now included in the base tree.
400	In order to use them one must agree to the respective LICENSE in
401	share/doc/legal and define legal.intel_<name>.license_ack=1 via
402	loader.conf(5) or kenv(1).  Make sure to deinstall the now
403	deprecated modules from the respective firmware ports.
404
40520070228:
406	The name resolution/mapping functions addr2ascii(3) and ascii2addr(3)
407	were removed from FreeBSD's libc. These originally came from INRIA
408	IPv6. Nothing in FreeBSD ever used them. They may be regarded as
409	deprecated in previous releases.
410	The AF_LINK support for getnameinfo(3) was merged from NetBSD to
411	replace it as a more portable (and re-entrant) API.
412
41320070224:
414	To support interrupt filtering a modification to the newbus API
415	has occurred, ABI was broken and __FreeBSD_version was bumped
416	to 700031. Please make sure that your kernel and modules are in
417	sync. For more info:
418	http://docs.freebsd.org/cgi/mid.cgi?20070221233124.GA13941
419
42020070224:
421	The IPv6 multicast forwarding code may now be loaded into GENERIC
422	kernels by loading the ip_mroute.ko module. This is built into the
423	module unless WITHOUT_INET6 or WITHOUT_INET6_SUPPORT options are
424	set; see src.conf(5) for more information.
425
42620070214:
427	The output of netstat -r has changed. Without -n, we now only
428	print a "network name" without the prefix length if the network
429	address and mask exactly match a Class A/B/C network, and an entry
430	exists in the nsswitch "networks" map.
431	With -n, we print the full unabbreviated CIDR network prefix in
432	the form "a.b.c.d/p". 0.0.0.0/0 is always printed as "default".
433	This change is in preparation for changes such as equal-cost
434	multipath, and to more generally assist operational deployment
435	of FreeBSD as a modern IPv4 router.
436
43720070210:
438	PIM has been turned on by default in the IPv4 multicast
439	routing code. The kernel option 'PIM' has now been removed.
440	PIM is now built by default if option 'MROUTING' is specified.
441	It may now be loaded into GENERIC kernels by loading the
442	ip_mroute.ko module.
443
44420070207:
445	Support for IPIP tunnels (VIFF_TUNNEL) in IPv4 multicast routing
446	has been removed. Its functionality may be achieved by explicitly
447	configuring gif(4) interfaces and using the 'phyint' keyword in
448	mrouted.conf.
449	XORP does not support source-routed IPv4 multicast tunnels nor the
450	integrated IPIP tunneling, therefore it is not affected by this
451	change. The __FreeBSD_version macro has been bumped to 700030.
452
45320061221:
454	Support for PCI Message Signalled Interrupts has been
455	re-enabled in the bge driver, only for those chips which are
456	believed to support it properly.  If there are any problems,
457	MSI can be disabled completely by setting the
458	'hw.pci.enable_msi' and 'hw.pci.enable_msix' tunables to 0
459	in the loader.
460
46120061214:
462	Support for PCI Message Signalled Interrupts has been
463	disabled again in the bge driver.  Many revisions of the
464	hardware fail to support it properly.  Support can be
465	re-enabled by removing the #define of BGE_DISABLE_MSI in
466	"src/sys/dev/bge/if_bge.c".
467
46820061214:
469	Support for PCI Message Signalled Interrupts has been added
470	to the bge driver.  If there are any problems, MSI can be
471	disabled completely by setting the 'hw.pci.enable_msi' and
472	'hw.pci.enable_msix' tunables to 0 in the loader.
473
47420061205:
475	The removal of several facets of the experimental Threading
476	system from the kernel means that the proc and thread structures
477	have changed quite a bit. I suggest all kernel modules that might
478	reference these structures be recompiled.. Especially the
479	linux module.
480
48120061126:
482	Sound infrastructure has been updated with various fixes and
483	improvements. Most of the changes are pretty much transparent,
484	with exceptions of followings:
485	1) All sound driver specific sysctls (hw.snd.pcm%d.*) have been
486	   moved to their own dev sysctl nodes, for example:
487		hw.snd.pcm0.vchans -> dev.pcm.0.vchans
488	2) /dev/dspr%d.%d has been deprecated. Each channel now has its
489	   own chardev in the form of "dsp%d.<function>%d", where <function>
490	   is p = playback, r = record and v = virtual, respectively. Users
491	   are encouraged to use these devs instead of (old) "/dev/dsp%d.%d".
492	   This does not affect those who are using "/dev/dsp".
493
49420061122:
495	geom(4)'s gmirror(8) class metadata structure has been
496	rev'd from v3 to v4. If you update across this point and
497	your metadata is converted for you, you will not be easily
498	able to downgrade since the /boot/kernel.old/geom_mirror.ko
499	kernel module will be unable to read the v4 metadata.  You
500	can resolve this by doing from the loader(8) prompt:
501
502		set vfs.root.mountfrom="ufs:/dev/XXX"
503
504	where XXX is the root slice of one of the disks that composed
505	the mirror (i.e.: /dev/ad0s1a). You can then rebuild
506	the array the same way you built it originally.
507
50820061122:
509	The following binaries have been disconnected from the build:
510	mount_devfs, mount_ext2fs, mount_fdescfs, mount_procfs, mount_linprocfs,
511	and mount_std.  The functionality of these programs has been
512	moved into the mount program.  For example, to mount a devfs
513	filesystem, instead of using mount_devfs, use: "mount -t devfs".
514	This does not affect entries in /etc/fstab, since entries in
515	/etc/fstab are always processed with "mount -t fstype".
516
51720061113:
518	Support for PCI Message Signalled Interrupts on i386 and amd64
519	has been added to the kernel and various drivers will soon be
520	updated to use MSI when it is available.  If there are any problems,
521	MSI can be disabled completely by setting the 'hw.pci.enable_msi'
522	and 'hw.pci.enable_msix' tunables to 0 in the loader.
523
52420061110:
525	The MUTEX_PROFILING option has been renamed to LOCK_PROFILING.
526	The lockmgr object layout has been changed as a result of having
527	a lock_object embedded in it. As a consequence all file system
528	kernel modules must be re-compiled. The mutex profiling man page
529	has not yet been updated to reflect this change.
530
53120061026:
532	KSE in the kernel has now been made optional and turned on by
533	default. Use 'nooption KSE' in your kernel config to turn it
534	off. All kernel modules *must* be recompiled after this change.
535	There-after, modules from a KSE kernel should be compatible with
536	modules from a NOKSE kernel due to the temporary padding fields
537	added to 'struct proc'.
538
53920060929:
540	mrouted and its utilities have been removed from the base system.
541
54220060927:
543	Some ioctl(2) command codes have changed.  Full backward ABI
544	compatibility is provided if the "options COMPAT_FREEBSD6" is
545	present in the kernel configuration file.  Make sure to add
546	this option to your kernel config file, or recompile X.Org
547	and the rest of ports; otherwise they may refuse to work.
548
54920060924:
550	tcpslice has been removed from the base system.
551
55220060913:
553	The sizes of struct tcpcb (and struct xtcpcb) have changed due to
554	the rewrite of TCP syncookies.  Tools like netstat, sockstat, and
555	systat needs to be rebuilt.
556
55720060903:
558	libpcap updated to v0.9.4 and tcpdump to v3.9.4
559
56020060816:
561	The IPFIREWALL_FORWARD_EXTENDED option is gone and the behaviour
562	for IPFIREWALL_FORWARD is now as it was before when it was first
563	committed and for years after. The behaviour is now ON.
564
56520060725:
566	enigma(1)/crypt(1) utility has been changed on 64 bit architectures.
567	Now it can decrypt files created from different architectures.
568	Unfortunately, it is no longer able to decrypt a cipher text
569	generated with an older version on 64 bit architectures.
570	If you have such a file, you need old utility to decrypt it.
571
57220060709:
573 	The interface version of the i4b kernel part has changed. So
574 	after updating the kernel sources and compiling a new kernel,
575 	the i4b user space tools in "/usr/src/usr.sbin/i4b" must also
576 	be rebuilt, and vice versa.
577
57820060627:
579	The XBOX kernel now defaults to the nfe(4) driver instead of
580	the nve(4) driver. Please update your configuration
581	accordingly.
582
58320060514:
584	The i386-only lnc(4) driver for the AMD Am7900 LANCE and Am79C9xx
585	PCnet family of NICs has been removed. The new le(4) driver serves
586	as an equivalent but cross-platform replacement with the pcn(4)
587	driver still providing performance-optimized support for the subset
588	of AMD Am79C971 PCnet-FAST and greater chips as before.
589
59020060511:
591	The machdep.* sysctls and the adjkerntz utility have been
592	modified a bit.  The new adjkerntz utility uses the new
593	sysctl names and sysctlbyname() calls, so it may be impossible
594	to run an old /sbin/adjkerntz utility in single-user mode
595	with a new kernel.  Replace the `adjkerntz -i' step before
596	`make installworld' with:
597
598	    /usr/obj/usr/src/sbin/adjkerntz/adjkerntz -i
599
600	and proceed as usual with the rest of the installworld-stage
601	steps.  Otherwise, you risk installing binaries with their
602	timestamp set several hours in the future, especially if
603	you are running with local time set to GMT+X hours.
604
60520060412:
606	The ip6fw utility has been removed.  The behavior provided by
607	ip6fw has been in ipfw2 for a good while and the rc.d scripts
608	have been updated to deal with it.  There are some rules that
609	might not migrate cleanly.  Use rc.firewall6 as a template to
610	rewrite rules.
611
61220060428:
613	The puc(4) driver has been overhauled. The ebus(4) and sbus(4)
614	attachments have been removed. Make sure to configure scc(4)
615	on sparc64. Note also that by default puc(4) will use uart(4)
616	and not sio(4) for serial ports because interrupt handling has
617	been optimized for multi-port serial cards and only uart(4)
618	implements the interface to support it.
619
62020060330:
621	The scc(4) driver replaces puc(4) for Serial Communications
622	Controllers (SCCs) like the Siemens SAB82532 and the Zilog
623	Z8530. On sparc64, it is advised to add scc(4) to the kernel
624	configuration to make sure that the serial ports remain
625	functional.
626
62720060317:
628	Most world/kernel related NO_* build options changed names.
629	New knobs have common prefixes WITHOUT_*/WITH_* (modelled
630	after FreeBSD ports) and should be set in /etc/src.conf
631	(the src.conf(5) manpage is provided).  Full backwards
632	compatibility is maintained for the time being though it's
633	highly recommended to start moving old options out of the
634	system-wide /etc/make.conf file into the new /etc/src.conf
635	while also properly renaming them.  More conversions will
636	likely follow.  Posting to current@:
637
638	http://lists.freebsd.org/pipermail/freebsd-current/2006-March/061725.html
639
64020060305:
641	The NETSMBCRYPTO kernel option has been retired because its
642	functionality is always included in NETSMB and smbfs.ko now.
643
64420060303:
645	The TDFX_LINUX kernel option was retired and replaced by the
646	tdfx_linux device.  The latter can be loaded as the 3dfx_linux.ko
647	kernel module.  Loading it alone should suffice to get 3dfx support
648	for Linux apps because it will pull in 3dfx.ko and linux.ko through
649	its dependencies.
650
65120060204:
652	The 'audit' group was added to support the new auditing functionality
653	in the base system.  Be sure to follow the directions for updating,
654	including the requirement to run mergemaster -p.
655
65620060201:
657	The kernel ABI to file system modules was changed on i386.
658	Please make sure that your kernel and modules are in sync.
659
66020060118:
661	This actually occured some time ago, but installing the kernel
662	now also installs a bunch of symbol files for the kernel modules.
663	This increases the size of /boot/kernel to about 67Mbytes. You
664	will need twice this if you will eventually back this up to kernel.old
665	on your next install.
666	If you have a shortage of room in your root partition, you should add
667	-DINSTALL_NODEBUG to your make arguments or add INSTALL_NODEBUG="yes"
668	to your /etc/make.conf.
669
67020060113:
671	libc's malloc implementation has been replaced.  This change has the
672	potential to uncover application bugs that previously went unnoticed.
673	See the malloc(3) manual page for more details.
674
67520060112:
676	The generic netgraph(4) cookie has been changed. If you upgrade
677	kernel passing this point, you also need to upgrade userland
678	and netgraph(4) utilities like ports/net/mpd or ports/net/mpd4.
679
68020060106:
681	si(4)'s device files now contain the unit number.
682	Uses of {cua,tty}A[0-9a-f] should be replaced by {cua,tty}A0[0-9a-f].
683
68420060106:
685	The kernel ABI was mostly destroyed due to a change in the size
686	of struct lock_object which is nested in other structures such
687	as mutexes which are nested in all sorts of other structures.
688	Make sure your kernel and modules are in sync.
689
69020051231:
691	The page coloring algorithm in the VM subsystem was converted
692	from tuning with kernel options to autotuning. Please remove
693	any PQ_* option except PQ_NOOPT from your kernel config.
694
69520051211:
696	The net80211-related tools in the tools/tools/ath directory
697	have been moved to tools/tools/net80211 and renamed with a
698	"wlan" prefix.  Scripts that use them should be adjusted
699	accordingly.
700
70120051202:
702	Scripts in the local_startup directories (as defined in
703	/etc/defaults/rc.conf) that have the new rc.d semantics will
704	now be run as part of the base system rcorder. If there are
705	errors or problems with one of these local scripts, it could
706	cause boot problems. If you encounter such problems, boot in
707	single user mode, remove that script from the */rc.d directory.
708	Please report the problem to the port's maintainer, and the
709	freebsd-ports@freebsd.org mailing list.
710
71120051129:
712	The nodev mount option was deprecated in RELENG_6 (where it
713	was a no-op), and is now unsupported.  If you have nodev or dev listed
714	in /etc/fstab, remove it, otherwise it will result in a mount error.
715
71620051129:
717	ABI between ipfw(4) and ipfw(8) has been changed. You need
718	to rebuild ipfw(8) when rebuilding kernel.
719
72020051108:
721	rp(4)'s device files now contain the unit number.
722	Uses of {cua,tty}R[0-9a-f] should be replaced by {cua,tty}R0[0-9a-f].
723
72420051029:
725	/etc/rc.d/ppp-user has been renamed to /etc/rc.d/ppp.
726	Its /etc/rc.conf.d configuration file has been `ppp' from
727	the beginning, and hence there is no need to touch it.
728
72920051014:
730	Now most modules get their build-time options from the kernel
731	configuration file.  A few modules still have fixed options
732	due to their non-conformant implementation, but they will be
733	corrected eventually.  You may need to review the options of
734	the modules in use, explicitly specify the non-default options
735	in the kernel configuration file, and rebuild the kernel and
736	modules afterwards.
737
73820051001:
739	kern.polling.enable sysctl MIB is now deprecated. Use ifconfig(8)
740	to turn polling(4) on your interfaces.
741
74220050927:
743	The old bridge(4) implementation was retired.  The new
744	if_bridge(4) serves as a full functional replacement.
745
74620050722:
747	The ai_addrlen of a struct addrinfo was changed to a socklen_t
748	to conform to POSIX-2001.  This change broke an ABI
749	compatibility on 64 bit architecture.  You have to recompile
750	userland programs that use getaddrinfo(3) on 64 bit
751	architecture.
752
75320050711:
754	RELENG_6 branched here.
755
75620050629:
757	The pccard_ifconfig rc.conf variable has been removed and a new
758	variable, ifconfig_DEFAULT has been introduced.  Unlike
759	pccard_ifconfig, ifconfig_DEFAULT applies to ALL interfaces that
760	do not have ifconfig_ifn entries rather than just those in
761	removable_interfaces.
762
76320050616:
764	Some previous versions of PAM have permitted the use of
765	non-absolute paths in /etc/pam.conf or /etc/pam.d/* when referring
766	to third party PAM modules in /usr/local/lib.  A change has been
767	made to require the use of absolute paths in order to avoid
768	ambiguity and dependence on library path configuration, which may
769	affect existing configurations.
770
77120050610:
772	Major changes to network interface API.  All drivers must be
773	recompiled.  Drivers not in the base system will need to be
774	updated to the new APIs.
775
77620050609:
777	Changes were made to kinfo_proc in sys/user.h.  Please recompile
778	userland, or commands like `fstat', `pkill', `ps', `top' and `w'
779	will not behave correctly.
780
781	The API and ABI for hwpmc(4) have changed with the addition
782	of sampling support.  Please recompile lib/libpmc(3) and
783	usr.sbin/{pmcstat,pmccontrol}.
784
78520050606:
786	The OpenBSD dhclient was imported in place of the ISC dhclient
787	and the network interface configuration scripts were updated
788	accordingly.  If you use DHCP to configure your interfaces, you
789	must now run devd.  Also, DNS updating was lost so you will need
790	to find a workaround if you use this feature.
791
792	The '_dhcp' user was added to support the OpenBSD dhclient.  Be
793	sure to run mergemaster -p (like you are supposed to do every time
794	anyway).
795
79620050605:
797	if_bridge was added to the tree. This has changed struct ifnet.
798	Please recompile userland and all network related modules.
799
80020050603:
801	The n_net of a struct netent was changed to an uint32_t, and
802	1st argument of getnetbyaddr() was changed to an uint32_t, to
803	conform to POSIX-2001.  These changes broke an ABI
804	compatibility on 64 bit architecture.  With these changes,
805	shlib major of libpcap was bumped.  You have to recompile
806	userland programs that use getnetbyaddr(3), getnetbyname(3),
807	getnetent(3) and/or libpcap on 64 bit architecture.
808
80920050528:
810	Kernel parsing of extra options on '#!' first lines of shell
811	scripts has changed.  Lines with multiple options likely will
812	fail after this date.  For full details, please see
813		http://people.freebsd.org/~gad/Updating-20050528.txt
814
81520050503:
816	The packet filter (pf) code has been updated to OpenBSD 3.7
817	Please note the changed anchor syntax and the fact that
818	authpf(8) now needs a mounted fdescfs(5) to function.
819
82020050415:
821	The NO_MIXED_MODE kernel option has been removed from the i386
822	amd64 platforms as its use has been superceded by the new local
823	APIC timer code.  Any kernel config files containing this option
824	should be updated.
825
82620050227:
827	The on-disk format of LC_CTYPE files was changed to be machine
828	independent.  Please make sure NOT to use NO_CLEAN buildworld
829	when crossing this point. Crossing this point also requires
830	recompile or reinstall of all locale depended packages.
831
83220050225:
833	The ifi_epoch member of struct if_data has been changed to
834	contain the uptime at which the interface was created or the
835	statistics zeroed rather then the wall clock time because
836	wallclock time may go backwards.  This should have no impact
837	unless an snmp implementation is using this value (I know of
838	none at this point.)
839
84020050224:
841	The acpi_perf and acpi_throttle drivers are now part of the
842	acpi(4) main module.  They are no longer built separately.
843
84420050223:
845	The layout of struct image_params has changed. You have to
846	recompile all compatibility modules (linux, svr4, etc) for use
847	with the new kernel.
848
84920050223:
850	The p4tcc driver has been merged into cpufreq(4).  This makes
851	"options CPU_ENABLE_TCC" obsolete.  Please load cpufreq.ko or
852	compile in "device cpufreq" to restore this functionality.
853
85420050220:
855	The responsibility of recomputing the file system summary of
856	a SoftUpdates-enabled dirty volume has been transferred to the
857	background fsck.  A rebuild of fsck(8) utility is recommended
858	if you have updated the kernel.
859
860	To get the old behavior (recompute file system summary at mount
861	time), you can set vfs.ffs.compute_summary_at_mount=1 before
862	mounting the new volume.
863
86420050206:
865	The cpufreq import is complete.  As part of this, the sysctls for
866	acpi(4) throttling have been removed.  The power_profile script
867	has been updated, so you can use performance/economy_cpu_freq in
868	rc.conf(5) to set AC on/offline cpu frequencies.
869
87020050206:
871	NG_VERSION has been increased. Recompiling kernel (or ng_socket.ko)
872	requires recompiling libnetgraph and userland netgraph utilities.
873
87420050114:
875	Support for abbreviated forms of a number of ipfw options is
876	now deprecated.  Warnings are printed to stderr indicating the
877	correct full form when a match occurs.  Some abbreviations may
878	be supported at a later date based on user feedback.  To be
879	considered for support, abbreviations must be in use prior to
880	this commit and unlikely to be confused with current key words.
881
88220041221:
883	By a popular demand, a lot of NOFOO options were renamed
884	to NO_FOO (see bsd.compat.mk for a full list).  The old
885	spellings are still supported, but will cause annoying
886	warnings on stderr.  Make sure you upgrade properly (see
887	the COMMON ITEMS: section later in this file).
888
88920041219:
890	Auto-loading of ancillary wlan modules such as wlan_wep has
891	been temporarily disabled; you need to statically configure
892	the modules you need into your kernel or explicitly load them
893	prior to use.  Specifically, if you intend to use WEP encryption
894	with an 802.11 device load/configure wlan_wep; if you want to
895	use WPA with the ath driver load/configure wlan_tkip, wlan_ccmp,
896	and wlan_xauth as required.
897
89820041213:
899	The behaviour of ppp(8) has changed slightly.  If lqr is enabled
900	(``enable lqr''), older versions would revert to LCP ECHO mode on
901	negotiation failure.  Now, ``enable echo'' is required for this
902	behaviour.  The ppp version number has been bumped to 3.4.2 to
903	reflect the change.
904
90520041201:
906	The wlan support has been updated to split the crypto support
907	into separate modules.  For static WEP you must configure the
908	wlan_wep module in your system or build and install the module
909	in place where it can be loaded (the kernel will auto-load
910	the module when a wep key is configured).
911
91220041201:
913	The ath driver has been updated to split the tx rate control
914	algorithm into a separate module.  You need to include either
915	ath_rate_onoe or ath_rate_amrr when configuring the kernel.
916
91720041116:
918	Support for systems with an 80386 CPU has been removed.  Please
919	use FreeBSD 5.x or earlier on systems with an 80386.
920
92120041110:
922	We have had a hack which would mount the root filesystem
923	R/W if the device were named 'md*'.  As part of the vnode
924	work I'm doing I have had to remove this hack.  People
925	building systems which use preloaded MD root filesystems
926	may need to insert a "/sbin/mount -u -o rw /dev/md0 /" in
927	their /etc/rc scripts.
928
92920041104:
930	FreeBSD 5.3 shipped here.
931
93220041102:
933	The size of struct tcpcb has changed again due to the removal
934	of RFC1644 T/TCP.  You have to recompile userland programs that
935	read kmem for tcp sockets directly (netstat, sockstat, etc.)
936
93720041022:
938	The size of struct tcpcb has changed.  You have to recompile
939	userland programs that read kmem for tcp sockets directly
940	(netstat, sockstat, etc.)
941
94220041016:
943	RELENG_5 branched here.  For older entries, please see updating
944	in the RELENG_5 branch.
945
946COMMON ITEMS:
947
948	General Notes
949	-------------
950	Avoid using make -j when upgrading.  From time to time in the
951	past there have been problems using -j with buildworld and/or
952	installworld.  This is especially true when upgrading between
953	"distant" versions (eg one that cross a major release boundary
954	or several minor releases, or when several months have passed
955	on the -current branch).
956
957	Sometimes, obscure build problems are the result of environment
958	poisoning.  This can happen because the make utility reads its
959	environment when searching for values for global variables.
960	To run your build attempts in an "environmental clean room",
961	prefix all make commands with 'env -i '.  See the env(1) manual
962	page for more details.
963
964	When upgrading from one major version to another it is generally
965	best to upgrade to the latest code in the currently installed branch
966	first, then do an upgrade to the new branch. This is the best-tested
967	upgrade path, and has the highest probability of being successful.
968	Please try this approach before reporting problems with a major
969	version upgrade.
970
971	To build a kernel
972	-----------------
973	If you are updating from a prior version of FreeBSD (even one just
974	a few days old), you should follow this procedure.  It is the most
975	failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
976
977	make kernel-toolchain
978	make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
979	make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
980
981	To test a kernel once
982	---------------------
983	If you just want to boot a kernel once (because you are not sure
984	if it works, or if you want to boot a known bad kernel to provide
985	debugging information) run
986	make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
987	nextboot -k testkernel
988
989	To just build a kernel when you know that it won't mess you up
990	--------------------------------------------------------------
991	This assumes you are already running a 5.X system.  Replace
992	${arch} with the architecture of your machine (e.g. "i386",
993	"alpha", "amd64", "ia64", "pc98", "sparc64", etc).
994
995	cd src/sys/${arch}/conf
996	config KERNEL_NAME_HERE
997	cd ../compile/KERNEL_NAME_HERE
998	make depend
999	make
1000	make install
1001
1002	If this fails, go to the "To build a kernel" section.
1003
1004	To rebuild everything and install it on the current system.
1005	-----------------------------------------------------------
1006	# Note: sometimes if you are running current you gotta do more than
1007	# is listed here if you are upgrading from a really old current.
1008
1009	<make sure you have good level 0 dumps>
1010	make buildworld
1011	make kernel KERNCONF=YOUR_KERNEL_HERE
1012							[1]
1013	<reboot in single user>				[3]
1014	mergemaster -p					[5]
1015	make installworld
1016	make delete-old
1017	mergemaster					[4]
1018	<reboot>
1019
1020
1021	To cross-install current onto a separate partition
1022	--------------------------------------------------
1023	# In this approach we use a separate partition to hold
1024	# current's root, 'usr', and 'var' directories.   A partition
1025	# holding "/", "/usr" and "/var" should be about 2GB in
1026	# size.
1027
1028	<make sure you have good level 0 dumps>
1029	<boot into -stable>
1030	make buildworld
1031	make buildkernel KERNCONF=YOUR_KERNEL_HERE
1032	<maybe newfs current's root partition>
1033	<mount current's root partition on directory ${CURRENT_ROOT}>
1034	make installworld DESTDIR=${CURRENT_ROOT}
1035	make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
1036	make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
1037	cp /etc/fstab ${CURRENT_ROOT}/etc/fstab 		   # if newfs'd
1038	<edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
1039	<reboot into current>
1040	<do a "native" rebuild/install as described in the previous section>
1041	<maybe install compatibility libraries from ports/misc/compat*>
1042 	<reboot>
1043
1044
1045	To upgrade in-place from 5.x-stable to current
1046	----------------------------------------------
1047	<make sure you have good level 0 dumps>
1048	make buildworld					[9]
1049	make kernel KERNCONF=YOUR_KERNEL_HERE		[8]
1050							[1]
1051	<reboot in single user>				[3]
1052	mergemaster -p					[5]
1053	make installworld
1054	make delete-old
1055	mergemaster -i					[4]
1056	<reboot>
1057
1058	Make sure that you've read the UPDATING file to understand the
1059	tweaks to various things you need.  At this point in the life
1060	cycle of current, things change often and you are on your own
1061	to cope.  The defaults can also change, so please read ALL of
1062	the UPDATING entries.
1063
1064	Also, if you are tracking -current, you must be subscribed to
1065	freebsd-current@freebsd.org.  Make sure that before you update
1066	your sources that you have read and understood all the recent
1067	messages there.  If in doubt, please track -stable which has
1068	much fewer pitfalls.
1069
1070	[1] If you have third party modules, such as vmware, you
1071	should disable them at this point so they don't crash your
1072	system on reboot.
1073
1074	[3] From the bootblocks, boot -s, and then do
1075		fsck -p
1076		mount -u /
1077		mount -a
1078		cd src
1079		adjkerntz -i		# if CMOS is wall time
1080	Also, when doing a major release upgrade, it is required that
1081	you boot into single user mode to do the installworld.
1082
1083	[4] Note: This step is non-optional.  Failure to do this step
1084	can result in a significant reduction in the functionality of the
1085	system.  Attempting to do it by hand is not recommended and those
1086	that pursue this avenue should read this file carefully, as well
1087	as the archives of freebsd-current and freebsd-hackers mailing lists
1088	for potential gotchas.
1089
1090	[5] Usually this step is a noop.  However, from time to time
1091	you may need to do this if you get unknown user in the following
1092	step.  It never hurts to do it all the time.  You may need to
1093	install a new mergemaster (cd src/usr.sbin/mergemaster && make
1094	install) after the buildworld before this step if you last updated
1095	from current before 20020224 or from -stable before 20020408.
1096
1097	[8] In order to have a kernel that can run the 4.x binaries
1098	needed to do an installworld, you must include the COMPAT_FREEBSD4
1099	option in your kernel.  Failure to do so may leave you with a system
1100	that is hard to boot to recover. A similar kernel option COMPAT_FREEBSD5
1101	is required to run the 5.x binaries on more recent kernels.
1102
1103	Make sure that you merge any new devices from GENERIC since the
1104	last time you updated your kernel config file.
1105
1106	[9] When checking out sources, you must include the -P flag to have
1107	cvs prune empty directories.
1108
1109	If CPUTYPE is defined in your /etc/make.conf, make sure to use the
1110	"?=" instead of the "=" assignment operator, so that buildworld can
1111	override the CPUTYPE if it needs to.
1112
1113	MAKEOBJDIRPREFIX must be defined in an environment variable, and
1114	not on the command line, or in /etc/make.conf.  buildworld will
1115	warn if it is improperly defined.
1116FORMAT:
1117
1118This file contains a list, in reverse chronological order, of major
1119breakages in tracking -current.  Not all things will be listed here,
1120and it only starts on October 16, 2004.  Updating files can found in
1121previous releases if your system is older than this.
1122
1123Copyright information:
1124
1125Copyright 1998-2005 M. Warner Losh.  All Rights Reserved.
1126
1127Redistribution, publication, translation and use, with or without
1128modification, in full or in part, in any form or format of this
1129document are permitted without further permission from the author.
1130
1131THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
1132IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1133WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1134DISCLAIMED.  IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
1135INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1136(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1137SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1138HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1139STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
1140IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1141POSSIBILITY OF SUCH DAMAGE.
1142
1143If you find this document useful, and you want to, you may buy the
1144author a beer.
1145
1146Contact Warner Losh if you have any questions about your use of
1147this document.
1148
1149$FreeBSD$
1150