forked from Jehops/zap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
zap.1
271 lines (268 loc) · 7.54 KB
/
zap.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
.Dd July 25, 2021
.Dt ZAP 1
.Os
.Sh NAME
.Nm zap
.Nd "maintain and replicate ZFS snapshots"
.Sh SYNOPSIS
.Nm
.Ar snap Ns | Ns Ar snapshot
.Op Fl DLSv
.Ar TTL
.Oo Op Fl r
.Ar dataset Oc Ns ...
.Nm
.Ar rep Ns | Ns Ar replicate
.Op Fl CDFLSv
.Op Fl h Ar host
.Oo Oo Op Ar user Ns @ Oc Ns Ar host Ns : Ns
.Ar parent_dataset
.Op Fl r
.Ar dataset
.Oo Op Fl r
.Ar dataset Oc Ns ... Oc
.Nm
.Ar destroy
.Op Fl Dlsv
.Op Ar host Ns Oo , Ns Ar host Oc Ns ...
.Nm
.Fl v Ns | Ns Fl version Ns | Ns Fl -version
.Sh DESCRIPTION
.Nm
automates the management of zfs snapshots. With a few simple crontab entries,
it can be used to create a comprehensive zfs backup system. There are no
configuration files. All parameters are supplied on the command line or in zfs
properties and all snapshot information is stored in snapshot names.
.Pp
.Nm
will not interfere with manually created snapshots or snapshots from other
tools. It will only operate on snapshots it creates.
.Pp
If the pool is in a DEGRADED state, then snapshots will still be created,
replicated, and destroyed unless
.Fl D
is used. If the pool is being resilvered or scrubbed, then snapshots will still
created and replicated, but not destroyed. Use
.Fl L ,
.Fl l ,
.Fl S ,
and
.Fl s
to change this behaviour.
.Pp
.Sh SUBCOMMANDS
.Ss Ar snap Ns | Ns Ar snapshot
Use the
.Ar snap
subcommand to create snapshots that will expire after
.Ar TTL
(time to live) has elapsed. An expired snapshot will be destroyed the next time
.Nm
.Ar destroy
is run.
.Ar TTL
takes the form
.Bo 0-9 Bc Ns Bro 1,4 Brc Ns Bo dwmy Bc Ns .
That is, one to four digits followed by a character to represent the time unit
(day, week, month, or year). If datasets are not not supplied on the command
line, snapshots will be created for datasets with the property
.Sy zap:snap
set to
.Sy on Ns .
.Pp
.Ss Ar rep Ns | Ns Ar replicate
Use the
.Ar rep
subcommand to replicate datasets. If a destination and datasets are not
supplied on the command line, datasets with a destination set in the
.Sy zap:rep
user property are replicated. If the destination does not contain a
.Sy host
.Ns , or if the supplied host is
.Sy localhost
.Ns ,
.Sy 127.x.x.x
.Ns , or
.Sy ::1
.Ns , then any
.Sy user@
is ignored and ssh is not used. If the
.Sy canmount
property of the local dataset is set to
.Sy on Ns ,
after replication an attempt is made to set
.Sy canmount
to
.Sy noauto
on the remote side. This is done to prevent mountpoint collisions. By default,
snapshots originating from the local host (as returned by
.Ic hostname -s Ns
) are replicated, but
.Ic -h host
can be used to replicate snapshots originating from
.Ic host Ns .
Set the ZAP_FILTER environment variable to a command to filter the transfer.
For example, ZAP_FILTER="mbuffer -s 128k -m 10M" will filter the transfer
through mbuffer.
Note that the filter command must be available on both the sending and receiving
hosts.
.Pp
.Ss Ar destroy
Use the
.Ar destroy
subcommand to destroy expired snapshots. By default, only snapshots originating
from the local host are destroyed. If a comma separated list of hosts are
specified, then only destroy snapshots originating from those hosts. Hosts are
specified without any domain information, that is, as returned by
.Ic hostname -s Ns .
.Sh OPTIONS
.Bl -tag -width "12345678"
.It Fl C
Do not supply
.Ic -c
to
.Ar zfs send Ns
\&. This option is unsupported on some systems, such as Debian 9 and NetBSD 9.
.It Fl D
Do not operate on snapshots when the pool is in a DEGRADED state.
.It Fl F
Supply
.Ic -F
to
.Ar zfs receive Ns
, which destroys remote changes that do not exist on the sending side.
.It Fl h Ar host
Replicate snapshots originating from
.Ic host
instead of those originating from the local host (as returned by
.Ic hostname -s Ns
).
.It Fl L
Do not operate on snapshots if the pool has a resilver in progress. This is the
default for the
.Ar destroy
subcommand.
.It Fl l
Operate on snapshots, even if the pool has a resilver in progress. This is the
default for the
.Ar snap
and
.Ar rep
subcommands.
.It Fl S
Do not operate on snapshots if the pool is being scrubbed. This is the default
for the
.Ar destroy
subcommand.
.It Fl s
Operate on snapshots, even if the pool is being scrubbed. This is the default
for the
.Ar snap
and
.Ar rep
subcommands.
.It Fl r
Recursively create or replicate snapshots of all descendants.
.It Fl v
Be verbose.
.El
.Sh ENVIRONMENT
The following environment variable affects the execution of
.Nm :
.Bl -tag -width ".Ev CLICOLOR_FORCE"
.It Ev ZAP_FILTER
Filter
.Ar rep
through the command contained in the variable. For example, a value of "mbuffer
-s 128k -m 10M" will filter the transfer through mbuffer. Note that the filter
command must be available on both the sending and receiving hosts.
.El
.Sh EXAMPLES
Create snapshots that will expire after three weeks.
.Bd -literal -offset indent
zfs set zap:snap=on zroot/usr/home/nox zroot/var/
zfs set zap:snap=off zroot/var/crash zroot/var/tmp zroot/var/mail
zap snap 3w
.Ed
.Pp
Create snapshots specifying the datasets on the command line.
.Bd -literal -offset indent
zap snap 3w zroot/usr/home/nox -r zroot/var
.Ed
.Pp
Recursively create snapshots that will expire after one day. Be verbose.
.Bd -literal -offset indent
zfs set zap:snap=on zroot/usr/home
zap snap -v 1d
.Ed
.Pp
Replicate datasets to the remote host bravo, under the zback/phe dataset. If you
use a non-default ssh port, specify it in ~/.ssh/config.
.Bd -literal -offset indent
zfs set zap:rep='zap@bravo:zback/phe' zroot/ROOT zroot/usr/home/jrm
zap rep -v
.Ed
.Pp
Replicate datasets (recursively for zroot/ROOT) to the remote host bravo, under
the rback/phe dataset, but this time specify the datasets on the command
line. If you use a non-default ssh port, specify it in ~/.ssh/config.
.Bd -literal -offset indent
zap rep zap@bravo:rback/phe -r zroot/ROOT zroot/usr/home/jrm
.Ed
.Pp
Replicate datasets originating from awarnach to the remote host bravo, under the
zback/phe dataset. If you use a non-default ssh port, specify it in
~/.ssh/config. Filter the transfer through mbuffer by setting the ZAP_FILTER
environment variable. Note that mbuffer must be available on both the sending
and receiving hosts.
.Bd -literal -offset indent
zfs set zap:rep='zap@bravo:zback/phe' zroot/ROOT zroot/usr/home/jrm
zap rep -v -h awarnach
.Ed
.Pp
Destroy expired snapshots. Be verbose.
.Bd -literal -offset indent
zap destroy -v
.Ed
.Pp
Destroy expired snapshots that originated on either the host awarnach or the
host gly. Be verbose.
.Bd -literal -offset indent
zap destroy -v awarnach,gly
.Ed
.Pp
Example crontab entries for rolling snapshots and remote replication. Taking
snapshots is normally cheap, so do it often. Destroying snapshots can thrash
disks, so only do it every 24 hours.
.Pp
.Bd -literal -offset indent
#minute hour mday month wday command
# take snapshots
*/5 * * * * zap snap 1d
14 */4 * * * zap snap 1w
14 00 * * 1 zap snap 1m
# destroy snapshots
44 04 * * * zap destroy
# replicate datasets
54 */1 * * * zap rep -v
.Ed
.Sh SEE ALSO
.Bl -tag -compact -width "12345678"
.It Lk http://github.com/jehops/zap GitHub Page
.It Lk http://ftfl.ca/blog/2016-12-27-zfs-replication.html Replication strategy
.It Lk http://www.zfsnap.org/ Related tool
.It Xr crontab 5 , Xr zfs 8 , Xr zpool 8
.El
.Sh AUTHOR AND CONTRIBUTORS
.Bl -tag -compact -width "12345678"
.It An Joseph Mingrone Mt [email protected]
.It An Tobias Kortkamp Mt [email protected]
.It An David Samms Mt [email protected]
.It An Victor Naumov Mt [email protected]
.It An Dries Michiels Mt [email protected]
.It An Louis Kowolowski Mt [email protected]
.It An Maxime Soul\('e
.It An sevmonster
.El
.Sh BUGS
.Lk http://github.com/jehops/zap/issues Issue tracker