1.\" $OpenBSD: sysmerge.8,v 1.28 2009/08/23 20:06:32 ajacoutot Exp $ 2.\" 3.\" Copyright (c) 2008 Antoine Jacoutot <ajacoutot@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: August 23 2009 $ 18.Dt SYSMERGE 8 19.Os 20.Sh NAME 21.Nm sysmerge 22.Nd update system configuration files 23.Sh SYNOPSIS 24.Nm 25.Bk -words 26.Op Fl bd 27.Op Fl s Ar src \*(Ba etcXX.tgz 28.Op Fl x Ar xetcXX.tgz 29.Ek 30.Sh DESCRIPTION 31.Nm 32is a 33.Xr sh 1 34script designed to help the administrator update configuration files 35after upgrading to a new release or snapshot. 36The configuration files are typically those held in 37.Pa /etc , 38though 39.Nm 40is also able to update files held in 41.Pa /dev , 42.Pa /root , 43and 44.Pa /var . 45.Pp 46It is 47.Sy HIGHLY 48recommended to back up the 49.Pa /etc 50directory before running this script. 51.Pp 52.Nm 53works by comparing a temporary reference root directory 54against currently installed files. 55The reference files are created from a 56.Xr cvs 1 57source tree or a 58.Dq .tgz 59release or snapshot file. 60The default, if no source is specified on the command line, 61is to use 62.Pa /usr/src . 63All work is done under 64.Pa ${TMPDIR}/sysmerge.XXXXX 65(known as the 66.Em work directory ) . 67The temporary root directory 68.Pa temproot 69is created under the work directory. 70Each modified and/or replaced file is saved under the 71.Pa backup 72directory inside the work directory. 73.Pp 74To make sure configuration files are in sync with the actual binaries, 75use the same source as was used to upgrade the system: 76.Pa /usr/src 77when upgrading from source; 78.Pa etcXX.tgz 79and 80.Pa xetcXX.tgz 81when upgrading from binary sets. 82.Pp 83.Nm 84will work through the fileset, 85offering the chance to merge any differences using ${MERGE_CMD}. 86Merged files may be edited using a default editor, 87or one defined by the ${VISUAL} or ${EDITOR} environment variables. 88Files may also be left to deal with at a later date. 89Should any problems occur, 90such as a failure to upgrade a file, 91the user will be notified and have to deal with the issue by hand. 92.Pp 93By default (if 94.Fl d 95is not used) 96.Nm 97only compares files whose reference sources have changed since the last run 98and attempts to automatically upgrade them to the newest version, 99provided that they have no local changes. 100It automatically installs missing files and binaries, 101and updates files differing only by CVS Id. 102Files whose reference sources have matching CVS Id are skipped from comparison. 103.Pa /etc/fbtab , 104.Pa /etc/login.conf , 105.Pa /etc/sysctl.conf , 106and 107.Pa /etc/ttys 108are created using helper scripts and are 109.Sy always 110compared. 111.Pp 112.Nm 113will finish by running 114.Xr mtree 8 115to make sure the directory structure has correct permissions. 116.Pp 117The options are as follows: 118.Bl -tag -width Ds 119.It Fl b 120Batch mode. 121.Nm 122runs non-interactively, 123saving differing files for later manual processing. 124.It Fl d 125Diff mode. 126In this mode, 127.Nm 128will not take any automatic action, allowing for a full diff comparison. 129.It Fl s Ar src \*(Ba etcXX.tgz 130Specify a path to an 131.Ox 132top src directory or an etcXX.tgz tarball. 133A tarball path specified as an FTP or HTTP URL will be passed 134to ${FETCH_CMD}. 135.It Fl x Ar xetcXX.tgz 136Specify a path to an 137xetcXX.tgz tarball. 138A tarball path specified as an FTP or HTTP URL will be passed 139to ${FETCH_CMD}. 140.El 141.Pp 142Files and directories can be excluded from comparison 143by listing them in the file 144.Pa /etc/sysmerge.ignore , 145each entry separated by white space or a new line. 146The following files will always be skipped from comparison: 147.Pa /etc/*.db , 148.Pa /etc/mail/*.db , 149.Pa /etc/passwd , 150.Pa /etc/motd , 151.Pa /etc/myname , 152.Pa /var/mail/root . 153.Pp 154The 155.Xr sendmail 8 156configuration files 157.Pa /etc/mail/localhost.cf , 158.Pa /etc/mail/sendmail.cf 159and 160.Pa /etc/mail/submit.cf 161will always differ because they include their build date and directories. 162A special test was added to handle this 163and they are offered for comparison only if they really differ. 164.Sh ENVIRONMENT 165.Bl -tag -width "DESTDIRXXX" 166.It Ev DBDIR 167Directory in which checksum files are stored. 168If unset, this defaults to 169.Pa /var/db/sysmerge . 170.It Ev DESTDIR 171Directory in which to merge and install files. 172If unset, this defaults to 173.Pa / . 174.It Ev EDITOR , VISUAL 175Specifies an editor to use. 176If both 177.Ev EDITOR 178and 179.Ev VISUAL 180are set, 181.Ev VISUAL 182takes precedence. 183If neither 184.Ev EDITOR 185nor 186.Ev VISUAL 187are set, 188the default is 189.Xr vi 1 . 190.It Ev FETCH_CMD 191Command used to fetch remote files. 192Defaults to 193.Xr ftp 1 . 194.It Ev FTP_KEEPALIVE 195Have 196.Xr ftp 1 197send a byte after every 198.Ev FTP_KEEPALIVE 199seconds, 200so that incorrectly configured network equipment won't aggressively drop it. 201See 202.Dq ftp -k 203for more information. 204.It Ev MERGE_CMD 205Command used to merge diffs. 206This will be called with three arguments: the first argument is the 207output file to create, the second argument is the currently installed 208file and the third argument is the reference file. 209If unset, this defaults to 210.Dq sdiff -as -w ${SWIDTH} -o . 211.It Ev PAGER 212Specifies the pagination program to use. 213.It Ev REPORT 214Log summary which may contain information for further, manual, 215updating. 216Defaults to 217.Pa ${WRKDIR}/sysmerge.log . 218.It Ev TMPDIR 219Directory in which the work directory is created. 220If unset, this defaults to 221.Pa /var/tmp . 222.El 223.Sh FILES 224.Bl -tag -width "${TMPDIR}/sysmerge.XXXXXXXX" -compact 225.It ${TMPDIR}/sysmerge.XXXXX 226Default work directory. 227The 228.Sy temproot 229and 230.Sy backup 231directories are created relative to this. 232.It ${WRKDIR}/sysmerge.log 233Default log file. 234.It /etc/sysmerge.ignore 235Files and directories to ignore from comparison. 236.El 237.Sh SEE ALSO 238.Xr cap_mkdb 1 , 239.Xr diff 1 , 240.Xr mktemp 1 , 241.Xr more 1 , 242.Xr sdiff 1 , 243.Xr MAKEDEV 8 , 244.Xr makemap 8 , 245.Xr mtree 8 , 246.Xr newaliases 8 , 247.Xr pwd_mkdb 8 248.Pp 249.Pa /usr/src/etc/Makefile 250.Pp 251.Pa http://www.openbsd.org/faq/current.html 252.Pa http://www.openbsd.org/faq/upgradeXX.html 253.Sh HISTORY 254The 255.Nm 256script first appeared in 257.Ox 4.4 . 258.Sh AUTHORS 259.An -nosplit 260The 261.Nm 262shell script was written by 263.An Antoine Jacoutot Aq ajacoutot@openbsd.org 264using 265.Fx 266mergemaster written by 267.An Douglas Barton Aq DougB@FreeBSD.org 268as a base. 269