--- 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
freebsd-update to abort. When in doubt,
backup /etc and just accept the merges.
- See for more information about
- mergemaster.
+
# Directory in which to store downloaded updates and temporary
# files used by &os; Update.
@@ -1279,6 +1278,17 @@
+ If you have not previously performed an
+ installworld using the
+ &man.etcupdate.8; utility to perform the merging of the
+ configuration files in /etc/, 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 .
+
+
+
+ Read /usr/src/UPDATING 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.
+ If the &man.etcupdate.8; utility has not previously
+ been used during an update to perform the merging of the
+ configuration files in /etc/, then it
+ will need to be bootstrapped using a copy of the &os;
+ source tree which matches the currently
+ installed system (pre-update):
+
+ &prompt.root; etcupdate extract -s /PATH/TO/PREVIOUS/SOURCE/TREE
+
+
+ If the build world process has previously been run on
this system, a copy of the previous build may still exist
in /usr/obj. To
@@ -1462,23 +1483,19 @@
Remaking the world will not update certain
- directories, such as /etc,
- /var and /usr,
+ directories, such as /etc/,
+ /var/ and /usr/,
with new or changed configuration files. The next step is
to perform some initial configuration file updates
- to /etc in
- preparation for the new world. The following command
- compares only those files that are essential for the
- success of installworld. 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
- installworld step will be able
- to use any new system accounts, groups, and scripts.
- Refer to for more detailed
- instructions about this command:
+ to /etc/ in preparation for the new
+ world. Use the option to first perform a
+ "dry-run", which will report what actions would be taken,
+ but will not actually make any changes. Refer to
+ for more details about this
+ command:
- &prompt.root; mergemaster -p
+ &prompt.root; etcupdate -pn | less
+&prompt.root; etcupdate -p
@@ -1490,9 +1507,13 @@
- Update any remaining configuration files.
+ Update any remaining configuration files.
+ Use the option to first perform a
+ "dry-run", which will report what actions would be taken,
+ but will not actually make any changes.
- &prompt.root; mergemaster -iF
+ &prompt.root; etcupdate -n | less
+&prompt.root; etcupdate
@@ -1671,173 +1692,322 @@
-
+
- Merging Configuration Files
+ Merging Configuration Files
-
-
-
- Tom
- Rhodes
-
- Contributed by
-
-
-
+
+
+
+ Tom
+ Rhodes
+
+ Originally written to describe the mergemaster(8) utility by
+
+
-
-
- mergemaster
-
-
+
+
+
+ Ben
+ Woods
+
+ Modified to describe the etcupdate(8) utility by
+
+
+
+
- &os; provides the &man.mergemaster.8; Bourne script to aid
+
+
+ etcupdate
+
+
+
+ &os; provides the &man.etcupdate.8; Bourne script to aid
in determining the differences between the configuration files
- in /etc, and the configuration files in
- /usr/src/etc. This is the recommended
+ in /etc/, and the configuration files in
+ /usr/src/etc/. This is the recommended
solution for keeping the system configuration files up to date
- with those located in the source tree.
+ 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.
- Before using mergemaster, it is
- recommended to first copy the existing
- /etc somewhere safe. Include
- which does a recursive copy and
- which preserves times and the ownerships
- on files:
+
+ Bootstrapping <command>etcupdate</command> (First time only)
- &prompt.root; cp -Rp /etc /etc.old
+ If you have not previously performed an installworld
+ using the &man.etcupdate.8; utility to perform the merging
+ of the configuration files in /etc/,
+ then it will need to be bootstrapped. This step essentially
+ involves providing etcupdate with a copy
+ of the source tree that matches the
+ currently installed world.
- When run, mergemaster builds a
- temporary root environment, from / 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 sign
- representing added or modified lines, and
- 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.
+
+ This is only required the first time that
+ etcupdate is used to perform an install
+ world, as it saves a copy of the new world each time it is
+ used.
+
- Next, mergemaster 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.
+ To check whether etcupdate
+ 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
+ sign representing added or modified
+ lines, and representing lines that will
+ be either removed completely or replaced with a new file.
- Choosing to delete the temporary file will tell
- mergemaster to keep the current file
- unchanged and to delete the new version. This option is not
- recommended. To get help at any time, type
- ? at the mergemaster
- prompt. If the user chooses to skip a file, it will be
- presented again after all other files have been dealt
- with.
+ &prompt.root; etcupdate diff | less
- 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.
+ If this command fails with an error about a missing
+ reference tree, then etcupdate needs to
+ be bootstrapped. If the output shows more changes than
+ expected, it is likely that etcupdate
+ 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.
- 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, l selects the left
- contents and r 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.
+ To bootstrap etcupdate, you must
+ first obtain a copy of the source tree which matches your
+ currently 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 currently 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).
- Choosing to view the results again will redisplay the file
- differences.
+ If you already have a copy of the &os; source tree which
+ was checked-out using subversion,
+ but it does not match the currently
+ running system, it is possible to roll the tree back to the
+ matching version:
- After mergemaster 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.
-
+ * These post-install actions only occur if
+ etcupdate is updating file directly to
+ /etc/ (the default behaviour). Refer to
+ the &man.etcupdate.8; man page for behaviour if the
+ option has been used to merge
+ configuration files in a non-default destination directory
+ (for example, when using boot environments).
+
+
+
+
+ Resolving Conflicts After Merging Configuration Files
+
+ If etcupdate has reported any
+ conflicts when updating the configuration files, it must be
+ run once more in "resolve" mode.
+
+ &prompt.root; etcupdate resolve
+
+ In this mode, etcupdate 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:
+
+
+
+
+
+ Prompt
+ Action Description
+
+
+
+
+ (p) postpone
+ Ignore this conflict for now. It will remain for subsequent calls of etcupdate resolve.
+
+
+ (df) diff-full
+ Show all changes made to the merged file as a unified &man.diff.1;.
+
+
+ (e) edit
+ Manually edit the merged file in an editor.
+
+
+ (r) resolved
+ Install the manually edited version of the file into the destination directory. Used after the (e) edit option.
+
+
+ (mf) mine-full
+ Use the version of the file in the running system and ignore any changes made to the file in the new source tree.
+
+
+ (tf) theirs-full
+ Use the version of the file from the new source tree and discard any local changes made to the file.
+
+
+ (h) help
+ Display the list of commands.
+
+
+
+
+
+
@@ -1877,7 +2047,7 @@
during the system upgrade process.
After the make installworld and the
- subsequent mergemaster have finished
+ subsequent etcupdate have finished
successfully, check for obsolete files and libraries:&prompt.root; cd /usr/src
@@ -2216,7 +2386,7 @@
/usr/obj via NFS. Then,
run shutdown now to go to single-user mode in
order to install the new kernel and world and run
- mergemaster as usual. When done, reboot to
+ etcupdate as usual. When done, reboot to
return to normal multi-user operations.
After verifying that everything on the test machine is