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
This commit is contained in:
Warren Block 2013-01-21 23:27:12 +00:00
parent 404bf5a227
commit b8e9d58987
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=40712

View file

@ -352,15 +352,23 @@ MergeChanges /etc/ /var/named/etc/</programlisting>
</sect2> </sect2>
<sect2 id="freebsdupdate-upgrade"> <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;&nbsp;9.0 to &os;&nbsp;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;&nbsp;8.X to &os;&nbsp;9.X. Major version upgrades will remove old object files and
libraries which will break most third party applications. libraries which will break most third party applications.
It is recommended that all installed ports either be removed 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> <filename role="package">ports-mgmt/portupgrade</filename>
utility. Most users will want to run a test build using utility. A brute-force rebuild of all installed
the following command:</para> applications can be accomplished with this command:</para>
<screen>&prompt.root; <userinput>portupgrade -af</userinput></screen> <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
@ -371,81 +379,142 @@ MergeChanges /etc/ /var/named/etc/</programlisting>
any prompts during this process, removing the need for any prompts during this process, removing the need for
manual intervention during the build process.</para> manual intervention during the build process.</para>
<para>If a custom kernel is in use, the upgrade process is <sect3 id="freebsd-update-custom-kernel">
slightly more involved. A copy of the <title>Dealing with Custom Kernels</title>
<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> <para>If a custom kernel is in use, the upgrade process is
<listitem> slightly more involved, and the procedure varies depending on
<para>If a custom kernel has only been built once, the the version of &os;.</para>
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> <sect4 id="freebsd-update-custom-kernel-8x">
<para>Assuming physical access to the machine is possible, a <title>Custom Kernels with &os;&nbsp;8.X and Earlier</title>
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> <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>
&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput> &prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
&prompt.root; <userinput>./install.sh GENERIC</userinput></screen> &prompt.root; <userinput>./install.sh GENERIC</userinput></screen>
<para>Replace <filename <para>Replace <filename
class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
with the actual version of the release you are using. The with the actual version of the release you are using. The
<filename>GENERIC</filename> kernel will be installed in <filename>GENERIC</filename> kernel will be installed in
<filename class="directory">/boot/GENERIC</filename> by <filename class="directory">/boot/GENERIC</filename> by
default.</para> default.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Failing all the above, the <para>Failing all the above, the
<filename>GENERIC</filename> kernel may be rebuilt and <filename>GENERIC</filename> kernel may be rebuilt and
installed from the sources:</para> 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>env DESTDIR=/boot/GENERIC make kernel</userinput>
&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput> &prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen> &prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>
<para>For this kernel to be picked up as <para>For this kernel to be picked up as
<filename>GENERIC</filename> <filename>GENERIC</filename>
by <command>freebsd-update</command>, the by <command>freebsd-update</command>, the
<filename>GENERIC</filename> configuration file must not <filename>GENERIC</filename> configuration file must not
have been modified in any way. It is also suggested that have been modified in any way. It is also suggested that
it is built without any other special options (preferably it is built without any other special options (preferably
with an empty <filename>/etc/make.conf</filename>).</para> with an empty <filename>/etc/make.conf</filename>).</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel is <para>Rebooting to the <filename>GENERIC</filename> kernel is
not required at this stage.</para> not required at this stage.</para>
</sect4>
<para>Major and minor version updates may be performed by <sect4 id="freebsd-update-custom-kernel-9x">
providing <command>freebsd-update</command> with a release <title>Custom Kernels with &os;&nbsp;9.X and Later</title>
version target, for example, the following command will
update to &os;&nbsp;8.1:</para>
<screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen> <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>
<para>After the command has been received, <listitem>
<command>freebsd-update</command> will evaluate the <para>If physical access to the machine is available, a
configuration file and current system in an attempt to gather copy of the <literal>GENERIC</literal> kernel can be
the information necessary to update the system. A screen installed from the CD-ROM media. Load the
listing will display what components have been detected and installation disc and use these commands:</para>
what components have not been detected. For example:</para>
<screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found. <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>
<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;&nbsp;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 signature for 8.0-RELEASE from update1.FreeBSD.org... done.
Fetching metadata index... done. Fetching metadata index... done.
Inspecting system... done. Inspecting system... done.
@ -462,123 +531,128 @@ world/proflibs
Does this look reasonable (y/n)? y</screen> Does this look reasonable (y/n)? y</screen>
<para>At this point, <command>freebsd-update</command> will <para>At this point, <command>freebsd-update</command> will
attempt to download all files required for the upgrade. In attempt to download all files required for the upgrade. In
some cases, the user may be prompted with questions regarding some cases, the user may be prompted with questions regarding
what to install or how to proceed.</para> what to install or how to proceed.</para>
<para>When using a custom kernel, the above step will produce a <para>When using a custom kernel, the above step will produce a
warning similar to the following:</para> 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. kernel configuration distributed as part of FreeBSD 8.0-RELEASE.
This kernel will not be updated: you MUST update the kernel manually This kernel will not be updated: you MUST update the kernel manually
before running "/usr/sbin/freebsd-update install"</screen> before running "/usr/sbin/freebsd-update install"</screen>
<para>This warning may be safely ignored at this point. The <para>This warning may be safely ignored at this point. The
updated <filename>GENERIC</filename> kernel will be used as an updated <filename>GENERIC</filename> kernel will be used as an
intermediate step in the upgrade process.</para> intermediate step in the upgrade process.</para>
<para>After all patches have been downloaded to the local <para>After all patches have been downloaded to the local
system, they will then be applied. This process may take a system, they will then be applied. This process may take a
while depending on the speed and workload of the machine. while depending on the speed and workload of the machine.
Configuration files will then be merged&nbsp;&mdash; this part Configuration files will then be merged&nbsp;&mdash; this part
of the process requires some user intervention as a file may of the process requires some user intervention as a file may
be merged or an editor may appear on screen for a manual be merged or an editor may appear on screen for a manual
merge. The results of every successful merge will be shown to merge. The results of every successful merge will be shown to
the user as the process continues. A failed or ignored merge the user as the process continues. A failed or ignored merge
will cause the process to abort. Users may wish to make a will cause the process to abort. Users may wish to make a
backup of <filename class="directory">/etc</filename> and backup of <filename class="directory">/etc</filename> and
manually merge important files, such as manually merge important files, such as
<filename>master.passwd</filename> or <filename>master.passwd</filename> or
<filename>group</filename> at a later time.</para> <filename>group</filename> at a later time.</para>
<note> <note>
<para>The system is not being altered yet, all patching and <para>The system is not being altered yet, all patching and
merging is happening in another directory. When all merging is happening in another directory. When all
patches have been applied successfully, all configuration patches have been applied successfully, all configuration
files have been merged and it seems the process will go files have been merged and it seems the process will go
smoothly, the changes will need to be committed by the smoothly, the changes will need to be committed by the
user.</para> user.</para>
</note> </note>
<para>Once this process is complete, the upgrade may be <para>Once this process is complete, the upgrade may be
committed to disk using the following command.</para> 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 <para>The kernel and kernel modules will be patched first. At
this point the machine must be rebooted. If the system was this point the machine must be rebooted. If the system was
running with a custom kernel, use the &man.nextboot.8; command running with a custom kernel, use the &man.nextboot.8; command
to set the kernel for the next boot to to set the kernel for the next boot to
<filename class="directory">/boot/GENERIC</filename> (which <filename class="directory">/boot/GENERIC</filename> (which
was updated):</para> was updated):</para>
<screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen> <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>
<warning> <warning>
<para>Before rebooting with the <filename>GENERIC</filename> <para>Before rebooting with the <filename>GENERIC</filename>
kernel, make sure it contains all drivers required for your kernel, make sure it contains all drivers required for your
system to boot properly (and connect to the network, if the system to boot properly (and connect to the network, if the
machine that is being updated is accessed remotely). In machine that is being updated is accessed remotely). In
particular, if the previously running custom kernel particular, if the previously running custom kernel
contained built-in functionality usually provided by kernel contained built-in functionality usually provided by kernel
modules, make sure to temporarily load these modules into modules, make sure to temporarily load these modules into
the <filename>GENERIC</filename> kernel using the the <filename>GENERIC</filename> kernel using the
<filename>/boot/loader.conf</filename> facility. You may <filename>/boot/loader.conf</filename> facility. You may
also wish to disable non-essential services, disk and also wish to disable non-essential services, disk and
network mounts, etc. until the upgrade process is network mounts, etc. until the upgrade process is
complete.</para> complete.</para>
</warning> </warning>
<para>The machine should now be restarted with the updated <para>The machine should now be restarted with the updated
kernel:</para> 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, <para>Once the system has come back online,
<command>freebsd-update</command> will need to be started <command>freebsd-update</command> will need to be started
again. The state of the process has been saved and thus, again. The state of the process has been saved and thus,
<command>freebsd-update</command> will not start from the <command>freebsd-update</command> will not start from the
beginning, but will remove all old shared libraries and object beginning, but will remove all old shared libraries and object
files. To continue to this stage, issue the following files. To continue to this stage, issue the following
command:</para> command:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<note> <note>
<para>Depending on whether any libraries version numbers got <para>Depending on whether any libraries version numbers got
bumped, there may only be two install phases instead of bumped, there may only be two install phases instead of
three.</para> three.</para>
</note> </note>
</sect3>
<para>All third party software will now need to be rebuilt and <sect3 id="freebsdupdate-portsrebuild">
re-installed. This is required as installed software may <title>Rebuilding Ports After a Major Version Upgrade</title>
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> <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>
&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput> &prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput>
&prompt.root; <userinput>portupgrade -f ruby18-bdb</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>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput>
&prompt.root; <userinput>portupgrade -af</userinput></screen> &prompt.root; <userinput>portupgrade -af</userinput></screen>
<para>Once this has completed, finish the upgrade process with a <para>Once this has completed, finish the upgrade process with a
final call to <command>freebsd-update</command>. Issue the final call to <command>freebsd-update</command>. Issue the
following command to tie up all loose ends in the upgrade following command to tie up all loose ends in the upgrade
process:</para> process:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>If the <filename>GENERIC</filename> kernel was temporarily <para>If the <filename>GENERIC</filename> kernel was temporarily
used, this is the time to build and install a new custom used, this is the time to build and install a new custom
kernel in the usual way.</para> kernel in the usual way.</para>
<para>Reboot the machine into the new &os; version. The process <para>Reboot the machine into the new &os; version. The process
is complete.</para> is complete.</para>
</sect3>
</sect2> </sect2>
<sect2 id="freebsdupdate-system-comparison"> <sect2 id="freebsdupdate-system-comparison">