Date: Tue, 6 May 2014 17:43:53 +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: r44775 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201405061743.s46HhrK3038783@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Tue May 6 17:43:53 2014 New Revision: 44775 URL: http://svnweb.freebsd.org/changeset/doc/44775 Log: Finish editorial review of FreeBSD Update chapter. Sponsored by: iXsystems 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 Tue May 6 16:47:12 2014 (r44774) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Tue May 6 17:43:53 2014 (r44775) @@ -334,13 +334,15 @@ Uninstalling updates... done.</screen> system.</para> <note> - <para>It is a good idea to always keep a copy of the + <para>Always keep a copy of the <filename>GENERIC</filename> kernel in <filename>/boot/GENERIC</filename>. It will be helpful in diagnosing a variety of problems and in - performing version upgrades using - <command>freebsd-update</command> as described in - <xref linkend="freebsdupdate-upgrade"/>.</para> + performing version upgrades. Refer to either <xref + linkend="freebsd-update-custom-kernel-9x"/> or <xref + linkend="freebsd-update-custom-kernel-8x"/> for + instructions on how to get a copy of the + <filename>GENERIC</filename> kernel.</para> </note> <para>Unless the default configuration in @@ -377,7 +379,20 @@ Uninstalling updates... done.</screen> &os; is upgraded from one major version to another, like from &os; 9.X to &os; 10.X. Both types of upgrades can be performed by providing <command>freebsd-update</command> - with a release version target. The following command, when + with a release version target.</para> + + <note> + <para>If the system is running a custom kernel, make sure that + a copy of the <filename>GENERIC</filename> kernel exists in + <filename>/boot/GENERIC</filename> before starting the + upgrade. Refer to either <xref + linkend="freebsd-update-custom-kernel-9x"/> or <xref + linkend="freebsd-update-custom-kernel-8x"/> for + instructions on how to get a copy of the + <filename>GENERIC</filename> kernel.</para> + </note> + + <para>The following command, when run on a &os; 9.0 system, will upgrade it to &os; 9.1:</para> @@ -450,8 +465,8 @@ before running "/usr/sbin/freebsd-update </note> - <para>The kernel and kernel modules will be patched first. At - this point, the machine must be rebooted. If the system is + <para>The kernel and kernel modules will be patched first. 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>/boot/GENERIC</filename>:</para> @@ -480,9 +495,10 @@ before running "/usr/sbin/freebsd-update <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. Since the state of the process has been saved, <command>freebsd-update</command> will not start from the - beginning, but will remove all old shared libraries and + beginning, but will instead move on to the next phase and + remove all old shared libraries and object files.</para> <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> @@ -495,37 +511,34 @@ before running "/usr/sbin/freebsd-update <para>The upgrade is now complete. If this was a major version upgrade, reinstall all ports and packages as - described in <xref linkend="freebsdupdate-portsrebuild"/>. - If the system uses a custom kernel, refer to either <xref - linkend="freebsd-update-custom-kernel-9x"/> or <xref - linkend="freebsd-update-custom-kernel-8x"/> for - instructions on how to upgrade the custom kernel.</para> + described in <xref linkend="freebsdupdate-portsrebuild"/>.</para> <sect3 xml:id="freebsd-update-custom-kernel-9x"> <title>Custom Kernels with &os; 9.X and Later</title> - <itemizedlist> - <listitem> - <para>If a custom kernel has only been built once, the + <para>Before using <command>freebsd-update</command>, ensure + that a copy of the <filename>GENERIC</filename> kernel + exists in <filename>/boot/GENERIC</filename>. If a custom + kernel has only been built once, the kernel in <filename>/boot/kernel.old</filename> is - actually the <literal>GENERIC</literal> kernel. - Rename this directory to + the <literal>GENERIC</literal> kernel. + Simply rename this directory to <filename>/boot/kernel</filename>.</para> - </listitem> - <listitem> - <para>If physical access to the machine is available, a + <para>If a custom kernel has been built more than once + or if it is unknown how many times the custom kernel + has been built, obtain a copy of the + <literal>GENERIC</literal> kernel that matches the + current version of the operating system. If physical + access to the system is available, a copy of the <literal>GENERIC</literal> kernel can be - installed from the installation media using these - commands:</para> + installed from the installation media:</para> <screen>&prompt.root; <userinput>mount /cdrom</userinput> &prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput> &prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen> - </listitem> - <listitem> - <para>If the options above cannot be used, the + <para>Alternately, the <literal>GENERIC</literal> kernel may be rebuilt and installed from source:</para> @@ -539,33 +552,19 @@ before running "/usr/sbin/freebsd-update not have been modified in any way. It is also suggested that the kernel is built without any other special options.</para> - </listitem> - </itemizedlist> - <para>Rebooting to the <filename>GENERIC</filename> kernel - is not required at this stage.</para> + <para>Rebooting into the <filename>GENERIC</filename> kernel + is not required as <command>freebsd-update</command> only + needs <filename>/boot/GENERIC</filename> to exist.</para> </sect3> <sect3 xml:id="freebsd-update-custom-kernel-8x"> <title>Custom Kernels with &os; 8.X</title> - <para>A copy of the <filename>GENERIC</filename> kernel is - needed, and should be placed in - <filename>/boot/GENERIC</filename>. If the - <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>/boot/kernel.old</filename> is - actually <filename>GENERIC</filename>. Rename this - directory to - <filename>/boot/GENERIC</filename>.</para> - </listitem> + <para>On an &os; 8.X system, the instructions for + obtaining or building a + <filename>GENERIC</filename> kernel differ slightly.</para> - <listitem> <para>Assuming physical access to the machine is possible, a copy of the <filename>GENERIC</filename> kernel can be installed from the installation media @@ -577,16 +576,13 @@ before running "/usr/sbin/freebsd-update <para>Replace <filename class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> - with the actual version of the release being used. + with the version of the release being used. The <filename>GENERIC</filename> kernel will be installed in <filename>/boot/GENERIC</filename> by default.</para> - </listitem> - <listitem> - <para>Failing all the above, the - <filename>GENERIC</filename> kernel may be rebuilt and - installed from source:</para> + <para>To instead build the + <filename>GENERIC</filename> kernel 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> @@ -600,11 +596,9 @@ before running "/usr/sbin/freebsd-update not have been modified in any way. It is also suggested that it is built without any other special options.</para> - </listitem> - </itemizedlist> - <para>Rebooting to the <filename>GENERIC</filename> kernel - is not required at this stage.</para> + <para>Rebooting into the <filename>GENERIC</filename> kernel + is not required.</para> </sect3> <sect3 xml:id="freebsdupdate-portsrebuild"> @@ -629,7 +623,7 @@ before running "/usr/sbin/freebsd-update screens. To prevent this behavior, and use only the default options, include <option>-G</option> in the above command.</para> - <para>Once this has completed, finish the upgrade process with + <para>Once the software upgrades are complete, finish the upgrade process with a final call to <command>freebsd-update</command> in order to tie up all the loose ends in the upgrade process:</para> @@ -637,43 +631,49 @@ before running "/usr/sbin/freebsd-update <para>If the <filename>GENERIC</filename> kernel was temporarily used, this is the time to build and install a - new custom kernel in the usual way.</para> + new custom kernel using the instructions in <xref + linkend="kernelconfig"/>.</para> - <para>Reboot the machine into the new &os; version. The - process is complete.</para> + <para>Reboot the machine into the new &os; version. The upgrade + process is now complete.</para> </sect3> </sect2> <sect2 xml:id="freebsdupdate-system-comparison"> <title>System State Comparison</title> - <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> + <para>The state of the installed &os; version against a known + good copy can be tested using <command>freebsd-update IDS</command>. + This command evaluates the current version of system utilities, + libraries, and configuration files and can be used as a + built-in Intrusion Detection System (<acronym>IDS</acronym>).</para> <warning> - <para>While the command name is <acronym>IDS</acronym> it is - not a replacement for a real intrusion detection system such + <para>This command is + not a replacement for a real <acronym>IDS</acronym> such as <package>security/snort</package>. As <command>freebsd-update</command> stores data on disk, the possibility of tampering is evident. While this possibility 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 + 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> + <acronym>USB</acronym> disk device. An alternative method + for providing <acronym>IDS</acronym> functionality using a + built-in utility is described in <xref + linkend="security-ids"/></para> </warning> - <para>The system will now be inspected, and a lengthy listing of - files, along with the &man.sha256.1; hash values for both the + <para>To begin the comparison, + specify the output file to save the results to:</para> + + <screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen> + + <para>The system will now be inspected and a lengthy listing of + files, along with the <acronym>SHA256</acronym> 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> + be sent to the specified output file.</para> <para>The entries in the listing are extremely long, but the output format may be easily parsed. For instance, to obtain a @@ -688,16 +688,13 @@ before running "/usr/sbin/freebsd-update <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. Other files, such as - kernel modules, may differ as + <filename>/etc/passwd</filename> will be modified if + users have been added to the system. + 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> - - <para>This system may be used as part of an elaborate upgrade - method, aside from the previously discussed version.</para> </sect2> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405061743.s46HhrK3038783>