[distorted-backup] / snap.8.in

.TH snap 8 "6 November 2011" "distorted.org.uk backup"
.SH NAME
snap \- create and remove snapshot devices
.SH SYNOPSIS
.B snap
.RB [ \-u ]
.RB [ \-c
.IR file ]
.I device
.RI [ key \c
.BI = value
\&...]
.SH DESCRIPTION
The
.B snap
utility manages device-level snapshots in a mechanism-independent way.
It's intended to be used as part of automated filesystem maintenance
activities, such as backups or online filesystem checking.
.PP
The command line options are as follows.
.TP
.B "\-h, \-\-help"
Print a help message to standard output and exit with status zero.
.TP
.B "\-v, \-\-version"
Print the program's version number to standard output and exit with
status zero.
.TP
.BI "\-c, \-\-config-file=" file
Read configuration from
.I
file
rather than
.BR @sysconfdir@/snaptab .
.TP
.B "\-u, \-\-unsnap"
Remove a snapshot, rather than creating a new one.  Strictly speaking,
this just passes the option
.B op=unsnap
to the handler, though the conventional interpretation is to remove the
snapshot.
.SS Operation
An
.B op
option is synthesized from the command-line options.  Specifically, if the
.B \-u
as given, then
.B op=unsnap
is set; otherwise
.B op=snap
is assumed.
.PP
The
.B snap
program looks up the
.I device
in the configuration file \(en either
.B /etc/snaptab
or the
.I file
named by the
.B \-u
option \(en and retrieves a snapshot
.I type
and some options.  See
.BR snaptab (5)
for the details of the file format and the process of constructing the
options list.  The
.I device
is usually the name of a device node, relative to
.BR /dev ,
though specific handler programs may have their own conventions.
.PP
The option list from the configuration file, the synthesized
.B op
option, and the command-line option list, are concatenated, in that
order; then, if the resulting list contains two or more options with the
same
.I key
then only the last is retained.  (The
.I key
is the portion of the option before the first
.RB ` = '
character.)
.PP
Finally, the snapshot handler for the selected
.I type
is invoked, as
.IP
.BI @snaplibexecdir@/snap. type
.I device
.IR key = value
\&...
.SS Handler conventions
Much of the behaviour of
.B snap
is left up to individual type-specific handler programs.  In order to
maintain consistency, the following conventions are adopted.
.PP
Options are processed strictly left-to-right.  Each option is parsed as
.IP
.IR key [\fB. type ]\fB= value
.PP
where the
.I key
and
.I type
do not contain
.RB ` = '
characters, and the
.I type
does not contain a
.RB ` . '
character.  If the
.I type
is omitted, or is equal to the handler's type, then the option is
processed; the
.I type
suffix is otherwise ignored; an error is reported if the
.I key
is unrecognized.  Options bearing a different type are silently ignored.
If the same
.I key
occurs more than once, only the last occurrence is significant.
.PP
Two options are always recognized.
.TP
.B op
Synthesized by the
.B snap
program.  The value is
.B snap
if a snapshot is to be created, or
.B unsnap
if it is to be removed (the
.B \-u
option was given).  It is permissible for handlers to define meanings
for other
.B op
values; unrecognized values are an error.
.TP
.B tag
A short arbitrary string which is assigned to the snapshot to
distinguish it from snapshots created by other clients.  The acceptable
form for the tag may vary with the snapshot type, but alphanumerics and
hyphens are always allowed.  This option may be omitted, though this is
discouraged in scripted use: it is not specified whether this is
equivalent to providing some default tag.
.PP
If the
.B op
is
.B snap
then the handler should print the (full) pathname of the block device
containing the snapshot to standard output, followed by a newline.  If
.B op
is
.B unsnap
then the handler should print nothing to standard output.  Other
.B op
values may cause the handler to produce output at its discretion.
.SH BUGS
The
.B snap
program doesn't even try to handle filesystem-level snapshots, as you'd
get in ZFS or BtrFS.  Trying to do both device- and filesystem-level
snapshots in one program leads to all sorts of difficulties, and it's
probably a mistake to try.  The distinction is still annoying, though.
.SH SEE ALSO
.BR snaptab (5).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
99248ed2 MW	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>