Attachment 166466 Details for Bug 206866 – Patch to update handbook to replace mergemaster(8) with etcupdate(8)

[patch] Patch to update handbook to replace mergemaster(8) with etcupdate(8)

etcupdate.diff (text/plain), 18.54 KB, created by Ben Woods on 2016-02-03 00:51:36 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Ben Woods

Created: 2016-02-03 00:51:36 UTC

Size: 18.54 KB

patch

obsolete

>Index: en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
>===================================================================
>--- en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml	(revision 48129)
>+++ en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml	(working copy)
>@@ -247,8 +247,7 @@
> 	Merges are either accepted, open an editor, or cause
> 	<command>freebsd-update</command> to abort.  When in doubt,
> 	backup <filename>/etc</filename> and just accept the merges.
>-	See <xref linkend="mergemaster"/> for more information about
>-	<command>mergemaster</command>.</para>
>+      </para>
> 
>       <programlisting># Directory in which to store downloaded updates and temporary
> # files used by &os; Update.
>@@ -1279,6 +1278,17 @@
>       </step>
> 
>       <step>
>+	<para>If you have not previously performed an 
>+	  <buildtarget>installworld</buildtarget> using the
>+	  &man.etcupdate.8; utility to perform the post install
>+	  merging of the configuration files, then it will need to be
>+	  bootstrapped.  For details on how to perform the
>+	  bootstrapping procedure, or how to determine whether it is
>+	  required, see <xref linkend="etcupdate-bootstrap"/>.
>+	</para>
>+      </step>
>+
>+      <step>
> 	<para>Read <filename>/usr/src/UPDATING</filename> for any
> 	  extra steps necessary for that version of the source.  This
> 	  file contains important information about potential problems
>@@ -1370,6 +1380,17 @@
> 	  the function of each command.</para>
> 
> 	<step>
>+	  <para>If the &man.etcupdate.8; utility has not previously
>+	    been used to perform the post-<buildtarget>installworld</buildtarget>
>+	    merging of configuration files within <filename>/etc/</filename>,
>+	    then it will need to be bootstrapped using a copy of the
>+	    &os; source tree which matches the <emphasis>currently</emphasis>
>+	    installed system (pre-upgrade):</para>
>+
>+	  <screen>&prompt.root; <userinput>etcupdate extract -s <replaceable>/PATH/TO/PREVIOUS/SOURCE/TREE</replaceable></userinput></screen>
>+	</step>
>+
>+	<step>
> 	  <para>If the build world process has previously been run on
> 	    this system, a copy of the previous build may still exist
> 	    in <filename>/usr/obj</filename>.  To
>@@ -1475,10 +1496,10 @@
> 	    last update.  This is necessary so that the
> 	    <buildtarget>installworld</buildtarget> step will be able
> 	    to use any new system accounts, groups, and scripts.
>-	    Refer to <xref linkend="mergemaster"/> for more detailed
>+	    Refer to <xref linkend="etcupdate"/> for more detailed
> 	    instructions about this command:</para>
> 
>-	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
>+	  <screen>&prompt.root; <userinput>etcupdate -p</userinput></screen>
> 	</step>
> 
> 	<step>
>@@ -1492,7 +1513,7 @@
> 	<step>
> 	  <para>Update any remaining configuration files.</para>
> 
>-	  <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
>+	  <screen>&prompt.root; <userinput>etcupdate</userinput></screen>
> 	</step>
> 
> 	<step>
>@@ -1671,173 +1692,236 @@
>       </note>
>     </sect2>
> 
>-    <sect2 xml:id="mergemaster">
>+    <sect2 xml:id="etcupdate">
>       <info>
>-      <title>Merging Configuration Files</title>
>+	<title>Merging Configuration Files</title>
> 
>-	  <authorgroup>
>-	    <author>
>-	      <personname>
>-		<firstname>Tom</firstname>
>-		<surname>Rhodes</surname>
>-	      </personname>
>-	      <contrib>Contributed by </contrib>
>-	    </author>
>-	  </authorgroup>
>-	</info>
>+	<authorgroup>
>+	  <author>
>+	    <personname>
>+	      <firstname>Tom</firstname>
>+	      <surname>Rhodes</surname>
>+	    </personname>
>+	    <contrib>Originally written for the mergemaster(8) utility by </contrib>
>+	  </author>
>+	</authorgroup>
> 
>-	<indexterm>
>-	  <primary>
>-	    <command>mergemaster</command>
>-	  </primary>
>-	</indexterm>
>+	<authorgroup>
>+	  <author>
>+	    <personname>
>+	      <firstname>Ben</firstname>
>+	      <surname>Woods</surname>
>+	    </personname>
>+	    <contrib>Modified to use the newer etcupdate(8) utility by </contrib>
>+	  </author>
>+	  
>+	</authorgroup>
>+      </info>
> 
>-      <para>&os; provides the &man.mergemaster.8; Bourne script to aid
>+      <indexterm>
>+	<primary>
>+	  <command>etcupdate</command>
>+	</primary>
>+      </indexterm>
>+
>+      <para>&os; provides the &man.etcupdate.8; Bourne script to aid
> 	in determining the differences between the configuration files
> 	in <filename>/etc</filename>, and the configuration files in
> 	<filename>/usr/src/etc</filename>.  This is the recommended
> 	solution for keeping the system configuration files up to date
>-	with those located in the source tree.</para>
>+	with those located in the source tree, as it uses a 3-way
>+	merge algorithm to compare the source tree used for the
>+	previous installworld and current installworld, and
>+	automatically merges any updates to the installed system
>+	without clobbering local changes which have been made to the
>+	system.</para>
> 
>-      <para>Before using <command>mergemaster</command>, it is
>-	recommended to first copy the existing
>-	<filename>/etc</filename> somewhere safe.  Include
>-	<option>-R</option> which does a recursive copy and
>-	<option>-p</option> which preserves times and the ownerships
>-	on files:</para>
>+      <para>Note that <command>etcupdate</command> has replaced
>+	&man.mergemaster.8; as the recommended method to update
>+	configuration files, as the latter required the user to review
>+	all of the differences between the new source tree and the
>+	installed system, and manually select which changes should be
>+	applied, even if there had been no local changes made to the
>+	file from the previous source tree used to install it.</para>
> 
>-      <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
>+      <sect3 xml:id="etcupdate-bootstrap">
>+	<title>Bootstrapping <command>etcupdate</command> (First time only)</title>
> 
>-      <para>When run, <command>mergemaster</command> builds a
>-	temporary root environment, from <filename>/</filename> down,
>-	and populates it with various system configuration files.
>-	Those files are then compared to the ones currently installed
>-	in the system.  Files that differ will be shown in
>-	&man.diff.1; format, with the <option>+</option> sign
>-	representing added or modified lines, and <option>-</option>
>-	representing lines that will be either removed completely or
>-	replaced with a new file.  Refer to &man.diff.1; for more
>-	information about how file differences are shown.</para>
>+	<para>If you have not previously performed an install world
>+	  using the <command>etcupdate</command> utility to perform
>+	  the post install merging of the configuration files, then
>+	  it will need to be bootstrapped.  This step essentially
>+	  involves providing <command>etcupdate</command> with a copy
>+	  of the source tree that matches the
>+	  <emphasis>currently</emphasis> installed world.</para>
> 
>-      <para>Next, <command>mergemaster</command> will display each
>-	file that differs, and present options to: delete the new
>-	file, referred to as the temporary file, install the temporary
>-	file in its unmodified state, merge the temporary file with
>-	the currently installed file, or view the results
>-	again.</para>
>+	<important>
>+	  <para>This is only required the first time that
>+	  <command>etcupdate</command> is used to perform an install
>+	  world, as it saves a copy of the new world each time it is
>+	  used.</para>
>+	</important>
> 
>-      <para>Choosing to delete the temporary file will tell
>-	<command>mergemaster</command> to keep the current file
>-	unchanged and to delete the new version.  This option is not
>-	recommended.  To get help at any time, type
>-	<keycap>?</keycap> at the <command>mergemaster</command>
>-	prompt.  If the user chooses to skip a file, it will be
>-	presented again after all other files have been dealt
>-	with.</para>
>+	<para>To check whether <command>etcupdate</command>
>+	  already has a copy of the correct source tree, or if it
>+	  needs to be bootstrapped, confirm that the following command
>+	  shows only the local changes which have been made to the
>+	  system.  If it shows an unexpected result, or if it fails
>+	  with an error about a missing reference tree, then it is
>+	  likely that <command>etcupdate</command> needs to be
>+	  bootstrapped.</para>
> 
>-      <para>Choosing to install the unmodified temporary file will
>-	replace the current file with the new one.  For most
>-	unmodified files, this is the best option.</para>
>+	<screen>&prompt.root; <userinput>etcupdate diff | less</userinput></screen>
> 
>-      <para>Choosing to merge the file will present a text editor, and
>-	the contents of both files.  The files can be merged by
>-	reviewing both files side by side on the screen, and choosing
>-	parts from both to create a finished product.  When the files
>-	are compared side by side, <keycap>l</keycap> selects the left
>-	contents and <keycap>r</keycap> selects contents from the
>-	right.  The final output will be a file consisting of both
>-	parts, which can then be installed.  This option is
>-	customarily used for files where settings have been modified
>-	by the user.</para>
>+	<para>To bootstrap <command>etcupdate</command>, you must
>+	  first obtain a copy of the source tree which matches your
>+	  <emphasis>currently</emphasis> installed world.  This is not
>+	  referring to the updated source tree which is about to to
>+	  be installed to the system, but a copy of the source tree
>+	  which matches the <emphasis>currently</emphasis> running
>+	  system (used during the previous install or update).
>+	  If you are running a RELEASE branch, this must be a copy
>+	  of the source tree which includes all changes for
>+	  security/errata updates which have been installed (this
>+	  applies even if you have previously been performing binary
>+	  updates using the &man.freebsd-update.8; utility).</para>
> 
>-      <para>Choosing to view the results again will redisplay the file
>-	differences.</para>
>+	<para>If you do not have a copy of the matching source tree
>+	  readily available, the easiest way to obtain it is to
>+	  download it using <application>subversion</application>:
>+	</para>
> 
>-      <para>After <command>mergemaster</command> is done with the
>-	system files, it will prompt for other options.  It may prompt
>-	to rebuild the password file and will finish up with an option
>-	to remove left-over temporary files.</para>
>-
>+      </sect3>
>     </sect2>
> 
>     <sect2 xml:id="make-delete-old">
>@@ -1877,7 +1961,7 @@
> 	during the system upgrade process.</para>
> 
>       <para>After the <command>make installworld</command> and the
>-	subsequent <command>mergemaster</command> have finished
>+	subsequent <command>etcupdate</command> have finished
> 	successfully, check for obsolete files and libraries:</para>
> 
>       <screen>&prompt.root; <userinput>cd /usr/src</userinput>
>@@ -2216,7 +2300,7 @@
>       <filename>/usr/obj</filename> via <acronym>NFS</acronym>.  Then,
>       run <command>shutdown now</command> to go to single-user mode in
>       order to install the new kernel and world and run
>-      <command>mergemaster</command> as usual.  When done, reboot to
>+      <command>etcupdate</command> as usual.  When done, reboot to
>       return to normal multi-user operations.</para>
> 
>     <para>After verifying that everything on the test machine is

Actions: View | Diff

Attachments on bug 206866: 166466 | 166467 | 166719 | 166720