1.\" $OpenBSD: sysmerge.8,v 1.36 2012/02/17 14:06:42 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: February 17 2012 $ 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 Op Ar src \*(Ba etcXX.tgz 28.Op Fl x Ar xetcXX.tgz 29.Ek 30.Sh DESCRIPTION 31.Nm 32is a 33.Xr ksh 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 46.Nm 47works by comparing a temporary reference root directory 48against currently installed files. 49The reference files are created from a 50.Xr cvs 1 51source tree or a 52.Dq .tgz 53release or snapshot file. 54The default, if no source is specified on the command line, 55is to use 56.Pa /usr/src . 57All work is done under 58.Pa ${TMPDIR}/sysmerge.XXXXXXXXXX 59(known as the 60.Em work directory ) . 61The temporary root directory 62.Pa temproot 63is created under the work directory. 64Each modified and/or replaced file is saved under the 65.Pa backup 66directory inside the work directory. 67.Pp 68To make sure configuration files are in sync with the actual binaries, 69use the same source as was used to upgrade the system: 70.Pa /usr/src 71when upgrading from source; 72.Pa etcXX.tgz 73and 74.Pa xetcXX.tgz 75when upgrading from binary sets. 76.Pp 77.Nm 78will work through the fileset, 79offering the chance to merge any differences using ${MERGE_CMD}. 80Merged files may be edited using a default editor, 81or one defined by the ${VISUAL} or ${EDITOR} environment variables. 82Files may also be left to deal with at a later date. 83Should any problems occur, 84such as a failure to upgrade a file, 85the user will be notified and have to deal with the issue by hand. 86.Pp 87By default (if 88.Fl d 89is not used) 90.Nm 91only compares files whose reference sources have changed since the last run 92and attempts to automatically upgrade them to the newest version, 93provided that they have no local changes. 94It automatically installs missing files and binaries, 95and updates files differing only by CVS Id. 96Files whose reference sources have matching CVS Id are skipped from comparison. 97.Pa /etc/fbtab , 98.Pa /etc/login.conf , 99.Pa /etc/sysctl.conf , 100and 101.Pa /etc/ttys 102are created using helper scripts and are 103.Sy always 104compared. 105Users and groups that are missing from the current installation but 106present in the new 107.Xr master.passwd 5 108and 109.Xr group 5 110files will be automatically created. 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 Op 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/db/locate.database , 153.Pa /var/db/sysmerge/etcsum , 154.Pa /var/db/sysmerge/xetcsum , 155.Pa /var/games/tetris.scores , 156.Pa /var/mail/root . 157.Pp 158The 159.Xr sendmail 8 160configuration files 161.Pa /etc/mail/localhost.cf , 162.Pa /etc/mail/sendmail.cf 163and 164.Pa /etc/mail/submit.cf 165will always differ because they include their build date and directories. 166A special test was added to handle this 167and they are offered for comparison only if they really differ. 168.Sh ENVIRONMENT 169.Bl -tag -width "DESTDIRXXX" 170.It Ev DBDIR 171Directory in which checksum files are stored. 172If unset, this defaults to 173.Pa /var/db/sysmerge . 174.It Ev DESTDIR 175Directory in which to merge and install files. 176If unset, this defaults to 177.Pa / . 178.It Ev EDITOR , VISUAL 179Specifies an editor to use. 180If both 181.Ev EDITOR 182and 183.Ev VISUAL 184are set, 185.Ev VISUAL 186takes precedence. 187If neither 188.Ev EDITOR 189nor 190.Ev VISUAL 191are set, 192the default is 193.Xr vi 1 . 194.It Ev FETCH_CMD 195Command used to fetch remote files. 196Defaults to 197.Xr ftp 1 . 198.It Ev FTP_KEEPALIVE 199Have 200.Xr ftp 1 201send a byte after every 202.Ev FTP_KEEPALIVE 203seconds, 204so that incorrectly configured network equipment won't aggressively drop it. 205See 206.Dq ftp -k 207for more information. 208.It Ev MERGE_CMD 209Command used to merge diffs. 210This will be called with three arguments: the first argument is the 211output file to create, the second argument is the currently installed 212file and the third argument is the reference file. 213If unset, this defaults to 214.Dq sdiff -as -w ${SWIDTH} -o . 215.It Ev PAGER 216Specifies the pagination program to use. 217.It Ev REPORT 218Log summary which may contain information for further, manual, 219updating. 220Defaults to 221.Pa ${WRKDIR}/sysmerge.log . 222.It Ev TMPDIR 223Directory in which the work directory is created. 224If unset, this defaults to 225.Pa /var/tmp . 226.El 227.Sh FILES 228.Bl -tag -width "${TMPDIR}/sysmerge.XXXXXXXXXX" -compact 229.It ${TMPDIR}/sysmerge.XXXXXXXXXX 230Default work directory. 231The 232.Sy temproot 233and 234.Sy backup 235directories are created relative to this. 236.It ${WRKDIR}/sysmerge.log 237Default log file. 238.It /etc/sysmerge.ignore 239Files and directories to ignore from comparison. 240.El 241.Sh SEE ALSO 242.Xr cap_mkdb 1 , 243.Xr chpass 1 , 244.Xr diff 1 , 245.Xr mktemp 1 , 246.Xr more 1 , 247.Xr sdiff 1 , 248.Xr groupadd 8 , 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