os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Some shuffling to remove redundancy in Upgrade Major/Minor sections.

Browse source 
Put 9.x instructions before 8.x instructions.
More commits to come.

Sponsored by:	iXsystems
This commit is contained in:
Dru Lavigne 2014-05-06 16:47:12 +00:00
parent c9ae059f33
commit 39ef70bc70
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44774
1 changed files with 139 additions and 152 deletions

291
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
View file

@ -368,154 +368,18 @@ Uninstalling updates... done.</screen>
</sect2>
<sect2 xml:id="freebsdupdate-upgrade">
<title>Major and Minor Version Upgrades</title>
<title>Performing Major and Minor Version Upgrades</title>
<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 occur when
<firstterm>minor version</firstterm> upgrades.
<firstterm>Major version</firstterm> upgrades occur when
&os; is upgraded from one major version to another, like from
&os;&nbsp;9.X to &os;&nbsp;10.X. Major versions use different
Application Binary Interfaces (<acronym>ABI</acronym>s), which
which will break most third-party
applications. After a
major version upgrade, all installed packages and
ports need to be upgraded using a utility such as
<package>ports-mgmt/portmaster</package>. A
rebuild of all installed applications can be
accomplished with this command:</para>
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
<para>This command will display the configuration screens for
each application that has configurable options and wait for the user to interact with those
screens. To prevent this behavior, and use only the default
options, include <option>-G</option> in the above command.</para>
<sect3 xml:id="freebsd-update-custom-kernel">
<title>Dealing with Custom Kernels</title>
<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 xml:id="freebsd-update-custom-kernel-8x">
<title>Custom Kernels with &os;&nbsp;8.X</title>
<para>A copy of the <filename>GENERIC</filename> kernel is
needed, and should be placed in
<filename>/boot/GENERIC</filename>. If the
<filename>GENERIC</filename> kernel is not 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>/boot/kernel.old</filename> is
actually <filename>GENERIC</filename>. Rename this
directory to
<filename>/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 installation media
using 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>./install.sh GENERIC</userinput></screen>
<para>Replace <filename
class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
with the actual version of the release being used.
The <filename>GENERIC</filename> kernel will be
installed in <filename>/boot/GENERIC</filename> by
default.</para>
</listitem>
<listitem>
<para>Failing all the above, the
<filename>GENERIC</filename> kernel may be rebuilt and
installed from source:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</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.</para>
</listitem>
</itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel
is not required at this stage.</para>
</sect4>
<sect4 xml:id="freebsd-update-custom-kernel-9x">
<title>Custom Kernels with &os;&nbsp;9.X and Later</title>
<itemizedlist>
<listitem>
<para>If a custom kernel has only been built once, the
kernel in <filename>/boot/kernel.old</filename> is
actually the <literal>GENERIC</literal> kernel.
Rename this directory to
<filename>/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 installation media using 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 source:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</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.</para>
</listitem>
</itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel
is not required at this stage.</para>
</sect4>
</sect3>
<sect3 xml: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. The following command will update to
&os;&nbsp;9.1:</para>
&os;&nbsp;9.X to &os;&nbsp;10.X. Both types of upgrades can
be performed by providing <command>freebsd-update</command>
with a release version target. The following command, when
run on a &os;&nbsp;9.0 system, will upgrade it to
&os;&nbsp;9.1:</para>
<screen>&prompt.root; <userinput>freebsd-update -r 9.1-RELEASE upgrade</userinput></screen>
@ -541,7 +405,7 @@ The following components of FreeBSD do not seem to be installed:
kernel/generic world/catpages world/dict world/doc world/games
world/proflibs
Does this look reasonable (y/n)? y</screen>
Does this look reasonable (y/n)? <userinput>y</userinput></screen>
<para>At this point, <command>freebsd-update</command> will
attempt to download all files required for the upgrade. In
@ -628,19 +492,142 @@ before running "/usr/sbin/freebsd-update install"</screen>
were bumped, there may only be two install phases instead
of three.</para>
</note>
<para>The upgrade is now complete. If this was a major
version upgrade, reinstall all ports and packages as
described in <xref linkend="freebsdupdate-portsrebuild"/>.
If the system uses a custom kernel, refer to either <xref
linkend="freebsd-update-custom-kernel-9x"/> or <xref
linkend="freebsd-update-custom-kernel-8x"/> for
instructions on how to upgrade the custom kernel.</para>
<sect3 xml:id="freebsd-update-custom-kernel-9x">
<title>Custom Kernels with &os;&nbsp;9.X and Later</title>
<itemizedlist>
<listitem>
<para>If a custom kernel has only been built once, the
kernel in <filename>/boot/kernel.old</filename> is
actually the <literal>GENERIC</literal> kernel.
Rename this directory to
<filename>/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 installation media using 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 source:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</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.</para>
</listitem>
</itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel
is not required at this stage.</para>
</sect3>
<sect3 xml:id="freebsd-update-custom-kernel-8x">
<title>Custom Kernels with &os;&nbsp;8.X</title>
<para>A copy of the <filename>GENERIC</filename> kernel is
needed, and should be placed in
<filename>/boot/GENERIC</filename>. If the
<filename>GENERIC</filename> kernel is not 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>/boot/kernel.old</filename> is
actually <filename>GENERIC</filename>. Rename this
directory to
<filename>/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 installation media
using 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>./install.sh GENERIC</userinput></screen>
<para>Replace <filename
class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
with the actual version of the release being used.
The <filename>GENERIC</filename> kernel will be
installed in <filename>/boot/GENERIC</filename> by
default.</para>
</listitem>
<listitem>
<para>Failing all the above, the
<filename>GENERIC</filename> kernel may be rebuilt and
installed from source:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</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.</para>
</listitem>
</itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel
is not required at this stage.</para>
</sect3>
<sect3 xml:id="freebsdupdate-portsrebuild">
<title>Rebuilding Ports After a Major Version Upgrade</title>
<para>After a major version upgrade, all third party software
needs to be rebuilt and re-installed. This is required as
installed software may depend on libraries which have been
removed during the upgrade process. This process can be
automated using
<package>ports-mgmt/portmaster</package>:</para>
<para>Generally,
installed applications will continue to work without problems
after minor version upgrades. Major versions use different
Application Binary Interfaces (<acronym>ABI</acronym>s), which
which will break most third-party
applications. After a
major version upgrade, all installed packages and
ports need to be upgraded using a utility such as
<package>ports-mgmt/portmaster</package>. A
rebuild of all installed applications can be
accomplished with this command:</para>
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
<para>This command will display the configuration screens for
each application that has configurable options and wait for the user to interact with those
screens. To prevent this behavior, and use only the default
options, include <option>-G</option> in the above command.</para>
<para>Once this has completed, finish the upgrade process with
a final call to <command>freebsd-update</command> in order