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