UPDATING revision 147930
1Updating Information for FreeBSD current users 2 3This file is maintained and copyrighted by M. Warner Losh 4<imp@village.org>. See end of file for further details. For commonly 5done items, please see the COMMON ITEMS: section later in the file. 6 7Items affecting the ports and packages system can be found in 8/usr/ports/UPDATING. Please read that file before running 9portupgrade. 10 11NOTE TO PEOPLE WHO THINK THAT FreeBSD 7.x IS SLOW: 12 FreeBSD 7.x has many debugging features turned on, in 13 both the kernel and userland. These features attempt to detect 14 incorrect use of system primitives, and encourage loud failure 15 through extra sanity checking and fail stop semantics. They 16 also substantially impact system performance. If you want to 17 do performance measurement, benchmarking, and optimization, 18 you'll want to turn them off. This includes various WITNESS- 19 related kernel options, INVARIANTS, malloc debugging flags 20 in userland, and various verbose features in the kernel. Many 21 developers choose to disable these features on build machines 22 to maximize performance. 23 2420050711: 25 RELENG_6 branched here. 26 2720050629: 28 The pccard_ifconfig rc.conf variable has been removed and a new 29 variable, ifconfig_DEFAULT has been introduced. Unlike 30 pccard_ifconfig, ifconfig_DEFAULT applies to ALL interfaces that 31 do not have ifconfig_ifn entries rather than just those in 32 removable_interfaces. 33 3420050616: 35 Some previous versions of PAM have permitted the use of 36 non-absolute paths in /etc/pam.conf or /etc/pam.d/* when referring 37 to third party PAM modules in /usr/local/lib. A change has been 38 made to require the use of absolute paths in order to avoid 39 ambiguity and dependence on library path configuration, which may 40 affect existing configurations. 41 4220050610: 43 Major changes to network interface API. All drivers must be 44 recompiled. Drivers not in the base system will need to be 45 updated to the new APIs. 46 4720050609: 48 Changes were made to kinfo_proc in sys/user.h. Please recompile 49 userland, or commands like `fstat', `pkill', `ps', `top' and `w' 50 will not behave correctly. 51 52 The API and ABI for hwpmc(4) have changed with the addition 53 of sampling support. Please recompile lib/libpmc(3) and 54 usr.sbin/{pmcstat,pmccontrol}. 55 5620050606: 57 The OpenBSD dhclient was imported in place of the ISC dhclient 58 and the network interface configuration scripts were updated 59 accordingly. If you use DHCP to configure your interfaces, you 60 must now run devd. Also, DNS updating was lost so you will need 61 to find a workaround if you use this feature. 62 6320050605: 64 if_bridge was added to the tree. This has changed struct ifnet. 65 Please recompile userland and all network related modules. 66 6720050603: 68 The n_net of a struct netent was changed to an uint32_t, and 69 1st argument of getnetbyaddr() was changed to an uint32_t, to 70 conform to POSIX-2001. These changes broke an ABI 71 compatibility on 64 bit architecture. With these changes, 72 shlib major of libpcap was bumped. You have to recompile 73 userland programs that use getnetbyaddr(3), getnetbyname(3), 74 getnetent(3) and/or libpcap on 64 bit architecture. 75 7620050528: 77 Kernel parsing of extra options on '#!' first lines of shell 78 scripts has changed. Lines with multiple options likely will 79 fail after this date. For full details, please see 80 http://people.freebsd.org/~gad/Updating-20050528.txt 81 8220050503: 83 The packet filter (pf) code has been updated to OpenBSD 3.7 84 Please note the changed anchor syntax and the fact that 85 authpf(8) now needs a mounted fdescfs(5) to function. 86 8720050415: 88 The NO_MIXED_MODE kernel option has been removed from the i386 89 amd64 platforms as its use has been superceded by the new local 90 APIC timer code. Any kernel config files containing this option 91 should be updated. 92 9320050227: 94 The on-disk format of LC_CTYPE files was changed to be machine 95 independent. Please make sure NOT to use NO_CLEAN buildworld 96 when crossing this point. 97 9820050225: 99 The ifi_epoch member of struct if_data has been changed to 100 contain the uptime at which the interface was created or the 101 statistics zeroed rather then the wall clock time because 102 wallclock time may go backwards. This should have no impact 103 unless an snmp implementation is using this value (I know of 104 none at this point.) 105 10620050224: 107 The acpi_perf and acpi_throttle drivers are now part of the 108 acpi(4) main module. They are no longer built separately. 109 11020050223: 111 The layout of struct image_params has changed. You have to 112 recompile all compatibility modules (linux, svr4, etc) for use 113 with the new kernel. 114 11520050223: 116 The p4tcc driver has been merged into cpufreq(4). This makes 117 "options CPU_ENABLE_TCC" obsolete. Please load cpufreq.ko or 118 compile in "device cpufreq" to restore this functionality. 119 12020050220: 121 The responsibility of recomputing the file system summary of 122 a SoftUpdates-enabled dirty volume has been transferred to the 123 background fsck. A rebuild of fsck(8) utility is recommended 124 if you have updated the kernel. 125 126 To get the old behavior (recompute file system summary at mount 127 time), you can set vfs.ffs.compute_summary_at_mount=1 before 128 mounting the new volume. 129 13020050206: 131 The cpufreq import is complete. As part of this, the sysctls for 132 acpi(4) throttling have been removed. The power_profile script 133 has been updated, so you can use performance/economy_cpu_freq in 134 rc.conf(5) to set AC on/offline cpu frequencies. 135 13620050206: 137 NG_VERSION has been increased. Recompiling kernel (or ng_socket.ko) 138 requires recompiling libnetgraph and userland netgraph utilities. 139 14020050114: 141 Support for abbreviated forms of a number of ipfw options is 142 now deprecated. Warnings are printed to stderr indicating the 143 correct full form when a match occurs. Some abbreviations may 144 be supported at a later date based on user feedback. To be 145 considered for support, abbreviations must be in use prior to 146 this commit and unlikely to be confused with current key words. 147 14820041221: 149 By a popular demand, a lot of NOFOO options were renamed 150 to NO_FOO (see bsd.compat.mk for a full list). The old 151 spellings are still supported, but will cause annoying 152 warnings on stderr. Make sure you upgrade properly (see 153 the COMMON ITEMS: section later in this file). 154 15520041219: 156 Auto-loading of ancillary wlan modules such as wlan_wep has 157 been temporarily disabled; you need to statically configure 158 the modules you need into your kernel or explicitly load them 159 prior to use. Specifically, if you intend to use WEP encryption 160 with an 802.11 device load/configure wlan_wep; if you want to 161 use WPA with the ath driver load/configure wlan_tkip, wlan_ccmp, 162 and wlan_xauth as required. 163 16420041213: 165 The behaviour of ppp(8) has changed slightly. If lqr is enabled 166 (``enable lqr''), older versions would revert to LCP ECHO mode on 167 negotiation failure. Now, ``enable echo'' is required for this 168 behaviour. The ppp version number has been bumped to 3.4.2 to 169 reflect the change. 170 17120041201: 172 The wlan support has been updated to split the crypto support 173 into separate modules. For static WEP you must configure the 174 wlan_wep module in your system or build and install the module 175 in place where it can be loaded (the kernel will auto-load 176 the module when a wep key is configured). 177 17820041201: 179 The ath driver has been updated to split the tx rate control 180 algorithm into a separate module. You need to include either 181 ath_rate_onoe or ath_rate_amrr when configuring the kernel. 182 18320041116: 184 Support for systems with an 80386 CPU has been removed. Please 185 use FreeBSD 5.x or earlier on systems with an 80386. 186 18720041110: 188 We have had a hack which would mount the root filesystem 189 R/W if the device were named 'md*'. As part of the vnode 190 work I'm doing I have had to remove this hack. People 191 building systems which use preloaded MD root filesystems 192 may need to insert a "/sbin/mount -u -o rw /dev/md0 /" in 193 their /etc/rc scripts. 194 19520041104: 196 FreeBSD 5.3 shipped here. 197 19820041102: 199 The size of struct tcpcb has changed again due to the removal 200 of RFC1644 T/TCP. You have to recompile userland programs that 201 read kmem for tcp sockets directly (netstat, sockstat, etc.) 202 20320041022: 204 The size of struct tcpcb has changed. You have to recompile 205 userland programs that read kmem for tcp sockets directly 206 (netstat, sockstat, etc.) 207 20820041016: 209 RELENG_5 branched here. For older entries, please see updating 210 in the RELENG_5 branch. 211 212COMMON ITEMS: 213 214 General Notes 215 ------------- 216 Avoid using make -j when upgrading. From time to time in the 217 past there have been problems using -j with buildworld and/or 218 installworld. This is especially true when upgrading between 219 "distant" versions (eg one that cross a major release boundary 220 or several minor releases, or when several months have passed 221 on the -current branch). 222 223 Sometimes, obscure build problems are the result of environment 224 poisoning. This can happen because the make utility reads its 225 environment when searching for values for global variables. 226 To run your build attempts in an "environmental clean room", 227 prefix all make commands with 'env -i '. See the env(1) manual 228 page for more details. 229 230 To build a kernel 231 ----------------- 232 If you are updating from a prior version of FreeBSD (even one just 233 a few days old), you should follow this procedure. With a 234 /usr/obj tree with a fresh buildworld, 235 make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE 236 make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE 237 238 To test a kernel once 239 --------------------- 240 If you just want to boot a kernel once (because you are not sure 241 if it works, or if you want to boot a known bad kernel to provide 242 debugging information) run 243 make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel 244 nextboot -k testkernel 245 246 To just build a kernel when you know that it won't mess you up 247 -------------------------------------------------------------- 248 This assumes you are already running a 5.X system. Replace 249 ${arch} with the architecture of your machine (e.g. "i386", 250 "alpha", "amd64", "ia64", "pc98", "sparc64", etc). 251 252 cd src/sys/${arch}/conf 253 config KERNEL_NAME_HERE 254 cd ../compile/KERNEL_NAME_HERE 255 make depend 256 make 257 make install 258 259 If this fails, go to the "To build a kernel" section. 260 261 To rebuild everything and install it on the current system. 262 ----------------------------------------------------------- 263 # Note: sometimes if you are running current you gotta do more than 264 # is listed here if you are upgrading from a really old current. 265 266 <make sure you have good level 0 dumps> 267 make buildworld 268 make kernel KERNCONF=YOUR_KERNEL_HERE 269 [1] 270 <reboot in single user> [3] 271 mergemaster -p [5] 272 make installworld 273 mergemaster [4] 274 <reboot> 275 276 277 To cross-install current onto a separate partition 278 -------------------------------------------------- 279 # In this approach we use a separate partition to hold 280 # current's root, 'usr', and 'var' directories. A partition 281 # holding "/", "/usr" and "/var" should be about 2GB in 282 # size. 283 284 <make sure you have good level 0 dumps> 285 <boot into -stable> 286 make buildworld 287 make buildkernel KERNCONF=YOUR_KERNEL_HERE 288 <maybe newfs current's root partition> 289 <mount current's root partition on directory ${CURRENT_ROOT}> 290 make installworld DESTDIR=${CURRENT_ROOT} 291 cd src/etc; make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd 292 make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT} 293 cp /etc/fstab ${CURRENT_ROOT}/etc/fstab # if newfs'd 294 <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition> 295 <reboot into current> 296 <do a "native" rebuild/install as described in the previous section> 297 <maybe install compatibility libraries from src/lib/compat> 298 <reboot> 299 300 301 To upgrade in-place from 5.x-stable to current 302 ---------------------------------------------- 303 <make sure you have good level 0 dumps> 304 make buildworld [9] 305 make kernel KERNCONF=YOUR_KERNEL_HERE [8] 306 [1] 307 <reboot in single user> [3] 308 mergemaster -p [5] 309 make installworld 310 mergemaster -i [4] 311 <reboot> 312 313 Make sure that you've read the UPDATING file to understand the 314 tweaks to various things you need. At this point in the life 315 cycle of current, things change often and you are on your own 316 to cope. The defaults can also change, so please read ALL of 317 the UPDATING entries. 318 319 Also, if you are tracking -current, you must be subscribed to 320 freebsd-current@freebsd.org. Make sure that before you update 321 your sources that you have read and understood all the recent 322 messages there. If in doubt, please track -stable which has 323 much fewer pitfalls. 324 325 [1] If you have third party modules, such as vmware, you 326 should disable them at this point so they don't crash your 327 system on reboot. 328 329 [3] From the bootblocks, boot -s, and then do 330 fsck -p 331 mount -u / 332 mount -a 333 cd src 334 adjkerntz -i # if CMOS is wall time 335 Also, when doing a major release upgrade, it is required that 336 you boot into single user mode to do the installworld. 337 338 [4] Note: This step is non-optional. Failure to do this step 339 can result in a significant reduction in the functionality of the 340 system. Attempting to do it by hand is not recommended and those 341 that pursue this avenue should read this file carefully, as well 342 as the archives of freebsd-current and freebsd-hackers mailing lists 343 for potential gotchas. 344 345 [5] Usually this step is a noop. However, from time to time 346 you may need to do this if you get unknown user in the following 347 step. It never hurts to do it all the time. You may need to 348 install a new mergemaster (cd src/usr.sbin/mergemaster && make 349 install) after the buildworld before this step if you last updated 350 from current before 20020224 or from -stable before 20020408. 351 352 [8] In order to have a kernel that can run the 4.x binaries 353 needed to do an installworld, you must include the COMPAT_FREEBSD4 354 option in your kernel. Failure to do so may leave you with a system 355 that is hard to boot to recover. 356 357 Make sure that you merge any new devices from GENERIC since the 358 last time you updated your kernel config file. 359 360 [9] When checking out sources, you must include the -P flag to have 361 cvs prune empty directories. 362 363 If CPUTYPE is defined in your /etc/make.conf, make sure to use the 364 "?=" instead of the "=" assignment operator, so that buildworld can 365 override the CPUTYPE if it needs to. 366 367 MAKEOBJDIRPREFIX must be defined in an environment variable, and 368 not on the command line, or in /etc/make.conf. buildworld will 369 warn if it is improperly defined. 370FORMAT: 371 372This file contains a list, in reverse chronological order, of major 373breakages in tracking -current. Not all things will be listed here, 374and it only starts on October 16, 2004. Updating files can found in 375previous releases if your system is older than this. 376 377Copyright information: 378 379Copyright 1998-2005 M. Warner Losh. All Rights Reserved. 380 381Redistribution, publication, translation and use, with or without 382modification, in full or in part, in any form or format of this 383document are permitted without further permission from the author. 384 385THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR 386IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 387WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 388DISCLAIMED. IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT, 389INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 390(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 391SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 392HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 393STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 394IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 395POSSIBILITY OF SUCH DAMAGE. 396 397If you find this document useful, and you want to, you may buy the 398author a beer. 399 400Contact Warner Losh if you have any questions about your use of 401this document. 402 403$FreeBSD: head/UPDATING 147930 2005-07-11 15:46:45Z kensmith $ 404