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