]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - UPDATING
Vnode is not referenced by the vfs_domount() at the point where
[FreeBSD/FreeBSD.git] / UPDATING
1 Updating Information for FreeBSD current users.
2
3 This file is maintained and copyrighted by M. Warner Losh <imp@freebsd.org>.
4 See end of file for further details.  For commonly done items, please see the
5 COMMON ITEMS: section later in the file.  These instructions assume that you
6 basically know what you are doing.  If not, then please consult the FreeBSD
7 handbook:
8
9     http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html
10
11 Items affecting the ports and packages system can be found in
12 /usr/ports/UPDATING.  Please read that file before running portupgrade.
13
14 NOTE: FreeBSD has switched from gcc to clang. If you have trouble bootstrapping
15 from older versions of FreeBSD, try WITHOUT_CLANG and WITH_GCC to bootstrap to
16 the tip of head, and then rebuild without this option. The bootstrap process from
17 older version of current across the gcc/clang cutover is a bit fragile.
18
19 NOTE TO PEOPLE WHO THINK THAT FreeBSD 11.x IS SLOW:
20         FreeBSD 11.x has many debugging features turned on, in both the kernel
21         and userland.  These features attempt to detect incorrect use of
22         system primitives, and encourage loud failure through extra sanity
23         checking and fail stop semantics.  They also substantially impact
24         system performance.  If you want to do performance measurement,
25         benchmarking, and optimization, you'll want to turn them off.  This
26         includes various WITNESS- related kernel options, INVARIANTS, malloc
27         debugging flags in userland, and various verbose features in the
28         kernel.  Many developers choose to disable these features on build
29         machines to maximize performance.  (To completely disable malloc
30         debugging, define MALLOC_PRODUCTION in /etc/make.conf, or to merely
31         disable the most expensive debugging functionality run
32         "ln -s 'abort:false,junk:false' /etc/malloc.conf".)
33
34 20150630:
35         The default kernel entropy-processing algorithm is now
36         Fortuna, replacing Yarrow.
37
38         Assuming you have 'device random' in your kernel config
39         file, the configurations allow a kernel option to override
40         this default. You may choose *ONE* of:
41
42         options RANDOM_YARROW   # Legacy /dev/random algorithm.
43         options RANDOM_DUMMY    # Blocking-only driver.
44
45         If you have neither, you get Fortuna.  For most people,
46         read no further, Fortuna will give a /dev/random that works
47         like it always used to, and the difference will be irrelevant.
48
49         If you remove 'device random', you get *NO* kernel-processed
50         entopy at all. This may be acceptable to folks building
51         embedded systems, but has complications. Carry on reading,
52         and it is assumed you know what you need.
53
54         *PLEASE* read random(4) and random(9) if you are in the
55         habit of tweeking kernel configs, and/or if you are a member
56         of the embedded community, wanting specific and not-usual
57         behaviour from your security subsystems.
58
59         NOTE!! If you use RANDOM_DUMMY and/or have no 'device
60         random', you will NOT have a functioning /dev/random, and
61         many cryptographic features will not work, including SSH.
62         You may also find strange behaviour from the random(3) set
63         of library functions, in particular sranddev(3), srandomdev(3)
64         and arc4random(3). The reason for this is that the KERN_ARND
65         sysctl only returns entropy if it thinks it has some to
66         share, and with RANDOM_DUMMY or no 'device random' this
67         will never happen.
68
69 20150623:
70         An additional fix for the issue described in the 20150614 sendmail
71         entry below has been been committed in revision 284717.
72
73 20150616:
74         FreeBSD's old make (fmake) has been removed from the system. It is
75         available as the devel/fmake port or via pkg install fmake.
76         
77 20150615:
78         The fix for the issue described in the 20150614 sendmail entry
79         below has been been committed in revision 284436.  The work
80         around described in that entry is no longer needed unless the
81         default setting is overridden by a confDH_PARAMETERS configuration
82         setting of '5' or pointing to a 512 bit DH parameter file.
83
84 20150614:
85         ALLOW_DEPRECATED_ATF_TOOLS/ATFFILE support has been removed from
86         atf.test.mk (included from bsd.test.mk). Please upgrade devel/atf
87         and devel/kyua to version 0.20+ and adjust any calling code to work
88         with Kyuafile and kyua.
89
90 20150614:
91         The import of openssl to address the FreeBSD-SA-15:10.openssl
92         security advisory includes a change which rejects handshakes
93         with DH parameters below 768 bits.  sendmail releases prior
94         to 8.15.2 (not yet released), defaulted to a 512 bit
95         DH parameter setting for client connections.  To work around
96         this interoperability, sendmail can be configured to use a
97         2048 bit DH parameter by:
98
99         1. Edit /etc/mail/`hostname`.mc 
100         2. If a setting for confDH_PARAMETERS does not exist or
101            exists and is set to a string beginning with '5',
102            replace it with '2'.
103         3. If a setting for confDH_PARAMETERS exists and is set to
104            a file path, create a new file with:
105                 openssl dhparam -out /path/to/file 2048
106         4. Rebuild the .cf file:
107                 cd /etc/mail/; make; make install
108         5. Restart sendmail:
109                 cd /etc/mail/; make restart
110
111         A sendmail patch is coming, at which time this file will be
112         updated.
113
114 20150604:
115         Generation of legacy formatted entries have been disabled by default
116         in pwd_mkdb(8), as all base system consumers of the legacy formatted
117         entries were converted to use the new format by default when the new,
118         machine independent format have been added and supported since FreeBSD
119         5.x.
120
121         Please see the pwd_mkdb(8) manual page for further details.
122
123 20150525:
124         Clang and llvm have been upgraded to 3.6.1 release.  Please see the
125         20141231 entry below for information about prerequisites and upgrading,
126         if you are not already using 3.5.0 or higher.
127
128 20150521:
129         TI platform code switched to using vendor DTS files and this update
130         may break existing systems running on Beaglebone, Beaglebone Black,
131         and Pandaboard:
132
133         - dtb files should be regenerated/reinstalled. Filenames are the
134           same but content is different now
135         - GPIO addressing was changed, now each GPIO bank (32 pins per bank)
136           has its own /dev/gpiocX device, e.g. pin 121 on /dev/gpioc0 in old
137           addressing scheme is now pin 25 on /dev/gpioc3.
138         - Pandaboard: /etc/ttys should be updated, serial console device is
139           now /dev/ttyu2, not /dev/ttyu0
140
141 20150501:
142         soelim(1) from gnu/usr.bin/groff has been replaced by usr.bin/soelim.
143         If you need the GNU extension from groff soelim(1), install groff
144         from package: pkg install groff, or via ports: textproc/groff.
145
146 20150423:
147         chmod, chflags, chown and chgrp now affect symlinks in -R mode as
148         defined in symlink(7); previously symlinks were silently ignored.
149
150 20150415:
151         The const qualifier has been removed from iconv(3) to comply with
152         POSIX.  The ports tree is aware of this from r384038 onwards.
153
154 20150416:
155         Libraries specified by LIBADD in Makefiles must have a corresponding
156         DPADD_<lib> variable to ensure correct dependencies.  This is now
157         enforced in src.libnames.mk.
158
159 20150324:
160         From legacy ata(4) driver was removed support for SATA controllers
161         supported by more functional drivers ahci(4), siis(4) and mvs(4).
162         Kernel modules ataahci and ataadaptec were removed completely,
163         replaced by ahci and mvs modules respectively.
164
165 20150315:
166         Clang, llvm and lldb have been upgraded to 3.6.0 release.  Please see
167         the 20141231 entry below for information about prerequisites and
168         upgrading, if you are not already using 3.5.0 or higher.
169
170 20150307:
171         The 32-bit PowerPC kernel has been changed to a position-independent
172         executable. This can only be booted with a version of loader(8)
173         newer than January 31, 2015, so make sure to update both world and
174         kernel before rebooting.
175
176 20150217:
177         If you are running a -CURRENT kernel since r273872 (Oct 30th, 2014),
178         but before r278950, the RNG was not seeded properly.  Immediately
179         upgrade the kernel to r278950 or later and regenerate any keys (e.g.
180         ssh keys or openssl keys) that were generated w/ a kernel from that
181         range.  This does not affect programs that directly used /dev/random
182         or /dev/urandom.  All userland uses of arc4random(3) are affected.
183
184 20150210:
185         The autofs(4) ABI was changed in order to restore binary compatibility
186         with 10.1-RELEASE.  The automountd(8) daemon needs to be rebuilt to work
187         with the new kernel.
188
189 20150131:
190         The powerpc64 kernel has been changed to a position-independent
191         executable. This can only be booted with a new version of loader(8),
192         so make sure to update both world and kernel before rebooting.
193
194 20150118:
195         Clang and llvm have been upgraded to 3.5.1 release.  This is a bugfix
196         only release, no new features have been added.  Please see the 20141231
197         entry below for information about prerequisites and upgrading, if you
198         are not already using 3.5.0.
199
200 20150107:
201         ELF tools addr2line, elfcopy (strip), nm, size, and strings are now
202         taken from the ELF Tool Chain project rather than GNU binutils. They
203         should be drop-in replacements, with the addition of arm64 support.
204         The WITHOUT_ELFTOOLCHAIN_TOOLS= knob may be used to obtain the
205         binutils tools, if necessary.
206
207 20150105:
208         The default Unbound configuration now enables remote control
209         using a local socket.  Users who have already enabled the
210         local_unbound service should regenerate their configuration
211         by running "service local_unbound setup" as root.
212         
213 20150102:
214         The GNU texinfo and GNU info pages have been removed.
215         To be able to view GNU info pages please install texinfo from ports.
216
217 20141231:
218         Clang, llvm and lldb have been upgraded to 3.5.0 release.
219
220         As of this release, a prerequisite for building clang, llvm and lldb is
221         a C++11 capable compiler and C++11 standard library.  This means that to
222         be able to successfully build the cross-tools stage of buildworld, with
223         clang as the bootstrap compiler, your system compiler or cross compiler
224         should either be clang 3.3 or later, or gcc 4.8 or later, and your
225         system C++ library should be libc++, or libdstdc++ from gcc 4.8 or
226         later.
227
228         On any standard FreeBSD 10.x or 11.x installation, where clang and
229         libc++ are on by default (that is, on x86 or arm), this should work out
230         of the box.
231
232         On 9.x installations where clang is enabled by default, e.g. on x86 and
233         powerpc, libc++ will not be enabled by default, so libc++ should be
234         built (with clang) and installed first.  If both clang and libc++ are
235         missing, build clang first, then use it to build libc++.
236
237         On 8.x and earlier installations, upgrade to 9.x first, and then follow
238         the instructions for 9.x above.
239
240         Sparc64 and mips users are unaffected, as they still use gcc 4.2.1 by
241         default, and do not build clang.
242
243         Many embedded systems are resource constrained, and will not be able to
244         build clang in a reasonable time, or in some cases at all.  In those
245         cases, cross building bootable systems on amd64 is a workaround.
246
247         This new version of clang introduces a number of new warnings, of which
248         the following are most likely to appear:
249
250         -Wabsolute-value
251
252         This warns in two cases, for both C and C++:
253         * When the code is trying to take the absolute value of an unsigned
254           quantity, which is effectively a no-op, and almost never what was
255           intended.  The code should be fixed, if at all possible.  If you are
256           sure that the unsigned quantity can be safely cast to signed, without
257           loss of information or undefined behavior, you can add an explicit
258           cast, or disable the warning.
259
260         * When the code is trying to take an absolute value, but the called
261           abs() variant is for the wrong type, which can lead to truncation.
262           If you want to disable the warning instead of fixing the code, please
263           make sure that truncation will not occur, or it might lead to unwanted
264           side-effects.
265
266         -Wtautological-undefined-compare and
267         -Wundefined-bool-conversion
268
269         These warn when C++ code is trying to compare 'this' against NULL, while
270         'this' should never be NULL in well-defined C++ code.  However, there is
271         some legacy (pre C++11) code out there, which actively abuses this
272         feature, which was less strictly defined in previous C++ versions.
273
274         Squid and openjdk do this, for example.  The warning can be turned off
275         for C++98 and earlier, but compiling the code in C++11 mode might result
276         in unexpected behavior; for example, the parts of the program that are
277         unreachable could be optimized away.
278
279 20141222:
280         The old NFS client and server (kernel options NFSCLIENT, NFSSERVER)
281         kernel sources have been removed. The .h files remain, since some
282         utilities include them. This will need to be fixed later.
283         If "mount -t oldnfs ..." is attempted, it will fail.
284         If the "-o" option on mountd(8), nfsd(8) or nfsstat(1) is used,
285         the utilities will report errors.
286
287 20141121:
288         The handling of LOCAL_LIB_DIRS has been altered to skip addition of
289         directories to top level SUBDIR variable when their parent
290         directory is included in LOCAL_DIRS.  Users with build systems with
291         such hierarchies and without SUBDIR entries in the parent
292         directory Makefiles should add them or add the directories to
293         LOCAL_DIRS.
294
295 20141109:
296         faith(4) and faithd(8) have been removed from the base system. Faith
297         has been obsolete for a very long time.
298
299 20141104:
300         vt(4), the new console driver, is enabled by default. It brings
301         support for Unicode and double-width characters, as well as
302         support for UEFI and integration with the KMS kernel video
303         drivers.
304
305         You may need to update your console settings in /etc/rc.conf,
306         most probably the keymap. During boot, /etc/rc.d/syscons will
307         indicate what you need to do.
308
309         vt(4) still has issues and lacks some features compared to
310         syscons(4). See the wiki for up-to-date information:
311           https://wiki.freebsd.org/Newcons
312
313         If you want to keep using syscons(4), you can do so by adding
314         the following line to /boot/loader.conf:
315           kern.vty=sc
316
317 20141102:
318         pjdfstest has been integrated into kyua as an opt-in test suite.
319         Please see share/doc/pjdfstest/README for more details on how to
320         execute it.
321
322 20141009:
323         gperf has been removed from the base system for architectures
324         that use clang. Ports that require gperf will obtain it from the
325         devel/gperf port.
326
327 20140923:
328         pjdfstest has been moved from tools/regression/pjdfstest to
329         contrib/pjdfstest .
330
331 20140922:
332         At svn r271982, The default linux compat kernel ABI has been adjusted
333         to 2.6.18 in support of the linux-c6 compat ports infrastructure
334         update.  If you wish to continue using the linux-f10 compat ports,
335         add compat.linux.osrelease=2.6.16 to your local sysctl.conf.  Users are
336         encouraged to update their linux-compat packages to linux-c6 during
337         their next update cycle.
338
339 20140729:
340         The ofwfb driver, used to provide a graphics console on PowerPC when
341         using vt(4), no longer allows mmap() of all physical memory. This
342         will prevent Xorg on PowerPC with some ATI graphics cards from
343         initializing properly unless x11-servers/xorg-server is updated to
344         1.12.4_8 or newer.
345
346 20140723:
347         The xdev targets have been converted to using TARGET and
348         TARGET_ARCH instead of XDEV and XDEV_ARCH.
349
350 20140719:
351         The default unbound configuration has been modified to address
352         issues with reverse lookups on networks that use private
353         address ranges.  If you use the local_unbound service, run
354         "service local_unbound setup" as root to regenerate your
355         configuration, then "service local_unbound reload" to load the
356         new configuration.
357
358 20140709:
359         The GNU texinfo and GNU info pages are not built and installed
360         anymore, WITH_INFO knob has been added to allow to built and install
361         them again.
362         UPDATE: see 20150102 entry on texinfo's removal
363
364 20140708:
365         The GNU readline library is now an INTERNALLIB - that is, it is
366         statically linked into consumers (GDB and variants) in the base
367         system, and the shared library is no longer installed.  The
368         devel/readline port is available for third party software that
369         requires readline.
370
371 20140702:
372         The Itanium architecture (ia64) has been removed from the list of
373         known architectures. This is the first step in the removal of the
374         architecture.
375
376 20140701:
377         Commit r268115 has added NFSv4.1 server support, merged from
378         projects/nfsv4.1-server.  Since this includes changes to the
379         internal interfaces between the NFS related modules, a full
380         build of the kernel and modules will be necessary.
381         __FreeBSD_version has been bumped.
382
383 20140629:
384         The WITHOUT_VT_SUPPORT kernel config knob has been renamed
385         WITHOUT_VT.  (The other _SUPPORT knobs have a consistent meaning
386         which differs from the behaviour controlled by this knob.)
387
388 20140619:
389         Maximal length of the serial number in CTL was increased from 16 to
390         64 chars, that breaks ABI.  All CTL-related tools, such as ctladm
391         and ctld, need to be rebuilt to work with a new kernel.
392
393 20140606:
394         The libatf-c and libatf-c++ major versions were downgraded to 0 and
395         1 respectively to match the upstream numbers.  They were out of
396         sync because, when they were originally added to FreeBSD, the
397         upstream versions were not respected.  These libraries are private
398         and not yet built by default, so renumbering them should be a
399         non-issue.  However, unclean source trees will yield broken test
400         programs once the operator executes "make delete-old-libs" after a
401         "make installworld".
402
403         Additionally, the atf-sh binary was made private by moving it into
404         /usr/libexec/.  Already-built shell test programs will keep the
405         path to the old binary so they will break after "make delete-old"
406         is run.
407
408         If you are using WITH_TESTS=yes (not the default), wipe the object
409         tree and rebuild from scratch to prevent spurious test failures.
410         This is only needed once: the misnumbered libraries and misplaced
411         binaries have been added to OptionalObsoleteFiles.inc so they will
412         be removed during a clean upgrade.
413
414 20140512:
415         Clang and llvm have been upgraded to 3.4.1 release.
416
417 20140508:
418         We bogusly installed src.opts.mk in /usr/share/mk. This file should
419         be removed to avoid issues in the future (and has been added to
420         ObsoleteFiles.inc).
421
422 20140505:
423         /etc/src.conf now affects only builds of the FreeBSD src tree. In the
424         past, it affected all builds that used the bsd.*.mk files. The old
425         behavior was a bug, but people may have relied upon it. To get this
426         behavior back, you can .include /etc/src.conf from /etc/make.conf
427         (which is still global and isn't changed). This also changes the
428         behavior of incremental builds inside the tree of individual
429         directories. Set MAKESYSPATH to ".../share/mk" to do that.
430         Although this has survived make universe and some upgrade scenarios,
431         other upgrade scenarios may have broken. At least one form of
432         temporary breakage was fixed with MAKESYSPATH settings for buildworld
433         as well... In cases where MAKESYSPATH isn't working with this
434         setting, you'll need to set it to the full path to your tree.
435
436         One side effect of all this cleaning up is that bsd.compiler.mk
437         is no longer implicitly included by bsd.own.mk. If you wish to
438         use COMPILER_TYPE, you must now explicitly include bsd.compiler.mk
439         as well.
440
441 20140430:
442         The lindev device has been removed since /dev/full has been made a
443         standard device.  __FreeBSD_version has been bumped.
444
445 20140424:
446         The knob WITHOUT_VI was added to the base system, which controls
447         building ex(1), vi(1), etc. Older releases of FreeBSD required ex(1)
448         in order to reorder files share/termcap and didn't build ex(1) as a
449         build tool, so building/installing with WITH_VI is highly advised for
450         build hosts for older releases.
451
452         This issue has been fixed in stable/9 and stable/10 in r277022 and
453         r276991, respectively.
454
455 20140418:
456         The YES_HESIOD knob has been removed. It has been obsolete for
457         a decade. Please move to using WITH_HESIOD instead or your builds
458         will silently lack HESIOD.
459
460 20140405:
461         The uart(4) driver has been changed with respect to its handling
462         of the low-level console. Previously the uart(4) driver prevented
463         any process from changing the baudrate or the CLOCAL and HUPCL
464         control flags. By removing the restrictions, operators can make
465         changes to the serial console port without having to reboot.
466         However, when getty(8) is started on the serial device that is
467         associated with the low-level console, a misconfigured terminal
468         line in /etc/ttys will now have a real impact.
469         Before upgrading the kernel, make sure that /etc/ttys has the
470         serial console device configured as 3wire without baudrate to
471         preserve the previous behaviour. E.g:
472             ttyu0  "/usr/libexec/getty 3wire"  vt100  on  secure
473
474 20140306:
475         Support for libwrap (TCP wrappers) in rpcbind was disabled by default
476         to improve performance.  To re-enable it, if needed, run rpcbind
477         with command line option -W.
478
479 20140226:
480         Switched back to the GPL dtc compiler due to updates in the upstream
481         dts files not being supported by the BSDL dtc compiler. You will need
482         to rebuild your kernel toolchain to pick up the new compiler. Core dumps
483         may result while building dtb files during a kernel build if you fail
484         to do so. Set WITHOUT_GPL_DTC if you require the BSDL compiler.
485
486 20140216:
487         Clang and llvm have been upgraded to 3.4 release.
488
489 20140216:
490         The nve(4) driver has been removed.  Please use the nfe(4) driver
491         for NVIDIA nForce MCP Ethernet adapters instead.
492
493 20140212:
494         An ABI incompatibility crept into the libc++ 3.4 import in r261283.
495         This could cause certain C++ applications using shared libraries built
496         against the previous version of libc++ to crash.  The incompatibility
497         has now been fixed, but any C++ applications or shared libraries built
498         between r261283 and r261801 should be recompiled.
499
500 20140204:
501         OpenSSH will now ignore errors caused by kernel lacking of Capsicum
502         capability mode support.  Please note that enabling the feature in
503         kernel is still highly recommended.
504
505 20140131:
506         OpenSSH is now built with sandbox support, and will use sandbox as
507         the default privilege separation method.  This requires Capsicum
508         capability mode support in kernel.
509
510 20140128:
511         The libelf and libdwarf libraries have been updated to newer
512         versions from upstream. Shared library version numbers for
513         these two libraries were bumped. Any ports or binaries
514         requiring these two libraries should be recompiled.
515         __FreeBSD_version is bumped to 1100006.
516
517 20140110:
518         If a Makefile in a tests/ directory was auto-generating a Kyuafile
519         instead of providing an explicit one, this would prevent such
520         Makefile from providing its own Kyuafile in the future during
521         NO_CLEAN builds.  This has been fixed in the Makefiles but manual
522         intervention is needed to clean an objdir if you use NO_CLEAN:
523           # find /usr/obj -name Kyuafile | xargs rm -f
524
525 20131213:
526         The behavior of gss_pseudo_random() for the krb5 mechanism
527         has changed, for applications requesting a longer random string
528         than produced by the underlying enctype's pseudo-random() function.
529         In particular, the random string produced from a session key of
530         enctype aes256-cts-hmac-sha1-96 or aes256-cts-hmac-sha1-96 will
531         be different at the 17th octet and later, after this change.
532         The counter used in the PRF+ construction is now encoded as a
533         big-endian integer in accordance with RFC 4402.
534         __FreeBSD_version is bumped to 1100004.
535
536 20131108:
537         The WITHOUT_ATF build knob has been removed and its functionality
538         has been subsumed into the more generic WITHOUT_TESTS.  If you were
539         using the former to disable the build of the ATF libraries, you
540         should change your settings to use the latter.
541
542 20131025:
543         The default version of mtree is nmtree which is obtained from
544         NetBSD.  The output is generally the same, but may vary
545         slightly.  If you found you need identical output adding
546         "-F freebsd9" to the command line should do the trick.  For the
547         time being, the old mtree is available as fmtree.
548
549 20131014:
550         libbsdyml has been renamed to libyaml and moved to /usr/lib/private.
551         This will break ports-mgmt/pkg. Rebuild the port, or upgrade to pkg
552         1.1.4_8 and verify bsdyml not linked in, before running "make
553         delete-old-libs":
554           # make -C /usr/ports/ports-mgmt/pkg build deinstall install clean
555           or
556           # pkg install pkg; ldd /usr/local/sbin/pkg | grep bsdyml
557
558 20131010:
559         The rc.d/jail script has been updated to support jail(8)
560         configuration file.  The "jail_<jname>_*" rc.conf(5) variables
561         for per-jail configuration are automatically converted to
562         /var/run/jail.<jname>.conf before the jail(8) utility is invoked.
563         This is transparently backward compatible.  See below about some
564         incompatibilities and rc.conf(5) manual page for more details.
565
566         These variables are now deprecated in favor of jail(8) configuration
567         file.  One can use "rc.d/jail config <jname>" command to generate
568         a jail(8) configuration file in /var/run/jail.<jname>.conf without
569         running the jail(8) utility.   The default pathname of the
570         configuration file is /etc/jail.conf and can be specified by
571         using $jail_conf or $jail_<jname>_conf variables.
572
573         Please note that jail_devfs_ruleset accepts an integer at
574         this moment.  Please consider to rewrite the ruleset name
575         with an integer.
576
577 20130930:
578         BIND has been removed from the base system.  If all you need
579         is a local resolver, simply enable and start the local_unbound
580         service instead.  Otherwise, several versions of BIND are
581         available in the ports tree.   The dns/bind99 port is one example.
582
583         With this change, nslookup(1) and dig(1) are no longer in the base
584         system.  Users should instead use host(1) and drill(1) which are
585         in the base system.  Alternatively, nslookup and dig can
586         be obtained by installing the dns/bind-tools port.
587
588 20130916:
589         With the addition of unbound(8), a new unbound user is now
590         required during installworld.  "mergemaster -p" can be used to
591         add the user prior to installworld, as documented in the handbook.
592
593 20130911:
594         OpenSSH is now built with DNSSEC support, and will by default
595         silently trust signed SSHFP records.  This can be controlled with
596         the VerifyHostKeyDNS client configuration setting.  DNSSEC support
597         can be disabled entirely with the WITHOUT_LDNS option in src.conf.
598
599 20130906:
600         The GNU Compiler Collection and C++ standard library (libstdc++)
601         are no longer built by default on platforms where clang is the system
602         compiler.  You can enable them with the WITH_GCC and WITH_GNUCXX
603         options in src.conf.  
604
605 20130905:
606         The PROCDESC kernel option is now part of the GENERIC kernel
607         configuration and is required for the rwhod(8) to work.
608         If you are using custom kernel configuration, you should include
609         'options PROCDESC'.
610
611 20130905:
612         The API and ABI related to the Capsicum framework was modified
613         in backward incompatible way. The userland libraries and programs
614         have to be recompiled to work with the new kernel. This includes the
615         following libraries and programs, but the whole buildworld is
616         advised: libc, libprocstat, dhclient, tcpdump, hastd, hastctl,
617         kdump, procstat, rwho, rwhod, uniq.
618
619 20130903:
620         AES-NI intrinsic support has been added to gcc.  The AES-NI module
621         has been updated to use this support.  A new gcc is required to build
622         the aesni module on both i386 and amd64.
623
624 20130821:
625         The PADLOCK_RNG and RDRAND_RNG kernel options are now devices.
626         Thus "device padlock_rng" and "device rdrand_rng" should be
627         used instead of "options PADLOCK_RNG" & "options RDRAND_RNG".
628
629 20130813:
630         WITH_ICONV has been split into two feature sets.  WITH_ICONV now
631         enables just the iconv* functionality and is now on by default.
632         WITH_LIBICONV_COMPAT enables the libiconv api and link time
633         compatability.  Set WITHOUT_ICONV to build the old way.
634         If you have been using WITH_ICONV before, you will very likely
635         need to turn on WITH_LIBICONV_COMPAT.
636
637 20130806:
638         INVARIANTS option now enables DEBUG for code with OpenSolaris and
639         Illumos origin, including ZFS.  If you have INVARIANTS in your
640         kernel configuration, then there is no need to set DEBUG or ZFS_DEBUG
641         explicitly.
642         DEBUG used to enable witness(9) tracking of OpenSolaris (mostly ZFS)
643         locks if WITNESS option was set.  Because that generated a lot of
644         witness(9) reports and all of them were believed to be false
645         positives, this is no longer done.  New option OPENSOLARIS_WITNESS
646         can be used to achieve the previous behavior.
647
648 20130806:
649         Timer values in IPv6 data structures now use time_uptime instead
650         of time_second.  Although this is not a user-visible functional
651         change, userland utilities which directly use them---ndp(8),
652         rtadvd(8), and rtsold(8) in the base system---need to be updated
653         to r253970 or later.
654
655 20130802:
656         find -delete can now delete the pathnames given as arguments,
657         instead of only files found below them or if the pathname did
658         not contain any slashes. Formerly, the following error message
659         would result:
660
661         find: -delete: <path>: relative path potentially not safe
662
663         Deleting the pathnames given as arguments can be prevented
664         without error messages using -mindepth 1 or by changing
665         directory and passing "." as argument to find. This works in the
666         old as well as the new version of find.
667
668 20130726:
669         Behavior of devfs rules path matching has been changed.
670         Pattern is now always matched against fully qualified devfs
671         path and slash characters must be explicitly matched by
672         slashes in pattern (FNM_PATHNAME). Rulesets involving devfs
673         subdirectories must be reviewed.
674
675 20130716:
676         The default ARM ABI has changed to the ARM EABI. The old ABI is
677         incompatible with the ARM EABI and all programs and modules will
678         need to be rebuilt to work with a new kernel.
679
680         To keep using the old ABI ensure the WITHOUT_ARM_EABI knob is set.
681
682         NOTE: Support for the old ABI will be removed in the future and
683         users are advised to upgrade.
684
685 20130709:
686         pkg_install has been disconnected from the build if you really need it
687         you should add WITH_PKGTOOLS in your src.conf(5).
688
689 20130709:
690         Most of network statistics structures were changed to be able
691         keep 64-bits counters. Thus all tools, that work with networking
692         statistics, must be rebuilt (netstat(1), bsnmpd(1), etc.)
693
694 20130629:
695         Fix targets that run multiple make's to use && rather than ;
696         so that subsequent steps depend on success of previous.
697
698         NOTE: if building 'universe' with -j* on stable/8 or stable/9
699         it would be better to start the build using bmake, to avoid
700         overloading the machine.
701
702 20130618:
703         Fix a bug that allowed a tracing process (e.g. gdb) to write
704         to a memory-mapped file in the traced process's address space
705         even if neither the traced process nor the tracing process had
706         write access to that file.
707
708 20130615:
709         CVS has been removed from the base system.  An exact copy
710         of the code is available from the devel/cvs port.
711
712 20130613:
713         Some people report the following error after the switch to bmake:
714
715                 make: illegal option -- J
716                 usage: make [-BPSXeiknpqrstv] [-C directory] [-D variable]
717                         ...
718                 *** [buildworld] Error code 2
719
720         this likely due to an old instance of make in
721         ${MAKEPATH} (${MAKEOBJDIRPREFIX}${.CURDIR}/make.${MACHINE})
722         which src/Makefile will use that blindly, if it exists, so if
723         you see the above error:
724
725                 rm -rf `make -V MAKEPATH`
726
727         should resolve it.
728
729 20130516:
730         Use bmake by default.
731         Whereas before one could choose to build with bmake via
732         -DWITH_BMAKE one must now use -DWITHOUT_BMAKE to use the old
733         make. The goal is to remove these knobs for 10-RELEASE.
734
735         It is worth noting that bmake (like gmake) treats the command
736         line as the unit of failure, rather than statements within the
737         command line.  Thus '(cd some/where && dosomething)' is safer
738         than 'cd some/where; dosomething'. The '()' allows consistent
739         behavior in parallel build.
740
741 20130429:
742         Fix a bug that allows NFS clients to issue READDIR on files.
743
744 20130426:
745         The WITHOUT_IDEA option has been removed because
746         the IDEA patent expired.
747
748 20130426:
749         The sysctl which controls TRIM support under ZFS has been renamed
750         from vfs.zfs.trim_disable -> vfs.zfs.trim.enabled and has been
751         enabled by default.
752
753 20130425:
754         The mergemaster command now uses the default MAKEOBJDIRPREFIX
755         rather than creating it's own in the temporary directory in
756         order allow access to bootstrapped versions of tools such as
757         install and mtree.  When upgrading from version of FreeBSD where
758         the install command does not support -l, you will need to
759         install a new mergemaster command if mergemaster -p is required.
760         This can be accomplished with the command (cd src/usr.sbin/mergemaster
761         && make install).
762
763 20130404:
764         Legacy ATA stack, disabled and replaced by new CAM-based one since
765         FreeBSD 9.0, completely removed from the sources.  Kernel modules
766         atadisk and atapi*, user-level tools atacontrol and burncd are
767         removed.  Kernel option `options ATA_CAM` is now permanently enabled
768         and removed.
769
770 20130319:
771         SOCK_CLOEXEC and SOCK_NONBLOCK flags have been added to socket(2)
772         and socketpair(2). Software, in particular Kerberos, may
773         automatically detect and use these during building. The resulting
774         binaries will not work on older kernels.
775
776 20130308:
777         CTL_DISABLE has also been added to the sparc64 GENERIC (for further
778         information, see the respective 20130304 entry).
779
780 20130304:
781         Recent commits to callout(9) changed the size of struct callout,
782         so the KBI is probably heavily disturbed. Also, some functions
783         in callout(9)/sleep(9)/sleepqueue(9)/condvar(9) KPIs were replaced
784         by macros. Every kernel module using it won't load, so rebuild
785         is requested.
786
787         The ctl device has been re-enabled in GENERIC for i386 and amd64,
788         but does not initialize by default (because of the new CTL_DISABLE
789         option) to save memory.  To re-enable it, remove the CTL_DISABLE
790         option from the kernel config file or set kern.cam.ctl.disable=0
791         in /boot/loader.conf.
792
793 20130301:
794         The ctl device has been disabled in GENERIC for i386 and amd64.
795         This was done due to the extra memory being allocated at system
796         initialisation time by the ctl driver which was only used if
797         a CAM target device was created.  This makes a FreeBSD system
798         unusable on 128MB or less of RAM.
799
800 20130208:
801         A new compression method (lz4) has been merged to -HEAD.  Please
802         refer to zpool-features(7) for more information.
803
804         Please refer to the "ZFS notes" section of this file for information
805         on upgrading boot ZFS pools.
806
807 20130129:
808         A BSD-licensed patch(1) variant has been added and is installed
809         as bsdpatch, being the GNU version the default patch.
810         To inverse the logic and use the BSD-licensed one as default,
811         while having the GNU version installed as gnupatch, rebuild
812         and install world with the WITH_BSD_PATCH knob set.
813
814 20130121:
815         Due to the use of the new -l option to install(1) during build
816         and install, you must take care not to directly set the INSTALL
817         make variable in your /etc/make.conf, /etc/src.conf, or on the
818         command line.  If you wish to use the -C flag for all installs
819         you may be able to add INSTALL+=-C to /etc/make.conf or
820         /etc/src.conf.
821
822 20130118:
823         The install(1) option -M has changed meaning and now takes an
824         argument that is a file or path to append logs to.  In the
825         unlikely event that -M was the last option on the command line
826         and the command line contained at least two files and a target
827         directory the first file will have logs appended to it.  The -M
828         option served little practical purpose in the last decade so its
829         use is expected to be extremely rare.
830
831 20121223:
832         After switching to Clang as the default compiler some users of ZFS
833         on i386 systems started to experience stack overflow kernel panics.
834         Please consider using 'options KSTACK_PAGES=4' in such configurations.
835
836 20121222:
837         GEOM_LABEL now mangles label names read from file system metadata.
838         Mangling affect labels containing spaces, non-printable characters,
839         '%' or '"'. Device names in /etc/fstab and other places may need to
840         be updated.
841
842 20121217:
843         By default, only the 10 most recent kernel dumps will be saved.  To
844         restore the previous behaviour (no limit on the number of kernel dumps
845         stored in the dump directory) add the following line to /etc/rc.conf:
846
847                 savecore_flags=""
848
849 20121201:
850         With the addition of auditdistd(8), a new auditdistd user is now
851         required during installworld.  "mergemaster -p" can be used to
852         add the user prior to installworld, as documented in the handbook.
853
854 20121117:
855         The sin6_scope_id member variable in struct sockaddr_in6 is now
856         filled by the kernel before passing the structure to the userland via
857         sysctl or routing socket.  This means the KAME-specific embedded scope
858         id in sin6_addr.s6_addr[2] is always cleared in userland application.
859         This behavior can be controlled by net.inet6.ip6.deembed_scopeid.
860         __FreeBSD_version is bumped to 1000025.
861
862 20121105:
863         On i386 and amd64 systems WITH_CLANG_IS_CC is now the default.
864         This means that the world and kernel will be compiled with clang
865         and that clang will be installed as /usr/bin/cc, /usr/bin/c++,
866         and /usr/bin/cpp.  To disable this behavior and revert to building
867         with gcc, compile with WITHOUT_CLANG_IS_CC. Really old versions
868         of current may need to bootstrap WITHOUT_CLANG first if the clang
869         build fails (its compatibility window doesn't extend to the 9 stable
870         branch point).
871
872 20121102:
873         The IPFIREWALL_FORWARD kernel option has been removed. Its
874         functionality now turned on by default.
875
876 20121023:
877         The ZERO_COPY_SOCKET kernel option has been removed and
878         split into SOCKET_SEND_COW and SOCKET_RECV_PFLIP.
879         NB: SOCKET_SEND_COW uses the VM page based copy-on-write
880         mechanism which is not safe and may result in kernel crashes.
881         NB: The SOCKET_RECV_PFLIP mechanism is useless as no current
882         driver supports disposeable external page sized mbuf storage.
883         Proper replacements for both zero-copy mechanisms are under
884         consideration and will eventually lead to complete removal
885         of the two kernel options.
886
887 20121023:
888         The IPv4 network stack has been converted to network byte
889         order. The following modules need to be recompiled together
890         with kernel: carp(4), divert(4), gif(4), siftr(4), gre(4),
891         pf(4), ipfw(4), ng_ipfw(4), stf(4).
892
893 20121022:
894         Support for non-MPSAFE filesystems was removed from VFS. The
895         VFS_VERSION was bumped, all filesystem modules shall be
896         recompiled.
897
898 20121018:
899         All the non-MPSAFE filesystems have been disconnected from
900         the build. The full list includes: codafs, hpfs, ntfs, nwfs,
901         portalfs, smbfs, xfs.
902
903 20121016:
904         The interface cloning API and ABI has changed. The following
905         modules need to be recompiled together with kernel:
906         ipfw(4), pfsync(4), pflog(4), usb(4), wlan(4), stf(4),
907         vlan(4), disc(4), edsc(4), if_bridge(4), gif(4), tap(4),
908         faith(4), epair(4), enc(4), tun(4), if_lagg(4), gre(4).
909
910 20121015:
911         The sdhci driver was split in two parts: sdhci (generic SD Host
912         Controller logic) and sdhci_pci (actual hardware driver).
913         No kernel config modifications are required, but if you
914         load sdhc as a module you must switch to sdhci_pci instead.
915
916 20121014:
917         Import the FUSE kernel and userland support into base system.
918
919 20121013:
920         The GNU sort(1) program has been removed since the BSD-licensed
921         sort(1) has been the default for quite some time and no serious
922         problems have been reported.  The corresponding WITH_GNU_SORT
923         knob has also gone.
924
925 20121006:
926         The pfil(9) API/ABI for AF_INET family has been changed. Packet
927         filtering modules: pf(4), ipfw(4), ipfilter(4) need to be recompiled
928         with new kernel.
929
930 20121001:
931         The net80211(4) ABI has been changed to allow for improved driver
932         PS-POLL and power-save support.  All wireless drivers need to be
933         recompiled to work with the new kernel.
934
935 20120913:
936         The random(4) support for the VIA hardware random number
937         generator (`PADLOCK') is no longer enabled unconditionally.
938         Add the padlock_rng device in the custom kernel config if
939         needed.  The GENERIC kernels on i386 and amd64 do include the
940         device, so the change only affects the custom kernel
941         configurations.
942
943 20120908:
944         The pf(4) packet filter ABI has been changed. pfctl(8) and
945         snmp_pf module need to be recompiled to work with new kernel.
946
947 20120828:
948         A new ZFS feature flag "com.delphix:empty_bpobj" has been merged
949         to -HEAD. Pools that have empty_bpobj in active state can not be
950         imported read-write with ZFS implementations that do not support
951         this feature. For more information read the zpool-features(5)
952         manual page.
953
954 20120727:
955         The sparc64 ZFS loader has been changed to no longer try to auto-
956         detect ZFS providers based on diskN aliases but now requires these
957         to be explicitly listed in the OFW boot-device environment variable. 
958
959 20120712:
960         The OpenSSL has been upgraded to 1.0.1c.  Any binaries requiring
961         libcrypto.so.6 or libssl.so.6 must be recompiled.  Also, there are
962         configuration changes.  Make sure to merge /etc/ssl/openssl.cnf.
963
964 20120712:
965         The following sysctls and tunables have been renamed for consistency
966         with other variables:
967           kern.cam.da.da_send_ordered   -> kern.cam.da.send_ordered
968           kern.cam.ada.ada_send_ordered -> kern.cam.ada.send_ordered
969
970 20120628:
971         The sort utility has been replaced with BSD sort.  For now, GNU sort
972         is also available as "gnusort" or the default can be set back to
973         GNU sort by setting WITH_GNU_SORT.  In this case, BSD sort will be
974         installed as "bsdsort".
975
976 20120611:
977         A new version of ZFS (pool version 5000) has been merged to -HEAD.
978         Starting with this version the old system of ZFS pool versioning
979         is superseded by "feature flags". This concept enables forward
980         compatibility against certain future changes in functionality of ZFS
981         pools. The first read-only compatible "feature flag" for ZFS pools
982         is named "com.delphix:async_destroy". For more information
983         read the new zpool-features(5) manual page.
984         Please refer to the "ZFS notes" section of this file for information
985         on upgrading boot ZFS pools.
986
987 20120417:
988         The malloc(3) implementation embedded in libc now uses sources imported
989         as contrib/jemalloc.  The most disruptive API change is to
990         /etc/malloc.conf.  If your system has an old-style /etc/malloc.conf,
991         delete it prior to installworld, and optionally re-create it using the
992         new format after rebooting.  See malloc.conf(5) for details
993         (specifically the TUNING section and the "opt.*" entries in the MALLCTL
994         NAMESPACE section).
995
996 20120328:
997         Big-endian MIPS TARGET_ARCH values no longer end in "eb".  mips64eb
998         is now spelled mips64.  mipsn32eb is now spelled mipsn32.  mipseb is
999         now spelled mips.  This is to aid compatibility with third-party
1000         software that expects this naming scheme in uname(3).  Little-endian
1001         settings are unchanged. If you are updating a big-endian mips64 machine
1002         from before this change, you may need to set MACHINE_ARCH=mips64 in
1003         your environment before the new build system will recognize your machine.
1004
1005 20120306:
1006         Disable by default the option VFS_ALLOW_NONMPSAFE for all supported
1007         platforms.
1008
1009 20120229:
1010         Now unix domain sockets behave "as expected" on nullfs(5). Previously
1011         nullfs(5) did not pass through all behaviours to the underlying layer,
1012         as a result if we bound to a socket on the lower layer we could connect
1013         only to the lower path; if we bound to the upper layer we could connect
1014         only to the upper path. The new behavior is one can connect to both the
1015         lower and the upper paths regardless what layer path one binds to.
1016
1017 20120211:
1018         The getifaddrs upgrade path broken with 20111215 has been restored.
1019         If you have upgraded in between 20111215 and 20120209 you need to
1020         recompile libc again with your kernel.  You still need to recompile
1021         world to be able to configure CARP but this restriction already
1022         comes from 20111215.
1023
1024 20120114:
1025         The set_rcvar() function has been removed from /etc/rc.subr.  All
1026         base and ports rc.d scripts have been updated, so if you have a
1027         port installed with a script in /usr/local/etc/rc.d you can either
1028         hand-edit the rcvar= line, or reinstall the port.
1029
1030         An easy way to handle the mass-update of /etc/rc.d:
1031         rm /etc/rc.d/* && mergemaster -i
1032
1033 20120109:
1034         panic(9) now stops other CPUs in the SMP systems, disables interrupts
1035         on the current CPU and prevents other threads from running.
1036         This behavior can be reverted using the kern.stop_scheduler_on_panic
1037         tunable/sysctl.
1038         The new behavior can be incompatible with kern.sync_on_panic.
1039
1040 20111215:
1041         The carp(4) facility has been changed significantly. Configuration
1042         of the CARP protocol via ifconfig(8) has changed, as well as format
1043         of CARP events submitted to devd(8) has changed. See manual pages
1044         for more information. The arpbalance feature of carp(4) is currently
1045         not supported anymore.
1046
1047         Size of struct in_aliasreq, struct in6_aliasreq has changed. User
1048         utilities using SIOCAIFADDR, SIOCAIFADDR_IN6, e.g. ifconfig(8),
1049         need to be recompiled.
1050
1051 20111122:
1052         The acpi_wmi(4) status device /dev/wmistat has been renamed to
1053         /dev/wmistat0.
1054
1055 20111108:
1056         The option VFS_ALLOW_NONMPSAFE option has been added in order to
1057         explicitely support non-MPSAFE filesystems.
1058         It is on by default for all supported platform at this present
1059         time.
1060
1061 20111101:
1062         The broken amd(4) driver has been replaced with esp(4) in the amd64,
1063         i386 and pc98 GENERIC kernel configuration files.
1064
1065 20110930:
1066         sysinstall has been removed
1067
1068 20110923:
1069         The stable/9 branch created in subversion.  This corresponds to the
1070         RELENG_9 branch in CVS.
1071
1072 COMMON ITEMS:
1073
1074         General Notes
1075         -------------
1076         Avoid using make -j when upgrading.  While generally safe, there are
1077         sometimes problems using -j to upgrade.  If your upgrade fails with
1078         -j, please try again without -j.  From time to time in the past there
1079         have been problems using -j with buildworld and/or installworld.  This
1080         is especially true when upgrading between "distant" versions (eg one
1081         that cross a major release boundary or several minor releases, or when
1082         several months have passed on the -current branch).
1083
1084         Sometimes, obscure build problems are the result of environment
1085         poisoning.  This can happen because the make utility reads its
1086         environment when searching for values for global variables.  To run
1087         your build attempts in an "environmental clean room", prefix all make
1088         commands with 'env -i '.  See the env(1) manual page for more details.
1089
1090         When upgrading from one major version to another it is generally best
1091         to upgrade to the latest code in the currently installed branch first,
1092         then do an upgrade to the new branch. This is the best-tested upgrade
1093         path, and has the highest probability of being successful.  Please try
1094         this approach before reporting problems with a major version upgrade.
1095
1096         When upgrading a live system, having a root shell around before
1097         installing anything can help undo problems. Not having a root shell
1098         around can lead to problems if pam has changed too much from your
1099         starting point to allow continued authentication after the upgrade.
1100
1101         ZFS notes
1102         ---------
1103         When upgrading the boot ZFS pool to a new version, always follow
1104         these two steps:
1105
1106         1.) recompile and reinstall the ZFS boot loader and boot block
1107         (this is part of "make buildworld" and "make installworld")
1108
1109         2.) update the ZFS boot block on your boot drive
1110
1111         The following example updates the ZFS boot block on the first
1112         partition (freebsd-boot) of a GPT partitioned drive ada0:
1113         "gpart bootcode -p /boot/gptzfsboot -i 1 ada0"
1114
1115         Non-boot pools do not need these updates.
1116
1117         To build a kernel
1118         -----------------
1119         If you are updating from a prior version of FreeBSD (even one just
1120         a few days old), you should follow this procedure.  It is the most
1121         failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
1122
1123         make kernel-toolchain
1124         make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
1125         make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
1126
1127         To test a kernel once
1128         ---------------------
1129         If you just want to boot a kernel once (because you are not sure
1130         if it works, or if you want to boot a known bad kernel to provide
1131         debugging information) run
1132         make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
1133         nextboot -k testkernel
1134
1135         To just build a kernel when you know that it won't mess you up
1136         --------------------------------------------------------------
1137         This assumes you are already running a CURRENT system.  Replace
1138         ${arch} with the architecture of your machine (e.g. "i386",
1139         "arm", "amd64", "ia64", "pc98", "sparc64", "powerpc", "mips", etc).
1140
1141         cd src/sys/${arch}/conf
1142         config KERNEL_NAME_HERE
1143         cd ../compile/KERNEL_NAME_HERE
1144         make depend
1145         make
1146         make install
1147
1148         If this fails, go to the "To build a kernel" section.
1149
1150         To rebuild everything and install it on the current system.
1151         -----------------------------------------------------------
1152         # Note: sometimes if you are running current you gotta do more than
1153         # is listed here if you are upgrading from a really old current.
1154
1155         <make sure you have good level 0 dumps>
1156         make buildworld
1157         make kernel KERNCONF=YOUR_KERNEL_HERE
1158                                                         [1]
1159         <reboot in single user>                         [3]
1160         mergemaster -Fp                                 [5]
1161         make installworld
1162         mergemaster -Fi                                 [4]
1163         make delete-old                                 [6]
1164         <reboot>
1165
1166         To cross-install current onto a separate partition
1167         --------------------------------------------------
1168         # In this approach we use a separate partition to hold
1169         # current's root, 'usr', and 'var' directories.   A partition
1170         # holding "/", "/usr" and "/var" should be about 2GB in
1171         # size.
1172
1173         <make sure you have good level 0 dumps>
1174         <boot into -stable>
1175         make buildworld
1176         make buildkernel KERNCONF=YOUR_KERNEL_HERE
1177         <maybe newfs current's root partition>
1178         <mount current's root partition on directory ${CURRENT_ROOT}>
1179         make installworld DESTDIR=${CURRENT_ROOT} -DDB_FROM_SRC
1180         make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
1181         make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
1182         cp /etc/fstab ${CURRENT_ROOT}/etc/fstab                    # if newfs'd
1183         <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
1184         <reboot into current>
1185         <do a "native" rebuild/install as described in the previous section>
1186         <maybe install compatibility libraries from ports/misc/compat*>
1187         <reboot>
1188
1189
1190         To upgrade in-place from stable to current
1191         ----------------------------------------------
1192         <make sure you have good level 0 dumps>
1193         make buildworld                                 [9]
1194         make kernel KERNCONF=YOUR_KERNEL_HERE           [8]
1195                                                         [1]
1196         <reboot in single user>                         [3]
1197         mergemaster -Fp                                 [5]
1198         make installworld
1199         mergemaster -Fi                                 [4]
1200         make delete-old                                 [6]
1201         <reboot>
1202
1203         Make sure that you've read the UPDATING file to understand the
1204         tweaks to various things you need.  At this point in the life
1205         cycle of current, things change often and you are on your own
1206         to cope.  The defaults can also change, so please read ALL of
1207         the UPDATING entries.
1208
1209         Also, if you are tracking -current, you must be subscribed to
1210         freebsd-current@freebsd.org.  Make sure that before you update
1211         your sources that you have read and understood all the recent
1212         messages there.  If in doubt, please track -stable which has
1213         much fewer pitfalls.
1214
1215         [1] If you have third party modules, such as vmware, you
1216         should disable them at this point so they don't crash your
1217         system on reboot.
1218
1219         [3] From the bootblocks, boot -s, and then do
1220                 fsck -p
1221                 mount -u /
1222                 mount -a
1223                 cd src
1224                 adjkerntz -i            # if CMOS is wall time
1225         Also, when doing a major release upgrade, it is required that
1226         you boot into single user mode to do the installworld.
1227
1228         [4] Note: This step is non-optional.  Failure to do this step
1229         can result in a significant reduction in the functionality of the
1230         system.  Attempting to do it by hand is not recommended and those
1231         that pursue this avenue should read this file carefully, as well
1232         as the archives of freebsd-current and freebsd-hackers mailing lists
1233         for potential gotchas.  The -U option is also useful to consider.
1234         See mergemaster(8) for more information.
1235
1236         [5] Usually this step is a noop.  However, from time to time
1237         you may need to do this if you get unknown user in the following
1238         step.  It never hurts to do it all the time.  You may need to
1239         install a new mergemaster (cd src/usr.sbin/mergemaster && make
1240         install) after the buildworld before this step if you last updated
1241         from current before 20130425 or from -stable before 20130430.
1242
1243         [6] This only deletes old files and directories. Old libraries
1244         can be deleted by "make delete-old-libs", but you have to make
1245         sure that no program is using those libraries anymore.
1246
1247         [8] In order to have a kernel that can run the 4.x binaries needed to
1248         do an installworld, you must include the COMPAT_FREEBSD4 option in
1249         your kernel.  Failure to do so may leave you with a system that is
1250         hard to boot to recover. A similar kernel option COMPAT_FREEBSD5 is
1251         required to run the 5.x binaries on more recent kernels.  And so on
1252         for COMPAT_FREEBSD6 and COMPAT_FREEBSD7.
1253
1254         Make sure that you merge any new devices from GENERIC since the
1255         last time you updated your kernel config file.
1256
1257         [9] When checking out sources, you must include the -P flag to have
1258         cvs prune empty directories.
1259
1260         If CPUTYPE is defined in your /etc/make.conf, make sure to use the
1261         "?=" instead of the "=" assignment operator, so that buildworld can
1262         override the CPUTYPE if it needs to.
1263
1264         MAKEOBJDIRPREFIX must be defined in an environment variable, and
1265         not on the command line, or in /etc/make.conf.  buildworld will
1266         warn if it is improperly defined.
1267 FORMAT:
1268
1269 This file contains a list, in reverse chronological order, of major
1270 breakages in tracking -current.  It is not guaranteed to be a complete
1271 list of such breakages, and only contains entries since October 10, 2007.
1272 If you need to see UPDATING entries from before that date, you will need
1273 to fetch an UPDATING file from an older FreeBSD release.
1274
1275 Copyright information:
1276
1277 Copyright 1998-2009 M. Warner Losh.  All Rights Reserved.
1278
1279 Redistribution, publication, translation and use, with or without
1280 modification, in full or in part, in any form or format of this
1281 document are permitted without further permission from the author.
1282
1283 THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
1284 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1285 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1286 DISCLAIMED.  IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
1287 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1288 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1289 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1290 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1291 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
1292 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1293 POSSIBILITY OF SUCH DAMAGE.
1294
1295 Contact Warner Losh if you have any questions about your use of
1296 this document.
1297
1298 $FreeBSD$