From owner-svn-doc-all@FreeBSD.ORG Thu May 1 18:12:23 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 21A4A8A8; Thu, 1 May 2014 18:12:23 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 0D7201A7A; Thu, 1 May 2014 18:12:23 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s41ICMU4078662; Thu, 1 May 2014 18:12:22 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s41ICMa0078661; Thu, 1 May 2014 18:12:22 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201405011812.s41ICMa0078661@svn.freebsd.org> From: Dru Lavigne Date: Thu, 1 May 2014 18:12:22 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44733 - head/en_US.ISO8859-1/books/handbook/cutting-edge X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 May 2014 18:12:23 -0000 Author: dru Date: Thu May 1 18:12:22 2014 New Revision: 44733 URL: http://svnweb.freebsd.org/changeset/doc/44733 Log: Begin to incorporate repeated info within the Rebuilding World chapter. Fix some xrefs. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu May 1 17:21:49 2014 (r44732) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu May 1 18:12:22 2014 (r44733) @@ -1109,7 +1109,7 @@ before running "/usr/sbin/freebsd-update compiling , read /usr/src/Makefile very carefully and follow the instructions in - Rebuilding "world". + . Read the &a.current; and /usr/src/UPDATING to stay up-to-date on other bootstrapping procedures that @@ -1216,8 +1216,8 @@ before running "/usr/sbin/freebsd-update -STABLE compiling , read /usr/src/Makefile - carefully and follow the instructions in Rebuilding "world". Read + 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 @@ -1290,7 +1290,7 @@ before running "/usr/sbin/freebsd-update - Rebuilding <quote>world</quote> + Rebuilding World Rebuilding world @@ -1333,12 +1333,12 @@ before running "/usr/sbin/freebsd-update Read /usr/src/UPDATING for any - pre-buildworld steps necessary for that version of the + 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 - installworld. These will be listed at the end of this file + 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 @@ -1430,20 +1430,32 @@ before running "/usr/sbin/freebsd-update Use the new compiler residing in /usr/obj to build the new kernel, in order to protect against compiler-kernel - mismatches: + 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. &prompt.root; make buildkernel Install the new kernel and kernel modules, making it - possible to boot with the newly updated kernel: + possible to boot with the newly updated kernel. If + kern.securelevel has been raised above + 1 and + noschg or 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. &prompt.root; make installkernel - Drop the system into single user mode in order to + 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. @@ -1475,7 +1487,11 @@ before running "/usr/sbin/freebsd-update - Next, perform some initial configuration file updates + 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 @@ -1485,13 +1501,14 @@ before running "/usr/sbin/freebsd-update last update. This is necessary so that the installworld step will be able to use any new system accounts, groups, and - scripts. + scripts. Refer to for more + detailed instructions about this command: &prompt.root; mergemaster -p - Install the new world from Install the new world and system binaries from /usr/obj. &prompt.root; cd /usr/src @@ -1532,9 +1549,9 @@ before running "/usr/sbin/freebsd-update single-user mode If the system can have a window of down-time, consider - compiling the system in single user mode instead of compiling + 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 + 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 @@ -1548,20 +1565,18 @@ before running "/usr/sbin/freebsd-update make.conf - This section describes the configuration files used by the - build world process. + This build world process uses several configuration + files. - The options available to &man.make.1; are described in + 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 way &man.make.1; runs and how it builds - programs. Such options take effect every time &man.make.1; is + 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 + 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. @@ -1676,7 +1691,7 @@ Script done, … buildworld can be run on a machine running in multi-user mode with no fear of ill-effects. It is still recommended that installworld - be run in part in single user mode, though. + be run in part in single-user mode, though. Secondly, it allows NFS mounts to be used to upgrade multiple machines on a network. If order to upgrade three @@ -1728,69 +1743,6 @@ Script done, … &os.stable; tree, with no tricks or shortcuts used during the process. A &os.current; tree will take somewhat longer. - - - - Compile and Install a New Kernel - - - kernel - compiling - - - To take full advantage of the new system, recompile the - kernel. This is practically a necessity, as certain memory - structures may have changed, and programs like &man.ps.1; and - &man.top.1; will fail to work until the kernel and source code - versions are the same. - - The simplest, safest way to do this is to build and - install a kernel based on GENERIC. While - GENERIC may not have all the necessary - devices for the system, it should contain everything necessary - to boot the system back to single user mode. This is a good - test that the new system works properly. After booting from - GENERIC and verifying that the system - works, a new kernel can be built based on a custom kernel - configuration file. - - On &os; it is important to - build world before - building a new kernel. - - - To build a custom kernel with an existing customized - configuration file, use - KERNCONF=MYKERNEL: - - &prompt.root; cd /usr/src -&prompt.root; make buildkernel KERNCONF=MYKERNEL -&prompt.root; make installkernel KERNCONF=MYKERNEL - - - - If kern.securelevel has been raised - above 1 and noschg or - similar flags have been set on the kernel binary, drop into - single user mode to use - installkernel. Otherwise, both - these commands 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. - - Reboot into single user mode to test that the new kernel - works. - - - - Install the New System Binaries - - Next, use installworld to - install the new system binaries: - - &prompt.root; cd /usr/src -&prompt.root; make installworld If variables were specified to @@ -1813,24 +1765,9 @@ Script done, … - - Update Files Not Updated by - <command>make installworld</command> - - Remaking the world will not update certain directories, - such as /etc, - /var and - /usr, with - new or changed configuration files. - - The simplest way to update the files in these directories - is to use &man.mergemaster.8;. Be sure to first make a backup - of /etc in case anything goes - wrong. - - + - <command>mergemaster</command> + Merging Configuration Files @@ -1909,10 +1846,6 @@ Script done, … it will prompt for other options. &man.mergemaster.8; may prompt to rebuild the password file and will finish up with an option to remove left-over temporary files. - - - - Manual Update To perform the update manually instead, do not just copy over the files from @@ -2066,7 +1999,6 @@ Script done, … &prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"` -