chiark - git - mdw - distorted-backup/blob - snap.8.in

   1 .TH snap 8 "6 November 2011" "distorted.org.uk backup"
   2 .SH NAME
   3 snap \- create and remove snapshot devices
   4 .SH SYNOPSIS
   5 .B snap
   6 .RB [ \-u ]
   7 .RB [ \-c
   8 .IR file ]
   9 .I device
  10 .RI [ key \c
  11 .BI = value
  12 \&...]
  13 .SH DESCRIPTION
  14 The
  15 .B snap
  16 utility manages device-level snapshots in a mechanism-independent way.
  17 It's intended to be used as part of automated filesystem maintenance
  18 activities, such as backups or online filesystem checking.
  19 .PP
  20 The command line options are as follows.
  21 .TP
  22 .B "\-h, \-\-help"
  23 Print a help message to standard output and exit with status zero.
  24 .TP
  25 .B "\-v, \-\-version"
  26 Print the program's version number to standard output and exit with
  27 status zero.
  28 .TP
  29 .BI "\-c, \-\-config-file=" file
  30 Read configuration from
  31 .I
  32 file
  33 rather than
  34 .BR @sysconfdir@/snaptab .
  35 .TP
  36 .B "\-u, \-\-unsnap"
  37 Remove a snapshot, rather than creating a new one.  Strictly speaking,
  38 this just passes the option
  39 .B op=unsnap
  40 to the handler, though the conventional interpretation is to remove the
  41 snapshot.
  42 .SS Operation
  43 An
  44 .B op
  45 option is synthesized from the command-line options.  Specifically, if the
  46 .B \-u
  47 as given, then
  48 .B op=unsnap
  49 is set; otherwise
  50 .B op=snap
  51 is assumed.
  52 .PP
  53 The
  54 .B snap
  55 program looks up the
  56 .I device
  57 in the configuration file \(en either
  58 .B /etc/snaptab
  59 or the
  60 .I file
  61 named by the
  62 .B \-u
  63 option \(en and retrieves a snapshot
  64 .I type
  65 and some options.  See
  66 .BR snaptab (5)
  67 for the details of the file format and the process of constructing the
  68 options list.  The
  69 .I device
  70 is usually the name of a device node, relative to
  71 .BR /dev ,
  72 though specific handler programs may have their own conventions.
  73 .PP
  74 The option list from the configuration file, the synthesized
  75 .B op
  76 option, and the command-line option list, are concatenated, in that
  77 order; then, if the resulting list contains two or more options with the
  78 same
  79 .I key
  80 then only the last is retained.  (The
  81 .I key
  82 is the portion of the option before the first
  83 .RB ` = '
  84 character.)
  85 .PP
  86 Finally, the snapshot handler for the selected
  87 .I type
  88 is invoked, as
  89 .IP
  90 .BI @snaplibexecdir@/snap. type
  91 .I device
  92 .IR key = value
  93 \&...
  94 .SS Handler conventions
  95 Much of the behaviour of
  96 .B snap
  97 is left up to individual type-specific handler programs.  In order to
  98 maintain consistency, the following conventions are adopted.
  99 .PP
 100 Options are processed strictly left-to-right.  Each option is parsed as
 101 .IP
 102 .IR key [\fB. type ]\fB= value
 103 .PP
 104 where the
 105 .I key
 106 and
 107 .I type
 108 do not contain
 109 .RB ` = '
 110 characters, and the
 111 .I type
 112 does not contain a
 113 .RB ` . '
 114 character.  If the
 115 .I type
 116 is omitted, or is equal to the handler's type, then the option is
 117 processed; the
 118 .I type
 119 suffix is otherwise ignored; an error is reported if the
 120 .I key
 121 is unrecognized.  Options bearing a different type are silently ignored.
 122 If the same
 123 .I key
 124 occurs more than once, only the last occurrence is significant.
 125 .PP
 126 Two options are always recognized.
 127 .TP
 128 .B op
 129 Synthesized by the
 130 .B snap
 131 program.  The value is
 132 .B snap
 133 if a snapshot is to be created, or
 134 .B unsnap
 135 if it is to be removed (the
 136 .B \-u
 137 option was given).  It is permissible for handlers to define meanings
 138 for other
 139 .B op
 140 values; unrecognized values are an error.
 141 .TP
 142 .B tag
 143 A short arbitrary string which is assigned to the snapshot to
 144 distinguish it from snapshots created by other clients.  The acceptable
 145 form for the tag may vary with the snapshot type, but alphanumerics and
 146 hyphens are always allowed.  This option may be omitted, though this is
 147 discouraged in scripted use: it is not specified whether this is
 148 equivalent to providing some default tag.
 149 .PP
 150 If the
 151 .B op
 152 is
 153 .B snap
 154 then the handler should print the (full) pathname of the block device
 155 containing the snapshot to standard output, followed by a newline.  If
 156 .B op
 157 is
 158 .B unsnap
 159 then the handler should print nothing to standard output.  Other
 160 .B op
 161 values may cause the handler to produce output at its discretion.
 162 .SH BUGS
 163 The
 164 .B snap
 165 program doesn't even try to handle filesystem-level snapshots, as you'd
 166 get in ZFS or BtrFS.  Trying to do both device- and filesystem-level
 167 snapshots in one program leads to all sorts of difficulties, and it's
 168 probably a mistake to try.  The distinction is still annoying, though.
 169 .SH SEE ALSO
 170 .BR snaptab (5).
 171 .SH AUTHOR
 172 Mark Wooding, <mdw@distorted.org.uk>