usr.sbin/mergemaster/mergemaster.8

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