View | Details | Raw Unified | Return to bug 206866 | Differences between
and this patch

Collapse All | Expand All

(-)en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml (-143 / +227 lines)
Lines 247-254 Link Here
247
	Merges are either accepted, open an editor, or cause
247
	Merges are either accepted, open an editor, or cause
248
	<command>freebsd-update</command> to abort.  When in doubt,
248
	<command>freebsd-update</command> to abort.  When in doubt,
249
	backup <filename>/etc</filename> and just accept the merges.
249
	backup <filename>/etc</filename> and just accept the merges.
250
	See <xref linkend="mergemaster"/> for more information about
250
      </para>
251
	<command>mergemaster</command>.</para>
252
251
253
      <programlisting># Directory in which to store downloaded updates and temporary
252
      <programlisting># Directory in which to store downloaded updates and temporary
254
# files used by &os; Update.
253
# files used by &os; Update.
Lines 1279-1284 Link Here
1279
      </step>
1278
      </step>
1280
1279
1281
      <step>
1280
      <step>
1281
	<para>If you have not previously performed an 
1282
	  <buildtarget>installworld</buildtarget> using the
1283
	  &man.etcupdate.8; utility to perform the post install
1284
	  merging of the configuration files, then it will need to be
1285
	  bootstrapped.  For details on how to perform the
1286
	  bootstrapping procedure, or how to determine whether it is
1287
	  required, see <xref linkend="etcupdate-bootstrap"/>.
1288
	</para>
1289
      </step>
1290
1291
      <step>
1282
	<para>Read <filename>/usr/src/UPDATING</filename> for any
1292
	<para>Read <filename>/usr/src/UPDATING</filename> for any
1283
	  extra steps necessary for that version of the source.  This
1293
	  extra steps necessary for that version of the source.  This
1284
	  file contains important information about potential problems
1294
	  file contains important information about potential problems
Lines 1370-1375 Link Here
1370
	  the function of each command.</para>
1380
	  the function of each command.</para>
1371
1381
1372
	<step>
1382
	<step>
1383
	  <para>If the &man.etcupdate.8; utility has not previously
1384
	    been used to perform the post-<buildtarget>installworld</buildtarget>
1385
	    merging of configuration files within <filename>/etc/</filename>,
1386
	    then it will need to be bootstrapped using a copy of the
1387
	    &os; source tree which matches the <emphasis>currently</emphasis>
1388
	    installed system (pre-upgrade):</para>
1389
1390
	  <screen>&prompt.root; <userinput>etcupdate extract -s <replaceable>/PATH/TO/PREVIOUS/SOURCE/TREE</replaceable></userinput></screen>
1391
	</step>
1392
1393
	<step>
1373
	  <para>If the build world process has previously been run on
1394
	  <para>If the build world process has previously been run on
1374
	    this system, a copy of the previous build may still exist
1395
	    this system, a copy of the previous build may still exist
1375
	    in <filename>/usr/obj</filename>.  To
1396
	    in <filename>/usr/obj</filename>.  To
Lines 1475-1484 Link Here
1475
	    last update.  This is necessary so that the
1496
	    last update.  This is necessary so that the
1476
	    <buildtarget>installworld</buildtarget> step will be able
1497
	    <buildtarget>installworld</buildtarget> step will be able
1477
	    to use any new system accounts, groups, and scripts.
1498
	    to use any new system accounts, groups, and scripts.
1478
	    Refer to <xref linkend="mergemaster"/> for more detailed
1499
	    Refer to <xref linkend="etcupdate"/> for more detailed
1479
	    instructions about this command:</para>
1500
	    instructions about this command:</para>
1480
1501
1481
	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
1502
	  <screen>&prompt.root; <userinput>etcupdate -p</userinput></screen>
1482
	</step>
1503
	</step>
1483
1504
1484
	<step>
1505
	<step>
Lines 1492-1498 Link Here
1492
	<step>
1513
	<step>
1493
	  <para>Update any remaining configuration files.</para>
1514
	  <para>Update any remaining configuration files.</para>
1494
1515
1495
	  <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
1516
	  <screen>&prompt.root; <userinput>etcupdate</userinput></screen>
1496
	</step>
1517
	</step>
1497
1518
1498
	<step>
1519
	<step>
Lines 1671-1843 Link Here
1671
      </note>
1692
      </note>
1672
    </sect2>
1693
    </sect2>
1673
1694
1674
    <sect2 xml:id="mergemaster">
1695
    <sect2 xml:id="etcupdate">
1675
      <info>
1696
      <info>
1676
      <title>Merging Configuration Files</title>
1697
	<title>Merging Configuration Files</title>
1677
1698
1678
	  <authorgroup>
1699
	<authorgroup>
1679
	    <author>
1700
	  <author>
1680
	      <personname>
1701
	    <personname>
1681
		<firstname>Tom</firstname>
1702
	      <firstname>Tom</firstname>
1682
		<surname>Rhodes</surname>
1703
	      <surname>Rhodes</surname>
1683
	      </personname>
1704
	    </personname>
1684
	      <contrib>Contributed by </contrib>
1705
	    <contrib>Originally written for the mergemaster(8) utility by </contrib>
1685
	    </author>
1706
	  </author>
1686
	  </authorgroup>
1707
	</authorgroup>
1687
	</info>
1688
1708
1689
	<indexterm>
1709
	<authorgroup>
1690
	  <primary>
1710
	  <author>
1691
	    <command>mergemaster</command>
1711
	    <personname>
1692
	  </primary>
1712
	      <firstname>Ben</firstname>
1693
	</indexterm>
1713
	      <surname>Woods</surname>
1714
	    </personname>
1715
	    <contrib>Modified to use the newer etcupdate(8) utility by </contrib>
1716
	  </author>
1717
	  <!-- Feb 2016 -->
1718
	</authorgroup>
1719
      </info>
1694
1720
1695
      <para>&os; provides the &man.mergemaster.8; Bourne script to aid
1721
      <indexterm>
1722
	<primary>
1723
	  <command>etcupdate</command>
1724
	</primary>
1725
      </indexterm>
1726
1727
      <para>&os; provides the &man.etcupdate.8; Bourne script to aid
1696
	in determining the differences between the configuration files
1728
	in determining the differences between the configuration files
1697
	in <filename>/etc</filename>, and the configuration files in
1729
	in <filename>/etc</filename>, and the configuration files in
1698
	<filename>/usr/src/etc</filename>.  This is the recommended
1730
	<filename>/usr/src/etc</filename>.  This is the recommended
1699
	solution for keeping the system configuration files up to date
1731
	solution for keeping the system configuration files up to date
1700
	with those located in the source tree.</para>
1732
	with those located in the source tree, as it uses a 3-way
1733
	merge algorithm to compare the source tree used for the
1734
	previous installworld and current installworld, and
1735
	automatically merges any updates to the installed system
1736
	without clobbering local changes which have been made to the
1737
	system.</para>
1701
1738
1702
      <para>Before using <command>mergemaster</command>, it is
1739
      <para>Note that <command>etcupdate</command> has replaced
1703
	recommended to first copy the existing
1740
	&man.mergemaster.8; as the recommended method to update
1704
	<filename>/etc</filename> somewhere safe.  Include
1741
	configuration files, as the latter required the user to review
1705
	<option>-R</option> which does a recursive copy and
1742
	all of the differences between the new source tree and the
1706
	<option>-p</option> which preserves times and the ownerships
1743
	installed system, and manually select which changes should be
1707
	on files:</para>
1744
	applied, even if there had been no local changes made to the
1745
	file from the previous source tree used to install it.</para>
1708
1746
1709
      <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
1747
      <sect3 xml:id="etcupdate-bootstrap">
1748
	<title>Bootstrapping <command>etcupdate</command> (First time only)</title>
1710
1749
1711
      <para>When run, <command>mergemaster</command> builds a
1750
	<para>If you have not previously performed an install world
1712
	temporary root environment, from <filename>/</filename> down,
1751
	  using the <command>etcupdate</command> utility to perform
1713
	and populates it with various system configuration files.
1752
	  the post install merging of the configuration files, then
1714
	Those files are then compared to the ones currently installed
1753
	  it will need to be bootstrapped.  This step essentially
1715
	in the system.  Files that differ will be shown in
1754
	  involves providing <command>etcupdate</command> with a copy
1716
	&man.diff.1; format, with the <option>+</option> sign
1755
	  of the source tree that matches the
1717
	representing added or modified lines, and <option>-</option>
1756
	  <emphasis>currently</emphasis> installed world.</para>
1718
	representing lines that will be either removed completely or
1719
	replaced with a new file.  Refer to &man.diff.1; for more
1720
	information about how file differences are shown.</para>
1721
1757
1722
      <para>Next, <command>mergemaster</command> will display each
1758
	<important>
1723
	file that differs, and present options to: delete the new
1759
	  <para>This is only required the first time that
1724
	file, referred to as the temporary file, install the temporary
1760
	  <command>etcupdate</command> is used to perform an install
1725
	file in its unmodified state, merge the temporary file with
1761
	  world, as it saves a copy of the new world each time it is
1726
	the currently installed file, or view the results
1762
	  used.</para>
1727
	again.</para>
1763
	</important>
1728
1764
1729
      <para>Choosing to delete the temporary file will tell
1765
	<para>To check whether <command>etcupdate</command>
1730
	<command>mergemaster</command> to keep the current file
1766
	  already has a copy of the correct source tree, or if it
1731
	unchanged and to delete the new version.  This option is not
1767
	  needs to be bootstrapped, confirm that the following command
1732
	recommended.  To get help at any time, type
1768
	  shows only the local changes which have been made to the
1733
	<keycap>?</keycap> at the <command>mergemaster</command>
1769
	  system.  If it shows an unexpected result, or if it fails
1734
	prompt.  If the user chooses to skip a file, it will be
1770
	  with an error about a missing reference tree, then it is
1735
	presented again after all other files have been dealt
1771
	  likely that <command>etcupdate</command> needs to be
1736
	with.</para>
1772
	  bootstrapped.</para>
1737
1773
1738
      <para>Choosing to install the unmodified temporary file will
1774
	<screen>&prompt.root; <userinput>etcupdate diff | less</userinput></screen>
1739
	replace the current file with the new one.  For most
1740
	unmodified files, this is the best option.</para>
1741
1775
1742
      <para>Choosing to merge the file will present a text editor, and
1776
	<para>To bootstrap <command>etcupdate</command>, you must
1743
	the contents of both files.  The files can be merged by
1777
	  first obtain a copy of the source tree which matches your
1744
	reviewing both files side by side on the screen, and choosing
1778
	  <emphasis>currently</emphasis> installed world.  This is not
1745
	parts from both to create a finished product.  When the files
1779
	  referring to the updated source tree which is about to to
1746
	are compared side by side, <keycap>l</keycap> selects the left
1780
	  be installed to the system, but a copy of the source tree
1747
	contents and <keycap>r</keycap> selects contents from the
1781
	  which matches the <emphasis>currently</emphasis> running
1748
	right.  The final output will be a file consisting of both
1782
	  system (used during the previous install or update).
1749
	parts, which can then be installed.  This option is
1783
	  If you are running a RELEASE branch, this must be a copy
1750
	customarily used for files where settings have been modified
1784
	  of the source tree which includes all changes for
1751
	by the user.</para>
1785
	  security/errata updates which have been installed (this
1786
	  applies even if you have previously been performing binary
1787
	  updates using the &man.freebsd-update.8; utility).</para>
1752
1788
1753
      <para>Choosing to view the results again will redisplay the file
1789
	<para>If you do not have a copy of the matching source tree
1754
	differences.</para>
1790
	  readily available, the easiest way to obtain it is to
1791
	  download it using <application>subversion</application>:
1792
	</para>
1755
1793
1756
      <para>After <command>mergemaster</command> is done with the
1794
	<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>
1757
	system files, it will prompt for other options.  It may prompt
1758
	to rebuild the password file and will finish up with an option
1759
	to remove left-over temporary files.</para>
1760
<!--
1761
Probably not needed as changes should be minimal and mergemaster does
1762
a good job of merging.
1763
	<tip>
1764
	  <title>Name the New Root Directory
1765
	    (<filename>/var/tmp/root</filename>)
1766
	    with a Time Stamp, so You Can Easily Compare Differences
1767
	    Between Versions</title>
1768
1795
1769
	  <para>Frequently rebuilding world entails frequently
1796
	<para>Once you have the source tree matching the current
1770
	    updating <filename>/etc</filename>
1797
	  world, use it to bootstrap <command>etcupdate</command>:</para>
1771
	    as well, which can be a bit of a chore.</para>
1772
1798
1773
	  <para>To speed up this process, use the following
1799
	<screen>&prompt.root; <userinput>etcupdate extract -s <replaceable>/PATH/TO/SAVED/SOURCE/TREE</replaceable></userinput></screen>
1774
	    procedure to keep a copy of the last set of changed files
1800
      </sect3>
1775
	    that were merged into <filename>/etc</filename>.</para>
1776
1801
1777
	  <procedure>
1802
      <sect3 xml:id="etcupdate-merge">
1778
	    <step>
1803
	<title>Merging Configuration Files (Post installworld)</title>
1779
	      <para>Make the world as normal.  When updating
1780
		<filename>/etc</filename> and the
1781
		other directories, give the target directory a name
1782
		based on the current date:</para>
1783
1804
1784
	      <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>
1805
	<para>Before using <command>etcupdate</command>, it is
1785
&prompt.root; <userinput>cd /usr/src/etc</userinput>
1806
	  recommended to have a backup or snapshot of
1786
&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \
1807
	  <filename>/etc</filename>.  If using the
1787
    distrib-dirs distribution</userinput></screen>
1808
	  <command>copy</command> command to take a local backup,
1788
	    </step>
1809
	  include <option>-R</option> which does a recursive copy and
1810
	  <option>-p</option> which preserves times and the ownerships
1811
	  on files:</para>
1789
1812
1790
	    <step>
1813
	<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
1791
	      <para>Merge in the changes from this directory as
1792
		outlined above.  <emphasis>Do not</emphasis> remove
1793
		the <filename>/var/tmp/root-20130214</filename>
1794
		directory when you have finished.</para>
1795
	    </step>
1796
1814
1797
	    <step>
1815
	<warning>
1798
	      <para>After downloading the latest version of the
1816
	  <para><command>etcupdate</command> needs to be bootstrapped the
1799
		source and remaking it, follow step 1.  Create a new
1817
	    first time it is used to merge configuration files
1800
		directory, which reflects the new date.  This example
1818
	    post-<buildtarget>installworld</buildtarget>.  See
1801
		uses
1819
	    <xref linkend="etcupdate-bootstrap"/>.</para>
1802
		<filename>/var/tmp/root-20130221</filename>.</para>
1820
	</warning>
1803
	    </step>
1804
1821
1805
	    <step>
1822
	<para>When run in the default mode (with no further arguments),
1806
	      <para>Use &man.diff.1; to see the differences that have
1823
	  <command>etcupdate</command> first moves it's backup of the
1807
		been made in the intervening week by creating a
1824
	  old source tree from
1808
		recursive diff between the two directories:</para>
1825
	  <filename>/var/db/etcupdate/current/</filename> to the
1826
	  <filename>/var/db/etcupdate/previous/</filename>, and then
1827
	  takes a copy of the new source tree from
1828
	  <filename>/usr/src/</filename> to
1829
	  <filename>/var/db/etcupdate/current/</filename>.</para>
1809
1830
1810
	      <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
1831
	<para>Next, <command>etcupdate</command> compares the files in
1811
&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>
1832
	  the "current" and "previous" trees, and performs a 3-way merge
1833
	  to the installed system.  New files will be added, removed
1834
	  files will be deleted, and modified files will be updated,
1835
	  only if it it will not cobber any local changes.  If the merge
1836
	  encounters conflicts, then a version of the offending file
1837
	  will be saved with conflict markers for future resolution, and
1838
	  <command>etcupdate</command> will generate a warning.</para>
1812
1839
1813
	      <para>Typically, this will be a much smaller set of
1840
	<para>For each file that is updated a line will be output with a
1814
		differences than those between
1841
	  leading character to indicate the action taken:</para>
1815
		<filename>/var/tmp/root-20130221/etc</filename> and
1816
		<filename>/etc</filename>.  Because the set of
1817
		differences is smaller, it is easier to migrate those
1818
		changes across into <filename>/etc</filename>.</para>
1819
	    </step>
1820
1842
1821
	    <step>
1843
	<informaltable>
1822
	      <para>When finished, remove the older of the two
1844
	  <tgroup cols="2">
1823
		<filename>/var/tmp/root-*</filename>
1845
	    <thead>
1824
		directories:</para>
1846
	      <row>
1847
	        <entry>Leading character</entry>
1848
	        <entry>Action taken</entry>
1849
	      </row>
1850
	    </thead>
1851
	    <tbody>
1852
	      <row>
1853
	        <entry>A</entry>
1854
	        <entry>Added</entry>
1855
	      </row>
1856
	      <row>
1857
	        <entry>C</entry>
1858
	        <entry>Conflict</entry>
1859
	      </row>
1860
	      <row>
1861
	        <entry>D</entry>
1862
	        <entry>Deleted</entry>
1863
	      </row>
1864
	      <row>
1865
	        <entry>M</entry>
1866
	        <entry>Merged</entry>
1867
	      </row>
1868
	      <row>
1869
	        <entry>U</entry>
1870
	        <entry>Updated</entry>
1871
	      </row>
1872
	    </tbody>
1873
	  </tgroup>
1874
	</informaltable>
1825
1875
1826
	      <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>
1876
	<para>Note that for certain files <command>etcupdate</command>
1827
	    </step>
1877
	  will perform post-install actions any time they updated:</para>
1828
1878
1829
	    <step>
1879
	<informaltable>
1830
	      <para>Repeat this process whenever merging
1880
	  <tgroup cols="2">
1831
		in changes to <filename>/etc</filename>.</para>
1881
	    <thead>
1832
	    </step>
1882
	      <row>
1833
	  </procedure>
1883
	        <entry>Modified file</entry>
1884
	        <entry>Post-install action</entry>
1885
	      </row>
1886
	    </thead>
1887
	    <tbody>
1888
	      <row>
1889
	        <entry><filename>/etc/master.passwd</filename></entry>
1890
	        <entry>&man.pwd.mkdb.8; is invoked</entry>
1891
	      </row>
1892
	      <row>
1893
	        <entry><filename>/etc/login.conf</filename></entry>
1894
	        <entry>&man.cap.mkdb.1; is invoked to update <filename>/etc/login.conf.db</filename></entry>
1895
	      </row>
1896
	      <row>
1897
	        <entry><filename>/etc/mail/aliases</filename></entry>
1898
	        <entry>&man.newaliases.1; is invoked *</entry>
1899
	      </row>
1900
	      <row>
1901
	        <entry><filename>/etc/services</filename></entry>
1902
	        <entry>&man.services.mkdb.8; is invoked</entry>
1903
	      </row>
1904
	      <row>
1905
	        <entry><filename>/etc/localtime</filename></entry>
1906
	        <entry>&man.tzsetup.8; is invoked if <filename>/var/db/zoneinfo</filename> exists</entry>
1907
	      </row>
1908
	      <row>
1909
	        <entry><filename>/etc/motd</filename></entry>
1910
	        <entry><command>/etc/rc.d/motd</command> is invoked *</entry>
1911
	      </row>
1912
	    </tbody>
1913
	  </tgroup>
1914
	</informaltable>
1834
1915
1835
	  <para>Use &man.date.1; to automate the generation of the
1916
	<para>* These post-install actions only occur if
1836
	    directory names:</para>
1917
	  <command>etcupdate</command> is updating file directly to
1918
	  <filename>/etc/</filename> (the default behaviour).  Refer to
1919
	  the &man.etcupdate.8; man page for behaviour if the
1920
	  <option>-D</option> option has been used to merge
1921
	  configuration files in a non-default destination directory
1922
	  (for example, when using boot environments).</para>
1837
1923
1838
	  <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
1924
      </sect3>
1839
	</tip>
1840
	-->
1841
    </sect2>
1925
    </sect2>
1842
1926
1843
    <sect2 xml:id="make-delete-old">
1927
    <sect2 xml:id="make-delete-old">
Lines 1877-1883 Link Here
1877
	during the system upgrade process.</para>
1961
	during the system upgrade process.</para>
1878
1962
1879
      <para>After the <command>make installworld</command> and the
1963
      <para>After the <command>make installworld</command> and the
1880
	subsequent <command>mergemaster</command> have finished
1964
	subsequent <command>etcupdate</command> have finished
1881
	successfully, check for obsolete files and libraries:</para>
1965
	successfully, check for obsolete files and libraries:</para>
1882
1966
1883
      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
1967
      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
Lines 2216-2222 Link Here
2216
      <filename>/usr/obj</filename> via <acronym>NFS</acronym>.  Then,
2300
      <filename>/usr/obj</filename> via <acronym>NFS</acronym>.  Then,
2217
      run <command>shutdown now</command> to go to single-user mode in
2301
      run <command>shutdown now</command> to go to single-user mode in
2218
      order to install the new kernel and world and run
2302
      order to install the new kernel and world and run
2219
      <command>mergemaster</command> as usual.  When done, reboot to
2303
      <command>etcupdate</command> as usual.  When done, reboot to
2220
      return to normal multi-user operations.</para>
2304
      return to normal multi-user operations.</para>
2221
2305
2222
    <para>After verifying that everything on the test machine is
2306
    <para>After verifying that everything on the test machine is

Return to bug 206866