FreeBSD Bugzilla – Attachment 166466 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.diff (text/plain), 18.54 KB, created by
Ben Woods
on 2016-02-03 00:51:36 UTC
(
hide
)
Description:
Patch to update handbook to replace mergemaster(8) with etcupdate(8)
Filename:
MIME Type:
Creator:
Ben Woods
Created:
2016-02-03 00:51:36 UTC
Size:
18.54 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 48129) >+++ 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 post install >+ merging of the configuration files, 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 to perform the post-<buildtarget>installworld</buildtarget> >+ merging of configuration files within <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-upgrade):</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 >@@ -1475,10 +1496,10 @@ > 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 >+ Refer to <xref linkend="etcupdate"/> for more detailed > instructions about this command:</para> > >- <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen> >+ <screen>&prompt.root; <userinput>etcupdate -p</userinput></screen> > </step> > > <step> >@@ -1492,7 +1513,7 @@ > <step> > <para>Update any remaining configuration files.</para> > >- <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen> >+ <screen>&prompt.root; <userinput>etcupdate</userinput></screen> > </step> > > <step> >@@ -1671,173 +1692,236 @@ > </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 for 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 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 > 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 > 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> >+ <para>Note that <command>etcupdate</command> has replaced >+ &man.mergemaster.8; as the recommended method to update >+ configuration files, as the latter required the user to review >+ all of the differences between the new source tree and the >+ installed system, and manually select which changes should be >+ 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 >- 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> >+ <para>If you have not previously performed an install world >+ using the <command>etcupdate</command> utility to perform >+ the post install merging of the configuration files, 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>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> >+ <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>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> >+ <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. If it shows an unexpected result, or if it fails >+ with an error about a missing reference tree, then it is >+ likely that <command>etcupdate</command> needs to be >+ bootstrapped.</para> > >- <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> >+ <screen>&prompt.root; <userinput>etcupdate diff | less</userinput></screen> > >- <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 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).</para> > >- <para>Choosing to view the results again will redisplay the file >- differences.</para> >+ <para>If you do not have a copy of the matching source tree >+ 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 >- 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>svn checkout -r <replaceable>YOURREVISION</replaceable> https://svn.FreeBSD.org/base/head/ <replaceable>/PATH/TO/SAVE/SOURCE/TREE</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>Once you have the source tree matching the current >+ world, use it to bootstrap <command>etcupdate</command>:</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.root; <userinput>etcupdate extract -s <replaceable>/PATH/TO/SAVED/SOURCE/TREE</replaceable></userinput></screen> >+ </sect3> > >- <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> >+ <sect3 xml:id="etcupdate-merge"> >+ <title>Merging Configuration Files (Post installworld)</title> > >- <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> >+ <para>Before using <command>etcupdate</command>, it is >+ recommended to have a backup or snapshot of >+ <filename>/etc</filename>. If using the >+ <command>copy</command> command to take a local backup, >+ include <option>-R</option> which does a recursive copy and >+ <option>-p</option> which preserves times and the ownerships >+ on files:</para> > >- <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> >+ <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> > >- <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 >+ post-<buildtarget>installworld</buildtarget>. 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>When run in the default mode (with no further arguments), >+ <command>etcupdate</command> first moves it's backup of the >+ old source tree from >+ <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> >-&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen> >+ <para>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> > >- <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>For each file that is updated a line will be output with a >+ leading character to indicate the action taken:</para> > >- <step> >- <para>When finished, remove the older of the two >- <filename>/var/tmp/root-*</filename> >- directories:</para> >+ <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> > >- <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen> >- </step> >+ <para>Note that for certain files <command>etcupdate</command> >+ will perform post-install actions any time they updated:</para> > >- <step> >- <para>Repeat this process whenever merging >- in changes to <filename>/etc</filename>.</para> >- </step> >- </procedure> >+ <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> > >- <para>Use &man.date.1; to automate the generation of the >- directory names:</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> > >- <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen> >- </tip> >- --> >+ </sect3> > </sect2> > > <sect2 xml:id="make-delete-old"> >@@ -1877,7 +1961,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 +2300,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