svn commit: r40998 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Sun Feb 17 17:28:27 UTC 2013
Author: dru
Date: Sun Feb 17 17:28:26 2013
New Revision: 40998
URL: http://svnweb.freebsd.org/changeset/doc/40998
Log:
Initial content fix. This patch addresses the following:
- missing &os; entities
- rewording to address you, we, and general redundancy
- adds missing directory tags
- replaces portupgrade with portmaster
- replaces old version examples with 9.x and 1998 names with 2013
- makes up-to-date consistent
Approved by: gjb (mentor)
Modified:
head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Feb 17 17:17:14 2013 (r40997)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Feb 17 17:28:26 2013 (r40998)
@@ -52,23 +52,21 @@
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. The basic
- tools for keeping your system up to date are also
- presented.</para>
+ provides all the necessary tools to keep the system updated, and
+ allows for easy upgrades between versions. This chapter
+ describes how to track the development system and the basic
+ tools for keeping a &os; system up-to-date.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
- <para>What utilities may be used to update the system and
+ <para>Which utilities are available to update the system and
the Ports Collection.</para>
</listitem>
<listitem>
- <para>How to keep your system up to date with
+ <para>How to keep a &os; system up-to-date with
<application>freebsd-update</application>,
<application>Subversion</application>, or
<application>CTM</application>.</para>
@@ -80,7 +78,7 @@
</listitem>
<listitem>
- <para>How to keep your documentation up to date with
+ <para>How to keep the installed documentation up-to-date with
<application>Subversion</application> or documentation
ports<!--, and <application>Docsnap</application>-->.</para>
</listitem>
@@ -92,7 +90,7 @@
<listitem>
<para>How to rebuild and reinstall the entire base
- system with <command>make buildworld</command> (etc).</para>
+ system.</para>
</listitem>
</itemizedlist>
@@ -100,7 +98,7 @@
<itemizedlist>
<listitem>
- <para>Properly set up your network connection (<xref
+ <para>Properly set up the network connection (<xref
linkend="advanced-networking"/>).</para>
</listitem>
@@ -111,10 +109,10 @@
</itemizedlist>
<note>
- <para>Throughout this chapter, the <command>svn</command>
- command is used to obtain and update &os; sources. To use it,
- you will need to install the port or the package for <filename
- role="package">devel/subversion</filename>.</para>
+ <para>Throughout this chapter, <command>svn</command> is used to
+ obtain and update &os; sources. To use it, first install the
+ <filename role="package">devel/subversion</filename> port or
+ package.</para>
</note>
</sect1>
@@ -135,7 +133,7 @@
</author>
</authorgroup>
</sect1info>
- <title>FreeBSD Update</title>
+ <title>&os; Update</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
@@ -145,13 +143,13 @@
<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.
+ 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
+ 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
@@ -159,12 +157,11 @@
<note>
<para>Binary updates are available for all architectures and
- releases currently supported by the security team.
- 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>
+ releases currently supported by the security team. Before
+ updating to a new release, its release announcement should be
+ reviewed as it contains important information pertinent to the
+ release. Release announcements are available from <ulink
+ url="http://www.FreeBSD.org/releases/"></ulink>.</para>
</note>
<para>If a <command>crontab</command> utilizing the features
@@ -175,39 +172,38 @@
<title>The Configuration File</title>
<para>Some users may wish to tweak the default configuration
- file in <filename>/etc/freebsd-update.conf</filename>,
- allowing better control of the process. The options are very
- well documented, but the following few may require a bit more
+ in <filename>/etc/freebsd-update.conf</filename>, allowing
+ better control of the process. The options are well
+ documented, but the following 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
- <literal>world/games</literal> here would allow game patches
- to be applied. Using <literal>src/bin</literal> would allow
- the source code in
- <filename class="directory">src/bin</filename> to be
- updated.</para>
+ <para>This parameter controls which 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 installation. For instance, adding
+ <literal>world/games</literal> would allow game patches to be
+ applied. Using <literal>src/bin</literal> 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>
+ changing it to include specific items requires the user to
+ list every item 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
+ <para>To leave specified directories, 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
+ <filename class="directory">/sbin</filename>, untouched during
+ the update process, add their paths to this statement. This
+ option may be used to prevent
<command>freebsd-update</command> from overwriting local
modifications.</para>
@@ -216,8 +212,8 @@ IgnorePaths</programlisting>
# 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
+ <para>This option will only update unmodified configuration
+ files in the specified directories. Any changes made by the
user will invalidate the automatic updating of these files.
There is another option,
<literal>KeepModifiedMetadata</literal>, which will instruct
@@ -229,24 +225,23 @@ UpdateIfUnmodified /etc/ /var/ /root/ /.
MergeChanges /etc/ /var/named/etc/</programlisting>
<para>List of directories with configuration files that
- <command>freebsd-update</command> should attempt merges in.
+ <command>freebsd-update</command> should attempt to merge.
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
+ similar to &man.mergemaster.8;, but with fewer options.
+ 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="mergemaster"/> for more
- information about the <command>mergemaster</command>
- command.</para>
+ information about <command>mergemaster</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>
+ <para>This directory is where all patches and temporary files
+ are 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
@@ -254,7 +249,7 @@ MergeChanges /etc/ /var/named/etc/</prog
# which actually are installed and upgrade those (StrictComponents no)?
# StrictComponents no</programlisting>
- <para>When set to <literal>yes</literal>,
+ <para>When this option is 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,
@@ -266,32 +261,30 @@ MergeChanges /etc/ /var/named/etc/</prog
<sect2 id="freebsdupdate-security-patches">
<title>Security Patches</title>
- <para>Security patches are stored on a remote machine and
- may be downloaded and installed using the following
- command:</para>
+ <para>&os; security patches 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 run as a nightly
- &man.cron.8; job. An entry in
- <filename>/etc/crontab</filename> would be sufficient to
- accomplish this task:</para>
+ <para>If the update applied any kernel patches, the system will
+ need a reboot in order to boot into the patched kernel.
+ Otherwise, the system should be patched and
+ <command>freebsd-update</command> may be run as a nightly
+ &man.cron.8; job by adding this entry to
+ <filename>/etc/crontab</filename>:</para>
<programlisting>@daily root freebsd-update cron</programlisting>
- <para>This entry states that once every day, the
- <command>freebsd-update</command> utility will be run. In
- this way, using the <option>cron</option> argument,
+ <para>This entry states that <command>freebsd-update</command>
+ will run once every day. When run with <option>cron</option>,
<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>
+ downloaded to the local disk but will not be applied. The
+ <username>root</username> user will be sent an email so that
+ they may be reviewed and manually installed.</para>
- <para>If anything went wrong, <command>freebsd-update</command>
+ <para>If anything goes wrong, <command>freebsd-update</command>
has the ability to roll back the last set of changes with
the following command:</para>
@@ -301,16 +294,15 @@ MergeChanges /etc/ /var/named/etc/</prog
kernel or any kernel modules were modified. This will allow
&os; to load the new binaries into memory.</para>
- <para>The <command>freebsd-update</command> utility can
- automatically update the <filename>GENERIC</filename> kernel
- only. If a custom kernel is in use, it will have to be
- rebuilt and reinstalled after
- <command>freebsd-update</command> finishes installing the rest
- of the updates. However, <command>freebsd-update</command>
- will detect and update the <filename>GENERIC</filename> kernel
- in
- <filename class="directory">/boot/GENERIC</filename> (if it
- exists), even if it is not the current (running) kernel of the
+ <para>Only the <filename>GENERIC</filename> kernel can be
+ automatically updated by <command>freebsd-update</command>.
+ If a custom kernel is installed, it will have to be rebuilt
+ and reinstalled after <command>freebsd-update</command>
+ finishes installing the rest of the updates. However,
+ <command>freebsd-update</command> will detect and update the
+ <filename>GENERIC</filename> kernel if
+ <filename class="directory">/boot/GENERIC</filename> exists,
+ even if it is not the current running kernel of the
system.</para>
<note>
@@ -327,22 +319,22 @@ MergeChanges /etc/ /var/named/etc/</prog
<filename>/etc/freebsd-update.conf</filename> has been
changed, <command>freebsd-update</command> will install the
updated kernel sources along with the rest of the updates.
- Rebuilding and reinstalling your new custom kernel can then be
+ Rebuilding and reinstalling a new custom kernel can then be
performed in the usual way.</para>
<note>
- <para>The updates distributed via
- <command>freebsd-update</command>, do not always involve the
- kernel. It will not be necessary to rebuild your custom
- kernel if the kernel sources have not been modified by the
- execution of <command>freebsd-update install</command>.
+ <para>The updates distributed by
+ <command>freebsd-update</command> do not always involve the
+ kernel. It is not necessary to rebuild a custom kernel if
+ the kernel sources have not been modified by the execution
+ of <command>freebsd-update install</command>.
However, <command>freebsd-update</command> will always
- update the <filename>/usr/src/sys/conf/newvers.sh</filename>
- file. The current patch level (as indicated by the
+ update <filename>/usr/src/sys/conf/newvers.sh</filename>.
+ The current patch level, as indicated by the
<literal>-p</literal> number reported by
- <command>uname -r</command>) is obtained from this file.
- Rebuilding your custom kernel, even if nothing else changed,
- will allow &man.uname.1; to accurately report the current
+ <command>uname -r</command>, is obtained from this file.
+ Rebuilding a custom kernel, even if nothing else changed,
+ allows &man.uname.1; to accurately report the current
patch level of the system. This is particularly helpful
when maintaining multiple systems, as it allows for a quick
assessment of the updates installed in each one.</para>
@@ -358,18 +350,18 @@ MergeChanges /etc/ /var/named/etc/</prog
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
- after a major version upgrade by using the
- <filename role="package">ports-mgmt/portupgrade</filename>
- utility. A brute-force rebuild of all installed
- applications can be accomplished with this command:</para>
+ <para><emphasis>Major version</emphasis> upgrades occur when
+ &os; is upgraded from one major version to another, like from
+ &os; 8.X to &os; 9.X. Major version upgrades 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 after a
+ major version upgrade using a utility such as
+ <filename role="package">ports-mgmt/portmaster</filename>. A
+ brute-force rebuild of all installed applications can be
+ accomplished with this command:</para>
- <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
+ <screen>&prompt.root; <userinput>portmaster -f</userinput></screen>
<para>This will ensure everything will be re-installed
correctly. Note that setting the
@@ -388,30 +380,28 @@ MergeChanges /etc/ /var/named/etc/</prog
<sect4 id="freebsd-update-custom-kernel-8x">
<title>Custom Kernels with &os; 8.X and Earlier</title>
- <para>A copy of the
- <filename>GENERIC</filename> kernel is needed, and it
- should be placed in <filename
+ <para>A copy of the <filename>GENERIC</filename> kernel is
+ needed, and 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>
+ <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
class="directory">/boot/kernel.old</filename> is
- actually the <filename>GENERIC</filename> one. Simply
- rename this directory to <filename
+ actually <filename>GENERIC</filename>. 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>
+ 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>
@@ -419,7 +409,7 @@ MergeChanges /etc/ /var/named/etc/</prog
<para>Replace <filename
class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
- with the actual version of the release you are using.
+ with the actual version of the release being used.
The <filename>GENERIC</filename> kernel will be
installed in <filename
class="directory">/boot/GENERIC</filename> by
@@ -429,7 +419,7 @@ MergeChanges /etc/ /var/named/etc/</prog
<listitem>
<para>Failing all the above, the
<filename>GENERIC</filename> kernel may be rebuilt and
- installed from the sources:</para>
+ 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>
@@ -437,8 +427,8 @@ MergeChanges /etc/ /var/named/etc/</prog
&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> 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
@@ -467,8 +457,8 @@ MergeChanges /etc/ /var/named/etc/</prog
<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>
+ 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>
@@ -478,7 +468,7 @@ MergeChanges /etc/ /var/named/etc/</prog
<listitem>
<para>If the options above cannot be used, the
<literal>GENERIC</literal> kernel may be rebuilt and
- installed from the sources:</para>
+ 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>
@@ -503,21 +493,20 @@ MergeChanges /etc/ /var/named/etc/</prog
<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>
+ version target. The following command will update to
+ &os; 9.1:</para>
- <screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen>
+ <screen>&prompt.root; <userinput>freebsd-update -r 9.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>
+ gather the information necessary to perform the upgrade. A
+ screen listing will display which components have and have
+ not been detected. For example:</para>
<screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found.
-Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done.
+Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done.
Fetching metadata index... done.
Inspecting system... done.
@@ -542,7 +531,7 @@ Does this look reasonable (y/n)? y</scre
a warning similar to the following:</para>
<screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a
-kernel configuration distributed as part of FreeBSD 8.0-RELEASE.
+kernel configuration distributed as part of FreeBSD 9.0-RELEASE.
This kernel will not be updated: you MUST update the kernel manually
before running "/usr/sbin/freebsd-update install"</screen>
@@ -550,57 +539,53 @@ before running "/usr/sbin/freebsd-update
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
+ <para>Once all the patches have been downloaded to the local
+ system, they will be applied. This process may take a
+ while, depending on the speed and workload of the machine.
+ Configuration files will then be merged. The merging
+ 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
+ <para>The system is not being altered yet as all patching
+ and merging is happening in another directory. Once 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>
+ smoothly, the changes can be committed to disk by the
+ user using the following command:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
+ </note>
+
<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>
+ this point, the machine must be rebooted. If the system is
+ running with a custom kernel, use &man.nextboot.8; to set
+ the kernel for the next boot to the updated
+ <filename class="directory">/boot/GENERIC</filename>:</para>
<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>
+ kernel, make sure it contains all the drivers required for
+ the system to boot properly and connect to the network,
+ if the machine being updated is accessed remotely. In
+ particular, if the running custom kernel contains 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.
+ It is recommended to disable non-essential services as
+ well as any disk and network mounts until the upgrade
+ process is complete.</para>
</warning>
<para>The machine should now be restarted with the updated
@@ -608,20 +593,19 @@ before running "/usr/sbin/freebsd-update
<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,
+ <para>Once the system has come back online, restart
+ <command>freebsd-update</command> using the following
+ command. 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>
+ object files.</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>
+ <para>Depending upon whether any library version numbers
+ were bumped, there may only be two install phases instead
+ of three.</para>
</note>
</sect3>
@@ -629,23 +613,17 @@ before running "/usr/sbin/freebsd-update
<title>Rebuilding Ports After a Major Version Upgrade</title>
<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>
+ 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 <filename
+ role="package">ports-mgmt/portmaster</filename>:</para>
+
+ <screen>&prompt.root; <userinput>portmaster -f</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>
+ a final call to <command>freebsd-update</command> in order
+ to tie up all the loose ends in the upgrade process:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
@@ -661,42 +639,38 @@ before running "/usr/sbin/freebsd-update
<sect2 id="freebsdupdate-system-comparison">
<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>
+ <para><command>freebsd-update</command> can 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 >> 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
+ <para>While the command name is <acronym>IDS</acronym> it is
+ not a replacement for a real 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
+ may be reduced using <varname>kern.securelevel</varname> and
+ by 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>
+ <para>The system will now be inspected, and a lengthy listing of
+ files, along with the &man.sha256.1; hash values for both the
+ known value in the release and the current installation, will
+ be sent to the specified
+ <filename>outfile.ids</filename> file.</para>
+
+ <para>The entries in the listing are extremely long, but the
+ output format may be easily parsed. For instance, to obtain a
+ list of all files which differ 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
@@ -704,12 +678,12 @@ before running "/usr/sbin/freebsd-update
/etc/passwd
/etc/pf.conf</screen>
- <para>This output has been truncated, many more files exist.
- Some of these files have natural modifications, the
+ <para>This sample output has been truncated as many more files
+ exist. Some files have natural modifications. For example,
<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.
+ users have been added to the system. Other files, such as
+ kernel modules, may 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>
@@ -744,14 +718,12 @@ before running "/usr/sbin/freebsd-update
<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>
+ <para>The base system of &os; includes &man.portsnap.8; for
+ updating the Ports Collection. This utility connects to a
+ &os; site, verifies the secure key, and downloads a new copy of
+ the Ports Collection. The key is used to verify the integrity
+ of all downloaded files. 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... 9 mirrors found.
@@ -767,16 +739,16 @@ Fetching 133 new ports or files... done.
<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
+ 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
+ subsequent patches which exist on the local system have passed
verification. The first time <command>portsnap</command> is
- executed, you have to use <literal>extract</literal> to install
- the downloaded files:</para>
+ executed, use <literal>extract</literal> to install the
+ downloaded files:</para>
<screen>&prompt.root; <userinput>portsnap extract</userinput>
/usr/ports/.cvsignore
@@ -792,22 +764,22 @@ Fetching 133 new ports or files... done.
/usr/ports/Mk/bsd.cmake.mk
<replaceable>...</replaceable></screen>
- <para>To update an already installed Ports Collection use the
- command <command>portsnap update</command>:</para>
+ <para>To update an already installed Ports Collection, use
+ <command>portsnap update</command>:</para>
<screen>&prompt.root; <userinput>portsnap update</userinput></screen>
<para>The process is now complete, and applications may be
installed or upgraded using the updated Ports Collection.</para>
- <para>The <literal>fetch</literal> and <literal>extract</literal>
- or <literal>update</literal> operations may be run
- consecutively, as shown in the following example:</para>
+ <para>When using <literal>fetch</literal>, the
+ <literal>extract</literal> or the <literal>update</literal>
+ operation may be run consecutively:</para>
<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
- <para>This command will download the latest version of the
- Ports Collection and update your local version under
+ <para>This command downloads the latest version of the Ports
+ Collection and updates the local version under
<filename class="directory">/usr/ports</filename>.</para>
</sect1>
@@ -821,71 +793,66 @@ Fetching 133 new ports or files... done.
<see>Updating and Upgrading</see>
</indexterm>
- <para>Besides the base system and the Ports Collection,
- documentation is an integral part of the &os; operating system.
- While an up-to-date version of the &os; Documentation Set is
- always available on the
- <ulink url="http://www.freebsd.org/doc/">&os; web site</ulink>,
- some users might have slow or no permanent network connectivity
- at all. Fortunately, there are several ways to update the
- documentation shipped with each release by maintaining a local
- copy of the latest &os; Documentation Set.</para>
+ <para>Documentation is an integral part of the &os; operating
+ system. While an up-to-date version of the &os; Documentation
+ Set is always available on the <ulink
+ url="http://www.freebsd.org/doc/">&os; web site</ulink>,
+ some users might have slow or no permanent network connectivity.
+ There are several ways to update the local copy of documentation
+ with the latest &os; Documentation Set.</para>
<sect2 id="dsvn-doc">
<title>Using <application>Subversion</application> to Update the
Documentation</title>
<para>The &os; documentation sources can be obtained with
- <application>Subversion</application>. This section
- describes:</para>
+ <application>svn</application>. This section
+ describes how to:</para>
<itemizedlist>
<listitem>
- <para>How to install the documentation toolchain, the tools
- that are required to rebuild the &os; documentation from
- its source.</para>
+ <para>Install the documentation toolchain, the tools that
+ are required to rebuild the &os; documentation from its
+ source.</para>
</listitem>
<listitem>
- <para>How to download a copy of the documentation source
- at <filename class="directory">/usr/doc</filename>,
- using <application>Subversion</application>.</para>
+ <para>Download a copy of the documentation source at
+ <filename class="directory">/usr/doc</filename>, using
+ <application>svn</application>.</para>
</listitem>
<listitem>
- <para>How to rebuild the &os; documentation from its source,
- and install it under <filename
+ <para>Rebuild the &os; documentation from its source, and
+ install it under <filename
class="directory">/usr/share/doc</filename>.</para>
</listitem>
<listitem>
- <para>Some of the build options that are supported by the
- build system of the documentation, i.e., the options that
- build only some of the different language translations of
- the documentation or the options that select a specific
- output format.</para>
+ <para>Recognize some of the build options that are
+ supported by the build system of the documentation, such
+ as the options that build only some of the different
+ language translations of the documentation or the options
+ that select a specific output format.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="installing-documentation-toolchain">
- <title>Installing <application>Subversion</application> and the
+ <title>Installing <application>svn</application> and the
Documentation Toolchain</title>
<para>Rebuilding the &os; documentation from source requires a
- fairly large collection of tools. These tools are not part of
- the &os; base system, because they need a large amount of disk
- space and they are not useful to all &os; users; they are only
- useful to those users that are actively writing new
- documentation for &os; or are frequently updating their
- documentation from source.</para>
-
- <para>All the required tools are available as part of the Ports
- Collection. The
- <filename role="package">textproc/docproj</filename> port is a
- master port that has been developed by the &os; Documentation
- Project, to ease the initial installation and future updates
- of these tools.</para>
+ collection of tools which are not part of the &os; base system
+ due to the amount of disk space these tools use. They are
+ also not useful to all &os; users, only those users that are
+ actively writing new documentation for &os; or are frequently
+ updating their documentation from source.</para>
+
+ <para>The required tools, including
+ <application>svn</application>, are available in the
+ <filename role="package">textproc/docproj</filename> meta-port
+ developed by the &os; Documentation Project.</para>
<note>
<para>When no &postscript; or PDF documentation required, one
@@ -898,23 +865,18 @@ Fetching 133 new ports or files... done.
of tools, so it may be quite sensible to omit its
installation if PDF output is not really necessary.</para>
</note>
-
- <para><application>Subversion</application> is installed with
- the <filename role="package">textproc/docproj</filename>
- port.</para>
</sect2>
<sect2 id="updating-documentation-sources">
<title>Updating the Documentation Sources</title>
- <para>The <application>Subversion</application> program can
+ <para>In this example, <application>svn</application> is used to
fetch a clean copy of the documentation sources from the
- western US mirror using the HTTPS protocol with this
- command:</para>
+ western US mirror using the HTTPS protocol:</para>
<screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen>
- <para>Please use the closest mirror from the available <link
+ <para>Select the closest mirror from the available <link
linkend="svn-mirrors">Subversion mirror sites</link>.</para>
<para>The initial download of the documentation sources may take
@@ -927,9 +889,8 @@ Fetching 133 new ports or files... done.
<para>After checking out the sources, an alternative way of
updating the documentation is supported by the
- <filename>Makefile</filename> of the
- <filename class="directory">/usr/doc</filename> directory by
- running:</para>
+ <filename>/usr/doc/Makefile</filename> by running the
+ following commands:</para>
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make update</userinput></screen>
@@ -939,14 +900,13 @@ Fetching 133 new ports or files... done.
<title>Tunable Options of the Documentation Sources</title>
<para>The updating and build system of the &os; documentation
- supports a few options that ease the process of updating only
- parts of the documentation, or the build of specific
+ set supports a few options that ease the process of updating
+ only parts of the documentation, or the build of specific
translations. These options can be set either as system-wide
- options in the <filename>/etc/make.conf</filename> file, or as
- command-line options passed to the &man.make.1;
- utility.</para>
+ options in <filename>/etc/make.conf</filename>, or as
+ command-line options passed to &man.make.1;.</para>
- <para>The following options are some of these:</para>
+ <para>The options include:</para>
<variablelist>
<varlistentry>
@@ -954,8 +914,8 @@ Fetching 133 new ports or files... done.
<listitem>
<para>The list of languages and encodings to build and
- install, e.g., <literal>en_US.ISO8859-1</literal> for
- the English documentation only.</para>
+ install, such as <literal>en_US.ISO8859-1</literal> for
+ English documentation.</para>
</listitem>
</varlistentry>
@@ -982,11 +942,12 @@ Fetching 133 new ports or files... done.
</varlistentry>
</variablelist>
- <para>For more make variables supported as system-wide options
- in &os;, see &man.make.conf.5;.</para>
+ <para>For more <command>make</command> variables supported as
+ system-wide options in &os;, refer to
+ &man.make.conf.5;.</para>
- <para>For more make variables supported by the build system of
- the &os; documentation, please refer to the
+ <para>For more <command>make</command> variables supported by
+ the build system of the &os; documentation, refer to the
<ulink url="&url.doc.langbase;/books/fdp-primer">&os;
Documentation Project Primer for New
Contributors</ulink>.</para>
@@ -995,14 +956,13 @@ Fetching 133 new ports or files... done.
<sect2 id="updating-installed-documentation">
<title>Installing the &os; Documentation from Source</title>
- <para>When an up-to-date snapshot of the documentation sources
- has been fetched in
- <filename class="directory">/usr/doc</filename>, everything is
+ <para>Once an up-to-date snapshot of the documentation sources
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-head
mailing list