Date: Mon, 21 Jan 2013 23:27:12 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201301212327.r0LNRCgb002421@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <gkontos.mail@gmail.com> 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/</prog </sect2> <sect2 id="freebsdupdate-upgrade"> - <title>Major and Minor Upgrades</title> + <title>Major and Minor Version Upgrades</title> - <para>This process will remove old object files and + <para>Upgrades from one minor version of &os; to another, like + from &os; 9.0 to &os; 9.1, are called + <emphasis>minor version</emphasis> upgrades. Generally, + installed applications will continue to work without problems + after minor version upgrades.</para> + + <para><emphasis>Major version</emphasis> 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 <filename role="package">ports-mgmt/portupgrade</filename> - utility. Most users will want to run a test build using - the following command:</para> + utility. A brute-force rebuild of all installed + applications can be accomplished with this command:</para> <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen> @@ -371,81 +379,142 @@ MergeChanges /etc/ /var/named/etc/</prog any prompts during this process, removing the need for manual intervention during the build process.</para> - <para>If a custom kernel is in use, the upgrade process is - slightly more involved. A copy of the - <filename>GENERIC</filename> kernel is needed, and it should - be placed in - <filename class="directory">/boot/GENERIC</filename>. If the - <filename>GENERIC</filename> kernel is not already present in - the system, it may be obtained using one of the following - methods:</para> + <sect3 id="freebsd-update-custom-kernel"> + <title>Dealing with Custom Kernels</title> - <itemizedlist> - <listitem> - <para>If a custom kernel has only been built once, the - kernel in - <filename class="directory">/boot/kernel.old</filename> is - actually the <filename>GENERIC</filename> one. Simply - rename this directory to <filename - class="directory">/boot/GENERIC</filename>.</para> - </listitem> - - <listitem> - <para>Assuming physical access to the machine is possible, a - copy of the <filename>GENERIC</filename> kernel can be - installed from the CD-ROM media. Insert your installation - disc and use the following commands:</para> + <para>If a custom kernel is in use, the upgrade process is + slightly more involved, and the procedure varies depending on + the version of &os;.</para> + + <sect4 id="freebsd-update-custom-kernel-8x"> + <title>Custom Kernels with &os; 8.X and Earlier</title> + + <para>A copy of the + <filename>GENERIC</filename> kernel is needed, and it should + be placed in + <filename class="directory">/boot/GENERIC</filename>. If the + <filename>GENERIC</filename> kernel is not already present in + the system, it may be obtained using one of the following + methods:</para> + + <itemizedlist> + <listitem> + <para>If a custom kernel has only been built once, the + kernel in + <filename class="directory">/boot/kernel.old</filename> is + actually the <filename>GENERIC</filename> one. Simply + rename this directory to <filename + class="directory">/boot/GENERIC</filename>.</para> + </listitem> + + <listitem> + <para>Assuming physical access to the machine is possible, a + copy of the <filename>GENERIC</filename> kernel can be + installed from the CD-ROM media. Insert your installation + disc and use the following commands:</para> - <screen>&prompt.root; <userinput>mount /cdrom</userinput> + <screen>&prompt.root; <userinput>mount /cdrom</userinput> &prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput> &prompt.root; <userinput>./install.sh GENERIC</userinput></screen> - <para>Replace <filename - class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> - with the actual version of the release you are using. The - <filename>GENERIC</filename> kernel will be installed in - <filename class="directory">/boot/GENERIC</filename> by - default.</para> - </listitem> - - <listitem> - <para>Failing all the above, the - <filename>GENERIC</filename> kernel may be rebuilt and - installed from the sources:</para> + <para>Replace <filename + class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> + with the actual version of the release you are using. The + <filename>GENERIC</filename> kernel will be installed in + <filename class="directory">/boot/GENERIC</filename> by + default.</para> + </listitem> + + <listitem> + <para>Failing all the above, the + <filename>GENERIC</filename> kernel may be rebuilt and + installed from the sources:</para> - <screen>&prompt.root; <userinput>cd /usr/src</userinput> + <screen>&prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel</userinput> &prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput> &prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen> - <para>For this kernel to be picked up as - <filename>GENERIC</filename> - by <command>freebsd-update</command>, the - <filename>GENERIC</filename> 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 <filename>/etc/make.conf</filename>).</para> - </listitem> - </itemizedlist> + <para>For this kernel to be picked up as + <filename>GENERIC</filename> + by <command>freebsd-update</command>, the + <filename>GENERIC</filename> 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 <filename>/etc/make.conf</filename>).</para> + </listitem> + </itemizedlist> + + <para>Rebooting to the <filename>GENERIC</filename> kernel is + not required at this stage.</para> + </sect4> - <para>Rebooting to the <filename>GENERIC</filename> kernel is - not required at this stage.</para> + <sect4 id="freebsd-update-custom-kernel-9x"> + <title>Custom Kernels with &os; 9.X and Later</title> - <para>Major and minor version updates may be performed by - providing <command>freebsd-update</command> with a release - version target, for example, the following command will - update to &os; 8.1:</para> - - <screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen> - - <para>After the command has been received, - <command>freebsd-update</command> 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:</para> + <itemizedlist> + <listitem> + <para>If a custom kernel has only been built once, the + kernel in + <filename class="directory">/boot/kernel.old</filename> + is actually the <literal>GENERIC</literal> kernel. + Rename this directory to <filename + class="directory">/boot/kernel</filename>.</para> + </listitem> + + <listitem> + <para>If physical access to the machine is available, a + copy of the <literal>GENERIC</literal> kernel can be + installed from the CD-ROM media. Load the + installation disc and use these commands:</para> + + <screen>&prompt.root; <userinput>mount /cdrom</userinput> +&prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput> +&prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen> + </listitem> + + <listitem> + <para>If the options above cannot be used, the + <literal>GENERIC</literal> kernel may be rebuilt and + installed from the sources:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make kernel</userinput></screen> + + <para>For this kernel to be identified as the + <literal>GENERIC</literal> kernel by + <command>freebsd-update</command>, the + <filename>GENERIC</filename> 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 + <filename>/etc/make.conf</filename>.</para> + </listitem> + </itemizedlist> - <screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found. + <para>Rebooting to the <filename>GENERIC</filename> kernel is + not required at this stage.</para> + </sect4> + </sect3> + + <sect3 id="freebsdupdate-using"> + <title>Performing the Upgrade</title> + + <para>Major and minor version upgrades may be performed by + providing <command>freebsd-update</command> with a release + version target, for example, the following command will + update to &os; 8.1:</para> + + <screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen> + + <para>After the command has been received, + <command>freebsd-update</command> 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:</para> + + <screen>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</screen> - <para>At this point, <command>freebsd-update</command> 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.</para> + <para>At this point, <command>freebsd-update</command> 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.</para> - <para>When using a custom kernel, the above step will produce a - warning similar to the following:</para> + <para>When using a custom kernel, the above step will produce a + warning similar to the following:</para> - <screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a + <screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" 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"</screen> - <para>This warning may be safely ignored at this point. The - updated <filename>GENERIC</filename> kernel will be used as an - intermediate step in the upgrade process.</para> - - <para>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 <filename class="directory">/etc</filename> and - manually merge important files, such as - <filename>master.passwd</filename> or - <filename>group</filename> at a later time.</para> + <para>This warning may be safely ignored at this point. The + updated <filename>GENERIC</filename> kernel will be used as an + intermediate step in the upgrade process.</para> + + <para>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 <filename class="directory">/etc</filename> and + manually merge important files, such as + <filename>master.passwd</filename> or + <filename>group</filename> at a later time.</para> - <note> - <para>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.</para> - </note> + <note> + <para>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.</para> + </note> - <para>Once this process is complete, the upgrade may be - committed to disk using the following command.</para> + <para>Once this process is complete, the upgrade may be + committed to disk using the following command.</para> - <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> + <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> - <para>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 - <filename class="directory">/boot/GENERIC</filename> (which - was updated):</para> + <para>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 + <filename class="directory">/boot/GENERIC</filename> (which + was updated):</para> - <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen> + <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen> - <warning> - <para>Before rebooting with the <filename>GENERIC</filename> - 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 <filename>GENERIC</filename> kernel using the - <filename>/boot/loader.conf</filename> facility. You may - also wish to disable non-essential services, disk and - network mounts, etc. until the upgrade process is - complete.</para> - </warning> + <warning> + <para>Before rebooting with the <filename>GENERIC</filename> + 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 <filename>GENERIC</filename> kernel using the + <filename>/boot/loader.conf</filename> facility. You may + also wish to disable non-essential services, disk and + network mounts, etc. until the upgrade process is + complete.</para> + </warning> - <para>The machine should now be restarted with the updated - kernel:</para> + <para>The machine should now be restarted with the updated + kernel:</para> - <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> + <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> - <para>Once the system has come back online, - <command>freebsd-update</command> will need to be started - again. The state of the process has been saved and thus, - <command>freebsd-update</command> 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:</para> + <para>Once the system has come back online, + <command>freebsd-update</command> will need to be started + again. The state of the process has been saved and thus, + <command>freebsd-update</command> 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:</para> - <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> + <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> - <note> - <para>Depending on whether any libraries version numbers got - bumped, there may only be two install phases instead of - three.</para> - </note> + <note> + <para>Depending on whether any libraries version numbers got + bumped, there may only be two install phases instead of + three.</para> + </note> + </sect3> - <para>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 - <filename role="package">ports-mgmt/portupgrade</filename> - command may be used to automate this process. The following - commands may be used to begin this process:</para> + <sect3 id="freebsdupdate-portsrebuild"> + <title>Rebuilding Ports After a Major Version Upgrade</title> + + <para>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 + <filename role="package">ports-mgmt/portupgrade</filename> + command may be used to automate this process. The following + commands may be used to begin this process:</para> - <screen>&prompt.root; <userinput>portupgrade -f ruby</userinput> + <screen>&prompt.root; <userinput>portupgrade -f ruby</userinput> &prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput> &prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput> &prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput> &prompt.root; <userinput>portupgrade -af</userinput></screen> - <para>Once this has completed, finish the upgrade process with a - final call to <command>freebsd-update</command>. Issue the - following command to tie up all loose ends in the upgrade - process:</para> - - <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> - - <para>If the <filename>GENERIC</filename> kernel was temporarily - used, this is the time to build and install a new custom - kernel in the usual way.</para> + <para>Once this has completed, finish the upgrade process with a + final call to <command>freebsd-update</command>. Issue the + following command to tie up all loose ends in the upgrade + process:</para> + + <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> + + <para>If the <filename>GENERIC</filename> kernel was temporarily + used, this is the time to build and install a new custom + kernel in the usual way.</para> - <para>Reboot the machine into the new &os; version. The process - is complete.</para> + <para>Reboot the machine into the new &os; version. The process + is complete.</para> + </sect3> </sect2> <sect2 id="freebsdupdate-system-comparison">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201301212327.r0LNRCgb002421>