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

Merge the Updating chapter into the Cutting Edge chapter, and rename the

Browse source 
new chapter "Updating and Upgrading FreeBSD."

Update other chapters to reference the new chapter name.

While here, add Audit chapter to the preface section.

Reviewed by:    murray, manolis, remko, pgj, -doc
This commit is contained in:
Tom Rhodes 2008-12-23 18:48:22 +00:00
parent 20e5c24c3d
commit 71682c57b3
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=33507
5 changed files with 506 additions and 22 deletions
en_US.ISO8859-1/books/handbook
cutting-edge
chapter.sgml
dtrace
chapter.sgml
kernelconfig
chapter.sgml
preface
preface.sgml
serialcomms
chapter.sgml

505
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml
View file

@ -4,7 +4,7 @@
$FreeBSD$
-->
<chapter id="cutting-edge">
<chapter id="updating-upgrading">
<chapterinfo>
<authorgroup>
<author>
@ -40,34 +40,49 @@
<!-- with feedback from various others -->
</chapterinfo>
<title>The Cutting Edge</title>
<title>Updating and Upgrading &os;</title>
<sect1 id="cutting-edge-synopsis">
<sect1 id="updating-upgrading-synopsis">
<title>Synopsis</title>
<para>&os; is under constant development between releases. For
people who want to be on the cutting edge, there are several easy
mechanisms for keeping your system in sync with the latest
developments. Be warned&mdash;the cutting edge is not for everyone!
<para>&os; is under constant development between releases. Some people
prefer to use the officially released versions, while others prefer
to keep in sync with the latest developments. However, even official
releases are often updated with security and other critical fixes.
Regardless of the version used, &os; provides all necessary tools
to keep your system updated, and also allows for easy upgrades between
versions.
This chapter will help you decide if you want to track the
development system, or stick with one of the released
versions.</para>
versions. The basic tools for keeping your system up to date are
also presented.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>The difference between the two development
branches: &os.stable; and &os.current;.</para>
<para>What utilities may be used to update the system and
the Ports Collection.</para>
</listitem>
<listitem>
<para>How to keep your system up to date with
<application>freebsd-update</application>,
<application>CVSup</application>,
<application>CVS</application>, or
<application>CTM</application>.</para>
</listitem>
<listitem>
<para>How to compare the state of an installed system against
a known pristine copy.</para>
</listitem>
<listitem>
<para>The difference between the two development
branches: &os.stable; and &os.current;.</para>
</listitem>
<listitem>
<para>How to rebuild and reinstall the entire base
system with <command>make buildworld</command> (etc).</para>
@ -98,8 +113,470 @@
</note>
</sect1>
<sect1 id="updating-upgrading-freebsdupdate">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Colin</firstname>
<surname>Percival</surname>
<contrib>Based on notes provided by </contrib>
</author>
</authorgroup>
</sect1info>
<title>FreeBSD Update</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
<primary>freebsd-update</primary>
<see>updating-upgrading</see>
</indexterm>
<para>Applying security patches is an important part of maintaining
computer software, especially the operating system. For the
longest time on &os; this process was not an easy one. Patches
had to be applied to the source code, the code rebuilt into
binaries, and then the binaries had to be re-installed.</para>
<para>This is no longer the case as &os; now includes a utility
simply called <command>freebsd-update</command>. This utility
provides two separate functions. First, it allows for binary
security and errata updates to be applied to the &os; base system
without the build and install requirements. Second, the utility
supports minor and major release upgrades.</para>
<note>
<para>Binary updates are available for all architectures and
releases currently supported by the security team; however,
some features, such as the &os; operating system upgrades,
require the latest release of &man.freebsd-update.8; and
&os; 6.3 or greater. Before updating to a new release, the current
release announcements should be reviewed as they may contain
important information pertinent to the desired release. These
announcements may be viewed at the following link:
<ulink url="http://www.FreeBSD.org/releases/"></ulink>.</para>
</note>
<para>If a <command>crontab</command> utilizing the features
of <command>freebsd-update</command> exists, it must be
disabled before the following operation is started.</para>
<sect2>
<title>The Configuration File</title>
<para>Some users may wish to tweak the configuration file,
allowing better control of the process. The options are
very well documented, but the following few may require a
bit more explanation:</para>
<programlisting># Components of the base system which should be kept updated.
Components src world kernel</programlisting>
<para>This parameter controls what parts of &os; will be kept
up to date. The default is to update the source code, the
entire base system, and the kernel. Components are the
same as those available during the install, for instance,
adding "world/games" here would allow game patches to be
applied. Using "src/bin" would allow the source code in
<filename class="directory">src/bin</filename> to be
updated.</para>
<para>The best option is to leave this at the default as
changing it to include specific items will require the user
to list every item they prefer to be updated. This could
have disastrous consequences as source code and binaries may
become out of sync.</para>
<programlisting># Paths which start with anything matching an entry in an IgnorePaths
# statement will be ignored.
IgnorePaths</programlisting>
<para>Add paths, such as
<filename class="directory">/bin</filename> or
<filename class="directory">/sbin</filename> to leave these
specific directories untouched during the update
process. This option may be used to prevent
<command>freebsd-update</command> from overwriting local
modifications.</para>
<programlisting># Paths which start with anything matching an entry in an UpdateIfUnmodified
# statement will only be updated if the contents of the file have not been
# modified by the user (unless changes are merged; see below).
UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting>
<para>Update configuration files in the specified directories
only if they have not been modified. Any changes made by the
user will invalidate the automatic updating of these files.
There is another option,
<literal>KeepModifiedMetadata</literal>, which will instruct
<command>freebsd-update</command> to save the changes during
the merge.</para>
<programlisting># When upgrading to a new &os; release, files which match MergeChanges
# will have any local changes merged into the version from the new release.
MergeChanges /etc/ /var/named/etc/</programlisting>
<para>List of directories with configuration files that
<command>freebsd-update</command> should attempt merges in.
The file merge process is a series of &man.diff.1; patches
similar to &man.mergemaster.8; with fewer options, the merges
are either accepted, open an editor, or
<command>freebsd-update</command> will abort. When in doubt,
backup <filename class="directory">/etc</filename> and just
accept the merges. See <xref linkend="updating-upgrading"> for more
information about the <command>mergemaster</command>
command.</para>
<programlisting># Directory in which to store downloaded updates and temporary
# files used by &os; Update.
# WorkDir /var/db/freebsd-update</programlisting>
<para>This directory is where all patches and temporary
files will be placed. In cases where the user is doing
a version upgrade, this location should have a least a
gigabyte of disk space available.</para>
<programlisting># When upgrading between releases, should the list of Components be
# read strictly (StrictComponents yes) or merely as a list of components
# which *might* be installed of which &os; Update should figure out
# which actually are installed and upgrade those (StrictComponents no)?
# StrictComponents no</programlisting>
<para>When set to <literal>yes</literal>,
<command>freebsd-update</command> will assume that the
<literal>Components</literal> list is complete and will not
attempt to make changes outside of the list. Effectively,
<command>freebsd-update</command> will attempt to update
every file which belongs to the <literal>Components</literal>
list.</para>
</sect2>
<sect2>
<title>Security Patches</title>
<para>Security patches are stored on a remote machine and
may be downloaded and installed using the following
command:</para>
<screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>If any kernel patches have been applied the system will
need a reboot. If all went well the system should be patched
and <command>freebsd-update</command> may be ran as a nightly
&man.cron.8; job. An entry in <filename>/etc/crontab</filename>
would be sufficient to accomplish this task:</para>
<programlisting>@daily root freebsd-update cron</programlisting>
<para>This entry states that once every day, the
<command>freebsd-update</command> will be ran. In this way,
using the <option>cron</option> argument,
<command>freebsd-update</command> will only check if updates
exist. If patches exist, they will automatically be downloaded
to the local disk but not applied. The
<username>root</username> user will be sent an email so they
may install them manually.</para>
<para>If anything went wrong, <command>freebsd-update</command>
has the ability to roll back the last set of changes with
the following command:</para>
<screen>&prompt.root; <userinput>freebsd-update rollback</userinput></screen>
<para>Once complete, the system should be restarted if the kernel
or any kernel modules were modified. This will allow &os; to
load the new binaries into memory.</para>
<note>
<para>The <command>freebsd-update</command> only works with
the <filename>GENERIC</filename> kernel. If any changes have
been made to <filename>GENERIC</filename> or a custom kernel
has been installed, <command>freebsd-update</command> will
not complete&nbsp;&mdash; failing in the former case and
producing an error in the latter.</para>
</note>
</sect2>
<sect2>
<title>Major and Minor Upgrades</title>
<para>This process 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
<filename role="package">ports-mgmt/portupgrade</filename>
utility. Most users will want to run a test build using
the following command:</para>
<screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
<para>This will ensure everything will be re-installed
correctly. Note that setting the
<makevar>BATCH</makevar> environment variable to
<literal>yes</literal> will answer <literal>yes</literal> to
any prompts during this process, removing the need for
manual intervention during the build process.</para>
<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;&nbsp;6.3:</para>
<screen>&prompt.root; <userinput>freebsd-update -r 6.3-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 6.3-BETA1 from update1.FreeBSD.org... done.
Fetching metadata index... done.
Inspecting system... done.
The following components of FreeBSD seem to be installed:
kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
world/base world/info world/lib32 world/manpages
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>
<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>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&nbsp;&mdash; 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>
<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>
<para>The kernel and kernel modules will be patched first. At
this point the machine must be rebooted. The following
command may be issued to restart the machine so the new
kernel will be loaded into memory:</para>
<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>
<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>
<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>
<screen>&prompt.root; <userinput>portupgrade -f ruby</userinput>
&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput>
&prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput>
&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput>
&prompt.root; <userinput>portupgrade -af</userinput></screen>
<para>Once this has completed, finish the upgrade process with a
final call to <command>freebsd-update</command>. Issue the
following command to tie up all loose ends in the upgrade
process:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>Reboot the machine into the new &os; version. The process
is complete.</para>
</sect2>
<sect2>
<title>System State Comparison</title>
<para>The <command>freebsd-update</command> utility may be used
to test the state of the installed &os; version against a
known good copy. This option evaluates the current version
of system utilities, libraries, and configuration files.
To begin the comparison, issue the following command:</para>
<screen>&prompt.root; <userinput>freebsd-update IDS &gt;&gt; outfile.ids</userinput></screen>
<warning>
<para>While the command name is <acronym>IDS</acronym> it should
in no way be a replacement for an intrusion detection system
such as <filename role="package">security/snort</filename>.
As <command>freebsd-update</command> stores data on disk, the
possibility of tampering is evident. While this possibility
may be reduced by using the
<varname>kern.securelevel</varname> setting and storing the
<command>freebsd-update</command> data on a read only file
system when not in use, a better solution would be to
compare the system against a secure disk, such as a
<acronym>DVD</acronym> or securely stored external
<acronym>USB</acronym> disk device.</para>
</warning>
<para>The system will now be inspected, and a list of files
along with their &man.sha256.1; hash values, both the known value
in the release and the current installed value, will be printed. This is why
the output has been sent to the
<filename>outfile.ids</filename> file. It scrolls by too
quickly for eye comparisons, and soon it fills up the console
buffer.</para>
<para>These lines are also extremely long, but the output format
may be parsed quite easily. For instance, to obtain a list of
all files different from those in the release, issue the
following command:</para>
<screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput>
/etc/master.passwd
/etc/motd
/etc/passwd
/etc/pf.conf</screen>
<para>This output has been truncated, many more files exist.
Some of these files have natural modifications, the
<filename>/etc/passwd</filename> has been modified because
users have been added to the system. In some cases, there
may be other files, such as kernel modules, which differ
as <command>freebsd-update</command> may have updated them.
To exclude specific files or directories, add them to the
<literal>IDSIgnorePaths</literal> option in
<filename>/etc/freebsd-update.conf</filename>.</para>
<para>This system may be used as part of an elaborate upgrade
method, aside from the previously discussed version.</para>
</sect2>
</sect1>
<sect1 id="updating-upgrading-portsnap">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Colin</firstname>
<surname>Percival</surname>
<contrib>Based on notes provided by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Portsnap: A Ports Collection Update Tool</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
<primary>Portsnap</primary>
<see>Updating and Upgrading</see>
</indexterm>
<para>The base system of &os; includes a utility for updating
the Ports Collection too: the &man.portsnap.8; utility. Upon
execution, it will connect to a remote site, verify the secure
key, and download a new copy of the Ports Collection. The key
is used to verify the integrity of all downloaded files, ensuring
they have not been modified in-flight. To download the latest
Ports Collection files, issue the following command:</para>
<screen>&prompt.root; <userinput>portsnap fetch</userinput>
Looking up portsnap.FreeBSD.org mirrors... 3 mirrors found.
Fetching snapshot tag from portsnap1.FreeBSD.org... done.
Fetching snapshot metadata... done.
Updating from Wed Aug 6 18:00:22 EDT 2008 to Sat Aug 30 20:24:11 EDT 2008.
Fetching 3 metadata patches.. done.
Applying metadata patches... done.
Fetching 3 metadata files... done.
Fetching 90 patches.....10....20....30....40....50....60....70....80....90. done.
Applying patches... done.
Fetching 133 new ports or files... done.</screen>
<para>What this example shows is that &man.portsnap.8;
has found and verified
several patches to the current ports data. This also indicates
that the utility was run previously, if it was a first time
run, the collection would have simply been downloaded.</para>
<para>When &man.portsnap.8; successfully completes
a <command>fetch</command> operation, the Ports Collection and
subsequent patches exist on the local system that have passed
verification. The updated files may be installed by
typing:</para>
<screen>&prompt.root; <userinput>portsnap extract</userinput>
/usr/ports/.cvsignore
/usr/ports/CHANGES
/usr/ports/COPYRIGHT
/usr/ports/GIDs
/usr/ports/KNOBS
/usr/ports/LEGAL
/usr/ports/MOVED
/usr/ports/Makefile
/usr/ports/Mk/bsd.apache.mk
/usr/ports/Mk/bsd.autotools.mk
/usr/ports/Mk/bsd.cmake.mk
<replaceable>...</replaceable></screen>
<para>The process is now complete, and applications may be
installed or upgraded using the updated Ports Collection.</para>
<para>To run both processes consecutively, issue the following
command:</para>
<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
</sect1>
<sect1 id="current-stable">
<title>&os.current; vs. &os.stable;</title>
<title>Tracking a Development Branch</title>
<indexterm><primary>-CURRENT</primary></indexterm>
<indexterm><primary>-STABLE</primary></indexterm>
@ -862,7 +1339,7 @@
&prompt.root; <userinput>rm -rf *</userinput></screen>
</sect2>
<sect2 id="cutting-edge-compilebase">
<sect2 id="updating-upgrading-compilebase">
<title>Recompile the Base System</title>
<sect3>
@ -1219,7 +1696,7 @@ Script done, &hellip;</screen>
<para>If you are using &man.mergemaster.8; (as recommended),
you can skip forward to the <link
linkend="cutting-edge-rebooting">next section</link>.</para>
linkend="updating-upgrading-rebooting">next section</link>.</para>
<para>The simplest way to do this by hand is to install the
files into a new directory, and then work through them looking
@ -1367,7 +1844,7 @@ Script done, &hellip;</screen>
</sect3>
</sect2>
<sect2 id="cutting-edge-rebooting">
<sect2 id="updating-upgrading-rebooting">
<title>Rebooting</title>
<para>You are now done. After you have verified that everything appears

2
en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml
View file

@ -84,7 +84,7 @@ that might make this chapter too large.
<listitem>
<para>Understand how to obtain and rebuild the &os; sources
(<xref linkend="cutting-edge">).</para>
(<xref linkend="updating-upgrading">).</para>
</listitem>
</itemizedlist>

4
en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml
View file

@ -336,7 +336,7 @@ following line in &man.loader.conf.5:
you to realize that you have deleted your custom kernel
configuration file. Also, do not edit <filename>GENERIC</filename>
directly, as it may get overwritten the next time you
<link linkend="cutting-edge">update your source tree</link>, and
<link linkend="updating-upgrading">update your source tree</link>, and
your kernel modifications will be lost.</para>
<para>You might want to keep your kernel configuration file
@ -374,7 +374,7 @@ following line in &man.loader.conf.5:
<note>
<para>If you <link
linkend="cutting-edge">sync your source tree</link> with the
linkend="updating-upgrading">sync your source tree</link> with the
latest sources of the &os; project,
be sure to always check the file
<filename>/usr/src/UPDATING</filename> before you perform any update

15
en_US.ISO8859-1/books/handbook/preface/preface.sgml
View file

@ -35,8 +35,8 @@
<itemizedlist>
<listitem>
<para><xref linkend="dtrace">, DTrace, has been added with
information about the powerful DTrace performance analysis
<para><xref linkend="dtrace">, &dtrace;, has been added with
information about the powerful &dtrace; performance analysis
tool.</para>
</listitem>
@ -46,6 +46,12 @@
&os;, such as ZFS from &sun;.</para>
</listitem>
<listitem>
<para><xref linkend="audit">, Security Event Auditing, has
been added to cover the new auditing capabilities in &os;
and explain its use.</para>
</listitem>
<listitem>
<para><xref linkend="virtualization">, Virtualization, has
been added with information about installing &os; on
@ -448,12 +454,13 @@
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis><xref linkend="cutting-edge">, The Cutting Edge</emphasis></term>
<term><emphasis><xref linkend="updating-upgrading">, Updating and Upgrading &os;</emphasis></term>
<listitem>
<para>Explains the differences between FreeBSD-STABLE,
FreeBSD-CURRENT, and FreeBSD releases. Describes which users
would benefit from tracking a development system and outlines
that process.</para>
that process. Covers the methods users may take to update their
system to the latest security release.</para>
</listitem>
</varlistentry>
<varlistentry>

2
en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml
View file

@ -2688,7 +2688,7 @@ console="comconsole,vidconsole"</programlisting>
<procedure>
<step>
<para>Get the kernel source. (See <xref
linkend="cutting-edge">)</para>
linkend="updating-upgrading">)</para>
</step>
<step>