usr.sbin/mergemaster/mergemaster.8

   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 April 16, 2024
  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
  45 The
  46 .Nm
  47 utility is deprecated and may not be available in
  48 .Fx 15.0
  49 or later.
  50 Users are advised to use
  51 .Xr etcupdate 8
  52 instead.
  53 .Ef
  54 .Pp
  55 The
  56 .Nm
  57 utility is a Bourne shell script which is designed to aid you
  58 in updating the various configuration and other files
  59 associated with
  60 .Fx .
  61 It is
  62 .Sy HIGHLY
  63 recommended that you back up your
  64 .Pa /etc
  65 directory before beginning this process.
  66 .Pp
  67 The script uses
  68 .Pa /usr/src/Makefile
  69 to build a temporary root environment from
  70 .Pa /
  71 down, populating that environment with the various
  72 files.
  73 You can specify a different source directory
  74 with the
  75 .Fl m
  76 command line option, or specify the destination
  77 directory with the
  78 .Fl D
  79 option.
  80 It then compares each file in that environment
  81 to its installed counterpart.
  82 When the script finds a
  83 change in the new file, or there is no installed
  84 version of the new file it gives you four options to
  85 deal with it.
  86 You can install the new file as is,
  87 delete the new file, merge the old and new
  88 files (as appropriate) using
  89 .Xr sdiff 1
  90 or leave the file in the temporary root environment to
  91 merge by hand later.
  92 .Pp
  93 By default it creates the temporary root in
  94 .Pa /var/tmp/temproot
  95 and compares the
  96 Version Control System (VCS) Id strings ($FreeBSD)
  97 for files that have them, deleting
  98 the temporary file if the strings match.
  99 If there is
 100 no Id string, or if the strings are different it
 101 compares the files themselves.
 102 You can
 103 also specify that the script ignore the Id strings and
 104 compare every file with the
 105 .Fl s
 106 option.
 107 Using the
 108 .Fl F
 109 option
 110 .Nm
 111 will install the new file for you if they differ only by
 112 VCS strings.
 113 .Pp
 114 The merge menu option is designed to let you easily combine your
 115 customizations from the old version of a file into the new one.
 116 While you can use the merge function to incorporate changes from
 117 files that you have not customized,
 118 it is not recommended.
 119 .Pp
 120 The
 121 .Nm
 122 utility checks your umask and issues a warning for anything
 123 other than 022.
 124 While it is not mandatory to grant
 125 world read permissions for most configuration files, you
 126 may run into problems without them.
 127 If you choose a
 128 umask other than 022 and experience trouble later this
 129 could be the cause.
 130 .Pa /etc/master.passwd
 131 is treated as a special case.
 132 If you choose to install
 133 this file or a merged version of it the file permissions
 134 are always 600 (rw-------) for security reasons.
 135 After
 136 installing an updated version of this file you should
 137 probably run
 138 .Xr pwd_mkdb 8
 139 with the
 140 .Fl p
 141 option to rebuild your password databases
 142 and recreate
 143 .Pa /etc/passwd .
 144 .Pp
 145 The script uses the owner and group ids
 146 that the files are created with by
 147 .Pa /usr/src/etc/Makefile ,
 148 and file permissions as specified by the umask.
 149 Unified diffs are used by default to display any
 150 differences unless you choose context diffs.
 151 .Pp
 152 The
 153 .Nm
 154 utility will source scripts that you specify right before
 155 it starts the comparison, and after it is done running.
 156 The easiest way to handle this is to place the path
 157 to the script(s) in the appropriate variables in your
 158 .Pa .mergemasterrc
 159 file.
 160 The script sourced before comparison is named in
 161 .Ev MM_PRE_COMPARE_SCRIPT ,
 162 and the one sourced after the script is done is
 163 .Ev MM_EXIT_SCRIPT .
 164 This is the recommended way to specify local modifications,
 165 or files that you want to give special handling to.
 166 This includes files that you want to be deleted without
 167 being compared.
 168 Because the named scripts are sourced from within
 169 .Nm ,
 170 all of the script's variables are available for use in
 171 your custom script.
 172 You can also use
 173 .Pa /etc/mergemaster.rc
 174 which will be read before
 175 .Pa .mergemasterrc .
 176 Options specified on the command line are updated last,
 177 and therefore can override both files.
 178 .Pp
 179 When the comparison is done if there are any files remaining
 180 in the temproot directory they will be listed, and if the
 181 .Fl a
 182 option is not in use the user will be given the option of
 183 deleting the temproot directory.
 184 If there are no files remaining in the temproot directory
 185 it will be deleted.
 186 .Pp
 187 The options are as follows:
 188 .Bl -tag -width Fl
 189 .It Fl s
 190 Perform a strict comparison, diffing every pair of files.
 191 This comparison is performed line by line,
 192 without regard to VCS Ids.
 193 .It Fl c
 194 Use context diffs instead of unified diffs.
 195 .It Fl r
 196 Re-run
 197 .Nm
 198 on a previously cleaned directory, skipping the creation of
 199 the temporary root environment.
 200 This option is compatible
 201 with all other options.
 202 .It Fl v
 203 Be more verbose about the process.
 204 You should probably use
 205 this option the first time you run
 206 .Nm .
 207 This option also gives you a list of files that exist
 208 only in the installed version of
 209 .Pa /etc .
 210 .It Fl a
 211 Run automatically.
 212 This option will leave all the files that
 213 differ from the installed versions in the temporary directory
 214 to be dealt with by hand.
 215 If the
 216 .Pa temproot
 217 directory exists, it creates a new one in a previously
 218 non-existent directory.
 219 This option unsets the verbose flag,
 220 and is not compatible with
 221 .Fl i ,
 222 .Fl F ,
 223 or
 224 .Fl U .
 225 Setting
 226 .Fl a
 227 makes
 228 .Fl w
 229 superfluous.
 230 .It Fl h
 231 Display usage and help information.
 232 .It Fl i
 233 Automatically install any files that do not exist in the
 234 destination directory.
 235 .It Fl p
 236 Pre-buildworld mode.
 237 Compares only files known to be essential to the success of
 238 {build|install}world, i.e.,
 239 .Pa /etc/group
 240 and
 241 .Pa /etc/master.passwd .
 242 .It Fl F
 243 If the files differ only by VCS Id ($FreeBSD)
 244 install the new file.
 245 .It Fl C
 246 After a standard
 247 .Nm
 248 run,
 249 compares your rc.conf[.local] options to the defaults.
 250 .It Fl P
 251 Preserve files that you replace in
 252 .Pa /var/tmp/mergemaster/preserved-files-<date> ,
 253 or another directory you specify in your
 254 .Nm
 255 rc file.
 256 .It Fl U
 257 Attempt to auto upgrade files that have not been user modified.
 258 This option can be dangerous when there are critical changes
 259 in the new versions that affect your running system.
 260 .It Fl -run-updates=[always|never]
 261 Specify always or never to run newaliases, pwd_mkdb, etc.
 262 at the end of the comparison run.
 263 If this option is omitted the default is to prompt the user
 264 for each update as necessary.
 265 .It Fl m Ar /path/to/sources
 266 Specify 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
 269 taken.)
 270 In older versions of
 271 .Nm
 272 the path to
 273 .Pa src/etc
 274 was required.
 275 .Nm
 276 will convert the path if this older method is used.
 277 .It Fl t Ar /path/to/temp/root
 278 Create the temporary root environment in
 279 .Pa /path/to/temp/root
 280 instead of the default
 281 .Pa /var/tmp/temproot .
 282 .It Fl d
 283 Add the date and time to the name of the temporary
 284 root directory.
 285 If
 286 .Fl t
 287 is specified, this option must
 288 follow it if you want the date added too.
 289 .It Fl u Ar N
 290 Specify a numeric umask.
 291 The default is 022.
 292 .It Fl w Ar N
 293 Supply an alternate screen width to the
 294 .Xr sdiff 1
 295 command in numbers of columns.
 296 The default is 80.
 297 .It Fl A Ar Target architecture
 298 Specify an alternative
 299 .Ev TARGET_ARCH
 300 architecture name.
 301 .It Fl D Ar /path
 302 Specify the destination directory for the installed files.
 303 .El
 304 .Sh ENVIRONMENT
 305 The
 306 .Nm
 307 utility uses the
 308 .Ev PAGER
 309 environment variable if set.
 310 Otherwise it uses
 311 .Xr less 1 .
 312 If
 313 .Ev PAGER
 314 specifies a program outside
 315 its
 316 limited
 317 .Ev PATH
 318 without specifying the full path,
 319 .Nm
 320 prompts you with options on how to proceed.
 321 The
 322 .Ev MM_PRE_COMPARE_SCRIPT
 323 and
 324 .Ev MM_EXIT_SCRIPT
 325 variables are used as described above.
 326 Other variables that are used by the script internally
 327 can be specified in
 328 .Pa .mergemasterrc
 329 as 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
 336 The
 337 .Nm
 338 utility will
 339 .Ic .\&
 340 (source) these files if they exist.
 341 Command line options
 342 will override rc file options.
 343 .Pa $HOME/.mergemasterrc
 344 overrides
 345 .Pa /etc/mergemaster.rc .
 346 Here is an example
 347 with 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
 422 Exit status is 0 on successful completion, or if the user bails out
 423 manually at some point during execution.
 424 .Pp
 425 Exit status is 1 if it fails for one of the following reasons:
 426 .Pp
 427 Invalid command line option
 428 .Pp
 429 Failure to create the temporary root environment
 430 .Pp
 431 Failure to populate the temporary root
 432 .Pp
 433 Presence of the 'nodev' option in
 434 .Pa <DESTDIR>/etc/fstab
 435 .Pp
 436 Failure to install a file
 437 .Sh EXAMPLES
 438 Typically all you will need to do is type
 439 .Nm
 440 at the prompt and the script will do all the work for you.
 441 .Pp
 442 To use context diffs and have
 443 .Nm
 444 explain more things as it goes along, use:
 445 .Pp
 446 .Dl # mergemaster -cv
 447 .Pp
 448 To specify that
 449 .Nm
 450 put the temporary root environment in
 451 .Pa /usr/tmp/root ,
 452 use:
 453 .Pp
 454 .Dl # mergemaster -t /usr/tmp/root
 455 .Pp
 456 To specify a 110 column screen with a strict
 457 comparison, 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
 474 The
 475 .Nm
 476 utility was first publicly available on one of my
 477 web pages in a much simpler form under the name
 478 .Pa comproot
 479 on 13 March 1998.
 480 The idea for creating the
 481 temporary root environment comes from Nik Clayton's
 482 make world tutorial which is referenced above.
 483 .Sh AUTHORS
 484 This manual page and the script itself were written by
 485 .An Douglas Barton Aq Mt dougb@FreeBSD.org .