usr.sbin/mergemaster/mergemaster.8

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