From owner-svn-doc-all@FreeBSD.ORG Mon Jan 21 23:27:12 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id C6E0D848; Mon, 21 Jan 2013 23:27:12 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id A298A31D; Mon, 21 Jan 2013 23:27:12 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.5/8.14.5) with ESMTP id r0LNRCgJ002422; Mon, 21 Jan 2013 23:27:12 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.5/8.14.5/Submit) id r0LNRCgb002421; Mon, 21 Jan 2013 23:27:12 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201301212327.r0LNRCgb002421@svn.freebsd.org> From: Warren Block Date: Mon, 21 Jan 2013 23:27:12 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40712 - 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.14 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: Mon, 21 Jan 2013 23:27:12 -0000 Author: wblock Date: Mon Jan 21 23:27:12 2013 New Revision: 40712 URL: http://svnweb.freebsd.org/changeset/doc/40712 Log: Update the freebsd-update section: Define minor and major version upgrades at the start of the section. Mention that installed applications will still run after a minor upgrade. Split the custom kernel portion into 8.X and earlier and 9.X and later. Make the portupgrade instructions specific to major version upgrades. PR: www/175069 Submitted by: George Kontostanos Reviewed by: freebsd-doc mailing list 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 Mon Jan 21 17:45:18 2013 (r40711) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Mon Jan 21 23:27:12 2013 (r40712) @@ -352,15 +352,23 @@ MergeChanges /etc/ /var/named/etc/ - Major and Minor Upgrades + Major and Minor Version Upgrades - This process will remove old object files and + Upgrades from one minor version of &os; to another, like + from &os; 9.0 to &os; 9.1, are called + minor version upgrades. Generally, + installed applications will continue to work without problems + after minor version upgrades. + + Major version upgrades are when &os; + is upgraded from one major version to another, like from + &os; 8.X to &os; 9.X. Major version upgrades will remove old object files and libraries which will break most third party applications. It is recommended that all installed ports either be removed - and re-installed or upgraded later using the + and re-installed or upgraded after a major version upgrade by using the ports-mgmt/portupgrade - utility. Most users will want to run a test build using - the following command: + utility. A brute-force rebuild of all installed + applications can be accomplished with this command: &prompt.root; portupgrade -af @@ -371,81 +379,142 @@ MergeChanges /etc/ /var/named/etc/ - If a custom kernel is in use, the upgrade process is - slightly more involved. A copy of the - GENERIC kernel is needed, and it should - be placed in - /boot/GENERIC. If the - GENERIC kernel is not already present in - the system, it may be obtained using one of the following - methods: + + Dealing with Custom Kernels - - - If a custom kernel has only been built once, the - kernel in - /boot/kernel.old is - actually the GENERIC one. Simply - rename this directory to /boot/GENERIC. - - - - Assuming physical access to the machine is possible, a - copy of the GENERIC kernel can be - installed from the CD-ROM media. Insert your installation - disc and use the following commands: + If a custom kernel is in use, the upgrade process is + slightly more involved, and the procedure varies depending on + the version of &os;. + + + Custom Kernels with &os; 8.X and Earlier + + A copy of the + GENERIC kernel is needed, and it should + be placed in + /boot/GENERIC. If the + GENERIC kernel is not already 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 the GENERIC one. Simply + rename this directory to /boot/GENERIC. + + + + Assuming physical access to the machine is possible, a + copy of the GENERIC kernel can be + installed from the CD-ROM media. Insert your installation + disc and use the following commands: - &prompt.root; mount /cdrom + &prompt.root; mount /cdrom &prompt.root; cd /cdrom/X.Y-RELEASE/kernels &prompt.root; ./install.sh GENERIC - Replace X.Y-RELEASE - with the actual version of the release you are using. The - GENERIC kernel will be installed in - /boot/GENERIC by - default. - - - - Failing all the above, the - GENERIC kernel may be rebuilt and - installed from the sources: + Replace X.Y-RELEASE + with the actual version of the release you are using. The + GENERIC kernel will be installed in + /boot/GENERIC by + default. + + + + Failing all the above, the + GENERIC kernel may be rebuilt and + installed from the sources: - &prompt.root; cd /usr/src + &prompt.root; cd /usr/src &prompt.root; env DESTDIR=/boot/GENERIC make kernel &prompt.root; mv /boot/GENERIC/boot/kernel/* /boot/GENERIC &prompt.root; rm -rf /boot/GENERIC/boot - For this kernel to be picked up as - GENERIC - by freebsd-update, the - GENERIC configuration file must not - have been modified in any way. It is also suggested that - it is built without any other special options (preferably - with an empty /etc/make.conf). - - + For this kernel to be picked up as + GENERIC + by freebsd-update, the + GENERIC configuration file must not + have been modified in any way. It is also suggested that + it is built without any other special options (preferably + with an empty /etc/make.conf). + + + + Rebooting to the GENERIC kernel is + not required at this stage. + - Rebooting to the GENERIC kernel is - not required at this stage. + + Custom Kernels with &os; 9.X and Later - Major and minor version updates may be performed by - providing freebsd-update with a release - version target, for example, the following command will - update to &os; 8.1: - - &prompt.root; freebsd-update -r 8.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 update the system. A screen - listing will display what components have been detected and - what components have not been detected. For example: + + + If a custom kernel has only been built once, the + kernel in + /boot/kernel.old + is actually the GENERIC kernel. + Rename this directory to /boot/kernel. + + + + If physical access to the machine is available, a + copy of the GENERIC kernel can be + installed from the CD-ROM media. Load the + installation disc and use these commands: + + &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 + GENERIC kernel may be rebuilt and + installed from the sources: + + &prompt.root; cd /usr/src +&prompt.root; make kernel + + 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, preferably with an empty + /etc/make.conf. + + - Looking up update.FreeBSD.org mirrors... 1 mirrors found. + Rebooting to the GENERIC kernel is + not required at this stage. + + + + + Performing the Upgrade + + Major and minor version upgrades may be performed by + providing freebsd-update with a release + version target, for example, the following command will + update to &os; 8.1: + + &prompt.root; freebsd-update -r 8.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 update the system. A screen + listing will display what components have been detected and + what components have not been detected. For example: + + Looking up update.FreeBSD.org mirrors... 1 mirrors found. Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. @@ -462,123 +531,128 @@ 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. + 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: + 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 + WARNING: This system is running a "MYKERNEL" kernel, which is not a kernel configuration distributed as part of FreeBSD 8.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. - - After all patches have been downloaded to the local - system, they will then be applied. This process may take a - while depending on the speed and workload of the machine. - Configuration files will then be merged — this part - of the 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. + This warning may be safely ignored at this point. The + updated GENERIC kernel will be used as an + intermediate step in the upgrade process. + + After all patches have been downloaded to the local + system, they will then be applied. This process may take a + while depending on the speed and workload of the machine. + Configuration files will then be merged — this part + of the 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, all patching and - merging is happening in another directory. When all - patches have been applied successfully, all configuration - files have been merged and it seems the process will go - smoothly, the changes will need to be committed by the - user. - + + The system is not being altered yet, all patching and + merging is happening in another directory. When all + patches have been applied successfully, all configuration + files have been merged and it seems the process will go + smoothly, the changes will need to be committed by the + user. + - Once this process is complete, the upgrade may be - committed to disk using the following command. + Once this process is complete, the upgrade may be + committed to disk using the following command. - &prompt.root; freebsd-update install + &prompt.root; freebsd-update install - The kernel and kernel modules will be patched first. At - this point the machine must be rebooted. If the system was - running with a custom kernel, use the &man.nextboot.8; command - to set the kernel for the next boot to - /boot/GENERIC (which - was updated): + The kernel and kernel modules will be patched first. At + this point the machine must be rebooted. If the system was + running with a custom kernel, use the &man.nextboot.8; command + to set the kernel for the next boot to + /boot/GENERIC (which + was updated): - &prompt.root; nextboot -k GENERIC + &prompt.root; nextboot -k GENERIC - - Before rebooting with the GENERIC - kernel, make sure it contains all drivers required for your - system to boot properly (and connect to the network, if the - machine that is being updated is accessed remotely). In - particular, if the previously running custom kernel - contained 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. You may - also wish to disable non-essential services, disk and - network mounts, etc. until the upgrade process is - complete. - + + Before rebooting with the GENERIC + kernel, make sure it contains all drivers required for your + system to boot properly (and connect to the network, if the + machine that is being updated is accessed remotely). In + particular, if the previously running custom kernel + contained 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. You may + also wish to disable non-essential services, disk and + network mounts, etc. until the upgrade process is + complete. + - The machine should now be restarted with the updated - kernel: + The machine should now be restarted with the updated + kernel: - &prompt.root; shutdown -r now + &prompt.root; shutdown -r now - Once the system has come back online, - freebsd-update will need to be started - again. The state of the process has been saved and thus, - freebsd-update will not start from the - beginning, but will remove all old shared libraries and object - files. To continue to this stage, issue the following - command: + Once the system has come back online, + freebsd-update will need to be started + again. The state of the process has been saved and thus, + freebsd-update will not start from the + beginning, but will remove all old shared libraries and object + files. To continue to this stage, issue the following + command: - &prompt.root; freebsd-update install + &prompt.root; freebsd-update install - - Depending on whether any libraries version numbers got - bumped, there may only be two install phases instead of - three. - + + Depending on whether any libraries version numbers got + bumped, there may only be two install phases instead of + three. + + - All third party software will now need to be rebuilt and - re-installed. This is required as installed software may - depend on libraries which have been removed during the upgrade - process. The - ports-mgmt/portupgrade - command may be used to automate this process. The following - commands may be used to begin this process: + + Rebuilding Ports After a Major Version Upgrade + + After a major version upgrade, all third party software will now need to be rebuilt and + re-installed. This is required as installed software may + depend on libraries which have been removed during the upgrade + process. The + ports-mgmt/portupgrade + command may be used to automate this process. The following + commands may be used to begin this process: - &prompt.root; portupgrade -f ruby + &prompt.root; portupgrade -f ruby &prompt.root; rm /var/db/pkg/pkgdb.db &prompt.root; portupgrade -f ruby18-bdb &prompt.root; rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db &prompt.root; portupgrade -af - Once this has completed, finish the upgrade process with a - final call to freebsd-update. Issue the - following command to tie up all 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 in the usual way. + Once this has completed, finish the upgrade process with a + final call to freebsd-update. Issue the + following command to tie up all 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 in the usual way. - Reboot the machine into the new &os; version. The process - is complete. + Reboot the machine into the new &os; version. The process + is complete. +