1.\" $OpenBSD: sysmerge.8,v 1.18 2009/04/06 14:39:23 jmc 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: April 6 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 ab 27.Op Fl S Ar etcXX.tgz 28.Op Fl s Ar src \*(Ba etcXX.tgz 29.Op Fl X Ar xetcXX.tgz 30.Op Fl x Ar xetcXX.tgz 31.Ek 32.Sh DESCRIPTION 33.Nm 34is a 35.Xr sh 1 36script designed to help the administrator update configuration files 37after upgrading to a new release or snapshot. 38The configuration files are typically those held in 39.Pa /etc , 40though 41.Nm 42is also able to update files held in 43.Pa /dev , 44.Pa /root , 45and 46.Pa /var . 47.Pp 48It is 49.Sy HIGHLY 50recommended to back up the 51.Pa /etc 52directory before running this script. 53.Pp 54.Nm 55works by comparing a temporary reference root directory 56against currently installed files. 57The reference files are created from a 58.Xr cvs 1 59source tree or a 60.Dq .tgz 61release or snapshot file. 62The default, if no source is specified on the command line, 63is to use 64.Pa /usr/src . 65All work is done under 66.Pa ${TMPDIR}/sysmerge.XXXXX 67(known as the 68.Em work directory ) . 69The temporary root directory 70.Pa temproot 71is created under the work directory. 72Each modified and/or replaced file is saved under the 73.Pa backup 74directory inside the work directory. 75.Pp 76To make sure configuration files are in sync with the actual binaries, 77use the same source as was used to upgrade the system: 78.Pa /usr/src 79when upgrading from source; 80.Pa etcXX.tgz 81and 82.Pa xetcXX.tgz 83when upgrading from binary sets. 84.Pp 85When run in 86.Em automatic 87mode 88.Pq Fl a 89.Nm 90will skip files with identical CVS Id and install missing ones. 91In 92.Em manual 93mode (the default unless 94.Fl a 95is specified), 96.Nm 97will perform a strict comparison of files. 98.Pa /etc/fbtab , 99.Pa /etc/login.conf , 100.Pa /etc/sysctl.conf , 101and 102.Pa /etc/ttys 103are created using helper scripts and will 104.Sy always 105be strictly compared even in 106.Fl a 107mode. 108.Pp 109.Nm 110will work through the fileset, 111offering the chance to merge any differences using ${MERGE_CMD}. 112Merged files may be edited using a default editor, 113or one defined by the ${VISUAL} or ${EDITOR} environment variables. 114Files may also be left to deal with at a later date. 115Should any problems occur, 116such as a failure to upgrade a file, 117the user will be notified and have to deal with the issue by hand. 118.Pp 119When updating from sets, a tarball from an older snapshot or release 120may be provided using the 121.Fl S 122or 123.Fl X 124options. 125If files differ between the supplied tarballs, then installed 126files which have not been modified from the originals will 127be updated automatically. 128Those that have been modified will be offered for comparison. 129.Pp 130Files and directories can be excluded from comparison 131by listing them in the file 132.Pa /etc/sysmerge.ignore , 133each entry separated by white space or a new line. 134The following files will always be skipped from comparison: 135.Pa /etc/*.db , 136.Pa /etc/mail/*.db , 137.Pa /etc/passwd , 138.Pa /etc/motd , 139.Pa /etc/myname , 140.Pa /var/mail/root . 141.Pp 142The 143.Xr sendmail 8 144configuration files 145.Pa /etc/mail/localhost.cf , 146.Pa /etc/mail/sendmail.cf 147and 148.Pa /etc/mail/submit.cf 149will always differ because they include their build date and directories. 150A special test was added to handle this 151and they are offered for comparison only if they really differ. 152.Pp 153.Nm 154will finish by running 155.Xr mtree 8 156to make sure the directory structure has correct permissions. 157.Pp 158The options are as follows: 159.Bl -tag -width Ds 160.It Fl a 161Automatic mode. 162If this option is specified, 163.Nm 164will automatically install missing files and disable strict file 165comparison when possible (using CVS Ids). 166.It Fl b 167Batch mode. 168If this option is specified, 169.Nm 170will run unattended (non-interactively), saving differing files for 171later manual processing. 172.It Fl S Ar etcXX.tgz 173Specify a path to an 174etcXX.tgz tarball, 175where XX represents the version to be upgraded from. 176.Nm 177will attempt to automatically upgrade files from this version 178to the one specified by 179.Fl s , 180provided that the file has no local changes. 181A tarball path specified as an FTP or HTTP URL will be passed 182to ${FETCH_CMD}. 183.It Fl s Ar src \*(Ba etcXX.tgz 184Specify a path to an 185.Ox 186top src directory or an etcXX.tgz tarball. 187A tarball path specified as an FTP or HTTP URL will be passed 188to ${FETCH_CMD}. 189.It Fl X Ar xetcXX.tgz 190Specify a path to an 191xetcXX.tgz tarball, 192where XX represents the version to be upgraded from. 193.Nm 194will attempt to automatically upgrade files from this version 195to the one specified by 196.Fl x , 197provided that the file has no local changes. 198A tarball path specified as an FTP or HTTP URL will be passed 199to ${FETCH_CMD}. 200.It Fl x Ar xetcXX.tgz 201Specify a path to an 202xetcXX.tgz tarball. 203A tarball path specified as an FTP or HTTP URL will be passed 204to ${FETCH_CMD}. 205.El 206.Sh ENVIRONMENT 207.Bl -tag -width "DESTDIRXXX" 208.It Ev DESTDIR 209Directory in which to merge and install files. 210If unset, this defaults to 211.Pa / . 212.It Ev EDITOR , VISUAL 213Specifies an editor to use. 214If both 215.Ev EDITOR 216and 217.Ev VISUAL 218are set, 219.Ev VISUAL 220takes precedence. 221If neither 222.Ev EDITOR 223nor 224.Ev VISUAL 225are set, 226the default is 227.Xr vi 1 . 228.It Ev FETCH_CMD 229Command used to fetch remote files. 230Defaults to 231.Xr ftp 1 . 232.It Ev MERGE_CMD 233Command used to merge diffs. 234This will be called with three arguments: the first argument is the 235output file to create, the second argument is the currently installed 236file and the third argument is the reference file. 237If unset, this defaults to 238.Dq sdiff -as -w ${SWIDTH} -o . 239.It Ev REPORT 240Log summary which may contain information for further, manual, 241updating. 242Defaults to 243.Pa ${WRKDIR}/sysmerge.log . 244.It Ev TMPDIR 245Directory in which the work directory is created. 246If unset, this defaults to 247.Pa /var/tmp . 248.El 249.Sh FILES 250.Bl -tag -width "${TMPDIR}/sysmerge.XXXXXXXX" -compact 251.It ${TMPDIR}/sysmerge.XXXXX 252Default work directory. 253The 254.Sy temproot 255and 256.Sy backup 257directories are created relative to this. 258.It ${WRKDIR}/sysmerge.log 259Default log file. 260.It /etc/sysmerge.ignore 261Files and directories to ignore from comparison. 262.El 263.Sh SEE ALSO 264.Xr cap_mkdb 1 , 265.Xr diff 1 , 266.Xr mktemp 1 , 267.Xr more 1 , 268.Xr sdiff 1 , 269.Xr MAKEDEV 8 , 270.Xr mtree 8 , 271.Xr newaliases 8 , 272.Xr pwd_mkdb 8 273.Pp 274.Pa /usr/src/etc/Makefile 275.Pp 276.Pa http://www.openbsd.org/faq/current.html 277.Pa http://www.openbsd.org/faq/upgradeXX.html 278.Sh HISTORY 279The 280.Nm 281script first appeared in 282.Ox 4.4 . 283.Sh AUTHORS 284.An -nosplit 285The 286.Nm 287shell script was written by 288.An Antoine Jacoutot Aq ajacoutot@openbsd.org 289using 290.Fx 291mergemaster written by 292.An Douglas Barton Aq DougB@FreeBSD.org 293as a base. 294