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

      </para>

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

	    directories, such as <filename>/etc</filename>,

	    directories, such as <filename>/etc/</filename>,

	    <filename>/var</filename> and <filename>/usr</filename>,

	    <filename>/var/</filename> and <filename>/usr/</filename>,

	    to <filename>/etc</filename> in

	    to <filename>/etc/</filename> in preparation for the new

	    preparation for the new world.  The following command

	    world.  Use the <option>-n</option> option to first perform a

	    compares only those files that are essential for the

	    "dry-run", which will report what actions would be taken,

	    success of <buildtarget>installworld</buildtarget>.  For

	    but will not actually make any changes.  Refer to

	    instance, this step may add new groups, system accounts,

	    <xref linkend="etcupdate"/> for more details about this

	    or startup scripts which have been added to &os; since the

	    command:</para>

	    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>

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

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

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

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

    <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 to describe 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 describe the 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

	in <filename>/etc</filename>, and the configuration files in

	in <filename>/etc/</filename>, and the configuration files in

	<filename>/usr/src/etc</filename>.  This is the recommended

	<filename>/usr/src/etc/</filename>.  This is the recommended

	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

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

	recommended to first copy the existing

	<title>Bootstrapping <command>etcupdate</command> (First time only)</title>

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

      <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

	<important>

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

	  <para>This is only required the first time that

	and populates it with various system configuration files.

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

	Those files are then compared to the ones currently installed

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

	in the system.  Files that differ will be shown in

	  used.</para>

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

	</important>

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

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

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

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

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

	  needs to be bootstrapped, confirm that the following command

	file in its unmodified state, merge the temporary file with

	  shows only the local changes which have been made to the

	the currently installed file, or view the results

	  system.  Files that differ from their originally installed

	again.</para>

	  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

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

	<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>Choosing to install the unmodified temporary file will

	  <para>If this command fails with an error about a missing

	replace the current file with the new one.  For most

	  reference tree, then <command>etcupdate</command> needs to

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

	  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

	<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 <literal>RELEASE</literal> branch,

	customarily used for files where settings have been modified

	  this must be a copy of the source tree which includes all

	by the user.</para>

	  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

	<para>If you already have a copy of the &os; source tree which

	differences.</para>

	  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

	<screen>&prompt.user; <userinput>uname -v</userinput>

	system files, it will prompt for other options.  It may prompt

&os; <replaceable>YOURRELEASE</replaceable> #0 <replaceable>YOURREVISION</replaceable>: <replaceable>BUILDTIMESTAMP</replaceable>     <replaceable>BUILDUSER@BUILDHOST:/PATH/TO/KERNCONF</replaceable>

	to rebuild the password file and will finish up with an option

&prompt.user; <userinput>svn update -r <replaceable>YOURREVISION</replaceable></userinput></screen>

	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>If you do not have a copy of the matching source tree

	    updating <filename>/etc</filename>

	  readily available, or have already updated it to a newer

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

	  version and do not want to roll it back, the easiest way to

	  obtain a new copy of the matching tree is to download it

	  using <application>subversion</application>.  Here,

	  <replaceable>BRANCH</replaceable> will typically be one of

	  <literal>head</literal>, <literal>stable/<replaceable>MAJORVERSION</replaceable></literal> or

	  <literal>releng/<replaceable>MAJORVERSION</replaceable>.<replaceable>MINORVERSION</replaceable></literal>

	  (as listed at <link xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>):

	</para>

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

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

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

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

	  <procedure>

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

	    <step>

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

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

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

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

      </sect3>

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

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

	    </step>

	    <step>

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

	      <para>Merge in the changes from this directory as

	<title>Merging Configuration Files</title>

		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

	    during an update.  See <xref linkend="etcupdate-bootstrap"/>.</para>

		uses

	</warning>

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

	    </step>

	    <step>

	<para><command>etcupdate</command> should typically be run

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

	  twice in the update process. The first time should be

		been made in the intervening week by creating a

	  immediately before <buildtarget>installworld</buildtarget>

		recursive diff between the two directories:</para>

	  with the <option>-p</option> option, which updates 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.  The second time should be immediately after

	  <buildtarget>installworld</buildtarget> and without the

	  <option>-p</option> option, to update the remainder of the

	  configuration files.</para>

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

	<para>Each time the <command>etcupdate</command> utility is

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

	  used, it is recommended to first perform a "dry-run" using

	  the <option>-n</option> option.  This will report what

	  actions would be taken, but will not actually make any

	  changes.</para>

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

	<para>When <command>etcupdate</command> is run after

		differences than those between

	  <buildtarget>installworld</buildtarget> (with no further

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

	  arguments), it first moves it's backup of the old source

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

	  tree from <filename>/var/db/etcupdate/current/</filename> to

		differences is smaller, it is easier to migrate those

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

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

	  takes a copy of the new source tree from

	    </step>

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

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

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

	  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>

	    <step>

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

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

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

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

		directories:</para>

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

	<informaltable>

	    </step>

	  <tgroup cols="2">

	    <thead>

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

	    <step>

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

	      <para>Repeat this process whenever merging

	  will automatically perform post-install actions any time

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

	  they are updated:</para>

	    </step>

	  </procedure>

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

	<informaltable>

	    directory names:</para>

	  <tgroup cols="2">

	    <thead>

	      <row>

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

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

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

	</tip>

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

	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