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
parent
404bf5a227
commit
b8e9d58987
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=40712
1 changed files with 226 additions and 152 deletions
|
|
@ -352,15 +352,23 @@ MergeChanges /etc/ /var/named/etc/</programlisting>
|
|||
</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/</programlisting>
|
|||
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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<sect4 id="freebsd-update-custom-kernel-8x">
|
||||
<title>Custom Kernels with &os; 8.X and Earlier</title>
|
||||
|
||||
<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>./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>
|
||||
<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>
|
||||
<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>
|
||||
<para>Rebooting to the <filename>GENERIC</filename> kernel is
|
||||
not required at this stage.</para>
|
||||
</sect4>
|
||||
|
||||
<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>
|
||||
<sect4 id="freebsd-update-custom-kernel-9x">
|
||||
<title>Custom Kernels with &os; 9.X and Later</title>
|
||||
|
||||
<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,
|
||||
<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>
|
||||
<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>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; 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>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>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>
|
||||
|
||||
<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>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>
|
||||
<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>
|
||||
<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>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">
|
||||
|
|
|
|||
Loading…
Reference in a new issue