| blob | 64b40a829b06fcc9eaed60f366a55529e254243f |
1 .\" $NetBSD: etcupdate.8,v 1.18 2008/10/04 08:07:38 apb Exp $
2 .\"
3 .\" Copyright (c) 2001-2008 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Martti Kuparinen.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd October 4, 2008
31 .Dt ETCUPDATE 8
32 .Os
33 .Sh NAME
34 .Nm etcupdate
35 .Nd update the configuration and startup files in
36 .Pa /etc
37 .Sh SYNOPSIS
38 .Nm
39 .Op Fl ahlv
40 .Op Fl p Ar pager
41 .Op Fl s Brq Ar srcdir | Ar tgzdir | Ar tgzfile
42 .Op Fl t Ar temproot
43 .Op Fl w Ar width
44 .Sh DESCRIPTION
45 .Nm
46 is a tool that lets the administrator update the configuration and
47 startup files in
48 .Pa /etc
49 (and some other directories like
50 .Pa /dev ,
51 .Pa /root
52 and
53 .Pa /var )
54 without having to manually check and modify every file.
55 The administrator should run this script after performing an operating
56 system update (e.g. after running
57 .Pa make build
58 in
59 .Pa /usr/src
60 or after extracting new binary distribution files)
61 to update to the latest configuration and startup files.
62 .Pp
63 .Nm
64 compares the new configuration files against the currently installed files.
65 The user is given the option of installing, merging or deleting each
66 modified or missing file.
67 The user can also view the differences between the files.
68 By default, it shows the differences in the unified diff format.
69 The default format can be toggled to show the differences
70 in unified, context, or side by side formats or an user-defined
71 command may be used to view differences.
72 (And if
73 .Nm wdiff
74 is installed, it can also show differences on a word by word basis.)
75 .Pp
76 .Nm
77 also detects if the user installs certain special files and performs
78 corresponding tasks like remaking device nodes or rebuilding a database
79 from the
80 .Xr aliases 5
81 file.
82 Finally,
83 .Nm
84 runs
85 .Xr postinstall 8
86 to check the results.
87 .Pp
88 .Nm
89 needs a clean set of new configuration files to compare the
90 existing files against.
91 These files, called the
92 .Dq reference files
93 in this manual, may be derived from either a source or binary
94 distribution of
95 .Nx .
96 .Pp
97 If the user is updating from sources (which is the default mode),
98 .Nm
99 will first create a copy of the reference files
100 by running
101 .Pa make distribution
102 in
103 .Pa /usr/src/etc ,
104 installing the files to a so-called
105 .Pa temproot .
106 (See usage of the
107 .Fl s Ar srcdir
108 and
109 .Fl t Ar temproot
110 options later in this manual page.)
111 Although this is the default mode, it is not recommended
112 (see the
113 .Dq BUGS
114 section).
115 .Pp
116 Instead of using sources, it is recommended that the user should extract
117 one or more binary distribution sets in a special location and use those
118 as the reference files (see usage of the
119 .Fl s Ar tgzdir
120 option later in this manual page),
121 or specify one or more binary distribution sets directly
122 (see usage of the
123 .Fl s Ar tgzfile
124 option later in this manual page).
125 .Pp
126 The following options are available:
127 .Bl -tag -width XXtXtemprootX
128 .It Fl a
129 .Nm
130 can automatically update files which have not been modified locally.
131 The
132 .Fl a
133 flag instructs
134 .Nm
135 to store MD5 checksums in
136 .Pa /var/etcupdate
137 and use these checksums to determine if there have been any
138 local modifications.
139 .It Fl h
140 Prints a help text.
141 .It Fl l
142 Automatically skip files with unchanged RCS IDs.
143 This has the effect of leaving alone files that have been altered
144 locally but which have not been changed in the
145 reference files.
146 Since this works using RCS IDs, files without RCS IDs will not be
147 skipped even if only modified locally.
148 This flag may be used together with the
149 .Fl a
150 flag described above.
151 .It Fl p Ar pager
152 The pager to use when displaying files.
153 By default this is
154 .Xr more 1
155 but it can be changed either with this option
156 or by defining the
157 .Ev PAGER
158 variable.
159 .It Fl s Brq Ar srcdir | Ar tgzdir | Ar tgzfile
160 The location of the reference files, or the
161 .Nx
162 source files used to create the reference files.
163 This may be specified in one of three ways:
164 .Bl -tag -width XXsXtgzfileXX
165 .It Fl s Ar srcdir
166 The top level directory of the
167 .Nx
168 source tree.
169 By default this is
170 .Pa /usr/src
171 but it can be changed either with this option
172 or the
173 .Ev SRCDIR
174 variable.
175 The reference files will be created by running
176 .Dq "make distribution"
177 in the
178 .Ar srcdir Ns Pa /etc
179 directory.
180 Note that
181 .Ar srcdir
182 should refer to the top of the source directory tree;
183 earlier versions of
184 .Nm
185 expected
186 .Ar srcdir
187 to refer to the
188 .Pa etc
189 subdirectory within the source tree.
190 .It Fl s Ar tgzdir
191 A directory in which reference files have been
192 extracted from a binary distribution of
193 .Nx .
194 The files that are distributed in the
195 .Dq Pa etc.tgz
196 set file must be present.
197 The files that are distributed in the
198 .Dq Pa xetc.tgz
199 set file are optional.
200 The reference files from the specified directory will be copied to the
201 .Pa temproot
202 directory.
203 .It Fl s Ar tgzfile
204 The location of a set file
205 (or
206 .Dq "tgz file" )
207 such as
208 .Dq Pa etc.tgz
209 or
210 .Dq Pa xetc.tgz
211 from a binary distribution of
212 .Nx .
213 Each set file is a compressed archive containing reference files,
214 which will be extracted to the
215 .Pa temproot
216 directory.
217 Multiple
218 .Fl s
219 options may be used to specify multiple set files.
220 The
221 .Dq Pa etc.tgz
222 set file must be specified.
223 The
224 .Dq Pa xetc.tgz
225 set file is optional.
226 .El
227 .It Fl t Ar temproot
228 Specifies the location of the
229 .Pa temproot
230 directory.
231 This directory will be used for a temporary copy of
232 the reference files created by running
233 .Dq "make distribution"
234 in the source directory specified by
235 .Fl s Ar srcdir ,
236 or a temporary copy of the reference files extracted from
237 the binary sets specified by
238 .Fl s Ar tgzfile ,
239 or a temporary copy of the reference files from the directory specified by
240 .Fl s Ar tempdir .
241 By default this is
242 .Pa /tmp/temproot
243 but can be changed either with this option or the
244 .Ev TEMPROOT
245 environment variable.
246 .It Fl v
247 Makes
248 .Nm
249 verbose about its actions.
250 .It Fl w Ar width
251 Sets screen width used during interactive merge.
252 By default this is the number of columns
253 .Xr stty 1
254 reports but it can be changed either with this
255 option or by defining the
256 .Ev WIDTH
257 variable.
258 This is useful for
259 .Xr xterm 1
260 users with wider shell windows.
261 .El
262 .Sh ENVIRONMENT
263 .Bl -tag -width IGNOREFILESXX
264 .It Ev TEMPROOT
265 Sets a default value for
266 .Pa temproot .
267 See
268 .Fl t
269 above.
270 .It Ev SRCDIR
271 The location of the
272 .Nx
273 sources files.
274 See
275 .Fl s
276 above.
277 .It Ev PAGER
278 The pager to use when displaying files.
279 See
280 .Fl p
281 above.
282 .It Ev WIDTH
283 The screen width used during interactive merge.
284 See
285 .Fl w
286 above.
287 .It Ev IGNOREFILES
288 A list of files that
289 .Nm
290 should ignore.
291 Files listed in this
292 variable will never be considered for updating by
293 .Nm .
294 .El
295 .Sh FILES
296 The environment variables can also be defined in the following configuration
297 files.
298 The user's personal configuration file settings override the global
299 settings.
300 .Pp
301 /etc/etcupdate.conf
302 .Pp
303 ~/.etcupdaterc
304 .Sh EXAMPLES
305 You have just upgraded your
306 .Nx
307 host from 3.0 to 4.0 and now it's time
308 to update the configuration files as well.
309 To update the configuration files from the sources (if you have the
310 .Pa /usr/src/etc
311 directory):
312 .Pp
313 .Dl etcupdate
314 .Pp
315 The default location of the source files is
316 .Pa /usr/src
317 but this may be overridden with the
318 .Fl s Ar srcdir
319 command line argument:
320 .Pp
321 .Dl etcupdate -s /some/where/src
322 .Pp
323 To update the configuration files from binary distribution sets
324 do something like this:
325 .Pp
326 .Dl etcupdate -s /some/where/etc.tgz -s /some/where/xetc.tgz
327 .Pp
328 or like this:
329 .Pp
330 .Dl mkdir /tmp/temproot
331 .Dl cd /tmp/temproot
332 .Dl tar -xpzf /some/where/etc.tgz
333 .Dl tar -xpzf /some/where/xetc.tgz
334 .Dl etcupdate -s /tmp/temproot
335 .Pp
336 You have modified only few files in the
337 .Pa /etc
338 directory so you would like install most of the updates without being asked.
339 To automatically update the unmodified configuration files:
340 .Pp
341 .Dl etcupdate -a
342 .Pp
343 To get a better idea what's going on, use the
344 .Fl v
345 flag:
346 .Pp
347 .Dl etcupdate -v
348 .Sh SEE ALSO
349 .Xr cmp 1 ,
350 .Xr more 1 ,
351 .Xr rcs 1 ,
352 .Xr sdiff 1 ,
353 .Xr stty 1 ,
354 .Xr aliases 5 ,
355 .Xr postinstall 8
356 .Sh HISTORY
357 The
358 .Nm
359 command appeared in
360 .Nx 1.6 .
361 .Pp
362 In
363 .Nx 4.0 ,
364 the
365 .Fl s Ar tgzfile
366 option was added, the
367 .Fl b Ar tempdir
368 option was converted to
369 .Fl s Ar tgzdir ,
370 and the
371 .Fl s Ar srcdir
372 option was changed to refer to the top of the
373 source directory tree rather than to the
374 .Pa etc
375 subdirectory.
376 .Pp
377 In
378 .Nx 5.0 ,
379 the ability to specify multiple colon-separated files with a single
380 .Fl s
381 option was deprecated,
382 and options deprecated in
383 .Nx 4.0
384 were removed.
385 .Sh AUTHORS
386 The script was written by
387 .An Martti Kuparinen
388 .Aq martti@NetBSD.org
389 and improved by several other
390 .Nx
391 users.
392 .Pp
393 The idea for this script (including code fragments, variable names etc.)
394 came from the
395 .Fx
396 mergemaster (by Douglas Barton).
397 Unlike the
398 .Fx
399 mergemaster, this does not use CVS version tags by default to compare if
400 the files need to be updated.
401 Files are compared with
402 .Xr cmp 1
403 as this is more reliable and the only way if the version numbers are the
404 same even though the files are different.
405 .\" when exactly are the version the same even though the file changes?
406 .\" .Pp
407 .Sh BUGS
408 If a source directory is specified via the
409 .Dq Fl s Ar srcdir
410 option (or if the
411 .Pa /usr/src
412 directory is used by default), then
413 .Nm
414 will run
415 .Dq "make distribution"
416 in the
417 .Pa etc
418 subdirectory of the source directory, but it will not use the same
419 options or environment variables that would be used during a full build
420 of the operating system.
421 For this reason, use of the
422 .Dq Fl s Ar srcdir
423 option is not recommended, and use of the
424 .Dq Fl s Ar tgzdir
425 or
426 .Dq Fl s Ar tgzfile
427 options is recommended.
428 .\" .Pp
429 .\" Because of the use of
430 .\" .Xr cmp 1
431 .\" to compare files, rather than CVS versions, files that are locally changed
432 .\" from the distribution are always considered needing to be updated.