UPDATING revision 142844
1185029SpjdUpdating Information for FreeBSD current users 2185029Spjd 3185029SpjdThis file is maintained and copyrighted by M. Warner Losh 4185029Spjd<imp@village.org>. See end of file for further details. For commonly 5185029Spjddone items, please see the COMMON ITEMS: section later in the file. 6185029Spjd 7185029SpjdItems affecting the ports and packages system can be found in 8185029Spjd/usr/ports/UPDATING. Please read that file before running 9185029Spjdportupgrade. Important recent entries: 20040724 (default X changes). 10185029Spjd 11185029SpjdNOTE TO PEOPLE WHO THINK THAT FreeBSD 6.x IS SLOW: 12185029Spjd FreeBSD 6.x has many debugging features turned on, in 13185029Spjd both the kernel and userland. These features attempt to detect 14185029Spjd incorrect use of system primitives, and encourage loud failure 15185029Spjd through extra sanity checking and fail stop semantics. They 16185029Spjd also substantially impact system performance. If you want to 17185029Spjd do performance measurement, benchmarking, and optimization, 18185029Spjd you'll want to turn them off. This includes various WITNESS- 19185029Spjd related kernel options, INVARIANTS, malloc debugging flags 20185029Spjd in userland, and various verbose features in the kernel. Many 21185029Spjd developers choose to disable these features on build machines 22185029Spjd to maximize performance. 23200516Sdelphij 24185029Spjd20050227: 25185029Spjd The on-disk format of LC_CTYPE files was changed to be machine 26185029Spjd independent. Please make sure NOT to use NO_CLEAN buildworld 27185029Spjd when crossing this point. 28185029Spjd 29185029Spjd20050225: 30185029Spjd The ifi_epoch member of struct if_data has been changed to 31185029Spjd contain the uptime at which the interface was created or the 32185029Spjd statistics zeroed rather then the wall clock time because 33185029Spjd wallclock time may go backwards. This should have no impact 34185029Spjd unless an snmp implementation is using this value (I know of 35185029Spjd none at this point.) 36185029Spjd 37186515Srwatson20050224: 38185029Spjd The acpi_perf and acpi_throttle drivers are now part of the 39185029Spjd acpi(4) main module. They are no longer built separately. 40185029Spjd 41185029Spjd20050223: 42185029Spjd The layout of struct image_params has changed. You have to 43185029Spjd recompile all compatibility modules (linux, svr4, etc) for use 44185029Spjd with the new kernel. 45185029Spjd 46185029Spjd20050223: 47185029Spjd The p4tcc driver has been merged into cpufreq(4). This makes 48185029Spjd "options CPU_ENABLE_TCC" obsolete. Please load cpufreq.ko or 49185029Spjd compile in "device cpufreq" to restore this functionality. 50185029Spjd 51185029Spjd20050220: 52185029Spjd The responsibility of recomputing the file system summary of 53185029Spjd a SoftUpdates-enabled dirty volume has been transferred to the 54185029Spjd background fsck. A rebuild of fsck(8) utility is recommended 55185029Spjd if you have updated the kernel. 56185029Spjd 57185029Spjd To get the old behavior (recompute file system summary at mount 58185029Spjd time), you can set vfs.ffs.compute_summary_at_mount=1 before 59185029Spjd mounting the new volume. 60185029Spjd 61185029Spjd20050206: 62185029Spjd The cpufreq import is complete. As part of this, the sysctls for 63185029Spjd acpi(4) throttling have been removed. The power_profile script 64185029Spjd has been updated, so you can use performance/economy_cpu_freq in 65185029Spjd rc.conf(5) to set AC on/offline cpu frequencies. 66185029Spjd 67185029Spjd20050206: 68185029Spjd NG_VERSION has been increased. Recompiling kernel (or ng_socket.ko) 69185029Spjd requires recompiling libnetgraph and userland netgraph utilities. 70185029Spjd 71185029Spjd20050114: 72185029Spjd Support for abbreviated forms of a number of ipfw options is 73185029Spjd now deprecated. Warnings are printed to stderr indicating the 74185029Spjd correct full form when a match occurs. Some abbreviations may 75185029Spjd be supported at a later date based on user feedback. To be 76185029Spjd considered for support, abbreviations must be in use prior to 77185029Spjd this commit and unlikely to be confused with current key words. 78185029Spjd 79185029Spjd20041221: 80185029Spjd By a popular demand, a lot of NOFOO options were renamed 81185029Spjd to NO_FOO (see bsd.compat.mk for a full list). The old 82185029Spjd spellings are still supported, but will cause annoying 83185029Spjd warnings on stderr. Make sure you upgrade properly (see 84185029Spjd the COMMON ITEMS: section later in this file). 85185029Spjd 86185029Spjd20041219: 87185029Spjd Auto-loading of ancillary wlan modules such as wlan_wep has 88185029Spjd been temporarily disabled; you need to statically configure 89185029Spjd the modules you need into your kernel or explicitly load them 90185029Spjd prior to use. Specifically, if you intend to use WEP encryption 91185029Spjd with an 802.11 device load/configure wlan_wep; if you want to 92185029Spjd use WPA with the ath driver load/configure wlan_tkip, wlan_ccmp, 93185029Spjd and wlan_xauth as required. 94185029Spjd 95185029Spjd20041213: 96185029Spjd The behaviour of ppp(8) has changed slightly. If lqr is enabled 97185029Spjd (``enable lqr''), older versions would revert to LCP ECHO mode on 98185029Spjd negotiation failure. Now, ``enable echo'' is required for this 99185029Spjd behaviour. The ppp version number has been bumped to 3.4.2 to 100185029Spjd reflect the change. 101185029Spjd 102185029Spjd20041201: 103185029Spjd The wlan support has been updated to split the crypto support 104185029Spjd into separate modules. For static WEP you must configure the 105185029Spjd wlan_wep module in your system or build and install the module 106185029Spjd in place where it can be loaded (the kernel will auto-load 107185029Spjd the module when a wep key is configured). 108185029Spjd 109185029Spjd20041201: 110185029Spjd The ath driver has been updated to split the tx rate control 111185029Spjd algorithm into a separate module. You need to include either 112185029Spjd ath_rate_onoe or ath_rate_amrr when configuring the kernel. 113185029Spjd 114185029Spjd20041116: 115185029Spjd Support for systems with an 80386 CPU has been removed. Please 116185029Spjd use FreeBSD 5.x or earlier on systems with an 80386. 117185029Spjd 118185029Spjd20041110: 119185029Spjd We have had a hack which would mount the root filesystem 120185029Spjd R/W if the device were named 'md*'. As part of the vnode 121185029Spjd work I'm doing I have had to remove this hack. People 122185029Spjd building systems which use preloaded MD root filesystems 123185029Spjd may need to insert a "/sbin/mount -u -o rw /dev/md0 /" in 124185029Spjd their /etc/rc scripts. 125185029Spjd 126185029Spjd20041104: 127185029Spjd FreeBSD 5.3 shipped here. 128185029Spjd 129185029Spjd20041102: 130185029Spjd The size of struct tcpcb has changed again due to the removal 131185029Spjd of RFC1644 T/TCP. You have to recompile userland programs that 132185029Spjd read kmem for tcp sockets directly (netstat, sockstat, etc.) 133185029Spjd 134185029Spjd20041022: 135185029Spjd The size of struct tcpcb has changed. You have to recompile 136185029Spjd userland programs that read kmem for tcp sockets directly 137185029Spjd (netstat, sockstat, etc.) 138185029Spjd 139185029Spjd20041016: 140185029Spjd RELENG_5 branched here. For older entries, please see updating 141185029Spjd in the RELENG_5 branch. 142185029Spjd 143185029SpjdCOMMON ITEMS: 144185029Spjd 145185029Spjd # NOTE: 5.x below applies to 6.0-current as well, for the 146185029Spjd # moment. 4.any -> 5.any upgrade support will remain in 147185029Spjd # place for 6.0 current, but after 5.3 RELEASE, the 4.any -> 148185029Spjd # 6.0-current upgrade path will require moving through 5.3 149185029Spjd # RELEASE or newer. 150185029Spjd 151185029Spjd General Notes 152185029Spjd ------------- 153185029Spjd Avoid using make -j when upgrading. From time to time in the 154185029Spjd past there have been problems using -j with buildworld and/or 155185029Spjd installworld. This is especially true when upgrading between 156185029Spjd "distant" versions (eg one that cross a major release boundary 157185029Spjd or several minor releases, or when several months have passed 158185029Spjd on the -current branch). 159185029Spjd 160185029Spjd Sometimes, obscure build problems are the result of environment 161185029Spjd poisoning. This can happen because the make utility reads its 162185029Spjd environment when searching for values for global variables. 163185029Spjd To run your build attempts in an "environmental clean room", 164185029Spjd prefix all make commands with 'env -i '. See the env(1) manual 165185029Spjd page for more details. 166185029Spjd 167185029Spjd To build a kernel 168185029Spjd ----------------- 169185029Spjd If you are updating from a prior version of FreeBSD (even one just 170185029Spjd a few days old), you should follow this procedure. With a 171185029Spjd /usr/obj tree with a fresh buildworld, 172185029Spjd make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE 173185029Spjd make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE 174185029Spjd 175185029Spjd To just build a kernel when you know that it won't mess you up 176185029Spjd -------------------------------------------------------------- 177185029Spjd This assumes you are already running a 5.X system. Replace 178185029Spjd ${arch} with the architecture of your machine (e.g. "i386", 179185029Spjd "alpha", "amd64", "ia64", "pc98", "sparc64", etc). 180185029Spjd 181185029Spjd cd src/sys/${arch}/conf 182185029Spjd config KERNEL_NAME_HERE 183185029Spjd cd ../compile/KERNEL_NAME_HERE 184185029Spjd make depend 185185029Spjd make 186185029Spjd make install 187185029Spjd 188185029Spjd If this fails, go to the "To build a kernel" section. 189185029Spjd 190185029Spjd To rebuild everything and install it on the current system. 191185029Spjd ----------------------------------------------------------- 192185029Spjd # Note: sometimes if you are running current you gotta do more than 193185029Spjd # is listed here if you are upgrading from a really old current. 194185029Spjd 195185029Spjd <make sure you have good level 0 dumps> 196185029Spjd <maybe fix /etc/fstab> [7] 197185029Spjd make buildworld 198185029Spjd make kernel KERNCONF=YOUR_KERNEL_HERE 199185029Spjd [1] 200185029Spjd <reboot in single user> [3] 201185029Spjd src/etc/rc.d/preseedrandom [10] 202185029Spjd mergemaster -p [5] 203185029Spjd make installworld 204185029Spjd mergemaster [4] 205185029Spjd <reboot> 206185029Spjd 207185029Spjd 208185029Spjd To cross-install current onto a separate partition 209185029Spjd -------------------------------------------------- 210185029Spjd # In this approach we use a separate partition to hold 211185029Spjd # current's root, 'usr', and 'var' directories. A partition 212185029Spjd # holding "/", "/usr" and "/var" should be about 2GB in 213185029Spjd # size. 214185029Spjd 215185029Spjd <make sure you have good level 0 dumps> 216185029Spjd <boot into -stable> 217185029Spjd make buildworld 218185029Spjd make buildkernel KERNCONF=YOUR_KERNEL_HERE 219185029Spjd <maybe newfs current's root partition> 220185029Spjd <mount current's root partition on directory ${CURRENT_ROOT}> 221185029Spjd make installworld DESTDIR=${CURRENT_ROOT} 222185029Spjd cd src/etc; make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd 223185029Spjd make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT} 224185029Spjd cp /etc/fstab ${CURRENT_ROOT}/etc/fstab # if newfs'd 225185029Spjd <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition> 226185029Spjd <reboot into current> 227185029Spjd <do a "native" rebuild/install as described in the previous section> 228185029Spjd <maybe install compatibility libraries from src/lib/compat> 229185029Spjd <reboot> 230185029Spjd 231185029Spjd 232185029Spjd To upgrade in-place from 4.x-stable to current 233185029Spjd ---------------------------------------------- 234185029Spjd # 5.x uses more space than 4.x. Also, the location of kernel 235185029Spjd # modules has changed. If you are installing 5.x onto a 4.x 236185029Spjd # system, you'll need about 30MB of free disk space on your / 237185029Spjd # partition. If you have less than this, you may encounter difficult 238185029Spjd # to back out of problems with this procedure. If /tmp is on 239185029Spjd # the / partition, you may want to completely remove all its content 240185029Spjd # before upgrading, as this can be a common source of shortage of 241185029Spjd # space on /. 242185029Spjd 243209962Smm <make sure you have good level 0 dumps> 244209962Smm <maybe fix /etc/fstab> [7] 245185029Spjd make buildworld [9] 246185029Spjd cp sys/${MACHINE}/conf/GENERIC.hints /boot/device.hints [2] 247185029Spjd make kernel KERNCONF=YOUR_KERNEL_HERE [8] 248185029Spjd cd sys/boot ; make STRIP="" install [6] 249185029Spjd [1] 250185029Spjd <reboot in single user> [3] 251185029Spjd src/etc/rc.d/preseedrandom [10] 252185029Spjd mergemaster -p [5] 253185029Spjd rm -rf /usr/include/g++ 254185029Spjd make installworld 255185029Spjd mergemaster -i [4] 256185029Spjd <reboot> 257185029Spjd 258185029Spjd Make sure that you've read the UPDATING file to understand the 259185029Spjd tweaks to various things you need. At this point in the life 260185029Spjd cycle of current, things change often and you are on your own 261185029Spjd to cope. The defaults can also change, so please read ALL of 262185029Spjd the UPDATING entries. 263185029Spjd 264185029Spjd Also, if you are tracking -current, you must be subscribed to 265185029Spjd freebsd-current@freebsd.org. Make sure that before you update 266185029Spjd your sources that you have read and understood all the recent 267185029Spjd messages there. If in doubt, please track -stable which has 268185029Spjd much fewer pitfalls. 269185029Spjd 270185029Spjd [1] If you have third party modules, such as vmware, you 271185029Spjd should disable them at this point so they don't crash your 272185029Spjd system on reboot. 273185029Spjd 274185029Spjd [2] If you have legacy ISA devices, you may need to create 275185029Spjd your own device.hints to reflect your unique hardware 276185029Spjd configuration. 277185029Spjd 278185029Spjd [3] From the bootblocks, boot -s, and then do 279185029Spjd fsck -p 280185029Spjd mount -u / 281185029Spjd mount -a 282185029Spjd cd src 283185029Spjd adjkerntz -i # if CMOS is wall time 284185029Spjd Also, when doing a major release upgrade, it is required that 285185029Spjd you boot into single user mode to do the installworld. 286185029Spjd For the 4.x -> 5.x upgrade, you will also see many messages about 287185029Spjd needing to recompile your userland. These are harmless and can 288185029Spjd be ignored while you proceed to the next step. 289185029Spjd 290185029Spjd [4] Note: This step is non-optional. Failure to do this step 291185029Spjd can result in a significant reduction in the functionality of the 292185029Spjd system. Attempting to do it by hand is not recommended and those 293185029Spjd that pursue this avenue should read this file carefully, as well 294185029Spjd as the archives of freebsd-current and freebsd-hackers mailing lists 295185029Spjd for potential gotchas. 296185029Spjd 297185029Spjd [5] Usually this step is a noop. However, from time to time 298185029Spjd you may need to do this if you get unknown user in the following 299185029Spjd step. It never hurts to do it all the time. You may need to 300185029Spjd install a new mergemaster (cd src/usr.sbin/mergemaster && make 301185029Spjd install) after the buildworld before this step if you last updated 302185029Spjd from current before 20020224 or from -stable before 20020408. 303185029Spjd 304185029Spjd [6] 4.x boot loader can be used to boot a 5.x system, however 305185029Spjd it is difficult to do that at best. If you wish to try, then 306185029Spjd you should interrupt the boot and at the ok prompt type: 307185029Spjd ok unload 308185029Spjd ok boot /boot/kernel/kernel 309185029Spjd If this fails to work, you must install a new boot loader as 310185029Spjd described here. 311185029Spjd 312185029Spjd [7] Before you upgrade, please make sure that you are not using 313185029Spjd compatibility slices. These are device names of the form /dev/ad0a 314185029Spjd without the actual slice name. These will break with 5.x and newer. 315185029Spjd You generally must update these entries to use the post FreeBSD 316185029Spjd 2.x form of /dev/ad0s1a. i386 and pc98 are affected, while alpha 317185029Spjd is not. 318185029Spjd 319185029Spjd [8] In order to have a kernel that can run the 4.x binaries 320185029Spjd needed to do an installworld, you must include the COMPAT_FREEBSD4 321185029Spjd option in your kernel. Failure to do so may leave you with a system 322185029Spjd that is hard to boot to recover. 323185029Spjd 324185029Spjd Make sure that you merge any new devices from GENERIC since the 325185029Spjd last time you updated your kernel config file. 326185029Spjd 327185029Spjd [9] When checking out sources, you must include the -P flag to have 328185029Spjd cvs prune empty directories. 329185029Spjd 330185029Spjd If CPUTYPE is defined in your /etc/make.conf, make sure to use the 331185029Spjd "?=" instead of the "=" assignment operator, so that buildworld can 332185029Spjd override the CPUTYPE if it needs to. 333185029Spjd 334185029Spjd MAKEOBJDIRPREFIX must be defined in an environment variable, and 335185029Spjd not on the command line, or in /etc/make.conf. buildworld will 336185029Spjd warn if it is improperly defined. 337185029Spjd 338185029Spjd In case you would like to avoid installing new packages of everything, 339185029Spjd you might want to uncomment the "COMPAT4X= YES" entry, so that 4.x 340185029Spjd compatibility libraries are built which should allow you to continue 341185029Spjd using your existing software for a while. Alternatively, you can 342185029Spjd install the misc/compat4x port. 343185029Spjd 344185029Spjd [10] In order to create temporary files, /dev/random must be 345185029Spjd initialized by feeding data into it. src/etc/rc.d/preseedrandom 346185029Spjd takes care of this. 347185029SpjdFORMAT: 348185029Spjd 349185029SpjdThis file contains a list, in reverse chronological order, of major 350185029Spjdbreakages in tracking -current. Not all things will be listed here, 351185029Spjdand it only starts on March 15, 2000. Updating files can found in 352185029Spjdprevious releases if your system is older than this. 353185029Spjd 354185029SpjdCopyright information: 355185029Spjd 356185029SpjdCopyright 1998-2004 M. Warner Losh. All Rights Reserved. 357185029Spjd 358185029SpjdRedistribution, publication, translation and use, with or without 359185029Spjdmodification, in full or in part, in any form or format of this 360185029Spjddocument are permitted without further permission from the author. 361185029Spjd 362185029SpjdTHIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR 363185029SpjdIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 364185029SpjdWARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 365185029SpjdDISCLAIMED. IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT, 366185029SpjdINDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 367185029Spjd(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 368185029SpjdSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 369185029SpjdHOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 370185029SpjdSTRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 371185029SpjdIN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 372185029SpjdPOSSIBILITY OF SUCH DAMAGE. 373185029Spjd 374185029SpjdIf you find this document useful, and you want to, you may buy the 375185029Spjdauthor a beer. 376185029Spjd 377185029SpjdContact Warner Losh if you have any questions about your use of 378185029Spjdthis document. 379185029Spjd 380185029Spjd$FreeBSD: head/UPDATING 142844 2005-03-01 02:33:34Z delphij $ 381185029Spjd