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