]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - UPDATING
New release notes: msk(4), arcmsr(4) 1.20.00.13.
[FreeBSD/FreeBSD.git] / UPDATING
1 Updating Information for FreeBSD current users
2
3 This file is maintained and copyrighted by M. Warner Losh
4 <imp@village.org>.  See end of file for further details.  For commonly
5 done items, please see the COMMON ITEMS: section later in the file.
6
7 Items affecting the ports and packages system can be found in
8 /usr/ports/UPDATING.  Please read that file before running
9 portupgrade.
10
11 NOTE TO PEOPLE WHO THINK THAT FreeBSD 7.x IS SLOW:
12         FreeBSD 7.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.
23
24 20061205:
25         The removal of several facets of the experimental Threading 
26         system from the kernel means that the proc and thread structures 
27         have changed quite a bit. I suggest all kernel modules that might
28         reference these structures be recompiled.. Especially the
29         linux module.
30
31 20061126:
32         Sound infrastructure has been updated with various fixes and
33         improvements. Most of the changes are pretty much transparent,
34         with exceptions of followings:
35         1) All sound driver specific sysctls (hw.snd.pcm%d.*) have been
36            moved to their own dev sysctl nodes, for example:
37                 hw.snd.pcm0.vchans -> dev.pcm.0.vchans
38         2) /dev/dspr%d.%d has been deprecated. Each channel now has its
39            own chardev in the form of "dsp%d.<function>%d", where <function>
40            is p = playback, r = record and v = virtual, respectively. Users
41            are encouraged to use these devs instead of (old) "/dev/dsp%d.%d".
42            This does not affect those who are using "/dev/dsp".
43
44 20061122:
45         The following binaries have been disconnected from the build:
46         mount_devfs, mount_ext2fs, mount_fdescfs, mount_procfs, mount_linprocfs,
47         and mount_std.  The functionality of these programs has been
48         moved into the mount program.  For example, to mount a devfs
49         filesystem, instead of using mount_devfs, use: "mount -t devfs".
50         This does not affect entries in /etc/fstab, since entries in
51         /etc/fstab are always processed with "mount -t fstype".
52
53 20061113:
54         Support for PCI Message Signalled Interrupts on i386 and amd64
55         has been added to the kernel and various drivers will soon be
56         updated to use MSI when it is available.  If there are any problems,
57         MSI can be disabled completely by setting the 'hw.pci.enable_msi'
58         and 'hw.pci.enable_msix' tunables to 0 in the loader.
59
60 20061110:
61         The MUTEX_PROFILING option has been renamed to LOCK_PROFILING.
62         The lockmgr object layout has been changed as a result of having
63         a lock_object embedded in it. As a consequence all file system
64         kernel modules must be re-compiled. The mutex profiling man page 
65         has not yet been updated to reflect this change.
66
67 20061026:
68         KSE in the kernel has now been made optional and turned on by
69         default. Use 'nooption KSE' in your kernel config to turn it
70         off. All kernel modules *must* be recompiled after this change.
71         There-after, modules from a KSE kernel should be compatible with
72         modules from a NOKSE kernel due to the temporary padding fields
73         added to 'struct proc'.
74
75 20060929:
76         mrouted and its utilities have been removed from the base system.
77
78 20060927:
79         Some ioctl(2) command codes have changed.  Full backward ABI
80         compatibility is provided if the "options COMPAT_FREEBSD6" is
81         present in the kernel configuration file.  Make sure to add
82         this option to your kernel config file, or recompile X.Org
83         and the rest of ports; otherwise they may refuse to work.
84
85 20060924:
86         tcpslice has been removed from the base system.
87
88 20060913:
89         The sizes of struct tcpcb (and struct xtcpcb) have changed due to
90         the rewrite of TCP syncookies.  Tools like netstat, sockstat, and
91         systat needs to be rebuilt.
92
93 20060903:
94         libpcap updated to v0.9.4 and tcpdump to v3.9.4
95
96 20060816:
97         The IPFIREWALL_FORWARD_EXTENDED option is gone and the behaviour
98         for IPFIREWALL_FORWARD is now as it was before when it was first
99         committed and for years after. The behaviour is now ON.
100
101 20060725:
102         enigma(1)/crypt(1) utility has been changed on 64 bit architectures.
103         Now it can decrypt files created from different architectures.
104         Unfortunately, it is no longer able to decrypt a cipher text
105         generated with an older version on 64 bit architectures.
106         If you have such a file, you need old utility to decrypt it.
107
108 20060709:
109         The interface version of the i4b kernel part has changed. So
110         after updating the kernel sources and compiling a new kernel,
111         the i4b user space tools in "/usr/src/usr.sbin/i4b" must also
112         be rebuilt, and vice versa.
113  
114 20060627:
115         The XBOX kernel now defaults to the nfe(4) driver instead of
116         the nve(4) driver. Please update your configuration
117         accordingly.
118
119 20060514:
120         The i386-only lnc(4) driver for the AMD Am7900 LANCE and Am79C9xx
121         PCnet family of NICs has been removed. The new le(4) driver serves
122         as an equivalent but cross-platform replacement with the pcn(4)
123         driver still providing performance-optimized support for the subset
124         of AMD Am79C971 PCnet-FAST and greater chips as before.
125
126 20060511:
127         The machdep.* sysctls and the adjkerntz utility have been
128         modified a bit.  The new adjkerntz utility uses the new
129         sysctl names and sysctlbyname() calls, so it may be impossible
130         to run an old /sbin/adjkerntz utility in single-user mode
131         with a new kernel.  Replace the `adjkerntz -i' step before
132         `make installworld' with:
133
134             /usr/obj/usr/src/sbin/adjkerntz/adjkerntz -i
135
136         and proceed as usual with the rest of the installworld-stage
137         steps.  Otherwise, you risk installing binaries with their
138         timestamp set several hours in the future, especially if
139         you are running with local time set to GMT+X hours.
140
141 20060412:
142         The ip6fw utility has been removed.  The behavior provided by
143         ip6fw has been in ipfw2 for a good while and the rc.d scripts
144         have been updated to deal with it.  There are some rules that
145         might not migrate cleanly.  Use rc.firewall6 as a template to
146         rewrite rules.
147
148 20060428:
149         The puc(4) driver has been overhauled. The ebus(4) and sbus(4)
150         attachments have been removed. Make sure to configure scc(4)
151         on sparc64. Note also that by default puc(4) will use uart(4)
152         and not sio(4) for serial ports because interrupt handling has
153         been optimized for multi-port serial cards and only uart(4)
154         implements the interface to support it.
155
156 20060330:
157         The scc(4) driver replaces puc(4) for Serial Communications
158         Controllers (SCCs) like the Siemens SAB82532 and the Zilog
159         Z8530. On sparc64, it is advised to add scc(4) to the kernel
160         configuration to make sure that the serial ports remain
161         functional.
162
163 20060317:
164         Most world/kernel related NO_* build options changed names.
165         New knobs have common prefixes WITHOUT_*/WITH_* (modelled
166         after FreeBSD ports) and should be set in /etc/src.conf
167         (the src.conf(5) manpage is provided).  Full backwards
168         compatibility is maintained for the time being though it's
169         highly recommended to start moving old options out of the
170         system-wide /etc/make.conf file into the new /etc/src.conf
171         while also properly renaming them.  More conversions will
172         likely follow.  Posting to current@:
173
174         http://lists.freebsd.org/pipermail/freebsd-current/2006-March/061725.html
175
176 20060305:
177         The NETSMBCRYPTO kernel option has been retired because its
178         functionality is always included in NETSMB and smbfs.ko now.
179
180 20060303:
181         The TDFX_LINUX kernel option was retired and replaced by the
182         tdfx_linux device.  The latter can be loaded as the 3dfx_linux.ko
183         kernel module.  Loading it alone should suffice to get 3dfx support
184         for Linux apps because it will pull in 3dfx.ko and linux.ko through
185         its dependencies.
186
187 20060204:
188         The 'audit' group was added to support the new auditing functionality
189         in the base system.  Be sure to follow the directions for updating,
190         including the requirement to run mergemaster -p.
191
192 20060201:
193         The kernel ABI to file system modules was changed on i386.
194         Please make sure that your kernel and modules are in sync.
195         
196 20060118:
197         This actually occured some time ago, but installing the kernel
198         now also installs a bunch of symbol files for the kernel modules.
199         This increases the size of /boot/kernel to about 67Mbytes. You
200         will need twice this if you will eventually back this up to kernel.old
201         on your next install.
202         If you have a shortage of room in your root partition, you should add
203         -DINSTALL_NODEBUG to your make arguments or add INSTALL_NODEBUG="yes"
204         to your /etc/make.conf.
205
206 20060113:
207         libc's malloc implementation has been replaced.  This change has the
208         potential to uncover application bugs that previously went unnoticed.
209         See the malloc(3) manual page for more details.
210
211 20060112:
212         The generic netgraph(4) cookie has been changed. If you upgrade
213         kernel passing this point, you also need to upgrade userland
214         and netgraph(4) utilities like ports/net/mpd or ports/net/mpd4.
215
216 20060106:
217         si(4)'s device files now contain the unit number.
218         Uses of {cua,tty}A[0-9a-f] should be replaced by {cua,tty}A0[0-9a-f].
219
220 20060106:
221         The kernel ABI was mostly destroyed due to a change in the size
222         of struct lock_object which is nested in other structures such
223         as mutexes which are nested in all sorts of other structures.
224         Make sure your kernel and modules are in sync.
225
226 20051231:
227         The page coloring algorithm in the VM subsystem was converted
228         from tuning with kernel options to autotuning. Please remove
229         any PQ_* option except PQ_NOOPT from your kernel config.
230
231 20051211:
232         The net80211-related tools in the tools/tools/ath directory
233         have been moved to tools/tools/net80211 and renamed with a
234         "wlan" prefix.  Scripts that use them should be adjusted
235         accordingly.
236
237 20051202:
238         Scripts in the local_startup directories (as defined in
239         /etc/defaults/rc.conf) that have the new rc.d semantics will
240         now be run as part of the base system rcorder. If there are
241         errors or problems with one of these local scripts, it could
242         cause boot problems. If you encounter such problems, boot in
243         single user mode, remove that script from the */rc.d directory.
244         Please report the problem to the port's maintainer, and the
245         freebsd-ports@freebsd.org mailing list.
246
247 20051129:
248         The nodev mount option was deprecated in RELENG_6 (where it
249         was a no-op), and is now unsupported.  If you have nodev or dev listed
250         in /etc/fstab, remove it, otherwise it will result in a mount error.
251
252 20051129:
253         ABI between ipfw(4) and ipfw(8) has been changed. You need
254         to rebuild ipfw(8) when rebuilding kernel.
255
256 20051108:
257         rp(4)'s device files now contain the unit number.
258         Uses of {cua,tty}R[0-9a-f] should be replaced by {cua,tty}R0[0-9a-f].
259
260 20051029:
261         /etc/rc.d/ppp-user has been renamed to /etc/rc.d/ppp.
262         Its /etc/rc.conf.d configuration file has been `ppp' from
263         the beginning, and hence there is no need to touch it.
264
265 20051014:
266         Now most modules get their build-time options from the kernel
267         configuration file.  A few modules still have fixed options
268         due to their non-conformant implementation, but they will be
269         corrected eventually.  You may need to review the options of
270         the modules in use, explicitly specify the non-default options
271         in the kernel configuration file, and rebuild the kernel and
272         modules afterwards.
273
274 20051001:
275         kern.polling.enable sysctl MIB is now deprecated. Use ifconfig(8)
276         to turn polling(4) on your interfaces.
277
278 20050927:
279         The old bridge(4) implementation was retired.  The new
280         if_bridge(4) serves as a full functional replacement.
281
282 20050722:
283         The ai_addrlen of a struct addrinfo was changed to a socklen_t
284         to conform to POSIX-2001.  This change broke an ABI
285         compatibility on 64 bit architecture.  You have to recompile
286         userland programs that use getaddrinfo(3) on 64 bit
287         architecture.
288
289 20050711:
290         RELENG_6 branched here.
291
292 20050629:
293         The pccard_ifconfig rc.conf variable has been removed and a new
294         variable, ifconfig_DEFAULT has been introduced.  Unlike
295         pccard_ifconfig, ifconfig_DEFAULT applies to ALL interfaces that
296         do not have ifconfig_ifn entries rather than just those in
297         removable_interfaces.
298
299 20050616:
300         Some previous versions of PAM have permitted the use of
301         non-absolute paths in /etc/pam.conf or /etc/pam.d/* when referring
302         to third party PAM modules in /usr/local/lib.  A change has been
303         made to require the use of absolute paths in order to avoid
304         ambiguity and dependence on library path configuration, which may
305         affect existing configurations.
306
307 20050610:
308         Major changes to network interface API.  All drivers must be
309         recompiled.  Drivers not in the base system will need to be
310         updated to the new APIs.
311
312 20050609:
313         Changes were made to kinfo_proc in sys/user.h.  Please recompile
314         userland, or commands like `fstat', `pkill', `ps', `top' and `w'
315         will not behave correctly.
316
317         The API and ABI for hwpmc(4) have changed with the addition
318         of sampling support.  Please recompile lib/libpmc(3) and
319         usr.sbin/{pmcstat,pmccontrol}.
320
321 20050606:
322         The OpenBSD dhclient was imported in place of the ISC dhclient
323         and the network interface configuration scripts were updated
324         accordingly.  If you use DHCP to configure your interfaces, you
325         must now run devd.  Also, DNS updating was lost so you will need
326         to find a workaround if you use this feature.
327
328         The '_dhcp' user was added to support the OpenBSD dhclient.  Be
329         sure to run mergemaster -p (like you are supposed to do every time
330         anyway).
331
332 20050605:
333         if_bridge was added to the tree. This has changed struct ifnet.
334         Please recompile userland and all network related modules.
335
336 20050603:
337         The n_net of a struct netent was changed to an uint32_t, and
338         1st argument of getnetbyaddr() was changed to an uint32_t, to
339         conform to POSIX-2001.  These changes broke an ABI
340         compatibility on 64 bit architecture.  With these changes,
341         shlib major of libpcap was bumped.  You have to recompile
342         userland programs that use getnetbyaddr(3), getnetbyname(3),
343         getnetent(3) and/or libpcap on 64 bit architecture.
344
345 20050528:
346         Kernel parsing of extra options on '#!' first lines of shell
347         scripts has changed.  Lines with multiple options likely will
348         fail after this date.  For full details, please see
349                 http://people.freebsd.org/~gad/Updating-20050528.txt
350
351 20050503:
352         The packet filter (pf) code has been updated to OpenBSD 3.7
353         Please note the changed anchor syntax and the fact that
354         authpf(8) now needs a mounted fdescfs(5) to function.
355
356 20050415:
357         The NO_MIXED_MODE kernel option has been removed from the i386
358         amd64 platforms as its use has been superceded by the new local
359         APIC timer code.  Any kernel config files containing this option
360         should be updated.
361
362 20050227:
363         The on-disk format of LC_CTYPE files was changed to be machine
364         independent.  Please make sure NOT to use NO_CLEAN buildworld
365         when crossing this point. Crossing this point also requires
366         recompile or reinstall of all locale depended packages.
367
368 20050225:
369         The ifi_epoch member of struct if_data has been changed to
370         contain the uptime at which the interface was created or the
371         statistics zeroed rather then the wall clock time because
372         wallclock time may go backwards.  This should have no impact
373         unless an snmp implementation is using this value (I know of
374         none at this point.)
375
376 20050224:
377         The acpi_perf and acpi_throttle drivers are now part of the
378         acpi(4) main module.  They are no longer built separately.
379
380 20050223:
381         The layout of struct image_params has changed. You have to
382         recompile all compatibility modules (linux, svr4, etc) for use
383         with the new kernel.
384
385 20050223:
386         The p4tcc driver has been merged into cpufreq(4).  This makes
387         "options CPU_ENABLE_TCC" obsolete.  Please load cpufreq.ko or
388         compile in "device cpufreq" to restore this functionality.
389
390 20050220:
391         The responsibility of recomputing the file system summary of
392         a SoftUpdates-enabled dirty volume has been transferred to the
393         background fsck.  A rebuild of fsck(8) utility is recommended
394         if you have updated the kernel.
395
396         To get the old behavior (recompute file system summary at mount
397         time), you can set vfs.ffs.compute_summary_at_mount=1 before
398         mounting the new volume.
399
400 20050206:
401         The cpufreq import is complete.  As part of this, the sysctls for
402         acpi(4) throttling have been removed.  The power_profile script
403         has been updated, so you can use performance/economy_cpu_freq in
404         rc.conf(5) to set AC on/offline cpu frequencies.
405
406 20050206:
407         NG_VERSION has been increased. Recompiling kernel (or ng_socket.ko)
408         requires recompiling libnetgraph and userland netgraph utilities.
409
410 20050114:
411         Support for abbreviated forms of a number of ipfw options is
412         now deprecated.  Warnings are printed to stderr indicating the
413         correct full form when a match occurs.  Some abbreviations may
414         be supported at a later date based on user feedback.  To be
415         considered for support, abbreviations must be in use prior to
416         this commit and unlikely to be confused with current key words.
417
418 20041221:
419         By a popular demand, a lot of NOFOO options were renamed
420         to NO_FOO (see bsd.compat.mk for a full list).  The old
421         spellings are still supported, but will cause annoying
422         warnings on stderr.  Make sure you upgrade properly (see
423         the COMMON ITEMS: section later in this file).
424
425 20041219:
426         Auto-loading of ancillary wlan modules such as wlan_wep has
427         been temporarily disabled; you need to statically configure
428         the modules you need into your kernel or explicitly load them
429         prior to use.  Specifically, if you intend to use WEP encryption
430         with an 802.11 device load/configure wlan_wep; if you want to
431         use WPA with the ath driver load/configure wlan_tkip, wlan_ccmp,
432         and wlan_xauth as required.
433
434 20041213:
435         The behaviour of ppp(8) has changed slightly.  If lqr is enabled
436         (``enable lqr''), older versions would revert to LCP ECHO mode on
437         negotiation failure.  Now, ``enable echo'' is required for this
438         behaviour.  The ppp version number has been bumped to 3.4.2 to
439         reflect the change.
440
441 20041201:
442         The wlan support has been updated to split the crypto support
443         into separate modules.  For static WEP you must configure the
444         wlan_wep module in your system or build and install the module
445         in place where it can be loaded (the kernel will auto-load
446         the module when a wep key is configured).
447
448 20041201:
449         The ath driver has been updated to split the tx rate control
450         algorithm into a separate module.  You need to include either
451         ath_rate_onoe or ath_rate_amrr when configuring the kernel.
452
453 20041116:
454         Support for systems with an 80386 CPU has been removed.  Please
455         use FreeBSD 5.x or earlier on systems with an 80386.
456
457 20041110:
458         We have had a hack which would mount the root filesystem
459         R/W if the device were named 'md*'.  As part of the vnode
460         work I'm doing I have had to remove this hack.  People
461         building systems which use preloaded MD root filesystems
462         may need to insert a "/sbin/mount -u -o rw /dev/md0 /" in
463         their /etc/rc scripts.
464
465 20041104:
466         FreeBSD 5.3 shipped here.
467
468 20041102:
469         The size of struct tcpcb has changed again due to the removal
470         of RFC1644 T/TCP.  You have to recompile userland programs that
471         read kmem for tcp sockets directly (netstat, sockstat, etc.)
472
473 20041022:
474         The size of struct tcpcb has changed.  You have to recompile
475         userland programs that read kmem for tcp sockets directly
476         (netstat, sockstat, etc.)
477
478 20041016:
479         RELENG_5 branched here.  For older entries, please see updating
480         in the RELENG_5 branch.
481
482 COMMON ITEMS:
483
484         General Notes
485         -------------
486         Avoid using make -j when upgrading.  From time to time in the
487         past there have been problems using -j with buildworld and/or
488         installworld.  This is especially true when upgrading between
489         "distant" versions (eg one that cross a major release boundary
490         or several minor releases, or when several months have passed
491         on the -current branch).
492
493         Sometimes, obscure build problems are the result of environment
494         poisoning.  This can happen because the make utility reads its
495         environment when searching for values for global variables.
496         To run your build attempts in an "environmental clean room",
497         prefix all make commands with 'env -i '.  See the env(1) manual
498         page for more details.
499
500         When upgrading from one major version to another it is generally
501         best to upgrade to the latest code in the currently installed branch
502         first, then do an upgrade to the new branch. This is the best-tested
503         upgrade path, and has the highest probability of being successful.
504         Please try this approach before reporting problems with a major
505         version upgrade.
506
507         To build a kernel
508         -----------------
509         If you are updating from a prior version of FreeBSD (even one just
510         a few days old), you should follow this procedure.  It is the most
511         failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
512
513         make kernel-toolchain
514         make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
515         make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
516
517         To test a kernel once
518         ---------------------
519         If you just want to boot a kernel once (because you are not sure
520         if it works, or if you want to boot a known bad kernel to provide
521         debugging information) run
522         make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
523         nextboot -k testkernel
524
525         To just build a kernel when you know that it won't mess you up
526         --------------------------------------------------------------
527         This assumes you are already running a 5.X system.  Replace
528         ${arch} with the architecture of your machine (e.g. "i386",
529         "alpha", "amd64", "ia64", "pc98", "sparc64", etc).
530
531         cd src/sys/${arch}/conf
532         config KERNEL_NAME_HERE
533         cd ../compile/KERNEL_NAME_HERE
534         make depend
535         make
536         make install
537
538         If this fails, go to the "To build a kernel" section.
539
540         To rebuild everything and install it on the current system.
541         -----------------------------------------------------------
542         # Note: sometimes if you are running current you gotta do more than
543         # is listed here if you are upgrading from a really old current.
544
545         <make sure you have good level 0 dumps>
546         make buildworld
547         make kernel KERNCONF=YOUR_KERNEL_HERE
548                                                         [1]
549         <reboot in single user>                         [3]
550         mergemaster -p                                  [5]
551         make installworld
552         make delete-old
553         mergemaster                                     [4]
554         <reboot>
555
556
557         To cross-install current onto a separate partition
558         --------------------------------------------------
559         # In this approach we use a separate partition to hold
560         # current's root, 'usr', and 'var' directories.   A partition
561         # holding "/", "/usr" and "/var" should be about 2GB in
562         # size.
563
564         <make sure you have good level 0 dumps>
565         <boot into -stable>
566         make buildworld
567         make buildkernel KERNCONF=YOUR_KERNEL_HERE
568         <maybe newfs current's root partition>
569         <mount current's root partition on directory ${CURRENT_ROOT}>
570         make installworld DESTDIR=${CURRENT_ROOT}
571         make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
572         make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
573         cp /etc/fstab ${CURRENT_ROOT}/etc/fstab                    # if newfs'd
574         <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
575         <reboot into current>
576         <do a "native" rebuild/install as described in the previous section>
577         <maybe install compatibility libraries from src/lib/compat>
578         <reboot>
579
580
581         To upgrade in-place from 5.x-stable to current
582         ----------------------------------------------
583         <make sure you have good level 0 dumps>
584         make buildworld                                 [9]
585         make kernel KERNCONF=YOUR_KERNEL_HERE           [8]
586                                                         [1]
587         <reboot in single user>                         [3]
588         mergemaster -p                                  [5]
589         make installworld
590         make delete-old
591         mergemaster -i                                  [4]
592         <reboot>
593
594         Make sure that you've read the UPDATING file to understand the
595         tweaks to various things you need.  At this point in the life
596         cycle of current, things change often and you are on your own
597         to cope.  The defaults can also change, so please read ALL of
598         the UPDATING entries.
599
600         Also, if you are tracking -current, you must be subscribed to
601         freebsd-current@freebsd.org.  Make sure that before you update
602         your sources that you have read and understood all the recent
603         messages there.  If in doubt, please track -stable which has
604         much fewer pitfalls.
605
606         [1] If you have third party modules, such as vmware, you
607         should disable them at this point so they don't crash your
608         system on reboot.
609
610         [3] From the bootblocks, boot -s, and then do
611                 fsck -p
612                 mount -u /
613                 mount -a
614                 cd src
615                 adjkerntz -i            # if CMOS is wall time
616         Also, when doing a major release upgrade, it is required that
617         you boot into single user mode to do the installworld.
618
619         [4] Note: This step is non-optional.  Failure to do this step
620         can result in a significant reduction in the functionality of the
621         system.  Attempting to do it by hand is not recommended and those
622         that pursue this avenue should read this file carefully, as well
623         as the archives of freebsd-current and freebsd-hackers mailing lists
624         for potential gotchas.
625
626         [5] Usually this step is a noop.  However, from time to time
627         you may need to do this if you get unknown user in the following
628         step.  It never hurts to do it all the time.  You may need to
629         install a new mergemaster (cd src/usr.sbin/mergemaster && make
630         install) after the buildworld before this step if you last updated
631         from current before 20020224 or from -stable before 20020408.
632
633         [8] In order to have a kernel that can run the 4.x binaries
634         needed to do an installworld, you must include the COMPAT_FREEBSD4
635         option in your kernel.  Failure to do so may leave you with a system
636         that is hard to boot to recover. A similar kernel option COMPAT_FREEBSD5
637         is required to run the 5.x binaries on more recent kernels.
638
639         Make sure that you merge any new devices from GENERIC since the
640         last time you updated your kernel config file.
641
642         [9] When checking out sources, you must include the -P flag to have
643         cvs prune empty directories.
644
645         If CPUTYPE is defined in your /etc/make.conf, make sure to use the
646         "?=" instead of the "=" assignment operator, so that buildworld can
647         override the CPUTYPE if it needs to.
648
649         MAKEOBJDIRPREFIX must be defined in an environment variable, and
650         not on the command line, or in /etc/make.conf.  buildworld will
651         warn if it is improperly defined.
652 FORMAT:
653
654 This file contains a list, in reverse chronological order, of major
655 breakages in tracking -current.  Not all things will be listed here,
656 and it only starts on October 16, 2004.  Updating files can found in
657 previous releases if your system is older than this.
658
659 Copyright information:
660
661 Copyright 1998-2005 M. Warner Losh.  All Rights Reserved.
662
663 Redistribution, publication, translation and use, with or without
664 modification, in full or in part, in any form or format of this
665 document are permitted without further permission from the author.
666
667 THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
668 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
669 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
670 DISCLAIMED.  IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
671 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
672 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
673 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
674 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
675 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
676 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
677 POSSIBILITY OF SUCH DAMAGE.
678
679 If you find this document useful, and you want to, you may buy the
680 author a beer.
681
682 Contact Warner Losh if you have any questions about your use of
683 this document.
684
685 $FreeBSD$