From owner-svn-doc-all@FreeBSD.ORG Tue May 6 17:43:53 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 B8DDED59; Tue, 6 May 2014 17:43:53 +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 99537E61; Tue, 6 May 2014 17:43:53 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s46HhrU3038784; Tue, 6 May 2014 17:43:53 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s46HhrK3038783; Tue, 6 May 2014 17:43:53 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201405061743.s46HhrK3038783@svn.freebsd.org> From: Dru Lavigne Date: Tue, 6 May 2014 17:43:53 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44775 - 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.18 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: Tue, 06 May 2014 17:43:53 -0000 Author: dru Date: Tue May 6 17:43:53 2014 New Revision: 44775 URL: http://svnweb.freebsd.org/changeset/doc/44775 Log: Finish editorial review of FreeBSD Update chapter. 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 Tue May 6 16:47:12 2014 (r44774) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Tue May 6 17:43:53 2014 (r44775) @@ -334,13 +334,15 @@ Uninstalling updates... done. system. - It is a good idea to always keep a copy of the + 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 using - freebsd-update as described in - . + performing version upgrades. Refer to either or for + instructions on how to get a copy of the + GENERIC kernel. Unless the default configuration in @@ -377,7 +379,20 @@ Uninstalling updates... done. &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. The following command, when + 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 either or 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: @@ -450,8 +465,8 @@ before running "/usr/sbin/freebsd-update - The kernel and kernel modules will be patched first. At - this point, the machine must be rebooted. If the system is + 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: @@ -480,9 +495,10 @@ before running "/usr/sbin/freebsd-update Once the system has come back online, restart freebsd-update using the following - command. The state of the process has been saved and thus, + command. Since the state of the process has been saved, freebsd-update will not start from the - beginning, but will remove all old shared libraries and + beginning, but will instead move on to the next phase and + remove all old shared libraries and object files. &prompt.root; freebsd-update install @@ -495,37 +511,34 @@ before running "/usr/sbin/freebsd-update The upgrade is now complete. If this was a major version upgrade, reinstall all ports and packages as - described in . - If the system uses a custom kernel, refer to either or for - instructions on how to upgrade the custom kernel. + described in . Custom Kernels with &os; 9.X and Later - - - If a custom kernel has only been built once, the + 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 - actually the GENERIC kernel. - Rename this directory to + the GENERIC kernel. + Simply rename this directory to /boot/kernel. - - - If physical access to the machine is available, a + 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 using these - commands: + 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 - - - If the options above cannot be used, the + Alternately, the GENERIC kernel may be rebuilt and installed from source: @@ -539,33 +552,19 @@ before running "/usr/sbin/freebsd-update not have been modified in any way. It is also suggested that the kernel is built without any other special options. - - - Rebooting to the GENERIC kernel - is not required at this stage. + Rebooting into the GENERIC kernel + is not required as freebsd-update only + needs /boot/GENERIC to exist. Custom Kernels with &os; 8.X - A copy of the GENERIC kernel is - needed, and should be placed in - /boot/GENERIC. If the - GENERIC kernel is not present in the - system, it may be obtained using one of the following - methods: - - - - If a custom kernel has only been built once, the - kernel in /boot/kernel.old is - actually GENERIC. Rename this - directory to - /boot/GENERIC. - + On an &os; 8.X system, the instructions for + obtaining or building a + GENERIC kernel differ slightly. - Assuming physical access to the machine is possible, a copy of the GENERIC kernel can be installed from the installation media @@ -577,16 +576,13 @@ before running "/usr/sbin/freebsd-update Replace X.Y-RELEASE - with the actual version of the release being used. + with the version of the release being used. The GENERIC kernel will be installed in /boot/GENERIC by default. - - - Failing all the above, the - GENERIC kernel may be rebuilt and - installed from source: + To instead build the + GENERIC kernel from source: &prompt.root; cd /usr/src &prompt.root; env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null @@ -600,11 +596,9 @@ before running "/usr/sbin/freebsd-update not have been modified in any way. It is also suggested that it is built without any other special options. - - - Rebooting to the GENERIC kernel - is not required at this stage. + Rebooting into the GENERIC kernel + is not required. @@ -629,7 +623,7 @@ before running "/usr/sbin/freebsd-update screens. To prevent this behavior, and use only the default options, include in the above command. - Once this has completed, finish the upgrade process with + 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: @@ -637,43 +631,49 @@ before running "/usr/sbin/freebsd-update If the GENERIC kernel was temporarily used, this is the time to build and install a - new custom kernel in the usual way. + new custom kernel using the instructions in . - Reboot the machine into the new &os; version. The - process is complete. + Reboot the machine into the new &os; version. The upgrade + process is now complete. System State Comparison - freebsd-update can be used to test the - state of the installed &os; version against a known good copy. - This option evaluates the current version of system utilities, - libraries, and configuration files. To begin the comparison, - issue the following command: - - &prompt.root; freebsd-update IDS >> outfile.ids + 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). - While the command name is IDS it is - not a replacement for a real intrusion detection system such + 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 + 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. + USB disk device. An alternative method + for providing IDS functionality using a + built-in utility is described in - The system will now be inspected, and a lengthy listing of - files, along with the &man.sha256.1; hash values for both the + 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 - outfile.ids file. + 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 @@ -688,16 +688,13 @@ before running "/usr/sbin/freebsd-update This sample output has been truncated as many more files exist. Some files have natural modifications. For example, - /etc/passwd has been modified because - users have been added to the system. Other files, such as - kernel modules, may differ as + /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. - - This system may be used as part of an elaborate upgrade - method, aside from the previously discussed version.