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