Index: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml (revision 50250) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml (revision 50251) @@ -1,2205 +1,1606 @@ Updating and Upgrading &os; Jim Mock Restructured, reorganized, and parts updated by Jordan Hubbard Original work by Poul-Henning Kamp John Polstra Nik Clayton Synopsis &os; is under constant development between releases. Some people prefer to use the officially released versions, while others prefer to keep in sync with the latest developments. However, even official releases are often updated with security and other critical fixes. Regardless of the version used, &os; provides all the necessary tools to keep the system updated, and allows for easy upgrades between versions. This chapter describes how to track the development system and the basic tools for keeping a &os; system up-to-date. After reading this chapter, you will know: How to keep a &os; system up-to-date with freebsd-update or Subversion. How to compare the state of an installed system against a known pristine copy. How to keep the installed documentation up-to-date with Subversion or documentation ports. The difference between the two development branches: &os.stable; and &os.current;. How to rebuild and reinstall the entire base system. Before reading this chapter, you should: Properly set up the network connection (). Know how to install additional third-party software (). Throughout this chapter, svn is used to obtain and update &os; sources. To use it, first install the devel/subversion port or package. &os; Update Tom Rhodes Written by Colin Percival Based on notes provided by Updating and Upgrading freebsd-update updating-upgrading Applying security patches in a timely manner and upgrading to a newer release of an operating system are important aspects of ongoing system administration. &os; includes a utility called freebsd-update which can be used to perform both these tasks. This utility supports binary security and errata updates to &os;, without the need to manually compile and install the patch or a new kernel. Binary updates are available for all architectures and releases currently supported by the security team. The list of supported releases and their estimated end-of-life dates are listed at http://www.FreeBSD.org/security/. This utility also supports operating system upgrades to minor point releases as well as upgrades to another release branch. Before upgrading to a new release, review its release announcement as it contains important information pertinent to the release. Release announcements are available from http://www.FreeBSD.org/releases/. If a crontab utilizing the features of &man.freebsd-update.8; exists, it must be disabled before upgrading the operating system. This section describes the configuration file used by freebsd-update, demonstrates how to apply a security patch and how to upgrade to a minor or major operating system release, and discusses some of the considerations when upgrading the operating system. The Configuration File The default configuration file for freebsd-update works as-is. Some users may wish to tweak the default configuration in /etc/freebsd-update.conf, allowing better control of the process. The comments in this file explain the available options, but the following may require a bit more explanation: # Components of the base system which should be kept updated. Components world kernel This parameter controls which parts of &os; will be kept up-to-date. The default is to update the entire base system and the kernel. Individual components can instead be specified, such as src/base or src/sys. However, the best option is to leave this at the default as changing it to include specific items requires every needed item to be listed. Over time, this could have disastrous consequences as source code and binaries may become out of sync. # Paths which start with anything matching an entry in an IgnorePaths # statement will be ignored. IgnorePaths /boot/kernel/linker.hints To leave specified directories, such as /bin or /sbin, untouched during the update process, add their paths to this statement. This option may be used to prevent freebsd-update from overwriting local modifications. # Paths which start with anything matching an entry in an UpdateIfUnmodified # statement will only be updated if the contents of the file have not been # modified by the user (unless changes are merged; see below). UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile This option will only update unmodified configuration files in the specified directories. Any changes made by the user will prevent the automatic updating of these files. There is another option, KeepModifiedMetadata, which will instruct freebsd-update to save the changes during the merge. # When upgrading to a new &os; release, files which match MergeChanges # will have any local changes merged into the version from the new release. MergeChanges /etc/ /var/named/etc/ /boot/device.hints List of directories with configuration files that freebsd-update should attempt to merge. The file merge process is a series of &man.diff.1; patches similar to &man.mergemaster.8;, but with fewer options. Merges are either accepted, open an editor, or cause freebsd-update to abort. When in doubt, backup /etc and just accept the merges. See for more information about mergemaster. # Directory in which to store downloaded updates and temporary # files used by &os; Update. # WorkDir /var/db/freebsd-update This directory is where all patches and temporary files are placed. In cases where the user is doing a version upgrade, this location should have at least a gigabyte of disk space available. # When upgrading between releases, should the list of Components be # read strictly (StrictComponents yes) or merely as a list of components # which *might* be installed of which &os; Update should figure out # which actually are installed and upgrade those (StrictComponents no)? # StrictComponents no When this option is set to yes, freebsd-update will assume that the Components list is complete and will not attempt to make changes outside of the list. Effectively, freebsd-update will attempt to update every file which belongs to the Components list. Applying Security Patches The process of applying &os; security patches has been simplified, allowing an administrator to keep a system fully patched using freebsd-update. More information about &os; security advisories can be found in . &os; security patches may be downloaded and installed using the following commands. The first command will determine if any outstanding patches are available, and if so, will list the files that will be modifed if the patches are applied. The second command will apply the patches. &prompt.root; freebsd-update fetch &prompt.root; freebsd-update install If the update applies any kernel patches, the system will need a reboot in order to boot into the patched kernel. If the patch was applied to any running binaries, the affected applications should be restarted so that the patched version of the binary is used. The system can be configured to automatically check for updates once every day by adding this entry to /etc/crontab: @daily root freebsd-update cron If patches exist, they will automatically be downloaded but will not be applied. The root user will be sent an email so that the patches may be reviewed and manually installed with freebsd-update install. If anything goes wrong, freebsd-update has the ability to roll back the last set of changes with the following command: &prompt.root; freebsd-update rollback Uninstalling updates... done. Again, the system should be restarted if the kernel or any kernel modules were modified and any affected binaries should be restarted. Only the GENERIC kernel can be automatically updated by freebsd-update. If a custom kernel is installed, it will have to be rebuilt and reinstalled after freebsd-update finishes installing the updates. However, freebsd-update will detect and update the GENERIC kernel if /boot/GENERIC exists, even if it is not the current running kernel of the system. Always keep a copy of the GENERIC kernel in /boot/GENERIC. It will be helpful in diagnosing a variety of problems and in performing version upgrades. Refer to for instructions on how to get a copy of the GENERIC kernel. Unless the default configuration in /etc/freebsd-update.conf has been changed, freebsd-update will install the updated kernel sources along with the rest of the updates. Rebuilding and reinstalling a new custom kernel can then be performed in the usual way. The updates distributed by freebsd-update do not always involve the kernel. It is not necessary to rebuild a custom kernel if the kernel sources have not been modified by freebsd-update install. However, freebsd-update will always update /usr/src/sys/conf/newvers.sh. The current patch level, as indicated by the -p number reported by uname -r, is obtained from this file. Rebuilding a custom kernel, even if nothing else changed, allows uname to accurately report the current patch level of the system. This is particularly helpful when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one. Performing Major and Minor Version Upgrades Upgrades from one minor version of &os; to another, like from &os; 9.0 to &os; 9.1, are called minor version upgrades. Major version upgrades occur when &os; is upgraded from one major version to another, like from &os; 9.X to &os; 10.X. Both types of upgrades can be performed by providing freebsd-update with a release version target. If the system is running a custom kernel, make sure that a copy of the GENERIC kernel exists in /boot/GENERIC before starting the upgrade. Refer to for instructions on how to get a copy of the GENERIC kernel. The following command, when run on a &os; 9.0 system, will upgrade it to &os; 9.1: &prompt.root; freebsd-update -r 9.1-RELEASE upgrade After the command has been received, freebsd-update will evaluate the configuration file and current system in an attempt to gather the information necessary to perform the upgrade. A screen listing will display which components have and have not been detected. For example: Looking up update.FreeBSD.org mirrors... 1 mirrors found. Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. The following components of FreeBSD seem to be installed: kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin world/base world/info world/lib32 world/manpages The following components of FreeBSD do not seem to be installed: kernel/generic world/catpages world/dict world/doc world/games world/proflibs Does this look reasonable (y/n)? y At this point, freebsd-update will attempt to download all files required for the upgrade. In some cases, the user may be prompted with questions regarding what to install or how to proceed. When using a custom kernel, the above step will produce a warning similar to the following: WARNING: This system is running a "MYKERNEL" kernel, which is not a kernel configuration distributed as part of FreeBSD 9.0-RELEASE. This kernel will not be updated: you MUST update the kernel manually before running "/usr/sbin/freebsd-update install" This warning may be safely ignored at this point. The updated GENERIC kernel will be used as an intermediate step in the upgrade process. Once all the patches have been downloaded to the local system, they will be applied. This process may take a while, depending on the speed and workload of the machine. Configuration files will then be merged. The merging process requires some user intervention as a file may be merged or an editor may appear on screen for a manual merge. The results of every successful merge will be shown to the user as the process continues. A failed or ignored merge will cause the process to abort. Users may wish to make a backup of /etc and manually merge important files, such as master.passwd or group at a later time. The system is not being altered yet as all patching and merging is happening in another directory. Once all patches have been applied successfully, all configuration files have been merged and it seems the process will go smoothly, the changes can be committed to disk by the user using the following command: &prompt.root; freebsd-update install The kernel and kernel modules will be patched first. If the system is running with a custom kernel, use &man.nextboot.8; to set the kernel for the next boot to the updated /boot/GENERIC: &prompt.root; nextboot -k GENERIC Before rebooting with the GENERIC kernel, make sure it contains all the drivers required for the system to boot properly and connect to the network, if the machine being updated is accessed remotely. In particular, if the running custom kernel contains built-in functionality usually provided by kernel modules, make sure to temporarily load these modules into the GENERIC kernel using the /boot/loader.conf facility. It is recommended to disable non-essential services as well as any disk and network mounts until the upgrade process is complete. The machine should now be restarted with the updated kernel: &prompt.root; shutdown -r now Once the system has come back online, restart freebsd-update using the following command. Since the state of the process has been saved, freebsd-update will not start from the beginning, but will instead move on to the next phase and remove all old shared libraries and object files. &prompt.root; freebsd-update install Depending upon whether any library version numbers were bumped, there may only be two install phases instead of three. The upgrade is now complete. If this was a major version upgrade, reinstall all ports and packages as described in . Custom Kernels with &os; 9.X and Later Before using freebsd-update, ensure that a copy of the GENERIC kernel exists in /boot/GENERIC. If a custom kernel has only been built once, the kernel in /boot/kernel.old is the GENERIC kernel. Simply rename this directory to /boot/kernel. If a custom kernel has been built more than once or if it is unknown how many times the custom kernel has been built, obtain a copy of the GENERIC kernel that matches the current version of the operating system. If physical access to the system is available, a copy of the GENERIC kernel can be installed from the installation media: &prompt.root; mount /cdrom &prompt.root; cd /cdrom/usr/freebsd-dist &prompt.root; tar -C/ -xvf kernel.txz boot/kernel/kernel Alternately, the GENERIC kernel may be rebuilt and installed from source: &prompt.root; cd /usr/src &prompt.root; make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null For this kernel to be identified as the GENERIC kernel by freebsd-update, the GENERIC configuration file must not have been modified in any way. It is also suggested that the kernel is built without any other special options. Rebooting into the GENERIC kernel is not required as freebsd-update only needs /boot/GENERIC to exist. Upgrading Packages After a Major Version Upgrade Generally, installed applications will continue to work without problems after minor version upgrades. Major versions use different Application Binary Interfaces (ABIs), which will break most third-party applications. After a major version upgrade, all installed packages and ports need to be upgraded. Packages can be upgraded using pkg upgrade. To upgrade installed ports, use a utility such as ports-mgmt/portmaster. A forced upgrade of all installed packages will replace the packages with fresh versions from the repository even if the version number has not increased. This is required because of the ABI version change when upgrading between major versions of &os;. The forced upgrade can be accomplished by performing: &prompt.root; pkg-static upgrade -f A rebuild of all installed applications can be accomplished with this command: &prompt.root; portmaster -af This command will display the configuration screens for each application that has configurable options and wait for the user to interact with those screens. To prevent this behavior, and use only the default options, include in the above command. Once the software upgrades are complete, finish the upgrade process with a final call to freebsd-update in order to tie up all the loose ends in the upgrade process: &prompt.root; freebsd-update install If the GENERIC kernel was temporarily used, this is the time to build and install a new custom kernel using the instructions in . Reboot the machine into the new &os; version. The upgrade process is now complete. System State Comparison The state of the installed &os; version against a known good copy can be tested using freebsd-update IDS. This command evaluates the current version of system utilities, libraries, and configuration files and can be used as a built-in Intrusion Detection System (IDS). This command is not a replacement for a real IDS such as security/snort. As freebsd-update stores data on disk, the possibility of tampering is evident. While this possibility may be reduced using kern.securelevel and by storing the freebsd-update data on a read-only file system when not in use, a better solution would be to compare the system against a secure disk, such as a DVD or securely stored external USB disk device. An alternative method for providing IDS functionality using a built-in utility is described in To begin the comparison, specify the output file to save the results to: &prompt.root; freebsd-update IDS >> outfile.ids The system will now be inspected and a lengthy listing of files, along with the SHA256 hash values for both the known value in the release and the current installation, will be sent to the specified output file. The entries in the listing are extremely long, but the output format may be easily parsed. For instance, to obtain a list of all files which differ from those in the release, issue the following command: &prompt.root; cat outfile.ids | awk '{ print $1 }' | more /etc/master.passwd /etc/motd /etc/passwd /etc/pf.conf This sample output has been truncated as many more files exist. Some files have natural modifications. For example, /etc/passwd will be modified if users have been added to the system. Kernel modules may differ as freebsd-update may have updated them. To exclude specific files or directories, add them to the IDSIgnorePaths option in /etc/freebsd-update.conf. Updating the Documentation Set Updating and Upgrading Documentation Updating and Upgrading Documentation is an integral part of the &os; operating system. While an up-to-date version of the &os; documentation is always available on the &os; web site (http://www.freebsd.org/doc/), it can be handy to have an up-to-date, local copy of the &os; website, handbooks, FAQ, and articles. This section describes how to use either source or the &os; Ports Collection to keep a local copy of the &os; documentation up-to-date. For information on editing and submitting corrections to the documentation, refer to the &os; Documentation Project Primer for New Contributors (http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/). Updating Documentation from Source Rebuilding the &os; documentation from source requires a collection of tools which are not part of the &os; base system. The required tools, including svn, can be installed from the textproc/docproj package or port developed by the &os; Documentation Project. Once installed, use svn to fetch a clean copy of the documentation source: &prompt.root; svn checkout https://svn.FreeBSD.org/doc/head /usr/doc The initial download of the documentation sources may take a while. Let it run until it completes. Future updates of the documentation sources may be fetched by running: &prompt.root; svn update /usr/doc Once an up-to-date snapshot of the documentation sources has been fetched to /usr/doc, everything is ready for an update of the installed documentation. A full update of all available languages may be performed by typing: &prompt.root; cd /usr/doc &prompt.root; make install clean If an update of only a specific language is desired, make can be invoked in a language-specific subdirectory of /usr/doc: &prompt.root; cd /usr/doc/en_US.ISO8859-1 &prompt.root; make install clean An alternative way of updating the documentation is to run this command from /usr/doc or the desired language-specific subdirectory: &prompt.root; make update The output formats that will be installed may be specified by setting FORMATS: &prompt.root; cd /usr/doc &prompt.root; make FORMATS='html html-split' install clean Several options are available to ease the process of updating only parts of the documentation, or the build of specific translations. These options can be set either as system-wide options in /etc/make.conf, or as command-line options passed to make. The options include: DOC_LANG The list of languages and encodings to build and install, such as en_US.ISO8859-1 for English documentation. FORMATS A single format or a list of output formats to be built. Currently, html, html-split, txt, ps, and pdf are supported. DOCDIR Where to install the documentation. It defaults to /usr/share/doc. For more make variables supported as system-wide options in &os;, refer to &man.make.conf.5;. Updating Documentation from Ports Marc Fonvieille Based on the work of Updating and Upgrading documentation package Updating and Upgrading The previous section presented a method for updating the &os; documentation from sources. This section describes an alternative method which uses the Ports Collection and makes it possible to: Install pre-built packages of the documentation, without having to locally build anything or install the documentation toolchain. Build the documentation sources through the ports framework, making the checkout and build steps a bit easier. This method of updating the &os; documentation is supported by a set of documentation ports and packages which are updated by the &a.doceng; on a monthly basis. These are listed in the &os; Ports Collection, under the docs category (http://www.freshports.org/docs/). Organization of the documentation ports is as follows: The misc/freebsd-doc-en package or port installs all of the English documentation. The misc/freebsd-doc-all meta-package or port installs all documentation in all available languages. There is a package and port for each translation, such as misc/freebsd-doc-hu for the Hungarian documentation. When binary packages are used, the &os; documentation will be installed in all available formats for the given language. For example, the following command will install the latest package of the Hungarian documentation: &prompt.root; pkg install hu-freebsd-doc Packages use a format that differs from the corresponding port's name: lang-freebsd-doc, where lang is the short format of the language code, such as hu for Hungarian, or zh_cn for Simplified Chinese. To specify the format of the documentation, build the port instead of installing the package. For example, to build and install the English documentation: &prompt.root; cd /usr/ports/misc/freebsd-doc-en &prompt.root; make install clean The port provides a configuration menu where the format to build and install can be specified. By default, split HTML, similar to the format used on http://www.FreeBSD.org, and PDF are selected. Alternately, several make options can be specified when building a documentation port, including: WITH_HTML Builds the HTML format with a single HTML file per document. The formatted documentation is saved to a file called article.html, or book.html. WITH_PDF The formatted documentation is saved to a file called article.pdf or book.pdf. DOCBASE Specifies where to install the documentation. It defaults to /usr/local/share/doc/freebsd. This example uses variables to install the Hungarian documentation as a PDF in the specified directory: &prompt.root; cd /usr/ports/misc/freebsd-doc-hu &prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean Documentation packages or ports can be updated using the instructions in . For example, the following command updates the installed Hungarian documentation using ports-mgmt/portmaster by using packages only: &prompt.root; portmaster -PP hu-freebsd-doc Tracking a Development Branch -CURRENT -STABLE &os; has two development branches: &os.current; and &os.stable;. This section provides an explanation of each branch and its intended audience, as well as how to keep a system up-to-date with each respective branch. Using &os.current; &os.current; is the bleeding edge of &os; development and &os.current; users are expected to have a high degree of technical skill. Less technical users who wish to track a development branch should track &os.stable; instead. &os.current; is the very latest source code for &os; and includes works in progress, experimental changes, and transitional mechanisms that might or might not be present in the next official release. While many &os; developers compile the &os.current; source code daily, there are short periods of time when the source may not be buildable. These problems are resolved as quickly as possible, but whether or not &os.current; brings disaster or new functionality can be a matter of when the source code was synced. &os.current; is made available for three primary interest groups: Members of the &os; community who are actively working on some part of the source tree. Members of the &os; community who are active testers. They are willing to spend time solving problems, making topical suggestions on changes and the general direction of &os;, and submitting patches. Users who wish to keep an eye on things, use the current source for reference purposes, or make the occasional comment or code contribution. &os.current; should not be considered a fast-track to getting new features before the next release as pre-release features are not yet fully tested and most likely contain bugs. It is not a quick way of getting bug fixes as any given commit is just as likely to introduce new bugs as to fix existing ones. &os.current; is not in any way officially supported. -CURRENT using To track &os.current;: Join the &a.current.name; and the &a.svn-src-head.name; lists. This is essential in order to see the comments that people are making about the current state of the system and to receive important bulletins about the current state of &os.current;. The &a.svn-src-head.name; list records the commit log entry for each change as it is made, along with any pertinent information on possible side effects. To join these lists, go to &a.mailman.lists.link;, click on the list to subscribe to, and follow the instructions. In order to track changes to the whole source tree, not just the changes to &os.current;, subscribe to the &a.svn-src-all.name; list. Synchronize with the &os.current; sources. Typically, svn is used to check out the -CURRENT code from the head branch of one of the Subversion mirror sites listed in . Due to the size of the repository, some users choose to only synchronize the sections of source that interest them or which they are contributing patches to. However, users that plan to compile the operating system from source must download all of &os.current;, not just selected portions. Before compiling &os.current; -CURRENT compiling , read /usr/src/Makefile very carefully and follow the instructions in . Read the &a.current; and /usr/src/UPDATING to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. Be active! &os.current; users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are always welcome. - - - Using &os.stable; - - &os.stable; is the development branch from which major - releases are made. Changes go into this branch at a slower - pace and with the general assumption that they have first been - tested in &os.current;. This is still a - development branch and, at any given time, the sources for - &os.stable; may or may not be suitable for general use. It is - simply another engineering development track, not a resource - for end-users. Users who do not have the resources to perform - testing should instead run the most recent release of - &os;. - - Those interested in tracking or contributing to the &os; - development process, especially as it relates to the next - release of &os;, should consider following &os.stable;. - - While the &os.stable; branch should compile and run at all - times, this cannot be guaranteed. Since more people run - &os.stable; than &os.current;, it is inevitable that bugs and - corner cases will sometimes be found in &os.stable; that were - not apparent in &os.current;. For this reason, one should not - blindly track &os.stable;. It is particularly important - not to update any production servers to - &os.stable; without thoroughly testing the code in a - development or testing environment. - - To track &os.stable;: - - - -STABLE - using - - - - Join the &a.stable.name; list in order to stay - informed of build dependencies that may appear in - &os.stable; or any other issues requiring special - attention. Developers will also make announcements in - this mailing list when they are contemplating some - controversial fix or update, giving the users a chance to - respond if they have any issues to raise concerning the - proposed change. - - Join the relevant svn list - for the branch being tracked. For example, users - tracking the 9-STABLE branch should join the - &a.svn-src-stable-9.name; list. This list records the - commit log entry for each change as it is made, along - with any pertinent information on possible - side effects. - - To join these lists, go to &a.mailman.lists.link;, - click on the list to subscribe to, and follow the - instructions. In order to track changes for the whole - source tree, subscribe to &a.svn-src-all.name;. - - - - To install a new &os.stable; system, install the most - recent &os.stable; release from the &os; mirror sites or use a - monthly snapshot built from &os.stable;. Refer to www.freebsd.org/snapshots - for more information about snapshots. - - To compile or upgrade to an existing &os; system to - &os.stable;, use svn - - Subversion - to check out the source for the desired - branch. Branch names, such as - stable/9, are listed at www.freebsd.org/releng. - - - - Before compiling or upgrading to &os.stable; - - -STABLE - compiling - , read /usr/src/Makefile - carefully and follow the instructions in . Read &a.stable; and - /usr/src/UPDATING to keep up-to-date - on other bootstrapping procedures that sometimes become - necessary on the road to the next release. - - - - - Synchronizing Source + + Updating &os; from Source - There are various methods for staying up-to-date with the - &os; sources. This section describes the primary service, - Subversion. + Updating &os; by compiling from source offers several + advantages over binary updates. Code can be built with options + to take advantage of specific hardware. Parts of the base + system can be built with non-default settings, or left out + entirely where they are not needed or desired. The build + process takes longer to update a system than binary updates, but + allows complete customization to produce a tailored version of + &os;. - - While it is possible to update only parts of the source - tree, the only supported update procedure is to update the - entire tree and recompile all the programs that run in user - space, such as those in /bin and - /sbin, and kernel sources. Updating only - part of the source tree, only the kernel, or only the userland - programs will often result in problems ranging from compile - errors to kernel panics or data corruption. - + + Quick Start - - Subversion - + This is a quick reference for the typical steps used to + update &os; by building from source. Later sections describe + the process in more detail. - Subversion uses the - pull model of updating sources. The user, - or a cron script, invokes the - svn program which updates the local version - of the source. Subversion is the - preferred method for updating local source trees as updates are - up-to-the-minute and the user controls when updates are - downloaded. It is easy to restrict updates to specific files or - directories and the requested updates are generated on the fly - by the server. How to synchronize source using - Subversion is described in . - - If a user inadvertently wipes out portions of the local - archive, Subversion will detect and - rebuild the damaged portions during an update. - - - - Rebuilding World - - - Rebuilding world - - Once the local source tree is synchronized against a - particular version of &os; such as &os.stable; or &os.current;, - the source tree can be used to rebuild the system. This process - is known as rebuilding world. - - Before rebuilding world, be sure to - perform the following tasks: - - - Perform These Tasks <emphasis>Before</emphasis> - Building World - - - Backup all important data to another system or removable - media, verify the integrity of the backup, and have a - bootable installation media at hand. It cannot be stressed - enough how important it is to make a backup of the system - before rebuilding the system. While - rebuilding world is an easy task, there will inevitably be - times when mistakes in the source tree render the system - unbootable. You will probably never have to use the backup, - but it is better to be safe than sorry! - - - - mailing list - Review the recent &a.stable.name; or &a.current.name; - entries, depending upon the branch being tracked. Be aware - of any known problems and which systems are affected. If a - known issue affects the version of synchronized code, wait - for an all clear announcement to be posted - stating that the problem has been solved. Resynchronize the - sources to ensure that the local version of source has the - needed fix. - - - - Read /usr/src/UPDATING for any - extra steps necessary for that version of the source. This - file contains important information about potential problems - and may specify the order to run certain commands. Many - upgrades require specific additional steps such as renaming - or deleting specific files prior to installing the new - world. These will be listed at the end of this file where - the currently recommended upgrade sequence is explicitly - spelled out. If UPDATING contradicts - any steps in this chapter, the instructions in - UPDATING take precedence and should be - followed. - - - - - Do Not Use <command>make world</command> - - Some older documentation recommends using make - world. However, that command skips some important - steps and should only be used by experts. For almost all - circumstances make world is the wrong thing - to do, and the procedure described here should be used - instead. - - - - Overview of Process - - The build world process assumes an upgrade from an older - &os; version using the source of a newer version that was - obtained using the instructions in . - - In &os;, the term world includes the - kernel, core system binaries, libraries, programming files, - and built-in compiler. The order in which these components - are built and installed is important. - - For example, the old compiler might have a bug and not be - able to compile the new kernel. Since the new kernel should - be built with the new compiler, the new compiler must be - built, but not necessarily installed, before the new kernel is - built. - - The new world might rely on new kernel features, so the - new kernel must be installed before the new world is - installed. The old world might not run correctly on the new - kernel, so the new world must be installed immediately upon - installing the new kernel. - - Some configuration changes must be made before the new - world is installed, but others might break the old world. - Hence, two different configuration upgrade steps are used. - For the most part, the update process only replaces or adds - files and existing old files are not deleted. Since this can - cause problems, /usr/src/UPDATING will - indicate if any files need to be manually deleted and at which - step to do so. - - These concerns have led to the recommended upgrade - sequence described in the following procedure. - - - It is a good idea to save the output from running - make to a file. If something goes wrong, - a copy of the error message can be posted to one of the &os; - mailing lists. - - The easiest way to do this is to use - script with a parameter that specifies - the name of the file to save all output to. Do not save the - output to /tmp as this directory may be - cleared at next reboot. A better place to save the file is - /var/tmp. Run this command immediately - before rebuilding the world, and then type - exit when the process has - finished: - - &prompt.root; script /var/tmp/mw.out -Script started, output file is /var/tmp/mw.out - - - Overview of Build World Process + + Preparing - The commands used in the build world process should be - run in the order specified here. This section summarizes - the function of each command. + The very first time a computer is updated from source, + run - - If the build world process has previously been run on - this system, a copy of the previous build may still exist - in /usr/obj. To - speed up the new build world process, and possibly save - some dependency headaches, remove this directory if it - already exists: + &prompt.root; etcupdate extract - &prompt.root; chflags -R noschg /usr/obj/* -&prompt.root; rm -rf /usr/obj - + This creates a checkpoint for later comparison and + merging of system settings. - - Compile the new compiler and a few related tools, then - use the new compiler to compile the rest of the new world. - The result is saved to /usr/obj. - - &prompt.root; cd /usr/src -&prompt.root; make buildworld + This step is only done once on a particular + computer. &man.etcupdate.8; does not need any + additional updates after the first + extract. - Use the new compiler residing in /usr/obj to build the new - kernel, in order to protect against compiler-kernel - mismatches. This is necessary, as certain memory - structures may have changed, and programs like - ps and top will fail - to work if the kernel and source code versions are not the - same. + Update and Build - &prompt.root; make buildkernel - + &prompt.root; svn update /usr/src +check /usr/src/UPDATING +&prompt.root; cd /usr/src +&prompt.root; make -j4 buildworld +&prompt.root; make -j4 kernel +&prompt.root; make installworld +&prompt.root; etcupdate +&prompt.root; shutdown -r now - - Install the new kernel and kernel modules, making it - possible to boot with the newly updated kernel. If - kern.securelevel has been raised above - 1 and - noschg or similar flags have been set - on the kernel binary, drop the system into single-user - mode first. Otherwise, this command can be run from - multi-user mode without problems. See &man.init.8; for - details about kern.securelevel and - &man.chflags.1; for details about the various file - flags. + + + Get the latest version of the source. See + for + more information on obtaining and updating + source. + - &prompt.root; make installkernel - + + Any manual steps required before or after building + from source are shown in + /usr/src/UPDATING. + - - Drop the system into single-user mode in order to - minimize problems from updating any binaries that are - already running. It also minimizes any problems from - running the old world on a new kernel. + + Go to the source directory. + - &prompt.root; shutdown now + + Compile the world, everything except the + kernel. + - Once in single-user mode, run these commands if the - system is formatted with UFS: + + Compile and install the kernel. This is + equivalent to + buildkernel + installkernel. + - &prompt.root; mount -u / -&prompt.root; mount -a -t ufs -&prompt.root; swapon -a + + Install the world. + - If the system is instead formatted with ZFS, run these - two commands. This example assumes a zpool name of - zroot: + + Update and merge configuration files in + /etc/. + - &prompt.root; zfs set readonly=off zroot -&prompt.root; zfs mount -a + + Restart the system to use the newly-built world + and kernel. + + - - - Optional: If a keyboard mapping other than the default - US English is desired, it can be changed with - &man.kbdmap.1;: - - &prompt.root; kbdmap - - - - Then, for either file system, if the - CMOS clock is set to local time (this - is true if the output of &man.date.1; does not show the - correct time and zone), run: - - &prompt.root; adjkerntz -i - - - - Remaking the world will not update certain - directories, such as /etc, - /var and /usr, - with new or changed configuration files. The next step is - to perform some initial configuration file updates - to /etc in - preparation for the new world. The following command - compares only those files that are essential for the - success of installworld. For - instance, this step may add new groups, system accounts, - or startup scripts which have been added to &os; since the - last update. This is necessary so that the - installworld step will be able - to use any new system accounts, groups, and scripts. - Refer to for more detailed - instructions about this command: - - &prompt.root; mergemaster -p - - - - Install the new world and system binaries from - /usr/obj. - - &prompt.root; cd /usr/src -&prompt.root; make installworld - - - - Update any remaining configuration files. - - &prompt.root; mergemaster -iF - - - - Delete any obsolete files. This is important as they - may cause problems if left on the disk. - - &prompt.root; make delete-old - - - - A full reboot is now needed to load the new kernel and - new world with the new configuration files. - - &prompt.root; reboot - - - - Make sure that all installed ports have first been - rebuilt before old libraries are removed using the - instructions in . When - finished, remove any obsolete libraries to avoid conflicts - with newer ones. For a more detailed description of this - step, refer to . - - &prompt.root; make delete-old-libs - - - single-user mode - - If the system can have a window of down-time, consider - compiling the system in single-user mode instead of compiling - the system in multi-user mode, and then dropping into - single-user mode for the installation. Reinstalling the - system touches a lot of important system files, all the - standard system binaries, libraries, and include files. - Changing these on a running system, particularly one with - active users, is asking for trouble. - - Configuration Files + + Preparing for a Source Update - - make.conf - + If this is the first time that a source update has + ever been done on this computer, run + etcupdate extract to create a record of + system settings for later update and merging. This step only + needs to be done once on a particular computer. - This build world process uses several configuration - files. - - The Makefile located in - /usr/src describes how the programs that - comprise &os; should be built and the order in which they - should be built. - - The options available to make are - described in &man.make.conf.5; and some common examples are - included in - /usr/share/examples/etc/make.conf. Any - options which are added to /etc/make.conf - will control the how make runs and builds - programs. These options take effect every time - make is used, including compiling - applications from the Ports Collection, compiling custom C - programs, or building the &os; operating system. Changes to - some settings can have far-reaching and potentially surprising - effects. Read the comments in both locations and keep in mind - that the defaults have been chosen for a combination of - performance and safety. - - - src.conf - - - How the operating system is built from source code is - controlled by /etc/src.conf. Unlike - /etc/make.conf, the contents of - /etc/src.conf only take effect when the - &os; operating system itself is being built. Descriptions of - the many options available for this file are shown in - &man.src.conf.5;. Be cautious about disabling seemingly - unneeded kernel modules and build options. Sometimes there - are unexpected or subtle interactions. + Read /usr/src/UPDATING. Any manual + steps that must be performed before or after an update are + described in this file. - - Variables and Targets + + Updating the Source - The general format for using make is as - follows: + &os; source code is located in + /usr/src/. The preferred method of + updating this source is through the + Subversion version control system. + Verify that the source code is under version control: - &prompt.root; make -x -DVARIABLE target + &prompt.root; svn info /usr/src +Path: /usr/src +Working Copy Root Path: /usr/src +... - In this example, - is an option - passed to make. Refer to &man.make.1; for - examples of the available options. + This indicates that /usr/src/ + is under version control and can be updated with + &man.svn.1;: - To pass a variable, specify the variable name with - . The - behavior of the Makefile is controlled by - variables. These can either be set in - /etc/make.conf or they can be specified - when using make. For example, this - variable specifies that profiled libraries should not be - built: + &prompt.root; svn update /usr/src - &prompt.root; make -DNO_PROFILE target + The update process can take some time if the directory has + not been updated recently. After it finishes, the source code + is up to date and the build process described in the next + section can begin. - It corresponds with this setting in - /etc/make.conf: + + Obtaining the Source - NO_PROFILE= true # Avoid compiling profiled libraries + If the output says + '/usr/src' is not a working copy, the + files there are missing or were installed with a different + method. A new checkout of the source is required. - The target tells - make what to do and the - Makefile defines the available targets. - Some targets are used by the build process to break out the - steps necessary to rebuild the system into a number of - sub-steps. + + &os; Versions and Repository Paths - Having separate options is useful for two reasons. First, - it allows for a build that does not affect any components of a - running system. Because of this, - buildworld can be safely run on a - machine running in multi-user mode. It is still recommended - that installworld be run in part in - single-user mode, though. + + + + uname -r Output + Repository Path + Description + + - Secondly, it allows NFS mounts to be - used to upgrade multiple machines on a network, as described - in . + + + X.Y-RELEASE + base/releng/X + The Release version plus only critical security + and bug fix patches. This branch is recommended + for most users. + - It is possible to specify which will - cause make to spawn several simultaneous - processes. Since much of the compiling process is - I/O-bound rather than - CPU-bound, this is useful on both single - CPU and multi-CPU - machines. + + X.Y-STABLE + base/stable/X + + The Release version plus all additional + development on that branch. + STABLE refers to the + Applications Binary Interface + (ABI) not changing, so software + compiled for earlier versions still runs. For + example, software compiled to run on &os; 10.1 + will still run on &os; 10-STABLE compiled + later. - On a single-CPU machine, run the - following command to have up to 4 processes running at any one - time. Empirical evidence posted to the mailing lists shows - this generally gives the best performance benefit. + STABLE branches occasionally have bugs or + incompatibilities which might affect users, + although these are typically fixed quickly. + + - &prompt.root; make -j4 buildworld + + X-CURRENT + base/head/ + The latest unreleased development version of + &os;. The CURRENT branch can have major bugs or + incompatibilities and is recommended only for + advanced users. + + + +
- On a multi-CPU machine, try values - between 6 and 10 to see - how they speed things up. + Determine which version of &os; is being used with + &man.uname.1;: - - rebuilding world - timings - + &prompt.root; uname -r +10.3-RELEASE - - If any variables were specified to make - buildworld, specify the same variables to - make installworld. However, - must never be used - with installworld. + Based on + , the + source used to update 10.3-RELEASE has a + repository path of base/releng/10. That + path is used when checking out the source: - For example, if this command was used: + &prompt.root; mv /usr/src /usr/src.bak +&prompt.root; svn checkout https://svn.freebsd.org/base/releng/10 /usr/src - &prompt.root; make -DNO_PROFILE buildworld + + + Move the old directory out of the way. If there are + no local modifications in this directory, it can be + deleted. + - Install the results with: - - &prompt.root; make -DNO_PROFILE installworld - - Otherwise, the second command will try to install - profiled libraries that were not built during the - make buildworld phase. + + The path from + is + added to the repository URL. The + third parameter is the destination directory for the + source code on the local system. + + - - - Merging Configuration Files + + Building from Source - - - - Tom - Rhodes - - Contributed by - - - + The world, or all + of the operating system except the kernel, is compiled. This + is done first to provide up-to-date tools to build the kernel. + Then the kernel itself is built: - - - mergemaster - - + &prompt.root; cd /usr/src +&prompt.root; make buildworld +&prompt.root; make buildkernel - &os; provides the &man.mergemaster.8; Bourne script to aid - in determining the differences between the configuration files - in /etc, and the configuration files in - /usr/src/etc. This is the recommended - solution for keeping the system configuration files up to date - with those located in the source tree. + The compiled code is written to + /usr/obj. - Before using mergemaster, it is - recommended to first copy the existing - /etc somewhere safe. Include - which does a recursive copy and - which preserves times and the ownerships - on files: + These are the basic steps. Additional options to control + the build are described below. - &prompt.root; cp -Rp /etc /etc.old + + Performing a Clean Build - When run, mergemaster builds a - temporary root environment, from / down, - and populates it with various system configuration files. - Those files are then compared to the ones currently installed - in the system. Files that differ will be shown in - &man.diff.1; format, with the sign - representing added or modified lines, and - representing lines that will be either removed completely or - replaced with a new file. Refer to &man.diff.1; for more - information about how file differences are shown. + Some versions of the &os; build system leave + previously-compiled code in the temporary object directory, + /usr/obj. This can speed up later + builds by avoiding recompiling code that has not changed. + To force a clean rebuild of everything, remove + /usr/obj before starting a build. + This is roughly equivalent to performing a + make clean, but much faster: - Next, mergemaster will display each - file that differs, and present options to: delete the new - file, referred to as the temporary file, install the temporary - file in its unmodified state, merge the temporary file with - the currently installed file, or view the results - again. + &prompt.root; rm -rf /usr/obj/* + - Choosing to delete the temporary file will tell - mergemaster to keep the current file - unchanged and to delete the new version. This option is not - recommended. To get help at any time, type - ? at the mergemaster - prompt. If the user chooses to skip a file, it will be - presented again after all other files have been dealt - with. + + Setting the Number of Jobs - Choosing to install the unmodified temporary file will - replace the current file with the new one. For most - unmodified files, this is the best option. + Increasing the number of build jobs on multi-core + processors can improve build speed. Determine the number of + cores with sysctl hw.ncpu. Processors + vary, as do the build systems used with different versions + of &os;, so testing is the only sure method to tell how a + different number of jobs affects the build speed. For a + starting point, consider values between half and double the + number of cores. The number of jobs is specified with + . - Choosing to merge the file will present a text editor with - the contents of both files open. The files can be merged by - reviewing both files side by side on the screen and choosing - parts from both to create a finished product. When the files - are compared side by side, l selects the left - contents and r selects contents from the - right. The final output will be a file consisting of both - parts, which can then be installed. This option is - customarily used for files where settings have been modified - by the user. + + Increasing the Number of Build Jobs - Choosing to view the results again will redisplay the file - differences. + Building the world and kernel with four jobs: - After mergemaster is done with the - system files, it will prompt for other options. It may prompt - to rebuild the password file and will finish up with an option - to remove left-over temporary files. - + &prompt.root; make buildkernel KERNCONF=STORAGESERVER + - - - Deleting Obsolete Files and Libraries + + Installing the Compiled Code - - - - Anton - Shterenlikht - - Based on notes provided by - - - + After the buildworld and + buildkernel steps have been + completed, the new kernel and world are installed: - - Deleting obsolete files and directories - - - As a part of the &os; development lifecycle, files and - their contents occasionally become obsolete. This may be - because functionality is implemented elsewhere, the version - number of the library has changed, or it was removed from the - system entirely. These obsoleted files, libraries, and - directories should be removed when updating the system. - This ensures that the system is not cluttered with old files - which take up unnecessary space on the storage and backup - media. Additionally, if the old library has a security or - stability issue, the system should be updated to the newer - library to keep it safe and to prevent crashes caused by the - old library. Files, directories, and libraries which are - considered obsolete are listed in - /usr/src/ObsoleteFiles.inc. The - following instructions should be used to remove obsolete files - during the system upgrade process. - - After the make installworld and the - subsequent mergemaster have finished - successfully, check for obsolete files and libraries: - &prompt.root; cd /usr/src -&prompt.root; make check-old +&prompt.root; make installkernel installworld - If any obsolete files are found, they can be deleted using - the following command: + If a custom kernel was built, KERNCONF + must also be set to use the new custom kernel: - &prompt.root; make delete-old - - A prompt is displayed before deleting each obsolete file. - To skip the prompt and let the system remove these files - automatically, use - BATCH_DELETE_OLD_FILES: - - &prompt.root; make -DBATCH_DELETE_OLD_FILES delete-old - - The same goal can be achieved by piping these commands - through yes: - - &prompt.root; yes|make delete-old - - - Warning - - Deleting obsolete files will break applications that - still depend on those obsolete files. This is especially - true for old libraries. In most cases, the programs, ports, - or libraries that used the old library need to be recompiled - before make delete-old-libs is - executed. - - - Utilities for checking shared library dependencies include - sysutils/libchk and - sysutils/bsdadminscripts. - - Obsolete shared libraries can conflict with newer - libraries, causing messages like these: - - /usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5 -/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5 - - To solve these problems, determine which port installed - the library: - - &prompt.root; pkg which /usr/local/lib/libtiff.so - /usr/local/lib/libtiff.so was installed by package tiff-3.9.4 -&prompt.root; pkg which /usr/local/lib/libXext.so - /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1 - - Then deinstall, rebuild, and reinstall the port. To - automate this process, - ports-mgmt/portmaster can be used. After - all ports are rebuilt and no longer use the old libraries, - delete the old libraries using the following command: - - &prompt.root; make delete-old-libs - - If something goes wrong, it is easy to rebuild a - particular piece of the system. For example, if - /etc/magic was accidentally deleted as - part of the upgrade or merge of /etc, - file will stop working. To fix this, - run: - - &prompt.root; cd /usr/src/usr.bin/file -&prompt.root; make all install + &prompt.root; cd /usr/src +&prompt.root; make installkernel installworld KERNCONF=STORAGESERVER - - Common Questions + + Completing the Update - - - Do I need to re-make the world for every - change? + A few final tasks complete the update. Any modified + configuration files are merged with the new versions, outdated + libraries are located and removed, then the system is + restarted. - - It depends upon the nature of the change. For - example, if svn only shows - the following files as being updated: + + Merging Configuration Files with + <application>etcupdate</application> - src/games/factor/factor.c -src/games/fortune/fortune/fortune.c -src/usr.sbin/bsdinstall/distextract/distextract.c -src/usr.sbin/bsdinstall/partedit/diskeditor.c -src/share/man/man7/intro.7 + etcupdate provides an easy + way to merge changes that have been made to system + configuration files with new versions of those files. - it probably is not worth rebuilding the entire - world. Instead, go into the appropriate sub-directories - and run make all install. But if - something major changes, such as - src/lib/libc/stdlib, a complete rebuild of - world is highly recommended. + etcupdate + - Some users rebuild world every fortnight and let - changes accumulate over that fortnight. Others only - re-make those things that have changed and are careful - to spot all the dependencies. It all depends on how - often a user wants to upgrade and whether they are - tracking &os.stable; or &os.current;. - - + + Merging Configuration Files with + <application>mergemaster</application> - - What would cause a compile to fail with lots of - signal 11 - signal 11 - - (or other signal number) errors? + mergemaster -Ui + - - This normally indicates a hardware problem. - Building world is an effective way to stress test - hardware, especially memory. A sure indicator of a - hardware issue is when make - is restarted and it dies at a different point in the - process. + + Checking for Outdated Files and Libraries - To resolve this error, swap out the components in - the machine, starting with RAM, to determine which - component is failing. - - + Some obsolete files or directories can remain after an + update. These files can be located: - - Can /usr/obj - be removed when finished? + &prompt.root; make check-old - - This directory contains all the object files that - were produced during the compilation phase. Normally, - one of the first steps in the make - buildworld process is to remove this - directory and start afresh. Keeping - /usr/obj around when finished makes - little sense, and its removal frees up a approximately - 2GB of disk space. - - + and deleted: - - Can interrupted builds be resumed? + &prompt.root; make delete-old - - This depends on how far into the process the - problem occurs. In general, make - buildworld builds new copies of essential - tools and the system libraries. These tools and - libraries are then installed, used to rebuild - themselves, and are installed again. The rest of the - system is then rebuilt with the new system - tools. + Some obsolete libraries can also remain. These can be + detected with: - During the last stage, it is fairly safe to run - these commands as they will not undo the work of the - previous make buildworld: + &prompt.root; make check-old-libs - &prompt.root; cd /usr/src -&prompt.root; make -DNO_CLEAN all + and deleted with - If this message appears: + &prompt.root; make delete-old-libs - -------------------------------------------------------------- -Building everything.. --------------------------------------------------------------- + Programs which were still using those old libraries will + stop working when the library has been deleted. These + programs must be rebuilt or replaced after deleting the old + libraries. - in the make buildworld output, - it is probably fairly safe to do so. + + When all the old files or directories are known to be + safe to delete, pressing y and + Enter to delete each file can be avoided + by setting BATCH_DELETE_OLD_FILES in + the command. For example: - If that message is not displayed, it is always - better to be safe than sorry and to restart the build - from scratch. - - + &prompt.root; make BATCH_DELETE_OLD_FILES=yes delete-old-libs + + - - Is it possible to speed up making the world? + + Restarting After the Update - - Several actions can speed up the build world - process. For example, the entire process can be run - from single-user mode. However, this will prevent users - from having access to the system until the process is - complete. + The last step after updating is to restart the computer + so all the changes take effect: - Careful file system design or the use of ZFS - datasets can make a difference. Consider putting - /usr/src and - /usr/obj on - separate file systems. If possible, place the file - systems on separate disks on separate disk controllers. - When mounting /usr/src, use - which prevents the file system - from recording the file access time. If /usr/src is not on its - own file system, consider remounting /usr with - . - - The file system holding /usr/obj can be mounted - or remounted with so that disk - writes happen asynchronously. The write completes - immediately, and the data is written to the disk a few - seconds later. This allows writes to be clustered - together, and can provide a dramatic performance - boost. - - - Keep in mind that this option makes the file - system more fragile. With this option, there is an - increased chance that, should power fail, the file - system will be in an unrecoverable state when the - machine restarts. - - If /usr/obj is the only - directory on this file system, this is not a problem. - If you have other, valuable data on the same file - system, ensure that there are verified backups before - enabling this option. - - - Turn off profiling by setting - NO_PROFILE=true in - /etc/make.conf. - - Pass - to &man.make.1; to run multiple processes in parallel. - This usually helps on both single- and multi-processor - machines. - - - - - What if something goes wrong? - - - First, make absolutely sure that the environment has - no extraneous cruft from earlier builds: - - &prompt.root; chflags -R noschg /usr/obj/usr -&prompt.root; rm -rf /usr/obj/usr -&prompt.root; cd /usr/src -&prompt.root; make cleandir -&prompt.root; make cleandir - - Yes, make cleandir really should - be run twice. - - Then, restart the whole process, starting with - make buildworld. - - If problems persist, send the error and the output - of uname -a to &a.questions;. Be - prepared to answer other questions about the - setup! - - - + &prompt.root; shutdown -r now + Tracking for Multiple Machines Mike Meyer Contributed by NFS installing multiple machines When multiple machines need to track the same source tree, it is a waste of disk space, network bandwidth, and CPU cycles to have each system download the sources and rebuild everything. The solution is to have one machine do most of the work, while the rest of the machines mount that work via NFS. This section outlines a method of doing so. For more information about using NFS, refer to . First, identify a set of machines which will run the same set of binaries, known as a build set. Each machine can have a custom kernel, but will run the same userland binaries. From that set, choose a machine to be the build machine that the world and kernel are built on. Ideally, this is a fast machine that has sufficient spare CPU to run make buildworld and make buildkernel. Select a machine to be the test machine, which will test software updates before they are put into production. This must be a machine that can afford to be down for an extended period of time. It can be the build machine, but need not be. All the machines in this build set need to mount /usr/obj and /usr/src from the build machine via NFS. For multiple build sets, /usr/src should be on one build machine, and NFS mounted on the rest. Ensure that /etc/make.conf and /etc/src.conf on all the machines in the build set agree with the build machine. That means that the build machine must build all the parts of the base system that any machine in the build set is going to install. Also, each build machine should have its kernel name set with KERNCONF in /etc/make.conf, and the build machine should list them all in its KERNCONF, listing its own kernel first. The build machine must have the kernel configuration files for each machine in its /usr/src/sys/arch/conf. On the build machine, build the kernel and world as described in , but do not install anything on the build machine. Instead, install the built kernel on the test machine. On the test machine, mount /usr/src and /usr/obj via NFS. Then, run shutdown now to go to single-user mode in order to install the new kernel and world and run mergemaster as usual. When done, reboot to return to normal multi-user operations. After verifying that everything on the test machine is working properly, use the same procedure to install the new software on each of the other machines in the build set. The same methodology can be used for the ports tree. The first step is to share /usr/ports via NFS to all the machines in the build set. To configure /etc/make.conf to share distfiles, set DISTDIR to a common shared directory that is writable by whichever user root is mapped to by the NFS mount. Each machine should set WRKDIRPREFIX to a local build directory, if ports are to be built locally. Alternately, if the build system is to build and distribute packages to the machines in the build set, set PACKAGES on the build system to a directory similar to DISTDIR.