1.\" $OpenBSD: sysmerge.8,v 1.11 2008/09/12 13:31:59 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: September 12 2008 $ 18.Dt SYSMERGE 8 19.Os 20.Sh NAME 21.Nm sysmerge 22.Nd update system configuration files 23.Sh SYNOPSIS 24.Nm 25.Op Fl ab 26.Op Fl s Ar src \*(Ba etcXX.tgz 27.Op Fl x Ar xetcXX.tgz 28.Sh DESCRIPTION 29.Nm 30is a 31.Xr sh 1 32script designed to help the administrator update configuration files 33after upgrading to a new release or snapshot. 34The configuration files are typically those held in 35.Pa /etc , 36though 37.Nm 38is also able to update files held in 39.Pa /dev , 40.Pa /root , 41and 42.Pa /var . 43.Pp 44It is 45.Sy HIGHLY 46recommended to back up the 47.Pa /etc 48directory before running this script. 49.Pp 50.Nm 51works by comparing a temporary reference root directory 52against currently installed files. 53The reference files are created from a 54.Xr cvs 1 55source tree or a 56.Dq .tgz 57release or snapshot file. 58The default, if no source is specified on the command line, 59is to use 60.Pa /usr/src . 61All work is done under 62.Pa ${TMPDIR}/sysmerge.XXXXX 63(known as the 64.Em work directory ) . 65The temporary root directory 66.Pa temproot 67is created under the work directory. 68Each modified and/or replaced file is saved under the 69.Pa backup 70directory inside the work directory. 71.Pp 72To make sure configuration files are in sync with the actual binaries, 73use the same source as was used to upgrade the system: 74.Pa /usr/src 75when upgrading from source; 76.Pa etcXX.tgz 77and 78.Pa xetcXX.tgz 79when upgrading from binary sets. 80.Pp 81When run in 82.Em automatic 83mode 84.Pq Fl a , 85.Nm 86will skip files with identical CVS Id, install missing ones and run commands 87associated with the following special files if they were modified: 88.Xr aliases 5 , 89.Xr login.conf 5 , 90.Xr MAKEDEV 8 , 91.Xr passwd 5 . 92In 93.Em manual 94mode (the default unless 95.Fl a 96is specified), 97.Nm 98will perform a strict comparison of files. 99.Pa /etc/fbtab , 100.Pa /etc/login.conf , 101.Pa /etc/sysctl.conf , 102and 103.Pa /etc/ttys 104are created using helper scripts and will 105.Sy always 106be strictly compared even in 107.Fl a 108mode. 109.Pp 110.Nm 111will work through the fileset, 112offering the chance to merge any differences 113using ${MERGE_CMD}. 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 119Files and directories can be excluded from comparison 120by listing them in the file 121.Pa /etc/sysmerge.ignore , 122each entry separated by white space or a new line. 123The following files will always be skipped from comparison: 124.Pa /etc/*.db , 125.Pa /etc/mail/*.db , 126.Pa /etc/passwd , 127.Pa /etc/motd , 128.Pa /etc/myname , 129.Pa /var/mail/root . 130.Pp 131The 132.Xr sendmail 8 133configuration files 134.Pa /etc/mail/localhost.cf , 135.Pa /etc/mail/sendmail.cf 136and 137.Pa /etc/mail/submit.cf 138will always differ because they include their build date and directories. 139A special test was added to handle this 140and they are offered for comparison only if they really differ. 141.Pp 142.Nm 143will finish by running 144.Xr mtree 8 145to make sure the directory structure has correct permissions. 146.Pp 147The options are as follows: 148.Bl -tag -width Ds 149.It Fl a 150Automatic mode. 151If this option is specified, 152.Nm 153will automatically install missing files, 154create databases and device nodes, 155and will disable strict file comparison when possible (using CVS Ids). 156.It Fl b 157Batch mode. 158If this option is specified, 159.Nm 160will run unattended (non-interactively), saving differing files for 161later manual processing. 162.It Fl s Ar src \*(Ba etcXX.tgz 163Specify a path to an 164.Ox 165top src directory or an etcXX.tgz tarball. 166A tarball path specified as an FTP or HTTP URL will be passed 167to ${FETCH_CMD}. 168.It Fl x Ar xetcXX.tgz 169Specify a path to an 170xetcXX.tgz tarball. 171A tarball path specified as an FTP or HTTP URL will be passed 172to ${FETCH_CMD}. 173.El 174.Sh ENVIRONMENT 175.Bl -tag -width "DESTDIRXXX" 176.It Ev DESTDIR 177Directory in which to merge and install files. 178If unset, this defaults to 179.Pa / . 180.It Ev FETCH_CMD 181Command used to fetch remote files. 182Defaults to 183.Xr ftp 1 . 184.It Ev MERGE_CMD 185Command used to merge diffs. 186This will be called with three arguments: the first argument is the 187output file to create, the second argument is the currently installed 188file and the third argument is the reference file. 189If unset, this defaults to 190.Dq sdiff -as -w ${SWIDTH} -o . 191.It Ev TMPDIR 192Directory in which the work directory is created. 193If unset, this defaults to 194.Pa /var/tmp . 195.El 196.Sh FILES 197.Bl -tag -width "${TMPDIR}/sysmerge.XXXXXXXX" -compact 198.It ${TMPDIR}/sysmerge.XXXXX 199Default work directory. 200The 201.Sy temproot 202and 203.Sy backup 204directories are created relative to this. 205.It /etc/sysmerge.ignore 206Files and directories to ignore from comparison. 207.El 208.Sh SEE ALSO 209.Xr cap_mkdb 1 , 210.Xr diff 1 , 211.Xr mktemp 1 , 212.Xr more 1 , 213.Xr sdiff 1 , 214.Xr MAKEDEV 8 , 215.Xr mtree 8 , 216.Xr newaliases 8 , 217.Xr pwd_mkdb 8 218.Pp 219.Pa /usr/src/etc/Makefile 220.Pp 221.Pa http://www.openbsd.org/faq/current.html 222.Pa http://www.openbsd.org/faq/upgradeXX.html 223.Sh HISTORY 224The 225.Nm 226script first appeared in 227.Ox 4.4 . 228.Sh AUTHORS 229.An -nosplit 230The 231.Nm 232shell script was written by 233.An Antoine Jacoutot Aq ajacoutot@openbsd.org 234using 235.Fx 236mergemaster written by 237.An Douglas Barton Aq DougB@FreeBSD.org 238as a base. 239