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