SBP(8)                                                                  SBP(8)



NAME
       sbp,  first-backup  -  synchronize backup partitions under an alternate
       root filesystem

SYNOPSIS
       sbp [-ajKFnv] [-C cmd]  [-E  rle]  [-f  fstab]  [-H  how]  [-M  marker]
       [-m backup] [-o fssnap-options] [-r source] [file-systems]
       sbp -h
       sbp -V
       first-backup ...

DESCRIPTION
       Sbp uses a common convention in the system file system list to locate a
       "backup" 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.

       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.  There is no rea-
       son  why the copy could not sent to a removable (aka. USB) disk device,
       to create a bootable backup of the running host.

       To make this image sbp runs a shell command to  duplicate  each  parti-
       tion,  in  the fstab file, that starts with the backup prefix and has a
       corresponding entry with the source prefix.  When either the source  or
       destination is missing sbp ignores the partition, for example /proc.

       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  first-backup  it
       tries  to emulate the common "install the boot loader" operation.  Also
       see installboot(8).

       As an optimization, minor changes can be  captured  with  a  delta-only
       copy using the rsync tool (see -H below).

OPTIONS
       If  the  program  is  called as sbp then no options are forced.  If the
       program is called first-backup 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  sin-
       gle  disk  configuration.   For real-world systems a wrapper to put the
       correct labels on more disks is required.

       -a
              Mount the destination file systems async to  speed  the  backup.
              On  hosts  with  no  known  async support this does nothing.  If
              either the primary or backup  partitions  are  normally  mounted
              async, then this is the default for that file system.

       -C cmd
              Cleanup  command  executed  after  copy, before umount.  This is
              often provided as an mk(1l)  command  on  the  fstab,  or  in  a
              locally written shell driver.  Examples include the "installboot
              spell" from the installboot manual page.  There are a  few  per-
              cent  escapes  that  may be embedded in this string to expand to
              parameters found at run-time. They are documented below.

       -E rule
              Larger drives require more fine tuning to get the  best  perfor-
              mance.  Sbp calls the mk(1l) processor to find the optimal shell
              command to build each filesystem (starting with sbp 2.0).   This
              option  tells  sbp  how to assemble the call to mk.  (See -V for
              the default value.)  Note the use of mk's -l option as zero  (0)
              to allow us to scan the whole file.

       -f fstab
              The   file   system  table  to  read,  defaults  to  /etc/fstab,
              /etc/vfstab, or  /etc/checklist as apropos for this host.

       -F
              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.

       -h
              Print only a brief help message.

       -H how
              Specify how to sync the partitions (use ? for help).   The  sup-
              ported  methods  are (at least) "dump", "mk", "rsync", and "dd".
              Note that the rsync and dd programs must  be  installed  in  the
              current  search  path.   The  "fssnap" method is available under
              Solaris 8 (and above) and works like "dump".   The  method  "mk"
              builds  a  rather  complex call to mk requesting the marked line
              which will backup the partition.  Note that a  dummy  entry  for
              the backup partition is required.  See "MK" below.

              The  how  parameter  may  include a colon (:) followed by method
              options.  These options are presented  to  the  method  in  some
              obvious  way.  For example the bs= (block size) option to dd may
              be specified to the dd method (-H dd:bs=768k).

              The special method "sane" checks the alternate configuration for
              some  obvious  errors.  The method option "fsck" runs fsck(8) on
              each partition before it mounts it.  The method option "nomount"
              may  be  used  by  mortal logins to check the sanity of the file
              system table without any superuser access.   The  method  option
              "strict"  makes the sane method more strict with reguard to fsck
              pass numbers, and possibly other nits.

              The special method "mount" simply mounts  the  alternate  parti-
              tions.   The  very dangerous method option "empty" runs newfs on
              each partition before it mounts it ("fsck" works here as  well).

       -j
              Just  guess  at the newfs(8) tune for backup partitions, this is
              useful under the "mk" method.  This option is  not  included  in
              the usage message under older versions of sbp, but it did exist.

       -K
              Try to copy source filesystems that are not  presently  mounted.
              This only works for the dd method (usually).

       -m backup
              Construct  the backup partition on this mount-point, rather than
              /backup.  Sbp doesn't allow the backup directory to  be  any  of
              the  common mount points (viz. /, /usr, /var, /opt) because that
              would destroy the running system.  One should use newfs directly
              to destroy their own host.

       -M marker
              Use  a  different  mk  marker  for  this  run.  The default name
              ("Newfs") doesn't mean anything to mk, viz.   the  code  indexed
              may  run  mkfs.   If  the  filesystem table has multiple sets of
              options this lets you pick another set.

       -n
              Do not execute commands, trace only. Implies -v

       -o fssnap-options
              Pass options to fssnap(1M), rather  than  the  default  backing-
              store in /tmp, rawdevice set.  You must include "rawdevname", at
              least for ufsdump to work.

       -r source
              The source hierarchy (default to the root filesystem).  When you
              want  to  sync  a  backup  to  a backup you need this option (or
              chroot).

       -T rules
              This file should contain a mk marked  line  which  matches  each
              filesystem that will be created by sbp.  The format is
                   $marker(raw-device): command
              Where  raw-device  is the full patch to the raw device, and com-
              mand is expanded by mk(1l) to  construct  the  filesystem.   Sbp
              creates  a  default  file  (in /tmp) when none is provided, then
              removes it when it is done.

       -v
              Be verbose by tracing shell commands as they are executed.

       -V
              Show version information, and exit.

UPDATED TABLE
       The new fstab 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 fstab.   Thus  the  alternate  root
       device is listed as source (usually "/") and the primary root device is
       listed as backup (usually "/backup").

       Another transformation is allowed.  Any  line  which  begins  with  the
       string  "#@ sbp run of" is replaced with that same text followed by the
       present time as output by ctime(3).  This helps track the last time sbp
       was applied to each host.

       The  intent  here is to allow the alternate boot slice to bring all the
       alternate partitions up as primary.  From that booted system the origi-
       nal partitions are now the alternates (so a run of sbp updates those to
       restore the host to the known good state).

ESCAPES
       The escapes below are used internally to product the shell commands  to
       drive the synchronization; they are documented here for the -C command.
       To write a new sync method see the comments in the source file sbp.c.

       +---------+------------------------------------------------------+
       |      %d | block device name                                    |
       +---------+------------------------------------------------------+
       |      %u | the c slice of our block device                      |
       +---------+------------------------------------------------------+
       |      %i | newfs tune options (-i, -c, -a) given or computed    |
       +---------+------------------------------------------------------+
       |      %m | mount point                                          |
       +---------+------------------------------------------------------+
       |      %r | raw device name                                      |
       +---------+------------------------------------------------------+
       |      %w | the c slice of our raw device                        |
       +---------+------------------------------------------------------+
       |     %Xx | any of the above on our primary                      |
       +---------+------------------------------------------------------+
       |         | (so %Xm is our primary's mount point)                |
       +---------+------------------------------------------------------+
       |         |                                                      |
       +---------+------------------------------------------------------+
       |      %a | the string "-o async" or nothing (see -a)            |
       +---------+------------------------------------------------------+
       |      %f | the fstab file we read for this run (from -m)        |
       +---------+------------------------------------------------------+
       |      %F | the fstab file we know the system uses               |
       +---------+------------------------------------------------------+
       |      %P | the method specific parameter for dd, rsync, GNU tar |
       +---------+------------------------------------------------------+
       |      %K | the method keys for cpio, dump                       |
       +---------+------------------------------------------------------+
       |      %O | the options for fssnap (see -o)                      |
       +---------+------------------------------------------------------+
       |         |                                                      |
       +---------+------------------------------------------------------+
       |      %M | the mk fs creation marker (see -M)                   |
       +---------+------------------------------------------------------+
       |      %Q | the path to mk 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)       |
       +---------+------------------------------------------------------+
       The %i 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 newfs.  For exam-
       ple:

                /dev/sd3a /backup ufs 0 2 # -i 12288 -c 20

       This line specifies the alternate partition for the root file system is
       on disk three-a and should be newfs'd with "-i 12288 -c 20".

MK
       The  "mk"  method  builds a single mk command to process each requested
       backup.  The command has quite a few parameters, and the API may change
       in future releases of sbp.  It takes advantage of mk's numbered parame-
       ters (viz. -pos) to provide 5 facts  into  the  command  as  positional
       parameters.

       -0 API-version
              This is the version of the interface as major.params.  The major
              number is a compatibility flag, all versions that share the same
              number  are  backwards  compatible.   While params specifies the
              index of the last parameter provided.   Sbp  presently  provides
              this value as "1.4".

       -1 async | the-empty-string
              This is set to async under -a and the empty string otherwise.

       -2 target-device
              This is the target device listed in the filesystem table.

       -3 fs-type
              The type of the target filesystem.

       -4 newfs-opts
              Any  newfs  options  provided  as  a  comment  after  the backup
              filesystem specification from the filesystem table, or after the
              primary  entry.  The options must start with a dash (-) followed
              by letter ([a-zA-Z]).

              Additional options to mk include:

       -l0 -t rules
              These request that mk search the entire file, and that the spec-
              ified rules table be included in the search (after the fstab).

       -m source-mount -d destination-mount
              These  ask mk to search the whole file for a command marked with
              either:
                       $source-mount(destination-mount): cmd
              or, using the mk matching rules, more likely:
                       $source-mount(*): cmd
              See mk(1l) for more matching possibilities.

       If any option are presented after the method (e.g.  "mk:-s"  or  better
       "mk:-vV"), then these are appended to the command.

       The  last  specification  is  the name of the filesystem table (fstab).
       That leaves mk totally in charge of managing the backup of  the  source
       filesystem.   For  example  the  command triggered could use rsync to a
       remote server.  Here is a three line excerpt from a test filesystem ta-
       ble:
              # $/home/local(*): TO='expr '_%{4}' : '_-\\(.*\\)'' && ${rsync:-rsync} -arxSH %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
       The  marked  comment  holds the template rsync command, and removes the
       necessary leading dash (-) from the  target  host  specification.   The
       backup  entry  encodes  the  backup  host and the location on that host
       where we should backup.

       Many other encodings are possible.  This one assures that the  destina-
       tion  filesystem  is  an  NFS  mount,  then rsync's the current mounted
       filesystem to that "device", over ssh.  The  mk  check  for  the  "nfs"
       string  is  a  sanity  check, since we promiscuously match any markers.
       This doesn't allow a match to the Newfs marker, for example.
              # $*(*): %=/_nfs/_%{3}/ ${rsync:-rsync} -arxSH -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
       Note that the -x option to rsync limits the copy to the source filesys-
       tem.  In some cases that option limits the copy too much.

EXAMPLES
       An example /etc/fstab might look like:

       #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

       or a Solaris host's /etc/vfstab might look more like:
       #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

       sbp
              Backup  all the partitions that have "/backup" prefixes relative
              to their primary versions.

       sbp -v /
              Copy the current root file system to  the  alternate  and  show,
              with shell commands, how you did it.

       sbp -Hrsync:--verbose /usr
              Update  just the /backup/usr partition with rsync, tell rsync to
              be verbose.

       sbp -H '?'
              Show all the method sbp knows to copy partitions.

       sbp -V
              Display the version of sbp installed, and the paths to the  pro-
              grams it calls directly.

       sbp -Hrsync /etc/passwd
              Backup  the  partition  that  contains  /etc/passwd  with rsync.
              (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.)

       sbp -v -Hdump:u -C 'installboot $T/bootblk %r' /
              Backup the root filesystem with dump and install  a  boot  block
              from  the $T directory.  One should set and export $T before the
              command is executed.  See installboot(8).

              If you install a link to sbp named  first-backup  it  makes  the
              alternate drive a clone of the primary in much the same way.

       sbp -v -Hsane:nomount,strict
              Output  a  list of possible bugs in the default fstab.  This may
              be run from hostlint(8).

       To show the differences between last  nights  backup  and  the  monthly
       backup:
              sbp -Hmount -m /backup
              sbp -Hrsync:--dry-run -r /backup -m /monthly
              sbp -Hsane -m /backup

BUGS
       In  Solaris  version  10 Sun has decided to be stupid.  The ZFS library
       that newfs(8) uses breaks when  the  filesystem  you  are  creating  is
       already  listed  in /etc/vfstab.  It expects you to set the environment
       variable $NOINUSE_CHECK to 1 to stop this madness.  This is tragic  for
       several reasons:

       Reading the documentation doesn't help
              They  didn't  document this well, like in newfs's manual page or
              in the new manual page "brain damaged system developers".

       Sun ignored backwards compatibility
              The older version of newfs was documented to  take  the  default
              options for the new file system from /etc/vfstab.

       The variable is negatively named
              Didn't  we  learn  from csh(1)'s nonomatch crazy syntax?  If you
              are going to play with this you might set a level of checking.

       Setting $NOINUSE_CHECK removes safety feature you want
              This one size fits all option turns off all 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.

       Sun doesn't listen to reason
              Having a Very Large Customer complain strong and long about this
              is not enough to make the "engineer" that coded it get some edu-
              cation on design, service, or operations.

       There is no way under Solaris to provide  comments  on  the  end  of  a
       vfstab  file.  The newfs option comment trick never works on that plat-
       form.   So we moved to mk in version 2.0.

       The dd method can create file systems that are so  corrupt  fsck  drops
       core.   It  also  copies the stuff under the mount points on the active
       partitions -- which might be a feature.

       The percent expander in this program is not as well documented as  oth-
       ers.

       The  per-partition command hooks like -C for before (-B) and after (-A)
       each partition is copied should be documented.   The  label  hook  (-L)
       should be documented.

       A  side-effect  of backing up just /usr is that we mkdir(2) /backup/usr
       to mount it, then never remove it.  The extra directories this  creates
       under  the mount point for /backup are just facts-of-life.  It would be
       more of a bug to rmdir them.

       It might be a feature (bug) that we ignore the file system type in  the
       fstab file.

       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
       first-backup).

       Sbp  might mount(8) source partitions that are not presently mounted --
       but that crosses that fine line between clever and stupid.   For  exam-
       ple,  they  might  be owned by another member of our fail-over cluster.
       Also -K helps in this matter,  for  splitting  large  filesystems  into
       smaller ones.

AUTHOR
       KS Braunsdorf
       NonPlayer Character Guild.Org
       sbp no-at-spam ksb.npcguild dot-N0Spam org

SEE ALSO
       sh(1), mk(1l), dicer(5l), xapply(1l), rsync(1), ssh(1), installboot(8),
       newfs(8) or mkfs(8),  dump(8),  restore(8)  ufsdump(8),  ufsrestore(8),
       cpio(1), tar(1) or gnutar(1), dd(1), rmdir(1),



FIRST-BACKUP(8)                      LOCAL                              SBP(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | UPDATED TABLE | ESCAPES | MK | EXAMPLES | BUGS | AUTHOR | SEE ALSO