1.\" $OpenBSD: sysmerge.8,v 1.44 2014/01/28 09:42: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: January 28 2014 $ 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 bdS 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. 54All work is done under 55.Pa ${TMPDIR}/sysmerge.XXXXXXXXXX 56(known as the 57.Em work directory ) . 58The temporary root directory 59.Pa temproot 60is created under the work directory. 61Each modified and/or replaced file is saved under the 62.Pa backup 63directory inside the work directory. 64.Pp 65If no source is specified on the command line, 66.Nm 67uses 68.Xr ftp 1 69to fetch the required sets from the URL pointed to by the 70.Ev SM_PATH 71environment variable, and falls back to 72.Pa /usr/src 73if this variable is unset. 74.Pp 75To make sure configuration files are in sync with the actual binaries, 76use the same source as was used to upgrade the system: 77.Pa /usr/src 78when upgrading from source; 79.Pa etcXX.tgz 80and 81.Pa xetcXX.tgz 82when upgrading from tgz sets. 83When using sets, 84.Nm 85will cryptographically verify their integrity, 86stopping immediately should signatures not match. 87.Pp 88.Nm 89will work through the fileset, 90offering the chance to merge any differences using ${MERGE_CMD}. 91Merged files may be edited using a default editor, 92or one defined by the ${VISUAL} or ${EDITOR} environment variables. 93Files may also be left to deal with at a later date. 94Should any problems occur, 95such as a failure to upgrade a file, 96the user will be notified and have to deal with the issue by hand. 97.Pp 98By default (if 99.Fl d 100is not used) 101.Nm 102only compares files whose reference sources have changed since the last run 103and attempts to automatically upgrade them to the newest version, 104provided that they have no local changes. 105It automatically installs missing files and binaries, 106and updates files differing only by CVS Id. 107Files whose reference sources have matching CVS Id are skipped from comparison. 108.Pa /etc/fbtab , 109.Pa /etc/login.conf , 110.Pa /etc/sysctl.conf , 111and 112.Pa /etc/ttys 113are created using helper scripts and are 114.Sy always 115compared. 116Users and groups that are missing from the current installation but 117present in the new 118.Xr master.passwd 5 119and 120.Xr group 5 121files will 122.Sy always 123be automatically (re)created. 124.Pp 125.Nm 126will finish by running 127.Xr mtree 8 128to make sure the directory structure has correct permissions. 129.Pp 130The options are as follows: 131.Bl -tag -width Ds 132.It Fl b 133Batch mode. 134.Nm 135runs non-interactively, 136saving differing files for later manual processing. 137.It Fl d 138Diff mode. 139In this mode, 140.Nm 141will not take any automatic action, allowing for a full diff comparison. 142.It Fl S 143Do not verify signatures for tgz sets. 144.It Fl s Op Ar src \*(Ba etcXX.tgz 145Specify a path to an 146.Ox 147top src directory or an etcXX.tgz tarball. 148A tarball path specified as a URL will be passed 149to 150.Xr ftp 1 . 151.It Fl x Ar xetcXX.tgz 152Specify a path to an 153xetcXX.tgz tarball. 154A tarball path specified as a URL will be passed 155to 156.Xr ftp 1 . 157.El 158.Pp 159Files and directories can be excluded from comparison 160by listing them in the file 161.Pa /etc/sysmerge.ignore , 162each entry separated by white space or a new line. 163The following files will always be skipped from comparison: 164.Pa /etc/*.db , 165.Pa /etc/localtime , 166.Pa /etc/mail/*.db , 167.Pa /etc/passwd , 168.Pa /etc/motd , 169.Pa /etc/myname , 170.Pa /var/db/locate.database , 171.Pa /var/db/sysmerge/etcsum , 172.Pa /var/db/sysmerge/xetcsum , 173.Pa /var/games/tetris.scores , 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 DBDIR 189Directory in which checksum files are stored. 190If unset, this defaults to 191.Pa /var/db/sysmerge . 192.It Ev DESTDIR 193Directory in which to merge and install files. 194If unset, this defaults to 195.Pa / . 196.It Ev EDITOR , VISUAL 197Specifies an editor to use. 198If both 199.Ev EDITOR 200and 201.Ev VISUAL 202are set, 203.Ev VISUAL 204takes precedence. 205If neither 206.Ev EDITOR 207nor 208.Ev VISUAL 209are set, 210the default is 211.Xr vi 1 . 212.It Ev FTP_KEEPALIVE 213Have 214.Xr ftp 1 215send a byte after every 216.Ev FTP_KEEPALIVE 217seconds, 218so that incorrectly configured network equipment won't aggressively drop it. 219See 220.Dq ftp -k 221for more information. 222.It Ev MERGE_CMD 223Command used to merge diffs. 224This will be called with three arguments: the first argument is the 225output file to create, the second argument is the currently installed 226file and the third argument is the reference file. 227If unset, this defaults to 228.Dq sdiff -as -w ${SWIDTH} -o . 229.It Ev PAGER 230Specifies the pagination program to use. 231.It Ev REPORT 232Log summary which may contain information for further, manual, 233updating. 234Defaults to 235.Pa ${WRKDIR}/sysmerge.log . 236.It Ev SM_PATH 237A URL, specifying the directory to search for sets matching the 238currently running release if none are specified on the command line. 239.It Ev TMPDIR 240Directory in which the work directory is created. 241If unset, this defaults to 242.Pa /var/tmp . 243.El 244.Sh FILES 245.Bl -tag -width "${TMPDIR}/sysmerge.XXXXXXXXXX" -compact 246.It ${TMPDIR}/sysmerge.XXXXXXXXXX 247Default work directory. 248The 249.Sy temproot 250and 251.Sy backup 252directories are created relative to this. 253.It ${WRKDIR}/sysmerge.log 254Default log file. 255.It /etc/sysmerge.ignore 256Files and directories to ignore from comparison. 257.El 258.Sh SEE ALSO 259.Xr more 1 , 260.Xr sdiff 1 261.Pp 262.Pa /usr/src/etc/Makefile 263.Pp 264.Lk http://www.openbsd.org/faq/current.html 265.Lk http://www.openbsd.org/faq/upgradeXX.html 266.Sh HISTORY 267The 268.Nm 269script first appeared in 270.Ox 4.4 . 271.Sh AUTHORS 272.An -nosplit 273The 274.Nm 275shell script was written by 276.An Antoine Jacoutot Aq Mt ajacoutot@openbsd.org 277using 278.Fx 279mergemaster written by 280.An Douglas Barton Aq Mt DougB@FreeBSD.org 281as a base. 282