UPDATING revision 196789
1Updating Information for FreeBSD current users 2 3This file is maintained and copyrighted by M. Warner Losh <imp@freebsd.org>. 4See end of file for further details. For commonly done items, please see the 5COMMON ITEMS: section later in the file. These instructions assume that you 6basically know what you are doing. If not, then please consult the FreeBSD 7handbook. 8 9Items affecting the ports and packages system can be found in 10/usr/ports/UPDATING. Please read that file before running portupgrade. 11 12NOTE TO PEOPLE WHO THINK THAT FreeBSD 9.x IS SLOW: 13 FreeBSD 9.x has many debugging features turned on, in both the kernel 14 and userland. These features attempt to detect incorrect use of 15 system primitives, and encourage loud failure through extra sanity 16 checking and fail stop semantics. They also substantially impact 17 system performance. If you want to do performance measurement, 18 benchmarking, and optimization, you'll want to turn them off. This 19 includes various WITNESS- related kernel options, INVARIANTS, malloc 20 debugging flags in userland, and various verbose features in the 21 kernel. Many developers choose to disable these features on build 22 machines to maximize performance. (To disable malloc debugging, run 23 ln -s aj /etc/malloc.conf.) 24 2520090813: 26 Remove the option STOP_NMI. The default action is now to use NMI only 27 for KDB via the newly introduced function stop_cpus_hard() and 28 maintain stop_cpus() to just use a normal IPI_STOP on ia32 and amd64. 29 3020090803: 31 RELENG_8 branched. 32 3320090719: 34 Bump the shared library version numbers for all libraries that do not 35 use symbol versioning as part of the 8.0-RELEASE cycle. Bump 36 __FreeBSD_version to 800105. 37 3820090714: 39 Due to changes in the implementation of virtual network stack support, 40 all network-related kernel modules must be recompiled. As this change 41 breaks the ABI, bump __FreeBSD_version to 800104. 42 4320090713: 44 The TOE interface to the TCP syncache has been modified to remove 45 struct tcpopt (<netinet/tcp_var.h>) from the ABI of the network stack. 46 The cxgb driver is the only TOE consumer affected by this change, and 47 needs to be recompiled along with the kernel. As this change breaks 48 the ABI, bump __FreeBSD_version to 800103. 49 5020090712: 51 Padding has been added to struct tcpcb, sackhint and tcpstat in 52 <netinet/tcp_var.h> to facilitate future MFCs and bug fixes whilst 53 maintainig the ABI. However, this change breaks the ABI, so bump 54 __FreeBSD_version to 800102. User space tools that rely on the size of 55 any of these structs (e.g. sockstat) need to be recompiled. 56 5720090630: 58 The NFS_LEGACYRPC option has been removed along with the old kernel 59 RPC implementation that this option selected. Kernel configurations 60 may need to be adjusted. 61 6220090629: 63 The network interface device nodes at /dev/net/<interface> have been 64 removed. All ioctl operations can be performed the normal way using 65 routing sockets. The kqueue functionality can generally be replaced 66 with routing sockets. 67 6820090628: 69 The documentation from the FreeBSD Documentation Project (Handbook, 70 FAQ, etc.) is now installed via packages by sysinstall(8) and under 71 the /usr/local/share/doc/freebsd directory instead of /usr/share/doc. 72 7320090624: 74 The ABI of various structures related to the SYSV IPC API have been 75 changed. As a result, the COMPAT_FREEBSD[456] and COMPAT_43 kernel 76 options now all require COMPAT_FREEBSD7. Bump __FreeBSD_version to 77 800100. 78 7920090622: 80 Layout of struct vnet has changed as routing related variables were 81 moved to their own Vimage module. Modules need to be recompiled. Bump 82 __FreeBSD_version to 800099. 83 8420090619: 85 NGROUPS_MAX and NGROUPS have been increased from 16 to 1023 and 1024 86 respectively. As long as no more than 16 groups per process are used, 87 no changes should be visible. When more than 16 groups are used, old 88 binaries may fail if they call getgroups() or getgrouplist() with 89 statically sized storage. Recompiling will work around this, but 90 applications should be modified to use dynamically allocated storage 91 for group arrays as POSIX.1-2008 does not cap an implementation's 92 number of supported groups at NGROUPS_MAX+1 as previous versions did. 93 94 NFS and portalfs mounts may also be affected as the list of groups is 95 truncated to 16. Users of NFS who use more than 16 groups, should 96 take care that negative group permissions are not used on the exported 97 file systems as they will not be reliable unless a GSSAPI based 98 authentication method is used. 99 10020090616: 101 The compiling option ADAPTIVE_LOCKMGRS has been introduced. This 102 option compiles in the support for adaptive spinning for lockmgrs 103 which want to enable it. The lockinit() function now accepts the flag 104 LK_ADAPTIVE in order to make the lock object subject to adaptive 105 spinning when both held in write and read mode. 106 10720090613: 108 The layout of the structure returned by IEEE80211_IOC_STA_INFO has 109 changed. User applications that use this ioctl need to be rebuilt. 110 11120090611: 112 The layout of struct thread has changed. Kernel and modules need to 113 be rebuilt. 114 11520090608: 116 The layout of structs ifnet, domain, protosw and vnet_net has changed. 117 Kernel modules need to be rebuilt. Bump __FreeBSD_version to 800097. 118 11920090602: 120 window(1) has been removed from the base system. It can now be 121 installed from ports. The port is called misc/window. 122 12320090601: 124 The way we are storing and accessing `routing table' entries has 125 changed. Programs reading the FIB, like netstat, need to be 126 re-compiled. 127 12820090601: 129 A new netisr implementation has been added for FreeBSD 8. Network 130 file system modules, such as igmp, ipdivert, and others, should be 131 rebuilt. 132 Bump __FreeBSD_version to 800096. 133 13420090530: 135 Remove the tunable/sysctl debug.mpsafevfs as its initial purpose is no 136 more valid. 137 13820090530: 139 Add VOP_ACCESSX(9). File system modules need to be rebuilt. 140 Bump __FreeBSD_version to 800094. 141 14220090529: 143 Add mnt_xflag field to 'struct mount'. File system modules need to be 144 rebuilt. 145 Bump __FreeBSD_version to 800093. 146 14720090528: 148 The compiling option ADAPTIVE_SX has been retired while it has been 149 introduced the option NO_ADAPTIVE_SX which handles the reversed logic. 150 The KPI for sx_init_flags() changes as accepting flags: 151 SX_ADAPTIVESPIN flag has been retired while the SX_NOADAPTIVE flag has 152 been introduced in order to handle the reversed logic. 153 Bump __FreeBSD_version to 800092. 154 15520090527: 156 Add support for hierarchical jails. Remove global securelevel. 157 Bump __FreeBSD_version to 800091. 158 15920090523: 160 The layout of struct vnet_net has changed, therefore modules 161 need to be rebuilt. 162 Bump __FreeBSD_version to 800090. 163 16420090523: 165 The newly imported zic(8) produces a new format in the output. Please 166 run tzsetup(8) to install the newly created data to /etc/localtime. 167 16820090520: 169 The sysctl tree for the usb stack has renamed from hw.usb2.* to 170 hw.usb.* and is now consistent again with previous releases. 171 17220090520: 173 802.11 monitor mode support was revised and driver api's were changed. 174 Drivers dependent on net80211 now support DLT_IEEE802_11_RADIO instead 175 of DLT_IEEE802_11. No user-visible data structures were changed but 176 applications that use DLT_IEEE802_11 may require changes. 177 Bump __FreeBSD_version to 800088. 178 17920090430: 180 The layout of the following structs has changed: sysctl_oid, 181 socket, ifnet, inpcbinfo, tcpcb, syncache_head, vnet_inet, 182 vnet_inet6 and vnet_ipfw. Most modules need to be rebuild or 183 panics may be experienced. World rebuild is required for 184 correctly checking networking state from userland. 185 Bump __FreeBSD_version to 800085. 186 18720090429: 188 MLDv2 and Source-Specific Multicast (SSM) have been merged 189 to the IPv6 stack. VIMAGE hooks are in but not yet used. 190 The implementation of SSM within FreeBSD's IPv6 stack closely 191 follows the IPv4 implementation. 192 193 For kernel developers: 194 195 * The most important changes are that the ip6_output() and 196 ip6_input() paths no longer take the IN6_MULTI_LOCK, 197 and this lock has been downgraded to a non-recursive mutex. 198 199 * As with the changes to the IPv4 stack to support SSM, filtering 200 of inbound multicast traffic must now be performed by transport 201 protocols within the IPv6 stack. This does not apply to TCP and 202 SCTP, however, it does apply to UDP in IPv6 and raw IPv6. 203 204 * The KPIs used by IPv6 multicast are similar to those used by 205 the IPv4 stack, with the following differences: 206 * im6o_mc_filter() is analogous to imo_multicast_filter(). 207 * The legacy KAME entry points in6_joingroup and in6_leavegroup() 208 are shimmed to in6_mc_join() and in6_mc_leave() respectively. 209 * IN6_LOOKUP_MULTI() has been deprecated and removed. 210 * IPv6 relies on MLD for the DAD mechanism. KAME's internal KPIs 211 for MLDv1 have an additional 'timer' argument which is used to 212 jitter the initial membership report for the solicited-node 213 multicast membership on-link. 214 * This is not strictly needed for MLDv2, which already jitters 215 its report transmissions. However, the 'timer' argument is 216 preserved in case MLDv1 is active on the interface. 217 218 * The KAME linked-list based IPv6 membership implementation has 219 been refactored to use a vector similar to that used by the IPv4 220 stack. 221 Code which maintains a list of its own multicast memberships 222 internally, e.g. carp, has been updated to reflect the new 223 semantics. 224 225 * There is a known Lock Order Reversal (LOR) due to in6_setscope() 226 acquiring the IF_AFDATA_LOCK and being called within ip6_output(). 227 Whilst MLDv2 tries to avoid this otherwise benign LOR, it is an 228 implementation constraint which needs to be addressed in HEAD. 229 230 For application developers: 231 232 * The changes are broadly similar to those made for the IPv4 233 stack. 234 235 * The use of IPv4 and IPv6 multicast socket options on the same 236 socket, using mapped addresses, HAS NOT been tested or supported. 237 238 * There are a number of issues with the implementation of various 239 IPv6 multicast APIs which need to be resolved in the API surface 240 before the implementation is fully compatible with KAME userland 241 use, and these are mostly to do with interface index treatment. 242 243 * The literature available discusses the use of either the delta / ASM 244 API with setsockopt(2)/getsockopt(2), or the full-state / ASM API 245 using setsourcefilter(3)/getsourcefilter(3). For more information 246 please refer to RFC 3768, 'Socket Interface Extensions for 247 Multicast Source Filters'. 248 249 * Applications which use the published RFC 3678 APIs should be fine. 250 251 For systems administrators: 252 253 * The mtest(8) utility has been refactored to support IPv6, in 254 addition to IPv4. Interface addresses are no longer accepted 255 as arguments, their names must be used instead. The utility 256 will map the interface name to its first IPv4 address as 257 returned by getifaddrs(3). 258 259 * The ifmcstat(8) utility has also been updated to print the MLDv2 260 endpoint state and source filter lists via sysctl(3). 261 262 * The net.inet6.ip6.mcast.loop sysctl may be tuned to 0 to disable 263 loopback of IPv6 multicast datagrams by default; it defaults to 1 264 to preserve the existing behaviour. Disabling multicast loopback is 265 recommended for optimal system performance. 266 267 * The IPv6 MROUTING code has been changed to examine this sysctl 268 instead of attempting to perform a group lookup before looping 269 back forwarded datagrams. 270 271 Bump __FreeBSD_version to 800084. 272 27320090422: 274 Implement low-level Bluetooth HCI API. 275 Bump __FreeBSD_version to 800083. 276 27720090419: 278 The layout of struct malloc_type, used by modules to register new 279 memory allocation types, has changed. Most modules will need to 280 be rebuilt or panics may be experienced. 281 Bump __FreeBSD_version to 800081. 282 28320090415: 284 Anticipate overflowing inp_flags - add inp_flags2. 285 This changes most offsets in inpcb, so checking v4 connection 286 state will require a world rebuild. 287 Bump __FreeBSD_version to 800080. 288 28920090415: 290 Add an llentry to struct route and struct route_in6. Modules 291 embedding a struct route will need to be recompiled. 292 Bump __FreeBSD_version to 800079. 293 29420090414: 295 The size of rt_metrics_lite and by extension rtentry has changed. 296 Networking administration apps will need to be recompiled. 297 The route command now supports show as an alias for get, weighting 298 of routes, sticky and nostick flags to alter the behavior of stateful 299 load balancing. 300 Bump __FreeBSD_version to 800078. 301 30220090408: 303 Do not use Giant for kbdmux(4) locking. This is wrong and 304 apparently causing more problems than it solves. This will 305 re-open the issue where interrupt handlers may race with 306 kbdmux(4) in polling mode. Typical symptoms include (but 307 not limited to) duplicated and/or missing characters when 308 low level console functions (such as gets) are used while 309 interrupts are enabled (for example geli password prompt, 310 mountroot prompt etc.). Disabling kbdmux(4) may help. 311 31220090407: 313 The size of structs vnet_net, vnet_inet and vnet_ipfw has changed; 314 kernel modules referencing any of the above need to be recompiled. 315 Bump __FreeBSD_version to 800075. 316 31720090320: 318 GEOM_PART has become the default partition slicer for storage devices, 319 replacing GEOM_MBR, GEOM_BSD, GEOM_PC98 and GEOM_GPT slicers. It 320 introduces some changes: 321 322 MSDOS/EBR: the devices created from MSDOS extended partition entries 323 (EBR) can be named differently than with GEOM_MBR and are now symlinks 324 to devices with offset-based names. fstabs may need to be modified. 325 326 BSD: the "geometry does not match label" warning is harmless in most 327 cases but it points to problems in file system misalignment with 328 disk geometry. The "c" partition is now implicit, covers the whole 329 top-level drive and cannot be (mis)used by users. 330 331 General: Kernel dumps are now not allowed to be written to devices 332 whose partition types indicate they are meant to be used for file 333 systems (or, in case of MSDOS partitions, as something else than 334 the "386BSD" type). 335 336 Most of these changes date approximately from 200812. 337 33820090319: 339 The uscanner(4) driver has been removed from the kernel. This follows 340 Linux removing theirs in 2.6 and making libusb the default interface 341 (supported by sane). 342 34320090319: 344 The multicast forwarding code has been cleaned up. netstat(1) 345 only relies on KVM now for printing bandwidth upcall meters. 346 The IPv4 and IPv6 modules are split into ip_mroute_mod and 347 ip6_mroute_mod respectively. The config(5) options for statically 348 compiling this code remain the same, i.e. 'options MROUTING'. 349 35020090315: 351 Support for the IFF_NEEDSGIANT network interface flag has been 352 removed, which means that non-MPSAFE network device drivers are no 353 longer supported. In particular, if_ar, if_sr, and network device 354 drivers from the old (legacy) USB stack can no longer be built or 355 used. 356 35720090313: 358 POSIX.1 Native Language Support (NLS) has been enabled in libc and 359 a bunch of new language catalog files have also been added. 360 This means that some common libc messages are now localized and 361 they depend on the LC_MESSAGES environmental variable. 362 36320090313: 364 The k8temp(4) driver has been renamed to amdtemp(4) since 365 support for K10 and K11 CPU families was added. 366 36720090309: 368 IGMPv3 and Source-Specific Multicast (SSM) have been merged 369 to the IPv4 stack. VIMAGE hooks are in but not yet used. 370 371 For kernel developers, the most important changes are that the 372 ip_output() and ip_input() paths no longer take the IN_MULTI_LOCK(), 373 and this lock has been downgraded to a non-recursive mutex. 374 375 Transport protocols (UDP, Raw IP) are now responsible for filtering 376 inbound multicast traffic according to group membership and source 377 filters. The imo_multicast_filter() KPI exists for this purpose. 378 Transports which do not use multicast (SCTP, TCP) already reject 379 multicast by default. Forwarding and receive performance may improve 380 as a mutex acquisition is no longer needed in the ip_input() 381 low-level input path. in_addmulti() and in_delmulti() are shimmed 382 to new KPIs which exist to support SSM in-kernel. 383 384 For application developers, it is recommended that loopback of 385 multicast datagrams be disabled for best performance, as this 386 will still cause the lock to be taken for each looped-back 387 datagram transmission. The net.inet.ip.mcast.loop sysctl may 388 be tuned to 0 to disable loopback by default; it defaults to 1 389 to preserve the existing behaviour. 390 391 For systems administrators, to obtain best performance with 392 multicast reception and multiple groups, it is always recommended 393 that a card with a suitably precise hash filter is used. Hash 394 collisions will still result in the lock being taken within the 395 transport protocol input path to check group membership. 396 397 If deploying FreeBSD in an environment with IGMP snooping switches, 398 it is recommended that the net.inet.igmp.sendlocal sysctl remain 399 enabled; this forces 224.0.0.0/24 group membership to be announced 400 via IGMP. 401 402 The size of 'struct igmpstat' has changed; netstat needs to be 403 recompiled to reflect this. 404 Bump __FreeBSD_version to 800070. 405 40620090309: 407 libusb20.so.1 is now installed as libusb.so.1 and the ports system 408 updated to use it. This requires a buildworld/installworld in order to 409 update the library and dependencies (usbconfig, etc). Its advisable to 410 rebuild all ports which uses libusb. More specific directions are given 411 in the ports collection UPDATING file. Any /etc/libmap.conf entries for 412 libusb are no longer required and can be removed. 413 41420090302: 415 A workaround is committed to allow the creation of System V shared 416 memory segment of size > 2 GB on the 64-bit architectures. 417 Due to a limitation of the existing ABI, the shm_segsz member 418 of the struct shmid_ds, returned by shmctl(IPC_STAT) call is 419 wrong for large segments. Note that limits must be explicitly 420 raised to allow such segments to be created. 421 42220090301: 423 The layout of struct ifnet has changed, requiring a rebuild of all 424 network device driver modules. 425 42620090227: 427 The /dev handling for the new USB stack has changed, a 428 buildworld/installworld is required for libusb20. 429 43020090223: 431 The new USB2 stack has now been permanently moved in and all kernel and 432 module names reverted to their previous values (eg, usb, ehci, ohci, 433 ums, ...). The old usb stack can be compiled in by prefixing the name 434 with the letter 'o', the old usb modules have been removed. 435 Updating entry 20090216 for xorg and 20090215 for libmap may still 436 apply. 437 43820090217: 439 The rc.conf(5) option if_up_delay has been renamed to 440 defaultroute_delay to better reflect its purpose. If you have 441 customized this setting in /etc/rc.conf you need to update it to 442 use the new name. 443 44420090216: 445 xorg 7.4 wants to configure its input devices via hald which does not 446 yet work with USB2. If the keyboard/mouse does not work in xorg then 447 add 448 Option "AllowEmptyInput" "off" 449 to your ServerLayout section. This will cause X to use the configured 450 kbd and mouse sections from your xorg.conf. 451 45220090215: 453 The GENERIC kernels for all architectures now default to the new USB2 454 stack. No kernel config options or code have been removed so if a 455 problem arises please report it and optionally revert to the old USB 456 stack. If you are loading USB kernel modules or have a custom kernel 457 that includes GENERIC then ensure that usb names are also changed over, 458 eg uftdi -> usb2_serial_ftdi. 459 460 Older programs linked against the ports libusb 0.1 need to be 461 redirected to the new stack's libusb20. /etc/libmap.conf can 462 be used for this: 463 # Map old usb library to new one for usb2 stack 464 libusb-0.1.so.8 libusb20.so.1 465 46620090203: 467 The ichsmb(4) driver has been changed to require SMBus slave 468 addresses be left-justified (xxxxxxx0b) rather than right-justified. 469 All of the other SMBus controller drivers require left-justified 470 slave addresses, so this change makes all the drivers provide the 471 same interface. 472 47320090201: 474 INET6 statistics (struct ip6stat) was updated. 475 netstat(1) needs to be recompiled. 476 47720090119: 478 NTFS has been removed from GENERIC kernel on amd64 to match 479 GENERIC on i386. Should not cause any issues since mount_ntfs(8) 480 will load ntfs.ko module automatically when NTFS support is 481 actually needed, unless ntfs.ko is not installed or security 482 level prohibits loading kernel modules. If either is the case, 483 "options NTFS" has to be added into kernel config. 484 48520090115: 486 TCP Appropriate Byte Counting (RFC 3465) support added to kernel. 487 New field in struct tcpcb breaks ABI, so bump __FreeBSD_version to 488 800061. User space tools that rely on the size of struct tcpcb in 489 tcp_var.h (e.g. sockstat) need to be recompiled. 490 49120081225: 492 ng_tty(4) module updated to match the new TTY subsystem. 493 Due to API change, user-level applications must be updated. 494 New API support added to mpd5 CVS and expected to be present 495 in next mpd5.3 release. 496 49720081219: 498 With __FreeBSD_version 800060 the makefs tool is part of 499 the base system (it was a port). 500 50120081216: 502 The afdata and ifnet locks have been changed from mutexes to 503 rwlocks, network modules will need to be re-compiled. 504 50520081214: 506 __FreeBSD_version 800059 incorporates the new arp-v2 rewrite. 507 RTF_CLONING, RTF_LLINFO and RTF_WASCLONED flags are eliminated. 508 The new code reduced struct rtentry{} by 16 bytes on 32-bit 509 architecture and 40 bytes on 64-bit architecture. The userland 510 applications "arp" and "ndp" have been updated accordingly. 511 The output from "netstat -r" shows only routing entries and 512 none of the L2 information. 513 51420081130: 515 __FreeBSD_version 800057 marks the switchover from the 516 binary ath hal to source code. Users must add the line: 517 518 options AH_SUPPORT_AR5416 519 520 to their kernel config files when specifying: 521 522 device ath_hal 523 524 The ath_hal module no longer exists; the code is now compiled 525 together with the driver in the ath module. It is now 526 possible to tailor chip support (i.e. reduce the set of chips 527 and thereby the code size); consult ath_hal(4) for details. 528 52920081121: 530 __FreeBSD_version 800054 adds memory barriers to 531 <machine/atomic.h>, new interfaces to ifnet to facilitate 532 multiple hardware transmit queues for cards that support 533 them, and a lock-less ring-buffer implementation to 534 enable drivers to more efficiently manage queueing of 535 packets. 536 53720081117: 538 A new version of ZFS (version 13) has been merged to -HEAD. 539 This version has zpool attribute "listsnapshots" off by 540 default, which means "zfs list" does not show snapshots, 541 and is the same as Solaris behavior. 542 54320081028: 544 dummynet(4) ABI has changed. ipfw(8) needs to be recompiled. 545 54620081009: 547 The uhci, ohci, ehci and slhci USB Host controller drivers have 548 been put into separate modules. If you load the usb module 549 separately through loader.conf you will need to load the 550 appropriate *hci module as well. E.g. for a UHCI-based USB 2.0 551 controller add the following to loader.conf: 552 553 uhci_load="YES" 554 ehci_load="YES" 555 55620081009: 557 The ABI used by the PMC toolset has changed. Please keep 558 userland (libpmc(3)) and the kernel module (hwpmc(4)) in 559 sync. 560 56120080820: 562 The TTY subsystem of the kernel has been replaced by a new 563 implementation, which provides better scalability and an 564 improved driver model. Most common drivers have been migrated to 565 the new TTY subsystem, while others have not. The following 566 drivers have not yet been ported to the new TTY layer: 567 568 PCI/ISA: 569 cy, digi, rc, rp, sio 570 571 USB: 572 ubser, ucycom 573 574 Line disciplines: 575 ng_h4, ng_tty, ppp, sl, snp 576 577 Adding these drivers to your kernel configuration file shall 578 cause compilation to fail. 579 58020080818: 581 ntpd has been upgraded to 4.2.4p5. 582 58320080801: 584 OpenSSH has been upgraded to 5.1p1. 585 586 For many years, FreeBSD's version of OpenSSH preferred DSA 587 over RSA for host and user authentication keys. With this 588 upgrade, we've switched to the vendor's default of RSA over 589 DSA. This may cause upgraded clients to warn about unknown 590 host keys even for previously known hosts. Users should 591 follow the usual procedure for verifying host keys before 592 accepting the RSA key. 593 594 This can be circumvented by setting the "HostKeyAlgorithms" 595 option to "ssh-dss,ssh-rsa" in ~/.ssh/config or on the ssh 596 command line. 597 598 Please note that the sequence of keys offered for 599 authentication has been changed as well. You may want to 600 specify IdentityFile in a different order to revert this 601 behavior. 602 60320080713: 604 The sio(4) driver has been removed from the i386 and amd64 605 kernel configuration files. This means uart(4) is now the 606 default serial port driver on those platforms as well. 607 608 To prevent collisions with the sio(4) driver, the uart(4) driver 609 uses different names for its device nodes. This means the 610 onboard serial port will now most likely be called "ttyu0" 611 instead of "ttyd0". You may need to reconfigure applications to 612 use the new device names. 613 614 When using the serial port as a boot console, be sure to update 615 /boot/device.hints and /etc/ttys before booting the new kernel. 616 If you forget to do so, you can still manually specify the hints 617 at the loader prompt: 618 619 set hint.uart.0.at="isa" 620 set hint.uart.0.port="0x3F8" 621 set hint.uart.0.flags="0x10" 622 set hint.uart.0.irq="4" 623 boot -s 624 62520080609: 626 The gpt(8) utility has been removed. Use gpart(8) to partition 627 disks instead. 628 62920080603: 630 The version that Linuxulator emulates was changed from 2.4.2 631 to 2.6.16. If you experience any problems with Linux binaries 632 please try to set sysctl compat.linux.osrelease to 2.4.2 and 633 if it fixes the problem contact emulation mailing list. 634 63520080525: 636 ISDN4BSD (I4B) was removed from the src tree. You may need to 637 update a your kernel configuration and remove relevant entries. 638 63920080509: 640 I have checked in code to support multiple routing tables. 641 See the man pages setfib(1) and setfib(2). 642 This is a hopefully backwards compatible version, 643 but to make use of it you need to compile your kernel 644 with options ROUTETABLES=2 (or more up to 16). 645 64620080420: 647 The 802.11 wireless support was redone to enable multi-bss 648 operation on devices that are capable. The underlying device 649 is no longer used directly but instead wlanX devices are 650 cloned with ifconfig. This requires changes to rc.conf files. 651 For example, change: 652 ifconfig_ath0="WPA DHCP" 653 to 654 wlans_ath0=wlan0 655 ifconfig_wlan0="WPA DHCP" 656 see rc.conf(5) for more details. In addition, mergemaster of 657 /etc/rc.d is highly recommended. Simultaneous update of userland 658 and kernel wouldn't hurt either. 659 660 As part of the multi-bss changes the wlan_scan_ap and wlan_scan_sta 661 modules were merged into the base wlan module. All references 662 to these modules (e.g. in kernel config files) must be removed. 663 66420080408: 665 psm(4) has gained write(2) support in native operation level. 666 Arbitrary commands can be written to /dev/psm%d and status can 667 be read back from it. Therefore, an application is responsible 668 for status validation and error recovery. It is a no-op in 669 other operation levels. 670 67120080312: 672 Support for KSE threading has been removed from the kernel. To 673 run legacy applications linked against KSE libmap.conf may 674 be used. The following libmap.conf may be used to ensure 675 compatibility with any prior release: 676 677 libpthread.so.1 libthr.so.1 678 libpthread.so.2 libthr.so.2 679 libkse.so.3 libthr.so.3 680 68120080301: 682 The layout of struct vmspace has changed. This affects libkvm 683 and any executables that link against libkvm and use the 684 kvm_getprocs() function. In particular, but not exclusively, 685 it affects ps(1), fstat(1), pkill(1), systat(1), top(1) and w(1). 686 The effects are minimal, but it's advisable to upgrade world 687 nonetheless. 688 68920080229: 690 The latest em driver no longer has support in it for the 691 82575 adapter, this is now moved to the igb driver. The 692 split was done to make new features that are incompatible 693 with older hardware easier to do. 694 69520080220: 696 The new geom_lvm(4) geom class has been renamed to geom_linux_lvm(4), 697 likewise the kernel option is now GEOM_LINUX_LVM. 698 69920080211: 700 The default NFS mount mode has changed from UDP to TCP for 701 increased reliability. If you rely on (insecurely) NFS 702 mounting across a firewall you may need to update your 703 firewall rules. 704 70520080208: 706 Belatedly note the addition of m_collapse for compacting 707 mbuf chains. 708 70920080126: 710 The fts(3) structures have been changed to use adequate 711 integer types for their members and so to be able to cope 712 with huge file trees. The old fts(3) ABI is preserved 713 through symbol versioning in libc, so third-party binaries 714 using fts(3) should still work, although they will not take 715 advantage of the extended types. At the same time, some 716 third-party software might fail to build after this change 717 due to unportable assumptions made in its source code about 718 fts(3) structure members. Such software should be fixed 719 by its vendor or, in the worst case, in the ports tree. 720 FreeBSD_version 800015 marks this change for the unlikely 721 case that a portable fix is impossible. 722 72320080123: 724 To upgrade to -current after this date, you must be running 725 FreeBSD not older than 6.0-RELEASE. Upgrading to -current 726 from 5.x now requires a stop over at RELENG_6 or RELENG_7 systems. 727 72820071128: 729 The ADAPTIVE_GIANT kernel option has been retired because its 730 functionality is the default now. 731 73220071118: 733 The AT keyboard emulation of sunkbd(4) has been turned on 734 by default. In order to make the special symbols of the Sun 735 keyboards driven by sunkbd(4) work under X these now have 736 to be configured the same way as Sun USB keyboards driven 737 by ukbd(4) (which also does AT keyboard emulation), f.e.: 738 739 Option "XkbLayout" "us" 740 Option "XkbRules" "xorg" 741 Option "XkbSymbols" "pc(pc105)+sun_vndr/usb(sun_usb)+us" 742 74320071024: 744 It has been decided that it is desirable to provide ABI 745 backwards compatibility to the FreeBSD 4/5/6 versions of the 746 PCIOCGETCONF, PCIOCREAD and PCIOCWRITE IOCTLs, which was 747 broken with the introduction of PCI domain support (see the 748 20070930 entry). Unfortunately, this required the ABI of 749 PCIOCGETCONF to be broken again in order to be able to 750 provide backwards compatibility to the old version of that 751 IOCTL. Thus consumers of PCIOCGETCONF have to be recompiled 752 again. As for prominent ports this affects neither pciutils 753 nor xorg-server this time, the hal port needs to be rebuilt 754 however. 755 75620071020: 757 The misnamed kthread_create() and friends have been renamed 758 to kproc_create() etc. Many of the callers already 759 used kproc_start().. 760 I will return kthread_create() and friends in a while 761 with implementations that actually create threads, not procs. 762 Renaming corresponds with version 800002. 763 76420071010: 765 RELENG_7 branched. 766 767COMMON ITEMS: 768 769 General Notes 770 ------------- 771 Avoid using make -j when upgrading. While generally safe, there are 772 sometimes problems using -j to upgrade. If your upgrade fails with 773 -j, please try again wtihout -j. From time to time in the past there 774 have been problems using -j with buildworld and/or installworld. This 775 is especially true when upgrading between "distant" versions (eg one 776 that cross a major release boundary or several minor releases, or when 777 several months have passed on the -current branch). 778 779 Sometimes, obscure build problems are the result of environment 780 poisoning. This can happen because the make utility reads its 781 environment when searching for values for global variables. To run 782 your build attempts in an "environmental clean room", prefix all make 783 commands with 'env -i '. See the env(1) manual page for more details. 784 785 When upgrading from one major version to another it is generally best 786 to upgrade to the latest code in the currently installed branch first, 787 then do an upgrade to the new branch. This is the best-tested upgrade 788 path, and has the highest probability of being successful. Please try 789 this approach before reporting problems with a major version upgrade. 790 791 To build a kernel 792 ----------------- 793 If you are updating from a prior version of FreeBSD (even one just 794 a few days old), you should follow this procedure. It is the most 795 failsafe as it uses a /usr/obj tree with a fresh mini-buildworld, 796 797 make kernel-toolchain 798 make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE 799 make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE 800 801 To test a kernel once 802 --------------------- 803 If you just want to boot a kernel once (because you are not sure 804 if it works, or if you want to boot a known bad kernel to provide 805 debugging information) run 806 make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel 807 nextboot -k testkernel 808 809 To just build a kernel when you know that it won't mess you up 810 -------------------------------------------------------------- 811 This assumes you are already running a CURRENT system. Replace 812 ${arch} with the architecture of your machine (e.g. "i386", 813 "arm", "amd64", "ia64", "pc98", "sparc64", "powerpc", "mips", etc). 814 815 cd src/sys/${arch}/conf 816 config KERNEL_NAME_HERE 817 cd ../compile/KERNEL_NAME_HERE 818 make depend 819 make 820 make install 821 822 If this fails, go to the "To build a kernel" section. 823 824 To rebuild everything and install it on the current system. 825 ----------------------------------------------------------- 826 # Note: sometimes if you are running current you gotta do more than 827 # is listed here if you are upgrading from a really old current. 828 829 <make sure you have good level 0 dumps> 830 make buildworld 831 make kernel KERNCONF=YOUR_KERNEL_HERE 832 [1] 833 <reboot in single user> [3] 834 mergemaster -p [5] 835 make installworld 836 make delete-old 837 mergemaster [4] 838 <reboot> 839 840 841 To cross-install current onto a separate partition 842 -------------------------------------------------- 843 # In this approach we use a separate partition to hold 844 # current's root, 'usr', and 'var' directories. A partition 845 # holding "/", "/usr" and "/var" should be about 2GB in 846 # size. 847 848 <make sure you have good level 0 dumps> 849 <boot into -stable> 850 make buildworld 851 make buildkernel KERNCONF=YOUR_KERNEL_HERE 852 <maybe newfs current's root partition> 853 <mount current's root partition on directory ${CURRENT_ROOT}> 854 make installworld DESTDIR=${CURRENT_ROOT} 855 make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd 856 make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT} 857 cp /etc/fstab ${CURRENT_ROOT}/etc/fstab # if newfs'd 858 <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition> 859 <reboot into current> 860 <do a "native" rebuild/install as described in the previous section> 861 <maybe install compatibility libraries from ports/misc/compat*> 862 <reboot> 863 864 865 To upgrade in-place from 8.x-stable to current 866 ---------------------------------------------- 867 <make sure you have good level 0 dumps> 868 make buildworld [9] 869 make kernel KERNCONF=YOUR_KERNEL_HERE [8] 870 [1] 871 <reboot in single user> [3] 872 mergemaster -p [5] 873 make installworld 874 make delete-old 875 mergemaster -i [4] 876 <reboot> 877 878 Make sure that you've read the UPDATING file to understand the 879 tweaks to various things you need. At this point in the life 880 cycle of current, things change often and you are on your own 881 to cope. The defaults can also change, so please read ALL of 882 the UPDATING entries. 883 884 Also, if you are tracking -current, you must be subscribed to 885 freebsd-current@freebsd.org. Make sure that before you update 886 your sources that you have read and understood all the recent 887 messages there. If in doubt, please track -stable which has 888 much fewer pitfalls. 889 890 [1] If you have third party modules, such as vmware, you 891 should disable them at this point so they don't crash your 892 system on reboot. 893 894 [3] From the bootblocks, boot -s, and then do 895 fsck -p 896 mount -u / 897 mount -a 898 cd src 899 adjkerntz -i # if CMOS is wall time 900 Also, when doing a major release upgrade, it is required that 901 you boot into single user mode to do the installworld. 902 903 [4] Note: This step is non-optional. Failure to do this step 904 can result in a significant reduction in the functionality of the 905 system. Attempting to do it by hand is not recommended and those 906 that pursue this avenue should read this file carefully, as well 907 as the archives of freebsd-current and freebsd-hackers mailing lists 908 for potential gotchas. 909 910 [5] Usually this step is a noop. However, from time to time 911 you may need to do this if you get unknown user in the following 912 step. It never hurts to do it all the time. You may need to 913 install a new mergemaster (cd src/usr.sbin/mergemaster && make 914 install) after the buildworld before this step if you last updated 915 from current before 20020224 or from -stable before 20020408. 916 917 [8] In order to have a kernel that can run the 4.x binaries needed to 918 do an installworld, you must include the COMPAT_FREEBSD4 option in 919 your kernel. Failure to do so may leave you with a system that is 920 hard to boot to recover. A similar kernel option COMPAT_FREEBSD5 is 921 required to run the 5.x binaries on more recent kernels. And so on 922 for COMPAT_FREEBSD6 and COMPAT_FREEBSD7. 923 924 Make sure that you merge any new devices from GENERIC since the 925 last time you updated your kernel config file. 926 927 [9] When checking out sources, you must include the -P flag to have 928 cvs prune empty directories. 929 930 If CPUTYPE is defined in your /etc/make.conf, make sure to use the 931 "?=" instead of the "=" assignment operator, so that buildworld can 932 override the CPUTYPE if it needs to. 933 934 MAKEOBJDIRPREFIX must be defined in an environment variable, and 935 not on the command line, or in /etc/make.conf. buildworld will 936 warn if it is improperly defined. 937FORMAT: 938 939This file contains a list, in reverse chronological order, of major 940breakages in tracking -current. Not all things will be listed here, 941and it only starts on October 16, 2004. Updating files can found in 942previous releases if your system is older than this. 943 944Copyright information: 945 946Copyright 1998-2009 M. Warner Losh. All Rights Reserved. 947 948Redistribution, publication, translation and use, with or without 949modification, in full or in part, in any form or format of this 950document are permitted without further permission from the author. 951 952THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR 953IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 954WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 955DISCLAIMED. IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT, 956INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 957(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 958SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 959HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 960STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 961IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 962POSSIBILITY OF SUCH DAMAGE. 963 964Contact Warner Losh if you have any questions about your use of 965this document. 966 967$FreeBSD: head/UPDATING 196789 2009-09-03 17:04:42Z imp $ 968