See <xref linkend="mergemaster"/> for more information about

      </para>

	<command>mergemaster</command>.</para>

	    Refer to <xref linkend="mergemaster"/> for more detailed

	    Refer to <xref linkend="etcupdate"/> for more detailed

	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>

	  <screen>&prompt.root; <userinput>etcupdate -p</userinput></screen>

	  <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>

	  <screen>&prompt.root; <userinput>etcupdate</userinput></screen>

    <sect2 xml:id="mergemaster">

    <sect2 xml:id="etcupdate">

      <title>Merging Configuration Files</title>

	<title>Merging Configuration Files</title>

	  <authorgroup>

	<authorgroup>

	    <author>

	  <author>

	      <personname>

	    <personname>

		<firstname>Tom</firstname>

	      <firstname>Tom</firstname>

		<surname>Rhodes</surname>

	      <surname>Rhodes</surname>

	      </personname>

	    </personname>

	      <contrib>Contributed by </contrib>

	    <contrib>Originally written for the mergemaster(8) utility by </contrib>

	    </author>

	  </author>

	  </authorgroup>

	</authorgroup>

	</info>

	<indexterm>

	<authorgroup>

	  <primary>

	  <author>

	    <command>mergemaster</command>

	    <personname>

	  </primary>

	      <firstname>Ben</firstname>

	</indexterm>

	      <surname>Woods</surname>

	    </personname>

	    <contrib>Modified to use the newer etcupdate(8) utility by </contrib>

	  </author>

	  <!-- Feb 2016 -->

	</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

	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

      <para>Note that <command>etcupdate</command> has replaced

	recommended to first copy the existing

	&man.mergemaster.8; as the recommended method to update

	<filename>/etc</filename> somewhere safe.  Include

	configuration files, as the latter required the user to review

	<option>-R</option> which does a recursive copy and

	all of the differences between the new source tree and the

	<option>-p</option> which preserves times and the ownerships

	installed system, and manually select which changes should be

	on files:</para>

	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

	<para>If you have not previously performed an install world

	temporary root environment, from <filename>/</filename> down,

	  using the <command>etcupdate</command> utility to perform

	and populates it with various system configuration files.

	  the post install merging of the configuration files, then

	Those files are then compared to the ones currently installed

	  it will need to be bootstrapped.  This step essentially

	in the system.  Files that differ will be shown in

	  involves providing <command>etcupdate</command> with a copy

	&man.diff.1; format, with the <option>+</option> sign

	  of the source tree that matches the

	representing added or modified lines, and <option>-</option>

	  <emphasis>currently</emphasis> installed world.</para>

	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>Next, <command>mergemaster</command> will display each

	<important>

	file that differs, and present options to: delete the new

	  <para>This is only required the first time that

	file, referred to as the temporary file, install the temporary

	  <command>etcupdate</command> is used to perform an install

	file in its unmodified state, merge the temporary file with

	  world, as it saves a copy of the new world each time it is

	the currently installed file, or view the results

	  used.</para>

	again.</para>

	</important>

      <para>Choosing to delete the temporary file will tell

	<para>To check whether <command>etcupdate</command>

	<command>mergemaster</command> to keep the current file

	  already has a copy of the correct source tree, or if it

	unchanged and to delete the new version.  This option is not

	  needs to be bootstrapped, confirm that the following command

	recommended.  To get help at any time, type

	  shows only the local changes which have been made to the

	<keycap>?</keycap> at the <command>mergemaster</command>

	  system.  If it shows an unexpected result, or if it fails

	prompt.  If the user chooses to skip a file, it will be

	  with an error about a missing reference tree, then it is

	presented again after all other files have been dealt

	  likely that <command>etcupdate</command> needs to be

	with.</para>

	  bootstrapped.</para>

      <para>Choosing to install the unmodified temporary file will

	<screen>&prompt.root; <userinput>etcupdate diff | less</userinput></screen>

	replace the current file with the new one.  For most

	unmodified files, this is the best option.</para>

      <para>Choosing to merge the file will present a text editor, and

	<para>To bootstrap <command>etcupdate</command>, you must

	the contents of both files.  The files can be merged by

	  first obtain a copy of the source tree which matches your

	reviewing both files side by side on the screen, and choosing

	  <emphasis>currently</emphasis> installed world.  This is not

	parts from both to create a finished product.  When the files

	  referring to the updated source tree which is about to to

	are compared side by side, <keycap>l</keycap> selects the left

	  be installed to the system, but a copy of the source tree

	contents and <keycap>r</keycap> selects contents from the

	  which matches the <emphasis>currently</emphasis> running

	right.  The final output will be a file consisting of both

	  system (used during the previous install or update).

	parts, which can then be installed.  This option is

	  If you are running a RELEASE branch, this must be a copy

	customarily used for files where settings have been modified

	  of the source tree which includes all changes for

	by the user.</para>

	  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

	<para>If you do not have a copy of the matching source tree

	differences.</para>

	  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

	<screen>&prompt.user; <userinput>svn checkout -r <replaceable>YOURREVISION</replaceable> https://svn.FreeBSD.org/base/head/ <replaceable>/PATH/TO/SAVE/SOURCE/TREE</replaceable></userinput></screen>

	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>

<!--

Probably not needed as changes should be minimal and mergemaster does

a good job of merging.

	<tip>

	  <title>Name the New Root Directory

	    (<filename>/var/tmp/root</filename>)

	    with a Time Stamp, so You Can Easily Compare Differences

	    Between Versions</title>

	  <para>Frequently rebuilding world entails frequently

	<para>Once you have the source tree matching the current

	    updating <filename>/etc</filename>

	  world, use it to bootstrap <command>etcupdate</command>:</para>

	    as well, which can be a bit of a chore.</para>

	  <para>To speed up this process, use the following

	<screen>&prompt.root; <userinput>etcupdate extract -s <replaceable>/PATH/TO/SAVED/SOURCE/TREE</replaceable></userinput></screen>

	    procedure to keep a copy of the last set of changed files

      </sect3>

	    that were merged into <filename>/etc</filename>.</para>

	  <procedure>

      <sect3 xml:id="etcupdate-merge">

	    <step>

	<title>Merging Configuration Files (Post installworld)</title>

	      <para>Make the world as normal.  When updating

		<filename>/etc</filename> and the

		other directories, give the target directory a name

		based on the current date:</para>

	      <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>

	<para>Before using <command>etcupdate</command>, it is

&prompt.root; <userinput>cd /usr/src/etc</userinput>

	  recommended to have a backup or snapshot of

&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \

	  <filename>/etc</filename>.  If using the

    distrib-dirs distribution</userinput></screen>

	  <command>copy</command> command to take a local backup,

	    </step>

	  include <option>-R</option> which does a recursive copy and

	  <option>-p</option> which preserves times and the ownerships

	  on files:</para>

	    <step>

	<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>

	      <para>Merge in the changes from this directory as

		outlined above.  <emphasis>Do not</emphasis> remove

		the <filename>/var/tmp/root-20130214</filename>

		directory when you have finished.</para>

	    </step>

	    <step>

	<warning>

	      <para>After downloading the latest version of the

	  <para><command>etcupdate</command> needs to be bootstrapped the

		source and remaking it, follow step 1.  Create a new

	    first time it is used to merge configuration files

		directory, which reflects the new date.  This example

	    post-<buildtarget>installworld</buildtarget>.  See

		uses

	    <xref linkend="etcupdate-bootstrap"/>.</para>

		<filename>/var/tmp/root-20130221</filename>.</para>

	</warning>

	    </step>

	    <step>

	<para>When run in the default mode (with no further arguments),

	      <para>Use &man.diff.1; to see the differences that have

	  <command>etcupdate</command> first moves it's backup of the

		been made in the intervening week by creating a

	  old source tree from

		recursive diff between the two directories:</para>

	  <filename>/var/db/etcupdate/current/</filename> to the

	  <filename>/var/db/etcupdate/previous/</filename>, and then

	  takes a copy of the new source tree from

	  <filename>/usr/src/</filename> to

	  <filename>/var/db/etcupdate/current/</filename>.</para>

	      <screen>&prompt.root; <userinput>cd /var/tmp</userinput>

	<para>Next, <command>etcupdate</command> compares the files in

&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>

	  the "current" and "previous" trees, and performs a 3-way merge

	  to the installed system.  New files will be added, removed

	  files will be deleted, and modified files will be updated,

	  only if it it will not cobber any local changes.  If the merge

	  encounters conflicts, then a version of the offending file

	  will be saved with conflict markers for future resolution, and

	  <command>etcupdate</command> will generate a warning.</para>

	      <para>Typically, this will be a much smaller set of

	<para>For each file that is updated a line will be output with a

		differences than those between

	  leading character to indicate the action taken:</para>

		<filename>/var/tmp/root-20130221/etc</filename> and

		<filename>/etc</filename>.  Because the set of

		differences is smaller, it is easier to migrate those

		changes across into <filename>/etc</filename>.</para>

	    </step>

	    <step>

	<informaltable>

	      <para>When finished, remove the older of the two

	  <tgroup cols="2">

		<filename>/var/tmp/root-*</filename>

	    <thead>

		directories:</para>

	      <row>

	        <entry>Leading character</entry>

	        <entry>Action taken</entry>

	      </row>

	    </thead>

	    <tbody>

	      <row>

	        <entry>A</entry>

	        <entry>Added</entry>

	      </row>

	      <row>

	        <entry>C</entry>

	        <entry>Conflict</entry>

	      </row>

	      <row>

	        <entry>D</entry>

	        <entry>Deleted</entry>

	      </row>

	      <row>

	        <entry>M</entry>

	        <entry>Merged</entry>

	      </row>

	      <row>

	        <entry>U</entry>

	        <entry>Updated</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</informaltable>

	      <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>

	<para>Note that for certain files <command>etcupdate</command>

	    </step>

	  will perform post-install actions any time they updated:</para>

	    <step>

	<informaltable>

	      <para>Repeat this process whenever merging

	  <tgroup cols="2">

		in changes to <filename>/etc</filename>.</para>

	    <thead>

	    </step>

	      <row>

	  </procedure>

	        <entry>Modified file</entry>

	        <entry>Post-install action</entry>

	      </row>

	    </thead>

	    <tbody>

	      <row>

	        <entry><filename>/etc/master.passwd</filename></entry>

	        <entry>&man.pwd.mkdb.8; is invoked</entry>

	      </row>

	      <row>

	        <entry><filename>/etc/login.conf</filename></entry>

	        <entry>&man.cap.mkdb.1; is invoked to update <filename>/etc/login.conf.db</filename></entry>

	      </row>

	      <row>

	        <entry><filename>/etc/mail/aliases</filename></entry>

	        <entry>&man.newaliases.1; is invoked *</entry>

	      </row>

	      <row>

	        <entry><filename>/etc/services</filename></entry>

	        <entry>&man.services.mkdb.8; is invoked</entry>

	      </row>

	      <row>

	        <entry><filename>/etc/localtime</filename></entry>

	        <entry>&man.tzsetup.8; is invoked if <filename>/var/db/zoneinfo</filename> exists</entry>

	      </row>

	      <row>

	        <entry><filename>/etc/motd</filename></entry>

	        <entry><command>/etc/rc.d/motd</command> is invoked *</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</informaltable>

	  <para>Use &man.date.1; to automate the generation of the

	<para>* These post-install actions only occur if

	    directory names:</para>

	  <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>

	  <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>

      </sect3>

	</tip>

	-->

	subsequent <command>mergemaster</command> have finished

	subsequent <command>etcupdate</command> have finished

      <command>mergemaster</command> as usual.  When done, reboot to

      <command>etcupdate</command> as usual.  When done, reboot to