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 9 https://docs.freebsd.org/en/books/handbook/cutting-edge/#makeworld 10 11Items affecting the ports and packages system can be found in 12/usr/ports/UPDATING. Please read that file before updating system packages 13and/or ports. 14 15NOTE TO PEOPLE WHO THINK THAT FreeBSD 14.x IS SLOW: 16 FreeBSD 14.x has many debugging features turned on, in both the kernel 17 and userland. These features attempt to detect incorrect use of 18 system primitives, and encourage loud failure through extra sanity 19 checking and fail stop semantics. They also substantially impact 20 system performance. If you want to do performance measurement, 21 benchmarking, and optimization, you'll want to turn them off. This 22 includes various WITNESS- related kernel options, INVARIANTS, malloc 23 debugging flags in userland, and various verbose features in the 24 kernel. Many developers choose to disable these features on build 25 machines to maximize performance. (To completely disable malloc 26 debugging, define WITH_MALLOC_PRODUCTION in /etc/src.conf and rebuild 27 world, or to merely disable the most expensive debugging functionality 28 at runtime, run "ln -s 'abort:false,junk:false' /etc/malloc.conf".) 29 3020221121: 31 The WITHOUT_CLANG_IS_CC option has been removed. When Clang is enabled 32 it is always installed as /usr/bin/cc (and c++, cpp). 33 3420221026: 35 Some programs have been moved into separate packages. It is recommended 36 for pkgbase users to do: 37 38 pkg install FreeBSD-dhclient FreeBSD-geom FreeBSD-resolvconf \ 39 FreeBSD-devd FreeBSD-devmatch 40 41 after upgrading to restore all the component that were previously 42 installed. 43 4420220610: 45 LinuxKPI pm.h changes require an update to the latest drm-kmod version 46 before re-compiling to avoid errors. 47 4820211230: 49 The macros provided for the manipulation of CPU sets (e.g. CPU_AND) 50 have been modified to take 2 source arguments instead of only 1. 51 Externally maintained sources that use these macros will have to 52 be adapted. The FreeBSD version has been bumped to 1400046 to 53 reflect this change. 54 5520211214: 56 A number of the kernel include files are able to be included by 57 themselves. A test has been added to buildworld to enforce this. 58 5920211209: 60 Remove mips as a recognized target. This starts the decommissioning of 61 mips support in FreeBSD. mips related items will be removed wholesale in 62 the coming days and weeks. 63 64 This broke the NO_CLEAN build for some people. Either do a clean build 65 or touch 66 lib/clang/include/llvm/Config/Targets.def 67 lib/clang/include/llvm/Config/AsmParsers.def 68 lib/clang/include/llvm/Config/Disassemblers.def 69 lib/clang/include/llvm/Config/AsmPrinters.def 70 before the build to force everything to rebuild that needs to. 71 7220211202: 73 Unbound support for RFC8375: The special-use domain 'home.arpa' is 74 by default blocked. To unblock it use a local-zone nodefault 75 statement in unbound.conf: 76 local-zone: "home.arpa." nodefault 77 78 Or use another type of local-zone to override with your choice. 79 80 The reason for this is discussed in Section 6.1 of RFC8375: 81 Because 'home.arpa.' is not globally scoped and cannot be secured 82 using DNSSEC based on the root domain's trust anchor, there is no way 83 to tell, using a standard DNS query, in which homenet scope an answer 84 belongs. Consequently, users may experience surprising results with 85 such names when roaming to different homenets. 86 8720211110: 88 Commit b8d60729deef changed the TCP congestion control framework so 89 that any of the included congestion control modules could be 90 the single module built into the kernel. Previously newreno 91 was automatically built in through direct reference. As of 92 this commit you are required to declare at least one congestion 93 control module (e.g. 'options CC_NEWRENO') and to also declare a 94 default using the CC_DEFAULT option (e.g. options CC_DEFAULT="newreno\"). 95 The GENERIC configuration includes CC_NEWRENO and defines newreno 96 as the default. If no congestion control option is built into the 97 kernel and you are including networking, the kernel compile will 98 fail. Also if no default is declared the kernel compile will fail. 99 10020211118: 101 Mips has been removed from universe builds. It will be removed from the 102 tree shortly. 103 10420211106: 105 Commit f0c9847a6c47 changed the arguments for VOP_ALLOCATE. 106 The NFS modules must be rebuilt from sources and any out 107 of tree file systems that implement their own VOP_ALLOCATE 108 may need to be modified. 109 11020211022: 111 The synchronous PPP kernel driver sppp(4) has been removed. 112 The cp(4) and ce(4) drivers are now always compiled with netgraph(4) 113 support, formerly enabled by NETGRAPH_CRONYX option. 114 11520211020: 116 sh(1) is now the default shell for the root user. To force root to use 117 the csh shell, please run the following command as root: 118 119 # chsh -s csh 120 12120211004: 122 Ncurses distribution has been split between libtinfow and libncurses 123 with libncurses.so becoming a linker (ld) script to seamlessly link 124 to libtinfow as needed. Bump _FreeBSD_version to 1400035 to reflect 125 this change. 126 12720210923: 128 As of commit 8160a0f62be6, the dummynet module no longer depends on the 129 ipfw module. Dummynet can now be used by pf as well as ipfw. As such 130 users who relied on this dependency may need to include ipfw in the 131 list of modules to load on their systems. 132 13320210922: 134 As of commit 903873ce1560, the mixer(8) utility has got a slightly 135 new syntax. Please refer to the mixer(8) manual page for more 136 information. The old mixer utility can be installed from ports: 137 audio/freebsd-13-mixer 138 13920210911: 140 As of commit 55089ef4f8bb, the global variable nfs_maxcopyrange has 141 been deleted from the nfscommon.ko. As such, nfsd.ko must be built 142 from up to date sources to avoid an undefined reference when 143 being loaded. 144 14520210817: 146 As of commit 62ca9fc1ad56 OpenSSL no longer enables kernel TLS 147 by default. Users can enable kernel TLS via the "KTLS" SSL 148 option. This can be enabled globally by using a custom 149 OpenSSL config file via OPENSSL_CONF or via an 150 application-specific configuration option for applications 151 which permit setting SSL options via SSL_CONF_cmd(3). 152 15320210811: 154 Commit 3ad1e1c1ce20 changed the internal KAPI between the NFS 155 modules. Therefore, all need to be rebuilt from sources. 156 15720210730: 158 Commit b69019c14cd8 removes pf's DIOCGETSTATESNV ioctl. 159 As of be70c7a50d32 it is no longer used by userspace, but it does mean 160 users may not be able to enumerate pf states if they update the kernel 161 past b69019c14cd8 without first updating userspace past be70c7a50d32. 162 16320210729: 164 As of commit 01ad0c007964 if_bridge member interfaces can no longer 165 change their MTU. Changing the MTU of the bridge itself will change the 166 MTU on all member interfaces instead. 167 16820210716: 169 Commit ee29e6f31111 changed the internal KAPI between the nfscommon 170 and nfsd modules. Therefore, both need to be rebuilt from sources. 171 Bump __FreeBSD_version to 1400026 for this KAPI change. 172 17320210715: 174 The 20210707 awk update brought in a change in behavior. This has 175 been corrected as of d4d252c49976. Between these dates, if you 176 installed a new awk binary, you may not be able to build a new 177 kernel because the change in behavior affected the genoffset 178 script used to build the kernel. If you did update, the fix is 179 to update your sources past the above hash and do 180 % cd usr.bin/awk 181 % make clean all 182 % sudo -E make install 183 to enable building kernels again. 184 18520210708: 186 Commit 1e0a518d6548 changed the internal KAPI between the NFS 187 modules. They all need to be rebuilt from sources. I did not 188 bump __FreeBSD_version, since it was bumped recently. 189 19020210707: 191 awk has been updated to the latest one-true-awk version 20210215. 192 This contains a number of minor bug fixes. 193 19420210624: 195 The NFSv4 client now uses the highest minor version of NFSv4 196 supported by the NFSv4 server by default instead of minor version 0, 197 for NFSv4 mounts. 198 The "minorversion" mount option may be used to override this default. 199 20020210618: 201 Bump __FreeBSD_version to 1400024 for LinuxKPI changes. 202 Most notably netdev.h can change now as the (last) dependencies 203 (mlx4/ofed) are now using struct ifnet directly, but also for PCI 204 additions and others. 205 20620210618: 207 The directory "blacklisted" under /usr/share/certs/ has been 208 renamed to "untrusted". 209 21020210611: 211 svnlite has been removed from base. Should you need svn for any reason 212 please install the svn package or port. 213 21420210611: 215 Commit e1a907a25cfa changed the internal KAPI between the krpc 216 and nfsserver. As such, both modules must be rebuilt from 217 sources. Bump __FreeBSD_version to 1400022. 218 21920210610: 220 The an(4) driver has been removed from FreeBSD. 221 22220210608: 223 The vendor/openzfs branch was renamed to vendor/openzfs/legacy to 224 start tracking OpenZFS upstream more closely. Please see 225https://lists.freebsd.org/archives/freebsd-current/2021-June/000153.html 226 for details on how to correct any errors that might result. The 227 short version is that you need to remove the old branch locally: 228 git update-ref -d refs/remotes/freebsd/vendor/openzfs 229 (assuming your upstream origin is named 'freebsd'). 230 23120210525: 232 Commits 17accc08ae15 and de102f870501 add new files to LinuxKPI 233 which break drm-kmod. In addition various other additions where 234 committed. Bump __FreeBSD_version to 1400015 to be able to 235 detect this. 236 23720210513: 238 Commit ca179c4d74f2 changed the package in which the OpenSSL 239 libraries and utilities are packaged. 240 It is recommended for pkgbase user to do: 241 pkg install -f FreeBSD-openssl 242 before pkg upgrade otherwise some dependencies might not be met 243 and pkg will stop working as libssl will not be present anymore 244 on the system. 245 24620210426: 247 Commit 875977314881 changed the internal KAPI between 248 the nfsd and nfscommon modules. As such these modules 249 need to be rebuilt from sources. 250 Without this patch in your NFSv4.1/4.2 server, enabling 251 delegations by setting vfs.nfsd.issue_delegations non-zero 252 is not recommended. 253 25420210411: 255 Commit 7763814fc9c2 changed the internal KAPI between 256 the krpc and NFS. As such, the krpc, nfscommon and 257 nfscl modules must all be rebuilt from sources. 258 Without this patch, NFSv4.1/4.2 mounts should not 259 be done with the nfscbd(8) daemon running, to avoid 260 needing a working back channel for server->client RPCs. 261 26220210330: 263 Commit 01ae8969a9ee fixed the NFSv4.1/4.2 server so that it 264 handles binding of the back channel as required by RFC5661. 265 Until this patch is in your server, avoid use of the "nconnects" 266 mount option for Linux NFSv4.1/4.2 mounts. 267 26820210225: 269 For 64-bit architectures the base system is now built with Position 270 Independent Executable (PIE) support enabled by default. It may be 271 disabled using the WITHOUT_PIE knob. A clean build is required. 272 27320210128: 274 Various LinuxKPI functionality was added which conflicts with DRM. 275 Please update your drm-kmod port to after the __FreeBSD_version 1400003 276 update. 277 278COMMON ITEMS: 279 280 General Notes 281 ------------- 282 Sometimes, obscure build problems are the result of environment 283 poisoning. This can happen because the make utility reads its 284 environment when searching for values for global variables. To run 285 your build attempts in an "environmental clean room", prefix all make 286 commands with 'env -i '. See the env(1) manual page for more details. 287 Occasionally a build failure will occur with "make -j" due to a race 288 condition. If this happens try building again without -j, and please 289 report a bug if it happens consistently. 290 291 When upgrading from one major version to another it is generally best to 292 upgrade to the latest code in the currently installed branch first, then 293 do an upgrade to the new branch. This is the best-tested upgrade path, 294 and has the highest probability of being successful. Please try this 295 approach if you encounter problems with a major version upgrade. Since 296 the stable 4.x branch point, one has generally been able to upgrade from 297 anywhere in the most recent stable branch to head / current (or even the 298 last couple of stable branches). See the top of this file when there's 299 an exception. 300 301 The update process will emit an error on an attempt to perform a build 302 or install from a FreeBSD version below the earliest supported version. 303 When updating from an older version the update should be performed one 304 major release at a time, including running `make delete-old` at each 305 step. 306 307 When upgrading a live system, having a root shell around before 308 installing anything can help undo problems. Not having a root shell 309 around can lead to problems if pam has changed too much from your 310 starting point to allow continued authentication after the upgrade. 311 312 This file should be read as a log of events. When a later event changes 313 information of a prior event, the prior event should not be deleted. 314 Instead, a pointer to the entry with the new information should be 315 placed in the old entry. Readers of this file should also sanity check 316 older entries before relying on them blindly. Authors of new entries 317 should write them with this in mind. 318 319 ZFS notes 320 --------- 321 When upgrading the boot ZFS pool to a new version, always follow 322 these two steps: 323 324 1.) recompile and reinstall the ZFS boot loader and boot block 325 (this is part of "make buildworld" and "make installworld") 326 327 2.) update the ZFS boot block on your boot drive 328 329 The following example updates the ZFS boot block on the 330 freebsd-boot partition of a GPT partitioned drive ada0: 331 "gpart bootcode -p /boot/gptzfsboot -i $N ada0" 332 The value $N will typically be 1 (if booting from BIOS) or 2 (if 333 booting from EFI). 334 335 Non-boot pools do not need these updates. 336 337 To build a kernel 338 ----------------- 339 If you are updating from a prior version of FreeBSD (even one just 340 a few days old), you should follow this procedure. It is the most 341 failsafe as it uses a /usr/obj tree with a fresh mini-buildworld, 342 343 make kernel-toolchain 344 make -DALWAYS_CHECK_MAKE buildkernel KERNCONF=YOUR_KERNEL_HERE 345 make -DALWAYS_CHECK_MAKE installkernel KERNCONF=YOUR_KERNEL_HERE 346 347 To test a kernel once 348 --------------------- 349 If you just want to boot a kernel once (because you are not sure 350 if it works, or if you want to boot a known bad kernel to provide 351 debugging information) run 352 make installkernel KERNCONF=YOUR_KERNEL_HERE KODIR=/boot/testkernel 353 nextboot -k testkernel 354 355 To rebuild everything and install it on the current system. 356 ----------------------------------------------------------- 357 # Note: sometimes if you are running current you gotta do more than 358 # is listed here if you are upgrading from a really old current. 359 360 <make sure you have good level 0 dumps> 361 make buildworld 362 make buildkernel KERNCONF=YOUR_KERNEL_HERE 363 make installkernel KERNCONF=YOUR_KERNEL_HERE 364 [1] 365 <reboot in single user> [3] 366 etcupdate -p [5] 367 make installworld 368 etcupdate -B [4] 369 make delete-old [6] 370 <reboot> 371 372 To cross-install current onto a separate partition 373 -------------------------------------------------- 374 # In this approach we use a separate partition to hold 375 # current's root, 'usr', and 'var' directories. A partition 376 # holding "/", "/usr" and "/var" should be about 2GB in 377 # size. 378 379 <make sure you have good level 0 dumps> 380 <boot into -stable> 381 make buildworld 382 make buildkernel KERNCONF=YOUR_KERNEL_HERE 383 <maybe newfs current's root partition> 384 <mount current's root partition on directory ${CURRENT_ROOT}> 385 make installworld DESTDIR=${CURRENT_ROOT} -DDB_FROM_SRC 386 make distribution DESTDIR=${CURRENT_ROOT} # if newfs'd 387 make installkernel KERNCONF=YOUR_KERNEL_HERE DESTDIR=${CURRENT_ROOT} 388 cp /etc/fstab ${CURRENT_ROOT}/etc/fstab # if newfs'd 389 <edit ${CURRENT_ROOT}/etc/fstab to mount "/" from the correct partition> 390 <reboot into current> 391 <do a "native" rebuild/install as described in the previous section> 392 <maybe install compatibility libraries from ports/misc/compat*> 393 <reboot> 394 395 396 To upgrade in-place from stable to current 397 ---------------------------------------------- 398 <make sure you have good level 0 dumps> 399 make buildworld [9] 400 make buildkernel KERNCONF=YOUR_KERNEL_HERE [8] 401 make installkernel KERNCONF=YOUR_KERNEL_HERE 402 [1] 403 <reboot in single user> [3] 404 etcupdate -p [5] 405 make installworld 406 etcupdate -B [4] 407 make delete-old [6] 408 <reboot> 409 410 Make sure that you've read the UPDATING file to understand the 411 tweaks to various things you need. At this point in the life 412 cycle of current, things change often and you are on your own 413 to cope. The defaults can also change, so please read ALL of 414 the UPDATING entries. 415 416 Also, if you are tracking -current, you must be subscribed to 417 freebsd-current@freebsd.org. Make sure that before you update 418 your sources that you have read and understood all the recent 419 messages there. If in doubt, please track -stable which has 420 much fewer pitfalls. 421 422 [1] If you have third party modules, such as vmware, you should disable 423 them at this point so they don't crash your system on 424 reboot. Alternatively, you should rebuild all the modules you have in 425 your system and install them as well. If you are running -current, you 426 should seriously consider placing all sources to all the modules for 427 your system (or symlinks to them) in /usr/local/sys/modules so this 428 happens automatically. If all your modules come from ports, then adding 429 the port origin directories to PORTS_MODULES instead is also automatic 430 and effective, eg: 431 PORTS_MODULES+=x11/nvidia-driver 432 433 [3] From the bootblocks, boot -s, and then do 434 fsck -p 435 mount -u / 436 mount -a 437 sh /etc/rc.d/zfs start # mount zfs filesystem, if needed 438 cd src # full path to source 439 adjkerntz -i # if CMOS is wall time 440 Also, when doing a major release upgrade, it is required that you boot 441 into single user mode to do the installworld. 442 443 [4] Note: This step is non-optional. Failure to do this step 444 can result in a significant reduction in the functionality of the 445 system. Attempting to do it by hand is not recommended and those 446 that pursue this avenue should read this file carefully, as well 447 as the archives of freebsd-current and freebsd-hackers mailing lists 448 for potential gotchas. See etcupdate(8) for more information. 449 450 [5] Usually this step is a no-op. However, from time to time 451 you may need to do this if you get unknown user in the following 452 step. 453 454 [6] This only deletes old files and directories. Old libraries 455 can be deleted by "make delete-old-libs", but you have to make 456 sure that no program is using those libraries anymore. 457 458 [8] The new kernel must be able to run existing binaries used by an 459 installworld. When upgrading across major versions, the new kernel's 460 configuration must include the correct COMPAT_FREEBSD<n> option for 461 existing binaries (e.g. COMPAT_FREEBSD11 to run 11.x binaries). Failure 462 to do so may leave you with a system that is hard to boot to recover. A 463 GENERIC kernel will include suitable compatibility options to run 464 binaries from older branches. Note that the ability to run binaries 465 from unsupported branches is not guaranteed. 466 467 Make sure that you merge any new devices from GENERIC since the 468 last time you updated your kernel config file. Options also 469 change over time, so you may need to adjust your custom kernels 470 for these as well. 471 472 [9] If CPUTYPE is defined in your /etc/make.conf, make sure to use the 473 "?=" instead of the "=" assignment operator, so that buildworld can 474 override the CPUTYPE if it needs to. 475 476 MAKEOBJDIRPREFIX must be defined in an environment variable, and 477 not on the command line, or in /etc/make.conf. buildworld will 478 warn if it is improperly defined. 479FORMAT: 480 481This file contains a list, in reverse chronological order, of major 482breakages in tracking -current. It is not guaranteed to be a complete 483list of such breakages, and only contains entries since September 23, 2011. 484If you need to see UPDATING entries from before that date, you will need 485to fetch an UPDATING file from an older FreeBSD release. 486 487Copyright information: 488 489Copyright 1998-2009 M. Warner Losh <imp@FreeBSD.org> 490 491Redistribution, publication, translation and use, with or without 492modification, in full or in part, in any form or format of this 493document are permitted without further permission from the author. 494 495THIS DOCUMENT IS PROVIDED BY WARNER LOSH ``AS IS'' AND ANY EXPRESS OR 496IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 497WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 498DISCLAIMED. IN NO EVENT SHALL WARNER LOSH BE LIABLE FOR ANY DIRECT, 499INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 500(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 501SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 502HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 503STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 504IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 505POSSIBILITY OF SUCH DAMAGE. 506 507Contact Warner Losh if you have any questions about your use of 508this document. 509 510$FreeBSD$ 511