Date: Sun, 17 Feb 2013 17:28:27 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40998 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201302171728.r1HHSRjC009018@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201302171728.r1HHSRjC009018>