1 Updating Information for FreeBSD current users
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
9 http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html
11 Items affecting the ports and packages system can be found in
12 /usr/ports/UPDATING. Please read that file before running portupgrade.
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.
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".)
35 The default unbound configuration has been modified to address
36 issues with reverse lookups on networks that use private
37 address ranges. If you use the local_unbound service, run
38 "service local_unbound setup" as root to regenerate your
39 configuration, then "service local_unbound reload" to load the
43 The GNU texinfo and GNU info pages are not built and installed
44 anymore, WITH_INFO knob has been added to allow to built and install
48 The GNU readline library is now an INTERNALLIB - that is, it is
49 statically linked into consumers (GDB and variants) in the base
50 system, and the shared library is no longer installed. The
51 devel/readline port is available for third party software that
55 The Itanium architecture (ia64) has been removed from the list of
56 known architectures. This is the first step in the removal of the
60 Commit r268115 has added NFSv4.1 server support, merged from
61 projects/nfsv4.1-server. Since this includes changes to the
62 internal interfaces between the NFS related modules, a full
63 build of the kernel and modules will be necessary.
64 __FreeBSD_version has been bumped.
67 The WITHOUT_VT_SUPPORT kernel config knob has been renamed
68 WITHOUT_VT. (The other _SUPPORT knobs have a consistent meaning
69 which differs from the behaviour controlled by this knob.)
72 Maximal length of the serial number in CTL was increased from 16 to
73 64 chars, that breaks ABI. All CTL-related tools, such as ctladm
74 and ctld, need to be rebuilt to work with a new kernel.
77 The libatf-c and libatf-c++ major versions were downgraded to 0 and
78 1 respectively to match the upstream numbers. They were out of
79 sync because, when they were originally added to FreeBSD, the
80 upstream versions were not respected. These libraries are private
81 and not yet built by default, so renumbering them should be a
82 non-issue. However, unclean source trees will yield broken test
83 programs once the operator executes "make delete-old-libs" after a
86 Additionally, the atf-sh binary was made private by moving it into
87 /usr/libexec/. Already-built shell test programs will keep the
88 path to the old binary so they will break after "make delete-old"
91 If you are using WITH_TESTS=yes (not the default), wipe the object
92 tree and rebuild from scratch to prevent spurious test failures.
93 This is only needed once: the misnumbered libraries and misplaced
94 binaries have been added to OptionalObsoleteFiles.inc so they will
95 be removed during a clean upgrade.
98 Clang and llvm have been upgraded to 3.4.1 release.
101 We bogusly installed src.opts.mk in /usr/share/mk. This file should
102 be removed to avoid issues in the future (and has been added to
106 /etc/src.conf now affects only builds of the FreeBSD src tree. In the
107 past, it affected all builds that used the bsd.*.mk files. The old
108 behavior was a bug, but people may have relied upon it. To get this
109 behavior back, you can .include /etc/src.conf from /etc/make.conf
110 (which is still global and isn't changed). This also changes the
111 behavior of incremental builds inside the tree of individual
112 directories. Set MAKESYSPATH to ".../share/mk" to do that.
113 Although this has survived make universe and some upgrade scenarios,
114 other upgrade scenarios may have broken. At least one form of
115 temporary breakage was fixed with MAKESYSPATH settings for buildworld
116 as well... In cases where MAKESYSPATH isn't working with this
117 setting, you'll need to set it to the full path to your tree.
119 One side effect of all this cleaning up is that bsd.compiler.mk
120 is no longer implicitly included by bsd.own.mk. If you wish to
121 use COMPILER_TYPE, you must now explicitly include bsd.compiler.mk
125 The lindev device has been removed since /dev/full has been made a
126 standard device. __FreeBSD_version has been bumped.
129 The YES_HESIOD knob has been removed. It has been obsolete for
130 a decade. Please move to using WITH_HESIOD instead or your builds
131 will silently lack HESIOD.
134 The uart(4) driver has been changed with respect to its handling
135 of the low-level console. Previously the uart(4) driver prevented
136 any process from changing the baudrate or the CLOCAL and HUPCL
137 control flags. By removing the restrictions, operators can make
138 changes to the serial console port without having to reboot.
139 However, when getty(8) is started on the serial device that is
140 associated with the low-level console, a misconfigured terminal
141 line in /etc/ttys will now have a real impact.
142 Before upgrading the kernel, make sure that /etc/ttys has the
143 serial console device configured as 3wire without baudrate to
144 preserve the previous behaviour. E.g:
145 ttyu0 "/usr/libexec/getty 3wire" vt100 on secure
148 Support for libwrap (TCP wrappers) in rpcbind was disabled by default
149 to improve performance. To re-enable it, if needed, run rpcbind
150 with command line option -W.
153 Switched back to the GPL dtc compiler due to updates in the upstream
154 dts files not being supported by the BSDL dtc compiler. You will need
155 to rebuild your kernel toolchain to pick up the new compiler. Core dumps
156 may result while building dtb files during a kernel build if you fail
157 to do so. Set WITHOUT_GPL_DTC if you require the BSDL compiler.
160 Clang and llvm have been upgraded to 3.4 release.
163 The nve(4) driver has been removed. Please use the nfe(4) driver
164 for NVIDIA nForce MCP Ethernet adapters instead.
167 An ABI incompatibility crept into the libc++ 3.4 import in r261283.
168 This could cause certain C++ applications using shared libraries built
169 against the previous version of libc++ to crash. The incompatibility
170 has now been fixed, but any C++ applications or shared libraries built
171 between r261283 and r261801 should be recompiled.
174 OpenSSH will now ignore errors caused by kernel lacking of Capsicum
175 capability mode support. Please note that enabling the feature in
176 kernel is still highly recommended.
179 OpenSSH is now built with sandbox support, and will use sandbox as
180 the default privilege separation method. This requires Capsicum
181 capability mode support in kernel.
184 The libelf and libdwarf libraries have been updated to newer
185 versions from upstream. Shared library version numbers for
186 these two libraries were bumped. Any ports or binaries
187 requiring these two libraries should be recompiled.
188 __FreeBSD_version is bumped to 1100006.
191 If a Makefile in a tests/ directory was auto-generating a Kyuafile
192 instead of providing an explicit one, this would prevent such
193 Makefile from providing its own Kyuafile in the future during
194 NO_CLEAN builds. This has been fixed in the Makefiles but manual
195 intervention is needed to clean an objdir if you use NO_CLEAN:
196 # find /usr/obj -name Kyuafile | xargs rm -f
199 The behavior of gss_pseudo_random() for the krb5 mechanism
200 has changed, for applications requesting a longer random string
201 than produced by the underlying enctype's pseudo-random() function.
202 In particular, the random string produced from a session key of
203 enctype aes256-cts-hmac-sha1-96 or aes256-cts-hmac-sha1-96 will
204 be different at the 17th octet and later, after this change.
205 The counter used in the PRF+ construction is now encoded as a
206 big-endian integer in accordance with RFC 4402.
207 __FreeBSD_version is bumped to 1100004.
210 The WITHOUT_ATF build knob has been removed and its functionality
211 has been subsumed into the more generic WITHOUT_TESTS. If you were
212 using the former to disable the build of the ATF libraries, you
213 should change your settings to use the latter.
216 The default version of mtree is nmtree which is obtained from
217 NetBSD. The output is generally the same, but may vary
218 slightly. If you found you need identical output adding
219 "-F freebsd9" to the command line should do the trick. For the
220 time being, the old mtree is available as fmtree.
223 libbsdyml has been renamed to libyaml and moved to /usr/lib/private.
224 This will break ports-mgmt/pkg. Rebuild the port, or upgrade to pkg
225 1.1.4_8 and verify bsdyml not linked in, before running "make
227 # make -C /usr/ports/ports-mgmt/pkg build deinstall install clean
229 # pkg install pkg; ldd /usr/local/sbin/pkg | grep bsdyml
232 The rc.d/jail script has been updated to support jail(8)
233 configuration file. The "jail_<jname>_*" rc.conf(5) variables
234 for per-jail configuration are automatically converted to
235 /var/run/jail.<jname>.conf before the jail(8) utility is invoked.
236 This is transparently backward compatible. See below about some
237 incompatibilities and rc.conf(5) manual page for more details.
239 These variables are now deprecated in favor of jail(8) configuration
240 file. One can use "rc.d/jail config <jname>" command to generate
241 a jail(8) configuration file in /var/run/jail.<jname>.conf without
242 running the jail(8) utility. The default pathname of the
243 configuration file is /etc/jail.conf and can be specified by
244 using $jail_conf or $jail_<jname>_conf variables.
246 Please note that jail_devfs_ruleset accepts an integer at
247 this moment. Please consider to rewrite the ruleset name
251 BIND has been removed from the base system. If all you need
252 is a local resolver, simply enable and start the local_unbound
253 service instead. Otherwise, several versions of BIND are
254 available in the ports tree. The dns/bind99 port is one example.
256 With this change, nslookup(1) and dig(1) are no longer in the base
257 system. Users should instead use host(1) and drill(1) which are
258 in the base system. Alternatively, nslookup and dig can
259 be obtained by installing the dns/bind-tools port.
262 With the addition of unbound(8), a new unbound user is now
263 required during installworld. "mergemaster -p" can be used to
264 add the user prior to installworld, as documented in the handbook.
267 OpenSSH is now built with DNSSEC support, and will by default
268 silently trust signed SSHFP records. This can be controlled with
269 the VerifyHostKeyDNS client configuration setting. DNSSEC support
270 can be disabled entirely with the WITHOUT_LDNS option in src.conf.
273 The GNU Compiler Collection and C++ standard library (libstdc++)
274 are no longer built by default on platforms where clang is the system
275 compiler. You can enable them with the WITH_GCC and WITH_GNUCXX
279 The PROCDESC kernel option is now part of the GENERIC kernel
280 configuration and is required for the rwhod(8) to work.
281 If you are using custom kernel configuration, you should include
285 The API and ABI related to the Capsicum framework was modified
286 in backward incompatible way. The userland libraries and programs
287 have to be recompiled to work with the new kernel. This includes the
288 following libraries and programs, but the whole buildworld is
289 advised: libc, libprocstat, dhclient, tcpdump, hastd, hastctl,
290 kdump, procstat, rwho, rwhod, uniq.
293 AES-NI intrinsic support has been added to gcc. The AES-NI module
294 has been updated to use this support. A new gcc is required to build
295 the aesni module on both i386 and amd64.
298 The PADLOCK_RNG and RDRAND_RNG kernel options are now devices.
299 Thus "device padlock_rng" and "device rdrand_rng" should be
300 used instead of "options PADLOCK_RNG" & "options RDRAND_RNG".
303 WITH_ICONV has been split into two feature sets. WITH_ICONV now
304 enables just the iconv* functionality and is now on by default.
305 WITH_LIBICONV_COMPAT enables the libiconv api and link time
306 compatability. Set WITHOUT_ICONV to build the old way.
307 If you have been using WITH_ICONV before, you will very likely
308 need to turn on WITH_LIBICONV_COMPAT.
311 INVARIANTS option now enables DEBUG for code with OpenSolaris and
312 Illumos origin, including ZFS. If you have INVARIANTS in your
313 kernel configuration, then there is no need to set DEBUG or ZFS_DEBUG
315 DEBUG used to enable witness(9) tracking of OpenSolaris (mostly ZFS)
316 locks if WITNESS option was set. Because that generated a lot of
317 witness(9) reports and all of them were believed to be false
318 positives, this is no longer done. New option OPENSOLARIS_WITNESS
319 can be used to achieve the previous behavior.
322 Timer values in IPv6 data structures now use time_uptime instead
323 of time_second. Although this is not a user-visible functional
324 change, userland utilities which directly use them---ndp(8),
325 rtadvd(8), and rtsold(8) in the base system---need to be updated
329 find -delete can now delete the pathnames given as arguments,
330 instead of only files found below them or if the pathname did
331 not contain any slashes. Formerly, the following error message
334 find: -delete: <path>: relative path potentially not safe
336 Deleting the pathnames given as arguments can be prevented
337 without error messages using -mindepth 1 or by changing
338 directory and passing "." as argument to find. This works in the
339 old as well as the new version of find.
342 Behavior of devfs rules path matching has been changed.
343 Pattern is now always matched against fully qualified devfs
344 path and slash characters must be explicitly matched by
345 slashes in pattern (FNM_PATHNAME). Rulesets involving devfs
346 subdirectories must be reviewed.
349 The default ARM ABI has changed to the ARM EABI. The old ABI is
350 incompatible with the ARM EABI and all programs and modules will
351 need to be rebuilt to work with a new kernel.
353 To keep using the old ABI ensure the WITHOUT_ARM_EABI knob is set.
355 NOTE: Support for the old ABI will be removed in the future and
356 users are advised to upgrade.
359 pkg_install has been disconnected from the build if you really need it
360 you should add WITH_PKGTOOLS in your src.conf(5).
363 Most of network statistics structures were changed to be able
364 keep 64-bits counters. Thus all tools, that work with networking
365 statistics, must be rebuilt (netstat(1), bsnmpd(1), etc.)
368 Fix targets that run multiple make's to use && rather than ;
369 so that subsequent steps depend on success of previous.
371 NOTE: if building 'universe' with -j* on stable/8 or stable/9
372 it would be better to start the build using bmake, to avoid
373 overloading the machine.
376 Fix a bug that allowed a tracing process (e.g. gdb) to write
377 to a memory-mapped file in the traced process's address space
378 even if neither the traced process nor the tracing process had
379 write access to that file.
382 CVS has been removed from the base system. An exact copy
383 of the code is available from the devel/cvs port.
386 Some people report the following error after the switch to bmake:
388 make: illegal option -- J
389 usage: make [-BPSXeiknpqrstv] [-C directory] [-D variable]
391 *** [buildworld] Error code 2
393 this likely due to an old instance of make in
394 ${MAKEPATH} (${MAKEOBJDIRPREFIX}${.CURDIR}/make.${MACHINE})
395 which src/Makefile will use that blindly, if it exists, so if
396 you see the above error:
398 rm -rf `make -V MAKEPATH`
403 Use bmake by default.
404 Whereas before one could choose to build with bmake via
405 -DWITH_BMAKE one must now use -DWITHOUT_BMAKE to use the old
406 make. The goal is to remove these knobs for 10-RELEASE.
408 It is worth noting that bmake (like gmake) treats the command
409 line as the unit of failure, rather than statements within the
410 command line. Thus '(cd some/where && dosomething)' is safer
411 than 'cd some/where; dosomething'. The '()' allows consistent
412 behavior in parallel build.
415 Fix a bug that allows NFS clients to issue READDIR on files.
418 The WITHOUT_IDEA option has been removed because
419 the IDEA patent expired.
422 The sysctl which controls TRIM support under ZFS has been renamed
423 from vfs.zfs.trim_disable -> vfs.zfs.trim.enabled and has been
427 The mergemaster command now uses the default MAKEOBJDIRPREFIX
428 rather than creating it's own in the temporary directory in
429 order allow access to bootstrapped versions of tools such as
430 install and mtree. When upgrading from version of FreeBSD where
431 the install command does not support -l, you will need to
432 install a new mergemaster command if mergemaster -p is required.
433 This can be accomplished with the command (cd src/usr.sbin/mergemaster
437 Legacy ATA stack, disabled and replaced by new CAM-based one since
438 FreeBSD 9.0, completely removed from the sources. Kernel modules
439 atadisk and atapi*, user-level tools atacontrol and burncd are
440 removed. Kernel option `options ATA_CAM` is now permanently enabled
444 SOCK_CLOEXEC and SOCK_NONBLOCK flags have been added to socket(2)
445 and socketpair(2). Software, in particular Kerberos, may
446 automatically detect and use these during building. The resulting
447 binaries will not work on older kernels.
450 CTL_DISABLE has also been added to the sparc64 GENERIC (for further
451 information, see the respective 20130304 entry).
454 Recent commits to callout(9) changed the size of struct callout,
455 so the KBI is probably heavily disturbed. Also, some functions
456 in callout(9)/sleep(9)/sleepqueue(9)/condvar(9) KPIs were replaced
457 by macros. Every kernel module using it won't load, so rebuild
460 The ctl device has been re-enabled in GENERIC for i386 and amd64,
461 but does not initialize by default (because of the new CTL_DISABLE
462 option) to save memory. To re-enable it, remove the CTL_DISABLE
463 option from the kernel config file or set kern.cam.ctl.disable=0
464 in /boot/loader.conf.
467 The ctl device has been disabled in GENERIC for i386 and amd64.
468 This was done due to the extra memory being allocated at system
469 initialisation time by the ctl driver which was only used if
470 a CAM target device was created. This makes a FreeBSD system
471 unusable on 128MB or less of RAM.
474 A new compression method (lz4) has been merged to -HEAD. Please
475 refer to zpool-features(7) for more information.
477 Please refer to the "ZFS notes" section of this file for information
478 on upgrading boot ZFS pools.
481 A BSD-licensed patch(1) variant has been added and is installed
482 as bsdpatch, being the GNU version the default patch.
483 To inverse the logic and use the BSD-licensed one as default,
484 while having the GNU version installed as gnupatch, rebuild
485 and install world with the WITH_BSD_PATCH knob set.
488 Due to the use of the new -l option to install(1) during build
489 and install, you must take care not to directly set the INSTALL
490 make variable in your /etc/make.conf, /etc/src.conf, or on the
491 command line. If you wish to use the -C flag for all installs
492 you may be able to add INSTALL+=-C to /etc/make.conf or
496 The install(1) option -M has changed meaning and now takes an
497 argument that is a file or path to append logs to. In the
498 unlikely event that -M was the last option on the command line
499 and the command line contained at least two files and a target
500 directory the first file will have logs appended to it. The -M
501 option served little practical purpose in the last decade so its
502 use is expected to be extremely rare.
505 After switching to Clang as the default compiler some users of ZFS
506 on i386 systems started to experience stack overflow kernel panics.
507 Please consider using 'options KSTACK_PAGES=4' in such configurations.
510 GEOM_LABEL now mangles label names read from file system metadata.
511 Mangling affect labels containing spaces, non-printable characters,
512 '%' or '"'. Device names in /etc/fstab and other places may need to
516 By default, only the 10 most recent kernel dumps will be saved. To
517 restore the previous behaviour (no limit on the number of kernel dumps
518 stored in the dump directory) add the following line to /etc/rc.conf:
523 With the addition of auditdistd(8), a new auditdistd user is now
524 required during installworld. "mergemaster -p" can be used to
525 add the user prior to installworld, as documented in the handbook.
528 The sin6_scope_id member variable in struct sockaddr_in6 is now
529 filled by the kernel before passing the structure to the userland via
530 sysctl or routing socket. This means the KAME-specific embedded scope
531 id in sin6_addr.s6_addr[2] is always cleared in userland application.
532 This behavior can be controlled by net.inet6.ip6.deembed_scopeid.
533 __FreeBSD_version is bumped to 1000025.
536 On i386 and amd64 systems WITH_CLANG_IS_CC is now the default.
537 This means that the world and kernel will be compiled with clang
538 and that clang will be installed as /usr/bin/cc, /usr/bin/c++,
539 and /usr/bin/cpp. To disable this behavior and revert to building
540 with gcc, compile with WITHOUT_CLANG_IS_CC. Really old versions
541 of current may need to bootstrap WITHOUT_CLANG first if the clang
542 build fails (its compatibility window doesn't extend to the 9 stable
546 The IPFIREWALL_FORWARD kernel option has been removed. Its
547 functionality now turned on by default.
550 The ZERO_COPY_SOCKET kernel option has been removed and
551 split into SOCKET_SEND_COW and SOCKET_RECV_PFLIP.
552 NB: SOCKET_SEND_COW uses the VM page based copy-on-write
553 mechanism which is not safe and may result in kernel crashes.
554 NB: The SOCKET_RECV_PFLIP mechanism is useless as no current
555 driver supports disposeable external page sized mbuf storage.
556 Proper replacements for both zero-copy mechanisms are under
557 consideration and will eventually lead to complete removal
558 of the two kernel options.
561 The IPv4 network stack has been converted to network byte
562 order. The following modules need to be recompiled together
563 with kernel: carp(4), divert(4), gif(4), siftr(4), gre(4),
564 pf(4), ipfw(4), ng_ipfw(4), stf(4).
567 Support for non-MPSAFE filesystems was removed from VFS. The
568 VFS_VERSION was bumped, all filesystem modules shall be
572 All the non-MPSAFE filesystems have been disconnected from
573 the build. The full list includes: codafs, hpfs, ntfs, nwfs,
574 portalfs, smbfs, xfs.
577 The interface cloning API and ABI has changed. The following
578 modules need to be recompiled together with kernel:
579 ipfw(4), pfsync(4), pflog(4), usb(4), wlan(4), stf(4),
580 vlan(4), disc(4), edsc(4), if_bridge(4), gif(4), tap(4),
581 faith(4), epair(4), enc(4), tun(4), if_lagg(4), gre(4).
584 The sdhci driver was split in two parts: sdhci (generic SD Host
585 Controller logic) and sdhci_pci (actual hardware driver).
586 No kernel config modifications are required, but if you
587 load sdhc as a module you must switch to sdhci_pci instead.
590 Import the FUSE kernel and userland support into base system.
593 The GNU sort(1) program has been removed since the BSD-licensed
594 sort(1) has been the default for quite some time and no serious
595 problems have been reported. The corresponding WITH_GNU_SORT
599 The pfil(9) API/ABI for AF_INET family has been changed. Packet
600 filtering modules: pf(4), ipfw(4), ipfilter(4) need to be recompiled
604 The net80211(4) ABI has been changed to allow for improved driver
605 PS-POLL and power-save support. All wireless drivers need to be
606 recompiled to work with the new kernel.
609 The random(4) support for the VIA hardware random number
610 generator (`PADLOCK') is no longer enabled unconditionally.
611 Add the padlock_rng device in the custom kernel config if
612 needed. The GENERIC kernels on i386 and amd64 do include the
613 device, so the change only affects the custom kernel
617 The pf(4) packet filter ABI has been changed. pfctl(8) and
618 snmp_pf module need to be recompiled to work with new kernel.
621 A new ZFS feature flag "com.delphix:empty_bpobj" has been merged
622 to -HEAD. Pools that have empty_bpobj in active state can not be
623 imported read-write with ZFS implementations that do not support
624 this feature. For more information read the zpool-features(5)
628 The sparc64 ZFS loader has been changed to no longer try to auto-
629 detect ZFS providers based on diskN aliases but now requires these
630 to be explicitly listed in the OFW boot-device environment variable.
633 The OpenSSL has been upgraded to 1.0.1c. Any binaries requiring
634 libcrypto.so.6 or libssl.so.6 must be recompiled. Also, there are
635 configuration changes. Make sure to merge /etc/ssl/openssl.cnf.
638 The following sysctls and tunables have been renamed for consistency
639 with other variables:
640 kern.cam.da.da_send_ordered -> kern.cam.da.send_ordered
641 kern.cam.ada.ada_send_ordered -> kern.cam.ada.send_ordered
644 The sort utility has been replaced with BSD sort. For now, GNU sort
645 is also available as "gnusort" or the default can be set back to
646 GNU sort by setting WITH_GNU_SORT. In this case, BSD sort will be
647 installed as "bsdsort".
650 A new version of ZFS (pool version 5000) has been merged to -HEAD.
651 Starting with this version the old system of ZFS pool versioning
652 is superseded by "feature flags". This concept enables forward
653 compatibility against certain future changes in functionality of ZFS
654 pools. The first read-only compatible "feature flag" for ZFS pools
655 is named "com.delphix:async_destroy". For more information
656 read the new zpool-features(5) manual page.
657 Please refer to the "ZFS notes" section of this file for information
658 on upgrading boot ZFS pools.
661 The malloc(3) implementation embedded in libc now uses sources imported
662 as contrib/jemalloc. The most disruptive API change is to
663 /etc/malloc.conf. If your system has an old-style /etc/malloc.conf,
664 delete it prior to installworld, and optionally re-create it using the
665 new format after rebooting. See malloc.conf(5) for details
666 (specifically the TUNING section and the "opt.*" entries in the MALLCTL
670 Big-endian MIPS TARGET_ARCH values no longer end in "eb". mips64eb
671 is now spelled mips64. mipsn32eb is now spelled mipsn32. mipseb is
672 now spelled mips. This is to aid compatibility with third-party
673 software that expects this naming scheme in uname(3). Little-endian
674 settings are unchanged. If you are updating a big-endian mips64 machine
675 from before this change, you may need to set MACHINE_ARCH=mips64 in
676 your environment before the new build system will recognize your machine.
679 Disable by default the option VFS_ALLOW_NONMPSAFE for all supported
683 Now unix domain sockets behave "as expected" on nullfs(5). Previously
684 nullfs(5) did not pass through all behaviours to the underlying layer,
685 as a result if we bound to a socket on the lower layer we could connect
686 only to the lower path; if we bound to the upper layer we could connect
687 only to the upper path. The new behavior is one can connect to both the
688 lower and the upper paths regardless what layer path one binds to.
691 The getifaddrs upgrade path broken with 20111215 has been restored.
692 If you have upgraded in between 20111215 and 20120209 you need to
693 recompile libc again with your kernel. You still need to recompile
694 world to be able to configure CARP but this restriction already
698 The set_rcvar() function has been removed from /etc/rc.subr. All
699 base and ports rc.d scripts have been updated, so if you have a
700 port installed with a script in /usr/local/etc/rc.d you can either
701 hand-edit the rcvar= line, or reinstall the port.
703 An easy way to handle the mass-update of /etc/rc.d:
704 rm /etc/rc.d/* && mergemaster -i
707 panic(9) now stops other CPUs in the SMP systems, disables interrupts
708 on the current CPU and prevents other threads from running.
709 This behavior can be reverted using the kern.stop_scheduler_on_panic
711 The new behavior can be incompatible with kern.sync_on_panic.
714 The carp(4) facility has been changed significantly. Configuration
715 of the CARP protocol via ifconfig(8) has changed, as well as format
716 of CARP events submitted to devd(8) has changed. See manual pages
717 for more information. The arpbalance feature of carp(4) is currently
718 not supported anymore.
720 Size of struct in_aliasreq, struct in6_aliasreq has changed. User
721 utilities using SIOCAIFADDR, SIOCAIFADDR_IN6, e.g. ifconfig(8),
722 need to be recompiled.
725 The acpi_wmi(4) status device /dev/wmistat has been renamed to
729 The option VFS_ALLOW_NONMPSAFE option has been added in order to
730 explicitely support non-MPSAFE filesystems.
731 It is on by default for all supported platform at this present
735 The broken amd(4) driver has been replaced with esp(4) in the amd64,
736 i386 and pc98 GENERIC kernel configuration files.
739 sysinstall has been removed
742 The stable/9 branch created in subversion. This corresponds to the
743 RELENG_9 branch in CVS.
749 Avoid using make -j when upgrading. While generally safe, there are
750 sometimes problems using -j to upgrade. If your upgrade fails with
751 -j, please try again without -j. From time to time in the past there
752 have been problems using -j with buildworld and/or installworld. This
753 is especially true when upgrading between "distant" versions (eg one
754 that cross a major release boundary or several minor releases, or when
755 several months have passed on the -current branch).
757 Sometimes, obscure build problems are the result of environment
758 poisoning. This can happen because the make utility reads its
759 environment when searching for values for global variables. To run
760 your build attempts in an "environmental clean room", prefix all make
761 commands with 'env -i '. See the env(1) manual page for more details.
763 When upgrading from one major version to another it is generally best
764 to upgrade to the latest code in the currently installed branch first,
765 then do an upgrade to the new branch. This is the best-tested upgrade
766 path, and has the highest probability of being successful. Please try
767 this approach before reporting problems with a major version upgrade.
769 When upgrading a live system, having a root shell around before
770 installing anything can help undo problems. Not having a root shell
771 around can lead to problems if pam has changed too much from your
772 starting point to allow continued authentication after the upgrade.
776 When upgrading the boot ZFS pool to a new version, always follow
779 1.) recompile and reinstall the ZFS boot loader and boot block
780 (this is part of "make buildworld" and "make installworld")
782 2.) update the ZFS boot block on your boot drive
784 The following example updates the ZFS boot block on the first
785 partition (freebsd-boot) of a GPT partitioned drive ad0:
786 "gpart bootcode -p /boot/gptzfsboot -i 1 ad0"
788 Non-boot pools do not need these updates.
792 If you are updating from a prior version of FreeBSD (even one just
793 a few days old), you should follow this procedure. It is the most
794 failsafe as it uses a /usr/obj tree with a fresh mini-buildworld,
796 make kernel-toolchain
797 make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE
798 make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE
800 To test a kernel once
801 ---------------------
802 If you just want to boot a kernel once (because you are not sure
803 if it works, or if you want to boot a known bad kernel to provide
804 debugging information) run
805 make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel
806 nextboot -k testkernel
808 To just build a kernel when you know that it won't mess you up
809 --------------------------------------------------------------
810 This assumes you are already running a CURRENT system. Replace
811 ${arch} with the architecture of your machine (e.g. "i386",
812 "arm", "amd64", "ia64", "pc98", "sparc64", "powerpc", "mips", etc).
814 cd src/sys/${arch}/conf
815 config KERNEL_NAME_HERE
816 cd ../compile/KERNEL_NAME_HERE
821 If this fails, go to the "To build a kernel" section.
823 To rebuild everything and install it on the current system.
824 -----------------------------------------------------------
825 # Note: sometimes if you are running current you gotta do more than
826 # is listed here if you are upgrading from a really old current.
828 <make sure you have good level 0 dumps>
830 make kernel KERNCONF=YOUR_KERNEL_HERE
832 <reboot in single user> [3]
839 To cross-install current onto a separate partition
840 --------------------------------------------------
841 # In this approach we use a separate partition to hold
842 # current's root, 'usr', and 'var' directories. A partition
843 # holding "/", "/usr" and "/var" should be about 2GB in
846 <make sure you have good level 0 dumps>
849 make buildkernel KERNCONF=YOUR_KERNEL_HERE
850 <maybe newfs current's root partition>
851 <mount current's root partition on directory ${CURRENT_ROOT}>
852 make installworld DESTDIR=${CURRENT_ROOT} -DDB_FROM_SRC
853 make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd
854 make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT}
855 cp /etc/fstab ${CURRENT_ROOT}/etc/fstab # if newfs'd
856 <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition>
857 <reboot into current>
858 <do a "native" rebuild/install as described in the previous section>
859 <maybe install compatibility libraries from ports/misc/compat*>
863 To upgrade in-place from stable to current
864 ----------------------------------------------
865 <make sure you have good level 0 dumps>
867 make kernel KERNCONF=YOUR_KERNEL_HERE [8]
869 <reboot in single user> [3]
876 Make sure that you've read the UPDATING file to understand the
877 tweaks to various things you need. At this point in the life
878 cycle of current, things change often and you are on your own
879 to cope. The defaults can also change, so please read ALL of
880 the UPDATING entries.
882 Also, if you are tracking -current, you must be subscribed to
883 freebsd-current@freebsd.org. Make sure that before you update
884 your sources that you have read and understood all the recent
885 messages there. If in doubt, please track -stable which has
888 [1] If you have third party modules, such as vmware, you
889 should disable them at this point so they don't crash your
892 [3] From the bootblocks, boot -s, and then do
897 adjkerntz -i # if CMOS is wall time
898 Also, when doing a major release upgrade, it is required that
899 you boot into single user mode to do the installworld.
901 [4] Note: This step is non-optional. Failure to do this step
902 can result in a significant reduction in the functionality of the
903 system. Attempting to do it by hand is not recommended and those
904 that pursue this avenue should read this file carefully, as well
905 as the archives of freebsd-current and freebsd-hackers mailing lists
906 for potential gotchas. The -U option is also useful to consider.
907 See mergemaster(8) for more information.
909 [5] Usually this step is a noop. However, from time to time
910 you may need to do this if you get unknown user in the following
911 step. It never hurts to do it all the time. You may need to
912 install a new mergemaster (cd src/usr.sbin/mergemaster && make
913 install) after the buildworld before this step if you last updated
914 from current before 20130425 or from -stable before 20130430.
916 [6] This only deletes old files and directories. Old libraries
917 can be deleted by "make delete-old-libs", but you have to make
918 sure that no program is using those libraries anymore.
920 [8] In order to have a kernel that can run the 4.x binaries needed to
921 do an installworld, you must include the COMPAT_FREEBSD4 option in
922 your kernel. Failure to do so may leave you with a system that is
923 hard to boot to recover. A similar kernel option COMPAT_FREEBSD5 is
924 required to run the 5.x binaries on more recent kernels. And so on
925 for COMPAT_FREEBSD6 and COMPAT_FREEBSD7.
927 Make sure that you merge any new devices from GENERIC since the
928 last time you updated your kernel config file.
930 [9] When checking out sources, you must include the -P flag to have
931 cvs prune empty directories.
933 If CPUTYPE is defined in your /etc/make.conf, make sure to use the
934 "?=" instead of the "=" assignment operator, so that buildworld can
935 override the CPUTYPE if it needs to.
937 MAKEOBJDIRPREFIX must be defined in an environment variable, and
938 not on the command line, or in /etc/make.conf. buildworld will
939 warn if it is improperly defined.
942 This file contains a list, in reverse chronological order, of major
943 breakages in tracking -current. It is not guaranteed to be a complete
944 list of such breakages, and only contains entries since October 10, 2007.
945 If you need to see UPDATING entries from before that date, you will need
946 to fetch an UPDATING file from an older FreeBSD release.
948 Copyright information:
950 Copyright 1998-2009 M. Warner Losh. All Rights Reserved.
952 Redistribution, publication, translation and use, with or without
953 modification, in full or in part, in any form or format of this
954 document are permitted without further permission from the author.
956 THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR
957 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
958 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
959 DISCLAIMED. IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT,
960 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
961 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
962 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
963 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
964 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
965 IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
966 POSSIBILITY OF SUCH DAMAGE.
968 Contact Warner Losh if you have any questions about your use of