1.\" $OpenBSD: sysmerge.8,v 1.38 2012/08/28 05:42:07 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 28 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 111.Sy always 112be automatically (re)created. 113.Pp 114.Nm 115will finish by running 116.Xr mtree 8 117to make sure the directory structure has correct permissions. 118.Pp 119The options are as follows: 120.Bl -tag -width Ds 121.It Fl b 122Batch mode. 123.Nm 124runs non-interactively, 125saving differing files for later manual processing. 126.It Fl d 127Diff mode. 128In this mode, 129.Nm 130will not take any automatic action, allowing for a full diff comparison. 131.It Fl s Op Ar src \*(Ba etcXX.tgz 132Specify a path to an 133.Ox 134top src directory or an etcXX.tgz tarball. 135A tarball path specified as an FTP or HTTP URL will be passed 136to ${FETCH_CMD}. 137.It Fl x Ar xetcXX.tgz 138Specify a path to an 139xetcXX.tgz tarball. 140A tarball path specified as an FTP or HTTP URL will be passed 141to ${FETCH_CMD}. 142.El 143.Pp 144Files and directories can be excluded from comparison 145by listing them in the file 146.Pa /etc/sysmerge.ignore , 147each entry separated by white space or a new line. 148The following files will always be skipped from comparison: 149.Pa /etc/*.db , 150.Pa /etc/mail/*.db , 151.Pa /etc/passwd , 152.Pa /etc/motd , 153.Pa /etc/myname , 154.Pa /var/db/locate.database , 155.Pa /var/db/sysmerge/etcsum , 156.Pa /var/db/sysmerge/xetcsum , 157.Pa /var/games/tetris.scores , 158.Pa /var/mail/root . 159.Pp 160The 161.Xr sendmail 8 162configuration files 163.Pa /etc/mail/localhost.cf , 164.Pa /etc/mail/sendmail.cf 165and 166.Pa /etc/mail/submit.cf 167will always differ because they include their build date and directories. 168A special test was added to handle this 169and they are offered for comparison only if they really differ. 170.Sh ENVIRONMENT 171.Bl -tag -width "DESTDIRXXX" 172.It Ev DBDIR 173Directory in which checksum files are stored. 174If unset, this defaults to 175.Pa /var/db/sysmerge . 176.It Ev DESTDIR 177Directory in which to merge and install files. 178If unset, this defaults to 179.Pa / . 180.It Ev EDITOR , VISUAL 181Specifies an editor to use. 182If both 183.Ev EDITOR 184and 185.Ev VISUAL 186are set, 187.Ev VISUAL 188takes precedence. 189If neither 190.Ev EDITOR 191nor 192.Ev VISUAL 193are set, 194the default is 195.Xr vi 1 . 196.It Ev FETCH_CMD 197Command used to fetch remote files. 198Defaults to 199.Xr ftp 1 . 200.It Ev FTP_KEEPALIVE 201Have 202.Xr ftp 1 203send a byte after every 204.Ev FTP_KEEPALIVE 205seconds, 206so that incorrectly configured network equipment won't aggressively drop it. 207See 208.Dq ftp -k 209for more information. 210.It Ev MERGE_CMD 211Command used to merge diffs. 212This will be called with three arguments: the first argument is the 213output file to create, the second argument is the currently installed 214file and the third argument is the reference file. 215If unset, this defaults to 216.Dq sdiff -as -w ${SWIDTH} -o . 217.It Ev PAGER 218Specifies the pagination program to use. 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.XXXXXXXXXX" -compact 231.It ${TMPDIR}/sysmerge.XXXXXXXXXX 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 chpass 1 , 246.Xr diff 1 , 247.Xr mktemp 1 , 248.Xr more 1 , 249.Xr sdiff 1 , 250.Xr groupadd 8 , 251.Xr MAKEDEV 8 , 252.Xr makemap 8 , 253.Xr mtree 8 , 254.Xr newaliases 8 , 255.Xr pwd_mkdb 8 256.Pp 257.Pa /usr/src/etc/Makefile 258.Pp 259.Lk http://www.openbsd.org/faq/current.html 260.Lk http://www.openbsd.org/faq/upgradeXX.html 261.Sh HISTORY 262The 263.Nm 264script first appeared in 265.Ox 4.4 . 266.Sh AUTHORS 267.An -nosplit 268The 269.Nm 270shell script was written by 271.An Antoine Jacoutot Aq ajacoutot@openbsd.org 272using 273.Fx 274mergemaster written by 275.An Douglas Barton Aq DougB@FreeBSD.org 276as a base. 277