1.\" Copyright (c) 1998-2011 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$ 26.\" 27.Dd November 27, 2018 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 scrvhpCP 36.Op Fl a|iFU 37.Op Fl -run-updates=[always|never] 38.Op Fl m Ar /path/to/sources 39.Op Fl t Ar /path/to/temp/root 40.Op Fl d 41.Op Fl u Ar N 42.Op Fl w Ar N 43.Op Fl A Ar Target architecture 44.Op Fl D Ar /destdir/path 45.Sh DESCRIPTION 46The 47.Nm 48utility is a Bourne shell script which is designed to aid you 49in updating the various configuration and other files 50associated with 51.Fx . 52It is 53.Sy HIGHLY 54recommended that you back up your 55.Pa /etc 56directory before beginning this process. 57.Pp 58The script uses 59.Pa /usr/src/Makefile 60to build a temporary root environment from 61.Pa / 62down, populating that environment with the various 63files. 64You can specify a different source directory 65with the 66.Fl m 67command line option, or specify the destination 68directory with the 69.Fl D 70option. 71It then compares each file in that environment 72to its installed counterpart. 73When the script finds a 74change in the new file, or there is no installed 75version of the new file it gives you four options to 76deal with it. 77You can install the new file as is, 78delete the new file, merge the old and new 79files (as appropriate) using 80.Xr sdiff 1 81or leave the file in the temporary root environment to 82merge by hand later. 83.Pp 84By default it creates the temporary root in 85.Pa /var/tmp/temproot 86and compares the 87Version Control System (VCS) Id strings ($FreeBSD) 88for files that have them, deleting 89the temporary file if the strings match. 90If there is 91no Id string, or if the strings are different it 92compares the files themselves. 93You can 94also specify that the script ignore the Id strings and 95compare every file with the 96.Fl s 97option. 98Using the 99.Fl F 100option 101.Nm 102will install the new file for you if they differ only by 103VCS strings. 104.Pp 105The merge menu option is designed to let you easily combine your 106customizations from the old version of a file into the new one. 107While you can use the merge function to incorporate changes from 108files that you have not customized, 109it is not recommended. 110.Pp 111The 112.Nm 113utility checks your umask and issues a warning for anything 114other than 022. 115While it is not mandatory to grant 116world read permissions for most configuration files, you 117may run into problems without them. 118If you choose a 119umask other than 022 and experience trouble later this 120could be the cause. 121.Pa /etc/master.passwd 122is treated as a special case. 123If you choose to install 124this file or a merged version of it the file permissions 125are always 600 (rw-------) for security reasons. 126After 127installing an updated version of this file you should 128probably run 129.Xr pwd_mkdb 8 130with the 131.Fl p 132option to rebuild your password databases 133and recreate 134.Pa /etc/passwd . 135.Pp 136The script uses the owner and group ids 137that the files are created with by 138.Pa /usr/src/etc/Makefile , 139and file permissions as specified by the umask. 140Unified diffs are used by default to display any 141differences unless you choose context diffs. 142.Pp 143The 144.Nm 145utility will source scripts that you specify right before 146it starts the comparison, and after it is done running. 147The easiest way to handle this is to place the path 148to the script(s) in the appropriate variables in your 149.Pa .mergemasterrc 150file. 151The script sourced before comparison is named in 152.Ev MM_PRE_COMPARE_SCRIPT , 153and the one sourced after the script is done is 154.Ev MM_EXIT_SCRIPT . 155This is the recommended way to specify local modifications, 156or files that you want to give special handling to. 157This includes files that you want to be deleted without 158being compared. 159Because the named scripts are sourced from within 160.Nm , 161all of the script's variables are available for use in 162your custom script. 163You can also use 164.Pa /etc/mergemaster.rc 165which will be read before 166.Pa .mergemasterrc . 167Options specified on the command line are updated last, 168and therefore can override both files. 169.Pp 170When the comparison is done if there are any files remaining 171in the temproot directory they will be listed, and if the 172.Fl a 173option is not in use the user will be given the option of 174deleting the temproot directory. 175If there are no files remaining in the temproot directory 176it will be deleted. 177.Pp 178The options are as follows: 179.Bl -tag -width Fl 180.It Fl s 181Perform a strict comparison, diffing every pair of files. 182This comparison is performed line by line, 183without regard to VCS Ids. 184.It Fl c 185Use context diffs instead of unified diffs. 186.It Fl r 187Re-run 188.Nm 189on a previously cleaned directory, skipping the creation of 190the temporary root environment. 191This option is compatible 192with all other options. 193.It Fl v 194Be more verbose about the process. 195You should probably use 196this option the first time you run 197.Nm . 198This option also gives you a list of files that exist 199only in the installed version of 200.Pa /etc . 201.It Fl a 202Run automatically. 203This option will leave all the files that 204differ from the installed versions in the temporary directory 205to be dealt with by hand. 206If the 207.Pa temproot 208directory exists, it creates a new one in a previously 209non-existent directory. 210This option unsets the verbose flag, 211and is not compatible with 212.Fl i , 213.Fl F , 214or 215.Fl U . 216Setting 217.Fl a 218makes 219.Fl w 220superfluous. 221.It Fl h 222Display usage and help information. 223.It Fl i 224Automatically install any files that do not exist in the 225destination directory. 226.It Fl p 227Pre-buildworld mode. 228Compares only files known to be essential to the success of 229{build|install}world, i.e., 230.Pa /etc/group 231and 232.Pa /etc/master.passwd . 233.It Fl F 234If the files differ only by VCS Id ($FreeBSD) 235install the new file. 236.It Fl C 237After a standard 238.Nm 239run, 240compares your rc.conf[.local] options to the defaults. 241.It Fl P 242Preserve files that you replace in 243.Pa /var/tmp/mergemaster/preserved-files-<date> , 244or another directory you specify in your 245.Nm 246rc file. 247.It Fl U 248Attempt to auto upgrade files that have not been user modified. 249This option can be dangerous when there are critical changes 250in the new versions that affect your running system. 251.It Fl -run-updates=[always|never] 252Specify always or never to run newaliases, pwd_mkdb, etc. 253at the end of the comparison run. 254If this option is omitted the default is to prompt the user 255for each update as necessary. 256.It Fl m Ar /path/to/sources 257Specify the path to the directory where you want to do the 258.Xr make 1 . 259(In other words, where your sources are, but -s was already 260taken.) 261In older versions of 262.Nm 263the path to 264.Pa src/etc 265was required. 266.Nm 267will convert the path if this older method is used. 268.It Fl t Ar /path/to/temp/root 269Create the temporary root environment in 270.Pa /path/to/temp/root 271instead of the default 272.Pa /var/tmp/temproot . 273.It Fl d 274Add the date and time to the name of the temporary 275root directory. 276If 277.Fl t 278is specified, this option must 279follow it if you want the date added too. 280.It Fl u Ar N 281Specify a numeric umask. 282The default is 022. 283.It Fl w Ar N 284Supply an alternate screen width to the 285.Xr sdiff 1 286command in numbers of columns. 287The default is 80. 288.It Fl A Ar Target architecture 289Specify an alternative 290.Ev TARGET_ARCH 291architecture name. 292.It Fl D Ar /path 293Specify the destination directory for the installed files. 294.El 295.Sh ENVIRONMENT 296The 297.Nm 298utility uses the 299.Ev PAGER 300environment variable if set. 301Otherwise it uses 302.Xr less 1 . 303If 304.Ev PAGER 305specifies a program outside 306its 307limited 308.Ev PATH 309without specifying the full path, 310.Nm 311prompts you with options on how to proceed. 312The 313.Ev MM_PRE_COMPARE_SCRIPT 314and 315.Ev MM_EXIT_SCRIPT 316variables are used as described above. 317Other variables that are used by the script internally 318can be specified in 319.Pa .mergemasterrc 320as described in more detail below. 321.Sh FILES 322.Bl -tag -width $HOME/.mergemasterrc -compact 323.It Pa /etc/mergemaster.rc 324.It Pa $HOME/.mergemasterrc 325.El 326.Pp 327The 328.Nm 329utility will 330.Ic .\& 331(source) these files if they exist. 332Command line options 333will override rc file options. 334.Pa $HOME/.mergemasterrc 335overrides 336.Pa /etc/mergemaster.rc . 337Here is an example 338with all values commented out: 339.Bd -literal 340# These are options for mergemaster, with their default values listed 341# The following options have command line overrides 342# 343# The target architecture (-A, unset by default) 344#ARCHSTRING='TARGET_ARCH=<foo>' 345# 346# Sourcedir is the directory to do the 'make' in (-m) 347#SOURCEDIR='/usr/src' 348# 349# Directory to install the temporary root environment into (-t) 350#TEMPROOT='/var/tmp/temproot' 351# 352# Specify the destination directory for the installed files (-D) 353#DESTDIR= 354# 355# Strict comparison skips the VCS Id test and compares every file (-s) 356#STRICT=no 357# 358# Type of diff, such as unified, context, etc. (-c) 359#DIFF_FLAG='-u' 360# 361# Install the new file if it differs only by VCS Id ($FreeBSD, -F) 362#FREEBSD_ID= 363# 364# Verbose mode includes more details and additional checks (-v) 365#VERBOSE= 366# 367# Automatically install files that do not exist on the system already (-i) 368#AUTO_INSTALL= 369# 370# Automatically upgrade files that have not been user modified (-U) 371# ***DANGEROUS*** 372#AUTO_UPGRADE= 373# 374# Either always or never run newaliases, pwd_mkdb at the end (--run-updates) 375#RUN_UPDATES= 376# 377# Compare /etc/rc.conf[.local] to /etc/defaults/rc.conf (-C) 378#COMP_CONFS= 379# 380# Preserve files that you replace (-P) 381#PRESERVE_FILES= 382#PRESERVE_FILES_DIR=/var/tmp/mergemaster/preserved-files-`date +%y%m%d-%H%M%S` 383# 384# The umask for mergemaster to compare the default file's modes to (-u) 385#NEW_UMASK=022 386# 387# The following options have no command line overrides 388# 389# Files to always avoid comparing 390#IGNORE_FILES='/etc/motd /etc/printcap foo bar' 391# 392# Additional options for diff. This will get unset when using -s. 393#DIFF_OPTIONS='-Bb' # Ignore changes in whitespace 394# 395# Location to store the list of mtree values for AUTO_UPGRADE purposes 396#MTREEDB='/var/db' 397# 398# For those who just cannot stand including the full path to PAGER 399#DONT_CHECK_PAGER= 400# 401# If you set 'yes' above, make sure to include the PATH to your pager 402#PATH=/bin:/usr/bin:/usr/sbin 403# 404# Delete stale files in /etc/rc.d without prompting 405#DELETE_STALE_RC_FILES= 406# 407# Specify the path to scripts to run before the comparison starts, 408# and/or after the script has finished its work 409#MM_PRE_COMPARE_SCRIPT= 410#MM_EXIT_SCRIPT= 411.Ed 412.Sh EXIT STATUS 413Exit status is 0 on successful completion, or if the user bails out 414manually at some point during execution. 415.Pp 416Exit status is 1 if it fails for one of the following reasons: 417.Pp 418Invalid command line option 419.Pp 420Failure to create the temporary root environment 421.Pp 422Failure to populate the temporary root 423.Pp 424Presence of the 'nodev' option in 425.Pa <DESTDIR>/etc/fstab 426.Pp 427Failure to install a file 428.Sh EXAMPLES 429Typically all you will need to do is type 430.Nm 431at the prompt and the script will do all the work for you. 432.Pp 433To use context diffs and have 434.Nm 435explain more things as it goes along, use: 436.Pp 437.Dl # mergemaster -cv 438.Pp 439To specify that 440.Nm 441put the temporary root environment in 442.Pa /usr/tmp/root , 443use: 444.Pp 445.Dl # mergemaster -t /usr/tmp/root 446.Pp 447To specify a 110 column screen with a strict 448comparison, use: 449.Pp 450.Dl # mergemaster -sw 110 451.Sh SEE ALSO 452.Xr diff 1 , 453.Xr make 1 , 454.Xr less 1 , 455.Xr sdiff 1 , 456.Xr etcupdate 8 , 457.Xr pwd_mkdb 8 458.Pp 459.Pa /usr/src/etc/Makefile 460.Rs 461.%U https://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html 462.%T The Cutting Edge (using make world) 463.%A Nik Clayton 464.Re 465.Sh HISTORY 466The 467.Nm 468utility was first publicly available on one of my 469web pages in a much simpler form under the name 470.Pa comproot 471on 13 March 1998. 472The idea for creating the 473temporary root environment comes from Nik Clayton's 474make world tutorial which is referenced above. 475.Sh AUTHORS 476This manual page and the script itself were written by 477.An Douglas Barton Aq Mt dougb@FreeBSD.org . 478