Attachment 166719 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-seconddraft.diff (text/plain), 23.99 KB, created by Ben Woods on 2016-02-07 21:29:45 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Ben Woods

Created: 2016-02-07 21:29:45 UTC

Size: 23.99 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 48153)
>+++ 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 merging of the
>+	  configuration files in <filename>/etc/</filename>, 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 during an update to perform the merging of the
>+	    configuration files in <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-update):</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
>@@ -1462,23 +1483,19 @@
> 
> 	<step>
> 	  <para>Remaking the world will not update certain
>-	    directories, such as <filename>/etc</filename>,
>-	    <filename>/var</filename> and <filename>/usr</filename>,
>+	    directories, such as <filename>/etc/</filename>,
>+	    <filename>/var/</filename> and <filename>/usr/</filename>,
> 	    with new or changed configuration files.  The next step is
> 	    to perform some initial configuration file updates
>-	    to <filename>/etc</filename> in
>-	    preparation for the new world.  The following command
>-	    compares only those files that are essential for the
>-	    success of <buildtarget>installworld</buildtarget>.  For
>-	    instance, this step may add new groups, system accounts,
>-	    or startup scripts which have been added to &os; since the
>-	    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
>-	    instructions about this command:</para>
>+	    to <filename>/etc/</filename> in preparation for the new
>+	    world.  Use the <option>-n</option> option to first perform a
>+	    "dry-run", which will report what actions would be taken,
>+	    but will not actually make any changes.  Refer to
>+	    <xref linkend="etcupdate"/> for more details about this
>+	    command:</para>
> 
>-	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
>+	  <screen>&prompt.root; <userinput>etcupdate -pn | less</userinput>
>+&prompt.root; <userinput>etcupdate -p</userinput></screen>
> 	</step>
> 
> 	<step>
>@@ -1490,9 +1507,13 @@
> 	</step>
> 
> 	<step>
>-	  <para>Update any remaining configuration files.</para>
>+	  <para>Update any remaining configuration files.
>+	    Use the <option>-n</option> option to first perform a
>+	    "dry-run", which will report what actions would be taken,
>+	    but will not actually make any changes.</para>
> 
>-	  <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
>+	  <screen>&prompt.root; <userinput>etcupdate -n | less</userinput>
>+&prompt.root; <userinput>etcupdate</userinput></screen>
> 	</step>
> 
> 	<step>
>@@ -1671,173 +1692,322 @@
>       </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 to describe 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 describe the 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
>+	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>
>+      <sect3 xml:id="etcupdate-bootstrap">
>+	<title>Bootstrapping <command>etcupdate</command> (First time only)</title>
> 
>-      <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
>+	<para>If you have not previously performed an <buildtarget>installworld</buildtarget>
>+	  using the &man.etcupdate.8; utility to perform the merging
>+	  of the configuration files in <filename>/etc/</filename>,
>+	  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>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>
>+	<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>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>
>+	<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.  Files that differ from their originally installed
>+	  state  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.</para>
> 
>-      <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>
>+	<screen>&prompt.root; <userinput>etcupdate diff | less</userinput></screen>
> 
>-      <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>
>+	  <para>If this command fails with an error about a missing
>+	  reference tree, then <command>etcupdate</command> needs to
>+	  be bootstrapped.  If the output shows more changes than
>+	  expected, it is likely that <command>etcupdate</command>
>+	  has either been bootstrapped from a source tree that doesn't
>+	  match the running system or was not run after the last
>+	  system update.  In either scenario, the solution is to
>+	  repeat the bootstrap process.</para>
> 
>-      <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 <literal>RELEASE</literal> 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 already have a copy of the &os; source tree which
>+	  was checked-out using <application>subversion</application>,
>+	  but it does not match the <emphasis>currently</emphasis>
>+	  running system, it is possible to roll the tree back to the
>+	  matching version:</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>
>-
>+	<para>* These post-install actions only occur if
>+	  <command>etcupdate</command> is updating file directly to
>+	  <filename>/etc/</filename> (the default behaviour).  Refer to
>+	  the &man.etcupdate.8; man page for behaviour if the
>+	  <option>-D</option> option has been used to merge
>+	  configuration files in a non-default destination directory
>+	  (for example, when using boot environments).</para>
>+
>+      </sect3>
>+
>+      <sect3 xml:id="etcupdate-resolve">
>+	<title>Resolving Conflicts After Merging Configuration Files</title>
>+
>+	<para>If <command>etcupdate</command> has reported any
>+	  conflicts when updating the configuration files, it must be
>+	  run once more in "resolve" mode.</para>
>+
>+	<screen>&prompt.root; <userinput>etcupdate resolve</userinput></screen>
>+
>+	<para>In this mode, <command>etcupdate</command> iterates over
>+	  any existing conflicts and prompts the user for actions to
>+	  take on each conflicted file.  For each file, the following
>+	  actions are available:</para>
>+
>+	<informaltable>
>+	  <tgroup cols="2">
>+	    <thead>
>+	      <row>
>+	        <entry>Prompt</entry>
>+	        <entry>Action Description</entry>
>+	      </row>
>+	    </thead>
>+	    <tbody>
>+	      <row>
>+	        <entry>(p) postpone</entry>
>+	        <entry>Ignore this conflict for now.  It will remain for subsequent calls of <command>etcupdate resolve</command>.</entry>
>+	      </row>
>+	      <row>
>+	        <entry>(df) diff-full</entry>
>+	        <entry>Show all changes made to the merged file as a unified &man.diff.1;.</entry>
>+	      </row>
>+	      <row>
>+	        <entry>(e) edit</entry>
>+	        <entry>Manually edit the merged file in an editor.</entry>
>+	      </row>
>+	      <row>
>+	        <entry>(r) resolved</entry>
>+	        <entry>Install the manually edited version of the file into the destination directory.  Used after the (e) edit option.</entry>
>+	      </row>
>+	      <row>
>+	        <entry>(mf) mine-full</entry>
>+	        <entry>Use the version of the file in the running system and ignore any changes made to the file in the new source tree.</entry>
>+	      </row>
>+	      <row>
>+	        <entry>(tf) theirs-full</entry>
>+	        <entry>Use the version of the file from the new source tree and discard any local changes made to the file.</entry>
>+	      </row>
>+	      <row>
>+	        <entry>(h) help</entry>
>+	        <entry>Display the list of commands.</entry>
>+	      </row>
>+	    </tbody>
>+	  </tgroup>
>+	</informaltable>
>+	
>+      </sect3>
>     </sect2>
> 
>     <sect2 xml:id="make-delete-old">
>@@ -1877,7 +2047,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 +2386,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