FreeBSD Bugzilla – Attachment 166719 Details for
Bug 206866
[handbook] Replace mergemaster(8) with newer etcupdate(8) utility for source upgrades
Home
|
New
|
Browse
|
Search
|
[?]
|
Reports
|
Help
|
New Account
|
Log In
Remember
[x]
|
Forgot Password
Login:
[x]
[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:
Patch to update handbook to replace mergemaster(8) with etcupdate(8)
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> >+ <!-- 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 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> >-<!-- >-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> >+ <screen>&prompt.user; <userinput>uname -v</userinput> >+&os; <replaceable>YOURRELEASE</replaceable> #0 <replaceable>YOURREVISION</replaceable>: <replaceable>BUILDTIMESTAMP</replaceable> <replaceable>BUILDUSER@BUILDHOST:/PATH/TO/KERNCONF</replaceable> >+&prompt.user; <userinput>svn update -r <replaceable>YOURREVISION</replaceable></userinput></screen> > >- <para>Frequently rebuilding world entails frequently >- updating <filename>/etc</filename> >- as well, which can be a bit of a chore.</para> >+ <para>If you do not have a copy of the matching source tree >+ readily available, or have already updated it to a newer >+ 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 >- procedure to keep a copy of the last set of changed files >- that were merged into <filename>/etc</filename>.</para> >+ <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> >- <step> >- <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> >+ <para>Once you have the source tree matching the current >+ world, use it to bootstrap <command>etcupdate</command>:</para> > >- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput> >-&prompt.root; <userinput>cd /usr/src/etc</userinput> >-&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \ >- distrib-dirs distribution</userinput></screen> >- </step> >+ <screen>&prompt.root; <userinput>etcupdate extract -s <replaceable>/PATH/TO/SAVED/SOURCE/TREE</replaceable></userinput></screen> >+ </sect3> > >- <step> >- <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> >+ <sect3 xml:id="etcupdate-merge"> >+ <title>Merging Configuration Files</title> > >- <step> >- <para>After downloading the latest version of the >- source and remaking it, follow step 1. Create a new >- directory, which reflects the new date. This example >- uses >- <filename>/var/tmp/root-20130221</filename>.</para> >- </step> >+ <warning> >+ <para><command>etcupdate</command> needs to be bootstrapped the >+ first time it is used to merge configuration files >+ during an update. See <xref linkend="etcupdate-bootstrap"/>.</para> >+ </warning> > >- <step> >- <para>Use &man.diff.1; to see the differences that have >- been made in the intervening week by creating a >- recursive diff between the two directories:</para> >+ <para><command>etcupdate</command> should typically be run >+ twice in the update process. The first time should be >+ immediately before <buildtarget>installworld</buildtarget> >+ 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> >-&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen> >+ <para>Each time the <command>etcupdate</command> utility is >+ 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 >- differences than those between >- <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> >+ <para>When <command>etcupdate</command> is run after >+ <buildtarget>installworld</buildtarget> (with no further >+ arguments), it first moves it's backup of the old source >+ tree from <filename>/var/db/etcupdate/current/</filename> to >+ <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>. >+ 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>When finished, remove the older of the two >- <filename>/var/tmp/root-*</filename> >- directories:</para> >+ <para>For each file that is updated a line will be output with a >+ leading character to indicate the action taken:</para> > >- <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen> >- </step> >+ <informaltable> >+ <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>Repeat this process whenever merging >- in changes to <filename>/etc</filename>.</para> >- </step> >- </procedure> >+ <para>Note that for certain files, <command>etcupdate</command> >+ will automatically perform post-install actions any time >+ they are updated:</para> > >- <para>Use &man.date.1; to automate the generation of the >- directory names:</para> >+ <informaltable> >+ <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> >- </tip> >- --> >+ <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
You cannot view the attachment while viewing its details because your browser does not support IFRAMEs.
View the attachment on a separate page
.
View Attachment As Diff
View Attachment As Raw
Actions:
View
|
Diff
Attachments on
bug 206866
:
166466
|
166467
|
166719
|
166720