freebsd-update and ports
Warren Block
wblock at wonkity.com
Sun Jan 13 21:44:24 UTC 2013
On Sun, 13 Jan 2013, Simon L. B. Nielsen wrote:
> On 13 Jan 2013 05:24, "Warren Block" <wblock at wonkity.com> wrote:
> >
> > Looking for some feedback from someone more familiar with freebsd-update(8) and ports.
> >
> > Define minor and major version upgrades at the start of the section.
>
> In the text you call it minor and major upgrades. I think that is misleading and should be written out as major version upgrades and minor version upgrades, as a minor version upgrade
> can still begin problematic and a major version upgrade can be a small thing.
That was the section title originally, but agreed.
> > Say that installed applications will generally still run after a minor
> > upgrade.
>
> I would say there is a bug if it doesn't work, but of course its always a risk and there are special cases...
> > - <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
> > + <para><emphasis>Major</emphasis> upgrades are when &os is
>
> Missing ; on entity.
Doh. Entity checking is even on the list of things that igor should do
but does not.
> > + <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>
>
> This is only correct for FreeBSD 8 and older. For 9..0 onwards other is a tgz in /usr/freebsd-dist .
Fixing that involved rewriting that section. I have done that, but this
has gone from minor patch to big update. The new section on 9.X and
higher GENERIC kernel has literal tags on GENERIC, because it's not a
directory any more. Except when GENERIC refers to the kernel config,
when it is a file. The procedure needs to be verified, and maybe
there's a simpler or better way to copy the kernel file.
The two custom kernel sections meant new sect3 and sect4 sections, and
consequent indentation changes to a bunch of the rest of this.
That said, it's better than it was.
Index: cutting-edge/chapter.xml
===================================================================
--- cutting-edge/chapter.xml (revision 40616)
+++ cutting-edge/chapter.xml (working copy)
@@ -352,15 +352,23 @@
</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 @@
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 @@
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">
-------------- next part --------------
Index: cutting-edge/chapter.xml
===================================================================
--- cutting-edge/chapter.xml (revision 40616)
+++ cutting-edge/chapter.xml (working copy)
@@ -352,15 +352,23 @@
</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 @@
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 @@
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">
More information about the freebsd-doc
mailing list