1.\" Copyright (c) 1998-2003 Douglas Barton 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/usr.sbin/mergemaster/mergemaster.8,v 1.5.2.12 2003/03/02 02:45:01 dougb Exp $ 26.\" 27.Dd February 5, 2001 28.Dt MERGEMASTER 8 29.Os 30.Sh NAME 31.Nm mergemaster 32.Nd merge configuration files, et al during an upgrade 33.Sh SYNOPSIS 34.Nm 35.Op Fl scrvahipC 36.Op Fl m Ar /path/to/sources 37.Op Fl t Ar /path/to/temp/root 38.Op Fl d 39.Op Fl u Ar N 40.Op Fl w Ar N 41.Op Fl D Ar /path 42.Sh DESCRIPTION 43The 44.Nm 45utility is a Bourne shell script which is designed to aid you 46in updating the various configuration and other files 47associated with 48.Fx . 49It is 50.Sy HIGHLY 51recommended that you back up your 52.Pa /etc 53directory before beginning this process. 54.Pp 55The script uses 56.Pa /usr/src/etc/Makefile 57to build a temporary root environment from 58.Pa / 59down, populating that environment with the various 60files. 61You can specify a different source directory 62with the 63.Op Fl m 64command line option, or specify the destination 65directory with the 66.Op Fl D 67option. 68It then compares each file in that environment 69to its installed counterpart. 70When the script finds a 71change in the new file, or there is no installed 72version of the new file it gives you four options to 73deal with it. 74You can install the new file as is, 75delete the new file, merge the old and new 76files (as appropriate) using 77.Xr sdiff 1 78or leave the file in the temporary root environment to 79merge by hand later. 80.Pp 81By default it creates the temporary root in 82.Pa /var/tmp/temproot 83and compares the 84.Xr cvs 1 85version $Id/$FreeBSD strings for files that have them, deleting 86the temporary file if the strings match. 87If there is 88no $Id string, or if the strings are different it 89compares the files themselves. 90You can 91also specify that the script ignore the $Id strings and 92compare every file. 93.Pp 94The 95.Nm 96utility checks your umask and issues a warning for anything 97other than 022. While it is not mandatory to grant 98world read permissions for most configuration files, you 99may run into problems without them. 100If you choose a 101umask other than 022 and experience trouble later this 102could be the cause. 103.Pa /etc/master.passwd 104is treated as a special case. 105If you choose to install 106this file or a merged version of it the file permissions 107are always 600 (rw-------) for security reasons. 108After 109installing an updated version of this file you should 110probably run 111.Xr pwd_mkdb 8 112with the -p option to rebuild your password databases 113and recreate 114.Pa /etc/passwd . 115.Pp 116The script uses the owner and group id's 117that the files are created with by 118.Pa /usr/src/etc/Makefile , 119and file permissions as specified by the umask. 120Unified diffs are used by default to display any 121differences unless you choose context diffs. 122.Pp 123The 124.Nm 125utility will source scripts that you specify right before 126it starts the comparison, and after it's done running. 127The easiest way to handle this is to place the path 128to the script(s) in the appropriate variables in your 129.Pa .mergemasterrc 130file. 131The script sourced before comparison is named in 132.Ev MM_PRE_COMPARE_SCRIPT , 133and the one sourced after the script is done is 134.Ev MM_EXIT_SCRIPT . 135This is the recommended way to specify local modifications, 136or files that you want to give special handling to. 137This includes files that you want to be deleted without 138being compared. 139Because the named scripts are sourced from within 140.Nm , 141all of the script's variables are available for use in 142your custom script. 143You can also use 144.Pa /etc/mergemaster.rc 145which will be read before 146.Pa .mergemasterrc . 147Options specified on the command line are updated last, 148and therefore can override both files. 149.Pp 150The options are as follows: 151.Bl -tag -width Fl 152.It Fl s 153Perform a strict comparison, diff'ing every pair of files. 154This comparison is performed line by line, 155without regard to CVS $Id's. 156.It Fl c 157Use context diffs instead of unified diffs. 158.It Fl r 159Re-run 160.Nm 161on a previously cleaned directory, skipping the creation of 162the temporary root environment. 163This option is compatible 164with all other options. 165.It Fl v 166Be more verbose about the process. 167You should probably use 168this option the first time you run 169.Nm . 170This option also gives you a list of files that exist 171only in the installed version of 172.Pa /etc . 173.It Fl a 174Run automatically. 175This option will leave all the files that 176differ from the installed versions in the temporary directory 177to be dealt with by hand. 178If the 179.Pa temproot 180directory exists, it creates a new one in a previously 181non-existent directory. 182This option unsets the verbose flag, 183but is compatible with all other options. 184Setting -a makes 185-w superfluous. 186.It Fl h 187Display usage and help information. 188.It Fl i 189Automatically install any files that do not exist in the 190destination directory. 191.It Fl p 192Pre-buildworld mode. 193Compares only files known to be essential to the success of 194{build|install}world, 195including 196.Pa /etc/make.conf . 197.It Fl C 198After a standard 199.Nm 200run, 201compares your rc.conf[.local] options to the defaults. 202.It Fl m Ar /path/to/sources 203Specify the path to the directory where you want to do the 204.Xr make 1 . 205(In other words, where your sources are, but -s was already 206taken.) 207.It Fl t Ar /path/to/temp/root 208Create the temporary root environment in 209.Pa /path/to/temp/root 210instead of the default 211.Pa /var/tmp/temproot . 212.It Fl d 213Add the date and time to the name of the temporary 214root directory. 215If -t is specified, this option must 216follow it if you want the date added too. 217.It Fl u Ar N 218Specify a numeric umask. 219The default is 022. 220.It Fl w Ar N 221Supply an alternate screen width to the 222.Xr sdiff 1 223command in numbers of columns. 224The default is 80. 225.It Fl D Ar /path 226Specify the destination directory for the installed files. 227.El 228.Sh ENVIRONMENT 229The 230.Nm 231utility uses the 232.Ev PAGER 233environment variable if set. 234Otherwise it uses 235.Xr more 1 . 236If 237.Ev PAGER 238specifies a program outside 239its 240limited 241.Ev PATH 242without specifying the full path, 243.Nm 244prompts you with options on how to proceed. 245The 246.Ev MM_PRE_COMPARE_SCRIPT 247and 248.Ev MM_EXIT_SCRIPT 249variables are used as described above. 250Other variables that are used by the script internally 251can be specified in 252.Pa .mergemasterrc 253as described in more detail below. 254.Sh EXAMPLES 255Typically all you will need to do is type 256.Nm 257at the prompt and the script will do all the work for you. 258.Pp 259To use context diff's and have 260.Nm 261explain more things as it goes along, use: 262.Pp 263.Dl # mergemaster -cv 264.Pp 265To specify that 266.Nm 267put the temporary root environment in 268.Pa /usr/tmp/root , 269use: 270.Pp 271.Dl # mergemaster -t /usr/tmp/root 272.Pp 273To specify a 110 column screen with a strict 274comparison, use: 275.Pp 276.Dl # mergemaster -sw 110 277.Sh FILES 278.Bl -tag -width $HOME/.mergemasterrc -compact 279.It Pa /etc/mergemaster.rc 280.It Pa $HOME/.mergemasterrc 281.El 282.Pp 283The 284.Nm 285utility will . (source) these files if they exist. 286Command line options 287will override rc file options. 288.Pa $HOME/.mergemasterrc 289overrides 290.Pa /etc/mergemaster.rc . 291Here is an example 292with all values commented out: 293.Pp 294.Bd -literal 295# These are options for mergemaster, with their default values listed 296# The following options have command line overrides 297# 298# Directory to install the temporary root environment into 299#TEMPROOT='/var/tmp/temproot' 300# 301# Strict comparison bypasses the CVS $Id tests and compares every file 302#STRICT=no 303# 304# Type of diff, such as unified, context, etc. 305#DIFF_FLAG='-u' 306# 307# Additional options for diff. This will get unset when using -s. 308#DIFF_OPTIONS='-I$\&FreeBSD:.*[$]' # Ignores CVS Id tags 309# 310# Verbose mode includes more details and additional checks 311#VERBOSE= 312# 313# Automatically install files that do not exist on the system already 314#AUTO_INSTALL= 315# 316# Compare /etc/rc.conf[.local] to /etc/defaults/rc.conf 317#COMP_CONFS=yes 318# 319# Sourcedir is the directory to do the 'make' in (where the new files are) 320#SOURCEDIR='/usr/src/etc' 321# 322# The umask for mergemaster to compare the default file's modes to 323#NEW_UMASK=022 324# 325# Specify the destination directory for the installed files 326#DESTDIR= 327# 328# The following options have no command line overrides 329# For those who just cannot stand including the full path to PAGER 330#DONT_CHECK_PAGER= 331# 332# If you set 'yes' above, make sure to include the PATH to your pager 333#PATH=/bin:/usr/bin:/usr/sbin 334# 335# Don't compare the old and new motd files 336#IGNORE_MOTD=yes 337# 338# Specify the path to scripts to run before the comparison starts, 339# and/or after the script has finished its work 340#MM_PRE_COMPARE_SCRIPT= 341#MM_EXIT_SCRIPT= 342.Ed 343.Sh SEE ALSO 344.Xr cvs 1 , 345.Xr diff 1 , 346.Xr make 1 , 347.Xr more 1 , 348.Xr sdiff 1 , 349.Xr pwd_mkdb 8 350.Pp 351.Pa /usr/src/etc/Makefile 352.Rs 353.%O http://www.FreeBSD.org/doc/handbook/makeworld.html 354.%T The Cutting Edge (using make world) 355.%A Nik Clayton 356.Re 357.Sh DIAGNOSTICS 358Exit status is 0 on successful completion, or if the user bails out 359manually at some point during execution. 360.Pp 361Exit status is 1 if it fails for one of the following reasons: 362.Pp 363Invalid command line option 364.Pp 365Failure to create the temporary root environment 366.Pp 367Failure to populate the temporary root 368.Sh HISTORY 369The 370.Nm 371utility was first publicly available on one of my 372web pages in a much simpler form under the name 373.Pa comproot 374on 13 March 1998. The idea for creating the 375temporary root environment comes from Nik Clayton's 376make world tutorial which is referenced above. 377.Sh AUTHORS 378This manual page and the script itself were written by 379.An Douglas Barton Aq DougB@FreeBSD.org . 380.Sh BUGS 381There are no known bugs. 382Please report any problems, 383comments or suggestions to the author. 384Several of the 385improvements to this program have come from user 386suggestions. 387Thank you. 388