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