[distorted-backup] / snap.lvm.8

.TH snap.lvm 8 "6 November 2011" "distorted.org.uk backup"
.SH NAME
snap.lvm \- snapshot handler for LVM logical volumes
.SH SYNOPSIS
.B snap.lvm
.IB vg-name / lv-name
.IB key = value
\&...
.SH DESCRIPTION
This is a snapshot handler for LVM volumes: see
.BR snap (8)
for more information about how snapshot handlers fit into the overall
system.  It creates or removes a snapshot of the logical volume named
.I lv-name
on the volume group
.IR vg-name .
.PP
The following options keys are recognized, either with a
.RB ` .lvm '
suffix or without.  Other keys are reported as errors, unless the key
contains a
.RB ` . '
character.
.TP
.BI op= op
The
.I op
must be either
.B snap
(the default) to create a snapshot, or
.B unsnap
to remove it.
.TP
.BI tag= tag
The snapshot volume will be named
.IB lv-name . tag \fR.
The default tag is
.BR snap .
It is recommended that scripts always provide a tag identifying their
purpose.
.TP
.BI snapsz= sz
The size to allocate for the snapshot's backing store.  This may be an
absolute size followed by an optional unit suffix
.RB ` K ',
.RB ` M ',
.RB ` T ',
.RB ` P ',
or
.RB ` E '
for kilobytes, megabytes (the default), terabytes, petabytes, or
exabytes, respectively; or a relative size of the form
.IB n % what \fR,
where
.I what
is
.BR VG ,
.BR FREE ,
or
.BR ORIGIN ,
to request
.IR n %
of the total space in the volume group, the free space remaining in the
volume group, or the size of the origin volume, respectively.  (The
.I what
suffix may be abbreviated to just the first letter; the suffixes are not
case-sensitive in either case.)
.SH BUGS
The LVM tools are rather buggy, and exhibit nasty races with
.B udev (8).
The
.BR lvremove (8)
tool is particularly awful.
The
.B snap.lvm
handler uses
.BR lvm-rmsnap (8)
to work around these bugs.
.PP
If you make a snapshot of a logical volume while a filesystem is
directly mounted from the logical volume on the same machine, and the
filesystem kernel driver implements the
.B freeze_fs
and
.B unfreeze_fs
superblock operations, then the kernel will arrange for the snapshot to
contain a consistent and clean snapshot of the filesystem \(en in
particular, it shouldn't need the ministrations of
.BR fsck (8).
If the filesystem is mounted by a different machine, e.g., a guest
running on the same host, or via a network block-device access protocol,
you will need to negotiate with the remote machine in order to obtain a
clean snapshot.  See
.BR snap.rfreezefs (8)
for a snapshot handler which copes with this, and
.BR rfreezefs (8)
for the actual machinery.
.SH SEE ALSO
.BR snap (8),
.BR lvm (8),
.BR lvm-rmsnap (8),
.BR rfreezefs (8).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
Commit	Line	Data
99248ed2 MW	1	.TH snap.lvm 8 "6 November 2011" "distorted.org.uk backup"
	2	.SH NAME
	3	snap.lvm \- snapshot handler for LVM logical volumes
	4	.SH SYNOPSIS
	5	.B snap.lvm
	6	.IB vg-name / lv-name
	7	.IB key = value
	8	\&...
	9	.SH DESCRIPTION
	10	This is a snapshot handler for LVM volumes: see
	11	.BR snap (8)
	12	for more information about how snapshot handlers fit into the overall
	13	system. It creates or removes a snapshot of the logical volume named
	14	.I lv-name
	15	on the volume group
	16	.IR vg-name .
	17	.PP
	18	The following options keys are recognized, either with a
	19	.RB ` .lvm '
	20	suffix or without. Other keys are reported as errors, unless the key
	21	contains a
	22	.RB ` . '
	23	character.
	24	.TP
	25	.BI op= op
	26	The
	27	.I op
	28	must be either
	29	.B snap
	30	(the default) to create a snapshot, or
	31	.B unsnap
	32	to remove it.
	33	.TP
	34	.BI tag= tag
	35	The snapshot volume will be named
	36	.IB lv-name . tag \fR.
	37	The default tag is
	38	.BR snap .
	39	It is recommended that scripts always provide a tag identifying their
	40	purpose.
	41	.TP
	42	.BI snapsz= sz
	43	The size to allocate for the snapshot's backing store. This may be an
	44	absolute size followed by an optional unit suffix
	45	.RB ` K ',
	46	.RB ` M ',
	47	.RB ` T ',
	48	.RB ` P ',
	49	or
	50	.RB ` E '
	51	for kilobytes, megabytes (the default), terabytes, petabytes, or
	52	exabytes, respectively; or a relative size of the form
	53	.IB n % what \fR,
	54	where
	55	.I what
	56	is
	57	.BR VG ,
	58	.BR FREE ,
	59	or
	60	.BR ORIGIN ,
	61	to request
	62	.IR n %
	63	of the total space in the volume group, the free space remaining in the
	64	volume group, or the size of the origin volume, respectively. (The
65	.I what
66	suffix may be abbreviated to just the first letter; the suffixes are not
67	case-sensitive in either case.)
68	.SH BUGS
69	The LVM tools are rather buggy, and exhibit nasty races with
70	.B udev (8).
71	The
72	.BR lvremove (8)
73	tool is particularly awful.
74	The
75	.B snap.lvm
76	handler uses
77	.BR lvm-rmsnap (8)
78	to work around these bugs.
79	.PP
80	If you make a snapshot of a logical volume while a filesystem is
81	directly mounted from the logical volume on the same machine, and the
82	filesystem kernel driver implements the
83	.B freeze_fs
84	and
85	.B unfreeze_fs
86	superblock operations, then the kernel will arrange for the snapshot to
87	contain a consistent and clean snapshot of the filesystem \(en in
88	particular, it shouldn't need the ministrations of
89	.BR fsck (8).
90	If the filesystem is mounted by a different machine, e.g., a guest
91	running on the same host, or via a network block-device access protocol,
92	you will need to negotiate with the remote machine in order to obtain a
93	clean snapshot. See
94	.BR snap.rfreezefs (8)
95	for a snapshot handler which copes with this, and
96	.BR rfreezefs (8)
97	for the actual machinery.
98	.SH SEE ALSO
99	.BR snap (8),
100	.BR lvm (8),
101	.BR lvm-rmsnap (8),
102	.BR rfreezefs (8).
103	.SH AUTHOR
104	Mark Wooding, <mdw@distorted.org.uk>