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