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