.\" $Id: sbp.man,v 2.23 2012/09/28 14:29:38 ksb Exp $ .\" by Kevin Braunsdorf .\" $Compile: Display%h .\" $Display: ${groff-groff} -Tascii -tbl -man %f | ${PAGER:-less} .\" $Display(*): ${groff-groff} -T%s -tbl -man %f .\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/sbp.8 .\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/sbp.8* .TH SBP 8 LOCAL "FIRST-BACKUP(8)" .SH NAME sbp, first-backup - synchronize backup partitions under an alternate root filesystem .SH SYNOPSIS .ds PN "sbp \fI\*(PN\fP [\fB\-ajKFnv\fP] [\fB\-C\fP\~\fIcmd\fP] [\fB\-E\fP\~\fIrle\fP] [\fB\-f\fP\~\fIfstab\fP] [\fB\-H\fP\~\fIhow\fP] [\fB\-M\fP\~\fImarker\fP] [\fB\-m\fP\~\fIbackup\fP] [\fB\-o\fP\~\fIfssnap-options\fP] [\fB\-r\fP\~\fIsource\fP] [\fIfile-systems\fP] .br \fI\*(PN\fP \fB\-h\fP .br \fI\*(PN\fP \fB\-V\fP .br \fIfirst-backup\fP \fI...\fP .SH DESCRIPTION \fBSbp\fP uses a common convention in the system file system list to locate a \*(lqbackup\*(rq copy of a partition. It then synchronizes the data from the primary (current) partition to the backup (alternate) location. These two disk slices are usually about the same size. .\" in the case of raw partitions they should be exactly the same size .PP This process is used to create an image of the running system just before major changes (like OS upgrades or major patches) are installed to provide a back-out path, should something go awry. .PP To make this image \fI\*(PN\fP runs a shell command to duplicate each partition, in the \fIfstab\fP file, that starts with the \fIbackup\fP prefix and has a corresponding entry with the \fIsource\fP prefix. When either the source or destination is missing \fI\*(PN\fP ignores the partition, for example \fB/proc\fP. .PP By convention there is a shell script driver for each production system (which might be the same for most) that does this operation the first time. This script remembers the options to force the boot loader onto the new root file system. If the program is called \fBfirst-backup\fP it tries to emulate the common \*(lqinstall the boot loader\*(rq operation. Also see \fBinstallboot\fP(8). .PP As an optimization, minor changes can be captured with a delta-only copy using the \fBrsync\fP tool (see \fB\-H\fP below). .SH OPTIONS If the program is called as \fI\*(PN\fP then no options are forced. If the program is called \fBfirst-backup\fP then it copies the disk label from the primary to the backup root disk, and it installs a boot block on the backup boot partition. This only works on a Solaris host, with a single disk configuration. For real-world systems a wrapper to put the correct labels on more disks is required. .TP \fB\-a\fP Mount the destination file systems \fBasync\fP to speed the backup. On hosts with no known \fBasync\fP support this does nothing. If either the primary or backup partitions are normally mounted \fBasync\fP, then this is the default for that file system. .TP \fB\-C\fP \fIcmd\fP Cleanup command executed after copy, before umount. This is often provided as an \fBmk\fP(1l) command on the fstab, or in a locally written shell driver. Examples include the \*(lqinstallboot spell\*(rq from the installboot manual page. There are a few percent escapes that may be embedded in this string to expand to parameters found at run-time. They are documented below. .TP \fB\-E\fP \fIrule\fP Larger drives require more fine tuning to get the best performance. \fISbp\fP calls the \fBmk\fP(1l) processor to find the optimal shell command to build each filesystem (starting with sbp 2.0). This option tells \fI\*(PN\fP how to assemble the call to \fBmk\fP. (See \fB\-V\fP for the default value.) Note the use of \fBmk\fP's \fB\-l\fP option as zero (0) to allow us to scan the whole file. .TP \fB\-f\fP \fIfstab\fP The file system table to read, defaults to \fI/etc/fstab\fP, \fI/etc/vfstab\fP, or \fI/etc/checklist\fP as apropos for this host. .TP \fB\-F\fP Leave the backup file system table as a clone of the original. This is handy for making exact copied of a disk to clone a host. .TP \fB\-h\fP Print a help message. .TP \fB\-H\fP \fIhow\fP Specify how to sync the partitions (use ? for help). The supported methods are (at least) \*(lqdump\*(rq, \*(lqmk\*(rq, \*(lqrsync\*(rq, and \*(lqdd\*(rq. Note that the \fBrsync\fP and \fBdd\fP programs must be installed in the current search path. The \*(lqfssnap\*(rq method is available under Solaris 8 (and above) and works like \*(lqdump\*(rq. The method \*(lqmk\*(rq builds a rather complex call to \fBmk\fP requesting the marked line which will backup the partition. Note that a dummy entry for the backup partition is required. See \*(lqMK\*(rq below. .sp The \fIhow\fP parameter may include a colon (:) followed by method options. These options are presented to the method in some obvious way. For example the \fBbs=\fP (block size) option to \fBdd\fP may be specified to the \fBdd\fP method (-H dd:bs=768k). .sp The special method \*(lqsane\*(rq checks the alternate configuration for some obvious errors. The method option \*(lqfsck\*(rq runs \fIfsck\fP on each partition before it mounts it. The method option \*(lqnomount\*(rq may be used by mortal logins to check the sanity of the file system table without any superuser access. The method option \*(lqstrict\*(rq makes the sane method more strict with reguard to \fIfsck\fP pass numbers, and possibly other nits. .sp The special method \*(lqmount\*(rq simply mounts the alternate partitions. The very dangerous method option \*(lqempty\*(rq runs \fInewfs\fP on each partition before it mounts it (\*(lqfsck\*(rq works here as well). .TP \fB\-j\fP Just guess at the \fBnewfs\fP tune for backup partitions, this is useful under the \*(lqmk\*(rq method. This option is not included in the usage message under older versions of \fI\*(PN\fP, but it did exist. .TP \fB\-K\fP Try to copy source filesystems that are not presently mounted. This only works for the \fBdd\fP method (usually). .TP \fB\-m\fP \fIbackup\fP Construct the backup partition on this mount-point, rather than \fI/backup\fP. \fBSbp\fP doesn't allow the \fIbackup\fP directory to be any of the common mount points (viz. /, \fI/usr\fP, \fI/var\fP, \fI/opt\fP) because that would destroy the running system. One should use \fBnewfs\fP(8) directly to destroy their own host. .TP \fB\-M\fP \fImarker\fP Use a different \fBmk\fP marker for this run. The default name (\*(lqNewfs\*(rq) doesn't mean anything to \fBmk\fP, viz. the code indexed may run \fBmkfs\fP. If the filesystem table has multiple sets of options this lets you pick the another set. .TP \fB\-n\fP Do not execute commands, trace only. Implies \fB\-v\fP .TP \fB\-o\fP \fIfssnap-options\fP Pass options to \fBfssnap\fP(1M), rather than the default backing-store in /tmp, rawdevice set. You \fBmust\fP include \*(lqrawdevname\*(rq, at least for ufsdump to work. .TP \fB\-r\fP \fIsource\fP The source hierarchy (default to the root filesystem). When you want to sync a backup to a backup you need this option (or chroot). .TP \fB\-T\fP \fIrules\fP This file should contain a \fBmk\fP marked line which matches each filesystem that will be created by sbp. The format is .nf \fB$\fP\fImarker\fP(\fIraw-device\fP): \fIcommand\fP .fi Where \fIraw-device\fP is the full patch to the raw device, and \fIcommand\fP is expanded by \fBmk\fP(1l) to construct the filesystem. \fISbp\fP creates a default file (in /tmp) when none is provided, then removes it when it is done. .TP \fB\-v\fP Be verbose by tracing shell commands as they are executed. .TP \fB\-V\fP Show version information, and exit. .SH "UPDATED TABLE" The new \fIfstab\fP on the alternate root partition is created by swapping the device specifications for the primary and backup partitions for each pair presented in the original \fIfstab\fP. Thus the alternate root device is listed as \fIsource\fP (usually \*(lq/\*(rq) and the primary root device is listed as \fIbackup\fP (usually \*(lq/backup\*(rq). .P Another transformation is allowed. Any line which begins with the string \*(lq#@ sbp run of\*(rq is replaced with that same text followed by the present time as output by \fBctime\fP(3). This helps track the last time \fI\*(PN\fP was applied to each host. .P The intent here is to allow the alternate boot slice to bring all the alternate partitions up as primary. From that booted system the original partitions are now the alternates (so a run of \fI\*(PN\fP updates those to restore the host to the known good state). .SH ESCAPES The escapes below are used internally to product the shell commands to drive the synchronization; they are documented here for the \fB\-C\fP command. To write a new sync method see the comments in the source file sbp.c. .TS allbox; r l. %d block device name %u the c slice of our block device %i \fBnewfs\fP tune options (\-i, \-c, \-a) given or computed %m mount point %r raw device name %w the c slice of our raw device %X\fIx\fP any of the above on our primary (so %Xm is our primary's mount point) %a the string \*(lq\-o async\*(rq or nothing (see \fB\-a\fP) %f the fstab file we read for this run (from \fB\-m\fP) %F the fstab file we know the system uses %P the method specific parameter for \fBdd\fP, \fBrsync\fP, GNU \fBtar\fP %K the method keys for \fBcpio\fP, \fBdump\fP %O the options for \fIfssnap\fP (see \fB\-o\fP) %M the mk fs creation marker (see \fB\-M\fP) %Q the path to \fBmk\fP found at compile time %T the table of marked lines for filesystem creation %{fs}... locate a filesystem by mount point or device name %[...] access the dicer around any above (see xapply) %(...) access the mixer around any above (see xapply) .TE .PP The \fB%i\fP escape above looks for a comment on the end of the primary or backup entry in the file system list that (after any leading white space) starts with a dash (\-) and a letter. If it can find a comment like that it assumes that those are all options for \fBnewfs\fP. For example: .sp /dev/sd3a /backup ufs 0 2 # \-i 12288 \-c 20 .sp This line specifies the alternate partition for the root file system is on disk three-a and should be newfs'd with \*(lq\-i 12288 \-c 20\*(rq. .\" .PP .\" If no such comment is found and \fB\-j\fP is presented we make a good guess. .\" There are some undocumented options (\-D, \-I) which tune this guess-work. .SH MK The \*(lqmk\*(rq method builds a single \fBmk\fP command to process each requested backup. The command has quite a few parameters, and the API may change in future releases of \fI\*(PN\fP. It takes advantage of \fBmk\fP's numbered parameters (viz. \fB\-\fP\fIpos\fP) to provide 5 facts into the command as positional parameters. .TP .nf \fB\-0\fP \fIAPI-version\fP .fi This is the version of the interface as \fImajor\fP\fB.\fP\fIparams\fP. The \fImajor\fP number is a compatibility flag, all versions that share the same number are backwards compatible. While \fIparams\fP specifies the index of the last parameter provided. \fISbp\fP presently provides this value as \*(lq1.4\*(rq. .TP .nf \fB\-1\fP \fBasync\fP | \fIthe-empty-string\fP .fi This is set to \fBasync\fP under \fB\-a\fP and the empty string otherwise. .TP .nf \fB\-2\fP \fItarget-device\fP .fi This is the target device listed in the filesystem table. .TP .nf \fB\-3\fP \fIfs-type\fP .fi The type of the target filesystem. .TP .nf \fB\-4\fP \fInewfs-opts\fP .fi Any \fBnewfs\fP options provided as a comment after the backup filesystem specification from the filesystem table, or after the primary entry. The options \fBmust\fP start with a dash (\fB\-\fP) followed by letter ([a-zA-Z]). .P Additional options to \fBmk\fP include: .TP .nf \fB\-l0 \-t\fP \fIrules\fP .fi These request that \fBmk\fP search the entire file, and that the specifed \fIrules\fP table be included in the search (after the \fIfstab\fP). .TP .nf \fB\-m\fP \fIsource-mount\fP \fB\-d\fP \fIdestination-mount\fP .fi These ask \fBmk\fP to search the whole file for a command marked with either: .nf \fB$\fP\fIsource-mount\fP(\fIdestination-mount\fP): \fIcmd\fP .fi or, using the \fBmk\fP matching rules, more likely: .nf \fB$\fP\fIsource-mount\fP(*): \fIcmd\fP .fi See \fBmk\fP(1l) for more matching possibilies. .P If any option are presented after the method (e.g. \*(lqmk:-s\*(rq or better \*(lqmk:-vV\*(rq), then these are appended to the command. .P The last specification is the name of the filesystem table (\fIfstab\fP). That leaves \fBmk\fP totally in charge of managing the backup of the source filesystem. For example the command triggered could use \fBrsync\fP to a remote server. Here is a three line excerpt from a test filesystem table: .RS .nf # $/home/local(*): TO=`expr '_%{4}' : '_\-\e\e(.*\e\e)'` && ${rsync:\-rsync} \-arSH %m $TO/%[m/$] /dev/ad0f /home/local ufs rw 30 4 /dev/null /backup/home/local nfs ro,noauto 30 4 # \-keeper:/var/dumps/sulaco .fi .RE The marked comment holds the template \fBrsync\fP command, and removes the necessary leading dash (\fB\-\fP) from the target host specification. The backup entry encodes the backup host and the location on that host where we should backup. .P Many other encodings are possible. This one assures that the destination filesystem is an \fBNFS\fP mount, then \fBrsync\fP's the current mounted filesystem to that \*(lqdevice\*(rq, over \fBssh\fP. The \fBmk\fP check for the \*(lqnfs\*(rq string is a sanity check, since we promiscuously match any markers. This doesn't allow a match to the \fBNewfs\fP marker, for example. .RS .nf # $*(*): %=/_nfs/_%{3}/ ${rsync:-rsync} \-arSH \-e ssh %m %{2} /dev/ad0 /home/local ufs rw 30 4 keeper:/var/dumps/sulaco/local /backup/home/local nfs ro,noauto 30 4 .fi .RE .SH EXAMPLES An example \fB/etc/fstab\fP might look like: .sp .nf #Device Mount-point FStype Options Dump Pass# /dev/ad0s1a / ufs rw 1 1 /dev/ad1s1e /var ufs rw 1 2 /dev/ad0s1f /usr ufs rw 1 3 /dev/vinum/tmp /tmp ufs rw 1 4 /dev/ad1s1a /backup ufs rw,noauto 0 2 /dev/ad0s1e /backup/var ufs rw,noauto 0 3 /dev/ad1s1f /backup/usr ufs rw,noauto 0 4 # $Newfs(/dev/ad0s1f): newfs \-i 79872 \-b 8192 \-f 8192 %s # $Newfs(/dev/ad1s1f): newfs \-i 79872 \-b 8192 \-f 8192 %s .fi .sp or a Solaris host's \fB/etc/vfstab\fP might look more like: .nf #device raw mount type pass atboot opts /dev/dsk/c0t0d0s0 /dev/rdsk/c0t0d0s0 / ufs 1 no \- /dev/dsk/c0t1d0s3 /dev/rdsk/c0t1d0s3 /usr ufs 2 no \- /dev/dsk/c0t0d0s6 /dev/rdsk/c0t0d0s6 /var ufs 4 no \- /dev/dsk/c0t1d0s0 /dev/rdsk/c0t1d0s0 /backup ufs 2 no \- /dev/dsk/c0t0d0s3 /dev/rdsk/c0t0d0s3 /backup/usr ufs 3 no \- /dev/dsk/c0t1d0s6 /dev/rdsk/c0t1d0s6 /backup/var ufs 5 no \- swap \- /tmp tmpfs \- yes \- # $Newfs(/dev/rdsk/c0t1d0s3): echo "yes" | newfs \-i 56320 \-b 8192 \-f 8192 %s # $Newfs(/dev/rdsk/c0t0d0s3): echo "yes" | newfs \-i 56320 \-b 8192 \-f 8192 %s .fi .TP .nf \fI\*(PN\fP .fi Backup all the partitions that have \*(lq/backup\*(rq prefixes relative to their primary versions. .TP .nf \fI\*(PN\fP \-v / .fi Copy the current root file system to the alternate and show, with shell commands, how you did it. .TP .nf \fI\*(PN\fP \-Hrsync:--verbose /usr .fi Update just the \fI/backup/usr\fP partition with \fBrsync\fP, tell \fBrsync\fP to be verbose. .TP .nf \fI\*(PN\fP \-H '?' .fi Show all the method \fI\*(PN\fP knows to copy partitions. .TP .nf \fI\*(PN\fP \-V .fi Display the version of \fI\*(PN\fP installed, and the paths to the programs it calls directly. .TP .nf \fI\*(PN\fP \-Hrsync /etc/passwd .fi Backup the partition that contains \fI/etc/passwd\fP with \fBrsync\fP. (Yeah, I know that should be the root partition: the point is that we find the apropos mount point automatically, and it does the whole file system, not just the one file.) .TP .nf \fI\*(PN\fP \-v \-Hdump:u \-C 'installboot $T/bootblk %r' / .fi Backup the root filesystem with \fBdump\fP and install a boot block from the $T directory. One should set and export $T before the command is executed. See \fBinstallboot\fP(8). .sp If you install a link to \fI\*(PN\fP named \fBfirst-backup\fP it makes the alternate drive a clone of the primary in much the same way. .TP .nf \fI\*(PN\fP \-v \-Hsane:nomount,strict .fi Output a list of possible bugs in the default \fIfstab\fP. This may be run from \fBhostlint\fP(8). .P To show the differences between last nights backup and the monthly backup: .RS \fI\*(PN\fP \-Hmount \-m /backup .br \fI\*(PN\fP \-Hrsync:--dry-run \-r /backup \-m /monthly .br \fI\*(PN\fP \-Hsane \-m /backup .RE .SH BUGS In Solaris version 10 Sun has decided to be stupid. The ZFS library that \fInewfs\fP uses breaks when the filesystem you are creating is already listed in \fI/etc/vfstab\fP. It expects you to set the environment variable $\fBNOINUSE_CHECK\fP to 1 to stop this madness. This is tragic for several reasons: .TP .nf Reading the documentation doesn't help .fi They didn't document this well, like in \fInewfs\fP's manual page or in the new manual page \*(lqbrain damaged system developers\*(rq. .TP .nf Sun ignored backwards compatibility .fi The older version of \fInewfs\fP was documented to take the default options for the new file system from \fI/etc/vfstab\fP. .TP .nf The variable is negatively named .fi Didn't we learn from \fBcsh\fP's nonomatch crazy syntax? If you are going to play with this you might set a level of checking. .TP .nf Setting $\fBNOINUSE_CHECK\fP removes safety feature you want .fi This one size fits all option turns off \fBall\fP the safety features! You can newfs a mounted partition with this on. Gee, thanks for forcing me to put a loaded gun to my head. .TP .nf Sun doesn't listen to reason .fi Having a Very Large Customer complain strong and long about this .\" crap is not enough to make the \*(lqengineer\*(rq that coded it get some education on design, service, or operations. .\" I hate them for this, if you couldn't tell. .PP There is no way under Solaris to provide comments on the end of a \fBvfstab\fP file. The newfs option comment trick never works on that platform. So we moved to \fBmk\fP in version 2.0. .PP The \fBdd\fP method can create file systems that are so corrupt \fBfsck\fP drops core. It also copies the stuff under the mount points on the active partitions -- which might be a feature. .PP The percent expander in this program is not as well documented as others. .PP The per-partition command hooks like \fB\-C\fP for before (\fB\-B\fP) and after (\fB\-A\fP) each partition is copied should be documented. The label hook (\fB\-L\fP) should be documented. .PP A side-effect of backing up just \fB/usr\fP is that we \fBmkdir\fP \fI/backup/usr\fP to mount it, then never remove it. The extra directories this creates under the mount point for \fI/backup\fP are just facts-of-life. It would be more of a bug to \fBrmdir\fP them. .PP It might be a feature (bug) that we ignore the file system type in the \fIfstab\fP file. .PP The code to copy a disk's VTOC and install a boot-loader is very vendor specific, so much so that ksb gave up trying to figure it out (for \fBfirst-backup\fP). .PP \fISbp\fP might \fBmount\fP source partitions that are not presently mounted -- but that crosses that fine line between clever and stupid. For example, they might be owned by another member of our fail-over cluster. Also \fB\-K\fP helps in this matter, for splitting large filesystems into smaller ones. .SH AUTHOR KS Braunsdorf .br NonPlayer Character Guild.Org .br sbp no-at-spam ksb.npcguild dot-N0Spam org .SH "SEE ALSO" .hlm 0 sh(1), mk(1l), dicer(5l), xapply(1l), rsync(1), ssh(1), installboot(8), newfs(8), dump(8), restore(8) ufsdump(8), ufsrestore(8), cpio(1), gnutar(1), dd(1), rmdir(1)