1.\" $OpenBSD: sysmerge.8,v 1.21 2009/04/12 07:43:17 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: April 12 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 85.Nm 86will work through the fileset, 87offering the chance to merge any differences using ${MERGE_CMD}. 88Merged files may be edited using a default editor, 89or one defined by the ${VISUAL} or ${EDITOR} environment variables. 90Files may also be left to deal with at a later date. 91Should any problems occur, 92such as a failure to upgrade a file, 93the user will be notified and have to deal with the issue by hand. 94.Pp 95.Nm 96will finish by running 97.Xr mtree 8 98to make sure the directory structure has correct permissions. 99.Pp 100The options are as follows: 101.Bl -tag -width Ds 102.It Fl a 103Automatic mode. 104If this option is specified, 105.Nm 106will automatically install missing files 107and files differing only by CVS Id, 108and will disable strict file comparison when possible (using CVS Id). 109.Pa /etc/fbtab , 110.Pa /etc/login.conf , 111.Pa /etc/sysctl.conf , 112and 113.Pa /etc/ttys 114are created using helper scripts and will 115.Sy always 116be strictly compared, even when 117.Fl a 118is specified. 119.It Fl b 120Batch mode. 121If this option is specified, 122.Nm 123will run unattended (non-interactively), saving differing files for 124later manual processing. 125.It Fl S Ar etcXX.tgz 126Specify a path to an 127etcXX.tgz tarball, 128where XX represents the version to be upgraded from. 129.Nm 130will attempt to automatically upgrade files from this version 131to the one specified by 132.Fl s , 133provided that the file has no local changes. 134Files that have not been modified between the supplied tarballs will 135not be offered for comparison. 136A tarball path specified as an FTP or HTTP URL will be passed 137to ${FETCH_CMD}. 138.It Fl s Ar src \*(Ba etcXX.tgz 139Specify a path to an 140.Ox 141top src directory or an etcXX.tgz tarball. 142A tarball path specified as an FTP or HTTP URL will be passed 143to ${FETCH_CMD}. 144.It Fl X Ar xetcXX.tgz 145Specify a path to an 146xetcXX.tgz tarball, 147where XX represents the version to be upgraded from. 148.Nm 149will attempt to automatically upgrade files from this version 150to the one specified by 151.Fl x , 152provided that the file has no local changes. 153Files that have not been modified between the supplied tarballs will 154not be offered for comparison. 155A tarball path specified as an FTP or HTTP URL will be passed 156to ${FETCH_CMD}. 157.It Fl x Ar xetcXX.tgz 158Specify a path to an 159xetcXX.tgz tarball. 160A tarball path specified as an FTP or HTTP URL will be passed 161to ${FETCH_CMD}. 162.El 163.Pp 164Files and directories can be excluded from comparison 165by listing them in the file 166.Pa /etc/sysmerge.ignore , 167each entry separated by white space or a new line. 168The following files will always be skipped from comparison: 169.Pa /etc/*.db , 170.Pa /etc/mail/*.db , 171.Pa /etc/passwd , 172.Pa /etc/motd , 173.Pa /etc/myname , 174.Pa /var/mail/root . 175.Pp 176The 177.Xr sendmail 8 178configuration files 179.Pa /etc/mail/localhost.cf , 180.Pa /etc/mail/sendmail.cf 181and 182.Pa /etc/mail/submit.cf 183will always differ because they include their build date and directories. 184A special test was added to handle this 185and they are offered for comparison only if they really differ. 186.Sh ENVIRONMENT 187.Bl -tag -width "DESTDIRXXX" 188.It Ev DESTDIR 189Directory in which to merge and install files. 190If unset, this defaults to 191.Pa / . 192.It Ev EDITOR , VISUAL 193Specifies an editor to use. 194If both 195.Ev EDITOR 196and 197.Ev VISUAL 198are set, 199.Ev VISUAL 200takes precedence. 201If neither 202.Ev EDITOR 203nor 204.Ev VISUAL 205are set, 206the default is 207.Xr vi 1 . 208.It Ev FETCH_CMD 209Command used to fetch remote files. 210Defaults to 211.Xr ftp 1 . 212.It Ev MERGE_CMD 213Command used to merge diffs. 214This will be called with three arguments: the first argument is the 215output file to create, the second argument is the currently installed 216file and the third argument is the reference file. 217If unset, this defaults to 218.Dq sdiff -as -w ${SWIDTH} -o . 219.It Ev REPORT 220Log summary which may contain information for further, manual, 221updating. 222Defaults to 223.Pa ${WRKDIR}/sysmerge.log . 224.It Ev TMPDIR 225Directory in which the work directory is created. 226If unset, this defaults to 227.Pa /var/tmp . 228.El 229.Sh FILES 230.Bl -tag -width "${TMPDIR}/sysmerge.XXXXXXXX" -compact 231.It ${TMPDIR}/sysmerge.XXXXX 232Default work directory. 233The 234.Sy temproot 235and 236.Sy backup 237directories are created relative to this. 238.It ${WRKDIR}/sysmerge.log 239Default log file. 240.It /etc/sysmerge.ignore 241Files and directories to ignore from comparison. 242.El 243.Sh SEE ALSO 244.Xr cap_mkdb 1 , 245.Xr diff 1 , 246.Xr mktemp 1 , 247.Xr more 1 , 248.Xr sdiff 1 , 249.Xr MAKEDEV 8 , 250.Xr makemap 8 , 251.Xr mtree 8 , 252.Xr newaliases 8 , 253.Xr pwd_mkdb 8 254.Pp 255.Pa /usr/src/etc/Makefile 256.Pp 257.Pa http://www.openbsd.org/faq/current.html 258.Pa http://www.openbsd.org/faq/upgradeXX.html 259.Sh HISTORY 260The 261.Nm 262script first appeared in 263.Ox 4.4 . 264.Sh AUTHORS 265.An -nosplit 266The 267.Nm 268shell script was written by 269.An Antoine Jacoutot Aq ajacoutot@openbsd.org 270using 271.Fx 272mergemaster written by 273.An Douglas Barton Aq DougB@FreeBSD.org 274as a base. 275