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
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
|
{ config, lib, pkgs, ... }:
with lib;
with types;
let
planDescription = ''
The znapzend backup plan to use for the source.
The plan specifies how often to backup and for how long to keep the
backups. It consists of a series of retention periods to interval
associations:
```
retA=>intA,retB=>intB,...
```
Both intervals and retention periods are expressed in standard units
of time or multiples of them. You can use both the full name or a
shortcut according to the following listing:
```
second|sec|s, minute|min, hour|h, day|d, week|w, month|mon|m, year|y
```
See {manpage}`znapzendzetup(1)` for more info.
'';
planExample = "1h=>10min,1d=>1h,1w=>1d,1m=>1w,1y=>1m";
# A type for a string of the form number{b|k|M|G}
mbufferSizeType = str // {
check = x: str.check x && builtins.isList (builtins.match "^[0-9]+[bkMG]$" x);
description = "string of the form number{b|k|M|G}";
};
enabledFeatures = concatLists (mapAttrsToList (name: enabled: optional enabled name) cfg.features);
# Type for a string that must contain certain other strings (the list parameter).
# Note that these would need regex escaping.
stringContainingStrings = list: let
matching = s: map (str: builtins.match ".*${str}.*" s) list;
in str // {
check = x: str.check x && all isList (matching x);
description = "string containing all of the characters ${concatStringsSep ", " list}";
};
timestampType = stringContainingStrings [ "%Y" "%m" "%d" "%H" "%M" "%S" ];
destType = srcConfig: submodule ({ name, ... }: {
options = {
label = mkOption {
type = str;
description = "Label for this destination. Defaults to the attribute name.";
};
plan = mkOption {
type = str;
description = planDescription;
example = planExample;
};
dataset = mkOption {
type = str;
description = "Dataset name to send snapshots to.";
example = "tank/main";
};
host = mkOption {
type = nullOr str;
description = ''
Host to use for the destination dataset. Can be prefixed with
`user@` to specify the ssh user.
'';
default = null;
example = "john@example.com";
};
presend = mkOption {
type = nullOr str;
description = ''
Command to run before sending the snapshot to the destination.
Intended to run a remote script via {command}`ssh` on the
destination, e.g. to bring up a backup disk or server or to put a
zpool online/offline. See also {option}`postsend`.
'';
default = null;
example = "ssh root@bserv zpool import -Nf tank";
};
postsend = mkOption {
type = nullOr str;
description = ''
Command to run after sending the snapshot to the destination.
Intended to run a remote script via {command}`ssh` on the
destination, e.g. to bring up a backup disk or server or to put a
zpool online/offline. See also {option}`presend`.
'';
default = null;
example = "ssh root@bserv zpool export tank";
};
};
config = {
label = mkDefault name;
plan = mkDefault srcConfig.plan;
};
});
srcType = submodule ({ name, config, ... }: {
options = {
enable = mkOption {
type = bool;
description = "Whether to enable this source.";
default = true;
};
recursive = mkOption {
type = bool;
description = "Whether to do recursive snapshots.";
default = false;
};
mbuffer = {
enable = mkOption {
type = bool;
description = "Whether to use {command}`mbuffer`.";
default = false;
};
port = mkOption {
type = nullOr ints.u16;
description = ''
Port to use for {command}`mbuffer`.
If this is null, it will run {command}`mbuffer` through
ssh.
If this is not null, it will run {command}`mbuffer`
directly through TCP, which is not encrypted but faster. In that
case the given port needs to be open on the destination host.
'';
default = null;
};
size = mkOption {
type = mbufferSizeType;
description = ''
The size for {command}`mbuffer`.
Supports the units b, k, M, G.
'';
default = "1G";
example = "128M";
};
};
presnap = mkOption {
type = nullOr str;
description = ''
Command to run before snapshots are taken on the source dataset,
e.g. for database locking/flushing. See also
{option}`postsnap`.
'';
default = null;
example = literalExpression ''
'''''${pkgs.mariadb}/bin/mysql -e "set autocommit=0;flush tables with read lock;\\! ''${pkgs.coreutils}/bin/sleep 600" & ''${pkgs.coreutils}/bin/echo $! > /tmp/mariadblock.pid ; sleep 10'''
'';
};
postsnap = mkOption {
type = nullOr str;
description = ''
Command to run after snapshots are taken on the source dataset,
e.g. for database unlocking. See also {option}`presnap`.
'';
default = null;
example = literalExpression ''
"''${pkgs.coreutils}/bin/kill `''${pkgs.coreutils}/bin/cat /tmp/mariadblock.pid`;''${pkgs.coreutils}/bin/rm /tmp/mariadblock.pid"
'';
};
timestampFormat = mkOption {
type = timestampType;
description = ''
The timestamp format to use for constructing snapshot names.
The syntax is `strftime`-like. The string must
consist of the mandatory `%Y %m %d %H %M %S`.
Optionally `- _ . :` characters as well as any
alphanumeric character are allowed. If suffixed by a
`Z`, times will be in UTC.
'';
default = "%Y-%m-%d-%H%M%S";
example = "znapzend-%m.%d.%Y-%H%M%SZ";
};
sendDelay = mkOption {
type = int;
description = ''
Specify delay (in seconds) before sending snaps to the destination.
May be useful if you want to control sending time.
'';
default = 0;
example = 60;
};
plan = mkOption {
type = str;
description = planDescription;
example = planExample;
};
dataset = mkOption {
type = str;
description = "The dataset to use for this source.";
example = "tank/home";
};
destinations = mkOption {
type = attrsOf (destType config);
description = "Additional destinations.";
default = {};
example = literalExpression ''
{
local = {
dataset = "btank/backup";
presend = "zpool import -N btank";
postsend = "zpool export btank";
};
remote = {
host = "john@example.com";
dataset = "tank/john";
};
};
'';
};
};
config = {
dataset = mkDefault name;
};
});
### Generating the configuration from here
cfg = config.services.znapzend;
onOff = b: if b then "on" else "off";
nullOff = b: if b == null then "off" else toString b;
stripSlashes = replaceStrings [ "/" ] [ "." ];
attrsToFile = config: concatStringsSep "\n" (builtins.attrValues (
mapAttrs (n: v: "${n}=${v}") config));
mkDestAttrs = dst: with dst;
mapAttrs' (n: v: nameValuePair "dst_${label}${n}" v) ({
"" = optionalString (host != null) "${host}:" + dataset;
_plan = plan;
} // optionalAttrs (presend != null) {
_precmd = presend;
} // optionalAttrs (postsend != null) {
_pstcmd = postsend;
});
mkSrcAttrs = srcCfg: with srcCfg; {
enabled = onOff enable;
# mbuffer is not referenced by its full path to accommodate non-NixOS systems or differing mbuffer versions between source and target
mbuffer = with mbuffer; if enable then "mbuffer"
+ optionalString (port != null) ":${toString port}" else "off";
mbuffer_size = mbuffer.size;
post_znap_cmd = nullOff postsnap;
pre_znap_cmd = nullOff presnap;
recursive = onOff recursive;
src = dataset;
src_plan = plan;
tsformat = timestampFormat;
zend_delay = toString sendDelay;
} // foldr (a: b: a // b) {} (
map mkDestAttrs (builtins.attrValues destinations)
);
files = mapAttrs' (n: srcCfg: let
fileText = attrsToFile (mkSrcAttrs srcCfg);
in {
name = srcCfg.dataset;
value = pkgs.writeText (stripSlashes srcCfg.dataset) fileText;
}) cfg.zetup;
in
{
options = {
services.znapzend = {
enable = mkEnableOption "ZnapZend ZFS backup daemon";
logLevel = mkOption {
default = "debug";
example = "warning";
type = enum ["debug" "info" "warning" "err" "alert"];
description = ''
The log level when logging to file. Any of debug, info, warning, err,
alert. Default in daemonized form is debug.
'';
};
logTo = mkOption {
type = str;
default = "syslog::daemon";
example = "/var/log/znapzend.log";
description = ''
Where to log to (syslog::\<facility\> or \<filepath\>).
'';
};
noDestroy = mkOption {
type = bool;
default = false;
description = "Does all changes to the filesystem except destroy.";
};
autoCreation = mkOption {
type = bool;
default = false;
description = "Automatically create the destination dataset if it does not exist.";
};
zetup = mkOption {
type = attrsOf srcType;
description = "Znapzend configuration.";
default = {};
example = literalExpression ''
{
"tank/home" = {
# Make snapshots of tank/home every hour, keep those for 1 day,
# keep every days snapshot for 1 month, etc.
plan = "1d=>1h,1m=>1d,1y=>1m";
recursive = true;
# Send all those snapshots to john@example.com:rtank/john as well
destinations.remote = {
host = "john@example.com";
dataset = "rtank/john";
};
};
};
'';
};
pure = mkOption {
type = bool;
description = ''
Do not persist any stateful znapzend setups. If this option is
enabled, your previously set znapzend setups will be cleared and only
the ones defined with this module will be applied.
'';
default = false;
};
features.oracleMode = mkEnableOption ''
destroying snapshots one by one instead of using one long argument list.
If source and destination are out of sync for a long time, you may have
so many snapshots to destroy that the argument gets is too long and the
command fails
'';
features.recvu = mkEnableOption ''
recvu feature which uses `-u` on the receiving end to keep the destination
filesystem unmounted
'';
features.compressed = mkEnableOption ''
compressed feature which adds the options `-Lce` to
the {command}`zfs send` command. When this is enabled, make
sure that both the sending and receiving pool have the same relevant
features enabled. Using `-c` will skip unnecessary
decompress-compress stages, `-L` is for large block
support and -e is for embedded data support. see
{manpage}`znapzend(1)`
and {manpage}`zfs(8)`
for more info
'';
features.sendRaw = mkEnableOption ''
sendRaw feature which adds the options `-w` to the
{command}`zfs send` command. For encrypted source datasets this
instructs zfs not to decrypt before sending which results in a remote
backup that can't be read without the encryption key/passphrase, useful
when the remote isn't fully trusted or not physically secure. This
option must be used consistently, raw incrementals cannot be based on
non-raw snapshots and vice versa
'';
features.skipIntermediates = mkEnableOption ''
the skipIntermediates feature to send a single increment
between latest common snapshot and the newly made one. It may skip
several source snaps if the destination was offline for some time, and
it should skip snapshots not managed by znapzend. Normally for online
destinations, the new snapshot is sent as soon as it is created on the
source, so there are no automatic increments to skip
'';
features.lowmemRecurse = mkEnableOption ''
use lowmemRecurse on systems where you have too many datasets, so a
recursive listing of attributes to fi
|