-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathbrandysnap.html
850 lines (533 loc) · 41.1 KB
/
brandysnap.html
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
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSYS">SYNOPSYS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#Very-Quick-Start">Very Quick Start</a></li>
<li><a href="#Remote-Sources-and-Destinations">Remote Sources and Destinations</a></li>
<li><a href="#Preserving-Ownership">Preserving Ownership</a></li>
<li><a href="#Keeping-Snapshots">Keeping Snapshots</a></li>
<li><a href="#Managing-Snapshots-Manually">Managing Snapshots Manually</a></li>
<li><a href="#Definition-of-snapshot-vs-full-incremental-backups">Definition of 'snapshot' vs full/incremental backups</a></li>
<li><a href="#Email-Notifications">Email Notifications</a></li>
<li><a href="#Options">Options</a>
<ul>
<li><a href="#Contexts">Contexts</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#OPTIONS">OPTIONS</a>
<ul>
<li><a href="#Main-options">Main options</a></li>
<li><a href="#Tuning-options">Tuning options</a></li>
<li><a href="#Helpful-options">Helpful options</a></li>
<li><a href="#Rsync-options">Rsync options</a></li>
<li><a href="#Email-Options">Email Options</a></li>
<li><a href="#Advanced-Options">Advanced Options</a></li>
<li><a href="#Development-options">Development options</a></li>
</ul>
</li>
<li><a href="#FURTHER-DETAILS">FURTHER DETAILS</a>
<ul>
<li><a href="#Calendar-mode">Calendar mode</a></li>
<li><a href="#Safe-mode">Safe mode</a></li>
<li><a href="#Strict-mode">Strict mode</a></li>
<li><a href="#Weeks-and-months-and-years">Weeks and months and years</a></li>
<li><a href="#Status-report">Status report</a></li>
<li><a href="#Snapshot-names">Snapshot names</a></li>
<li><a href="#Interrupt-handling">Interrupt handling</a></li>
<li><a href="#Other-notes">Other notes</a></li>
</ul>
</li>
<li><a href="#KNOWN-ISSUES">KNOWN ISSUES</a></li>
<li><a href="#AUTHOR">AUTHOR</a></li>
</ul>
<h1 id="NAME">NAME</h1>
<p>brandysnap - rsync snapshot manager</p>
<h1 id="SYNOPSYS">SYNOPSYS</h1>
<p>brandysnap [OPTION...]</p>
<p>typically</p>
<p>brandysnap --conf brandysnap.conf [OTHER OPTIONS...]</p>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<pre><code> This is part of the brandysnap documentation.
Copyright (c) 2011-2013 Chris Dennis [email protected]
See the file fdl-1.3.txt for copying conditions.</code></pre>
<p>Brandysnap is (yet another) script that uses rsync to create snapshot backups of files and directories.</p>
<p>It is still being developed, and should be considered 'beta' software. Use it at your own risk! On the other hand, it's getting better: the author already uses it 'in production'.</p>
<p>It is designed to be flexible and robust. In particular, it copes well with situations where snapshots are not created as regularly as they should be. This can be for a variety of reasons -- hardware failure, operator failure, weekends, holidays, someone forgot to plug in the external USB drive...</p>
<p>Rather than assigning 'importance' to snapshots according to when they were made (for example, keeping Friday afternoon backups for longer than Tuesday morning ones), it looks at what snapshots exist and decides if any can be deleted. If the Friday afternoon backup is missing, it will keep the nearest one it can find.</p>
<p>The basic rule is 'backup first, ask questions later'. Brandysnap assumes that snapshots are cheap -- in both time and space. In other words, making a snapshot is quick, and uses relatively little disk space because of the use of hard links. (Of course the first snapshot is not cheap. And snapshots over a network are never particularly quick.)</p>
<p>It therefore creates a new snapshot every time it is run, and then thinks about which snapshots, if any, are no longer required.</p>
<p>Brandysnap tries to cope with any situation. Either the source or the destination can be on a remote computer (but not both at the same time).</p>
<p>Brandysnap is designed to be run regularly from cron (or similar automation system). It can also be run manually if required without upsetting things.</p>
<p>One of the features of brandysnap is that it uses rsync to do all the work, even for deleting old snapshots locally etc. That means that, if you need root access to create the snapshot maintaining ownership and permissions, the script only needs sudo access for rsync, not for any other command nor for the script itself. (e.g. use <b>--rsync-cmd = 'sudo rsync'</b> and <b>--remote-rsync-cmd = 'sudo rsync'</b> to avoid the need for passwords [need more explanation here])</p>
<p>Brandysnap has been developed on Linux. It is written in Perl and uses a selection of fairly standard modules (all available in Ubuntu repositories, and no doubt elsewhere too). It relies on hard links [see ...] and will only work properly when creating snapshots on a filing system that can handle hard links, such as ext3 or ext4 [and others...].</p>
<p>Starting with version 0.2.19, Brandysnap can also run under Cygwin on Windows. Please note that this has not been extensively tested yet.</p>
<p>Lots of snapshots don't make a file more secure: if the file hasn't changed, and is the same in all snapshots, then it is only stored once on the disk. If it gets corrupted for any reason, then it will be corrupted in all snapshots. (If the file is DELETED from one snapshot, it will still exist in the others, because of the way hard links work.) Think of the whole set of snapshots as one backup, with multiple versions of files that have changed.</p>
<h2 id="Very-Quick-Start">Very Quick Start</h2>
<p>See the README file for brief installation instructions.</p>
<p>If you want to try it out without reading further, create a configuration file called brandysnap-test1.conf containing something like this:</p>
<pre><code> source = /path/to/something/to/backup
destination = /path/to/writable/directory
template = brandysnap-test1
spec = 4h1,1h,1d7</code></pre>
<p>and then run</p>
<pre><code> brandysnap --dry-run --conf brandysnap-test1.conf</code></pre>
<p>The <b>dry-run</b> option will mean that nothing will actually be done. Once you're happy that the script won't break anything, try it without the <b>dry-run</b>.</p>
<p>For more options, run <b>brandysnap --help</b>.</p>
<h2 id="Remote-Sources-and-Destinations">Remote Sources and Destinations</h2>
<p>Brandysnap assumes that any messing about with passwords has been taken care of.</p>
<p>In other words, it will call rsync on remote directories without supplying a password.</p>
<p>There are various ways of setting up rsync so that it doesn't prompt for a password -- they are not described here. [ a reference or two would be helpful here] So it's important to get the password-less access sorted out first. In fact rsync may be run many times during one run of brandysnap, and rsync would prompt for a password each time.</p>
<p>If the remote side of the transfer is running SSH on a non-standard port, you'll find that there is no way to include the port in the location: <b>[email protected]:/thingy</b>. The work-around is to create an alias in <b>~/.ssh/config</b> like this:</p>
<pre><code> Host eg2022
HostName example.com
Port 2022</code></pre>
<p>and then specify the location as <b>fred@eg2022:/thingy</b>.</p>
<p>Note that it's the user running rsync that needs to modify their <b>.ssh/config</b> file, not necessarily the one who runs brandysnap. If, for example you use <b>--rsync='sudo rsync'</b>, then you'll need to edit <b>/root/.ssh/config</b> rather than <b>~/.ssh/config</b>.</p>
<p>This does not apply when using an rsync daemon, in which case the port can be specified as part of the location, e.g. rsync://fred\@example.com:1234/thingy.</p>
<p>Multiple destinations can be configured, in which case snapshots will be created on all destinations that are available. This can be used to put snapshots on several external USB drives in rotation, for example. Or you could specify one local and one remote destination for security. But note that multiple destinations won't always be in sync with each other: that's not the intention. Destinations will end up with different lists of snapshots if they are available at different times.</p>
<h2 id="Preserving-Ownership">Preserving Ownership</h2>
<p>In order to preserve ownership of files, brandysnap needs to be run as root or via 'sudo'.</p>
<p>[More detail needed here re use of sudo and <b>remote-rsync-cmd = 'sudo rsync'</b>]</p>
<h2 id="Keeping-Snapshots">Keeping Snapshots</h2>
<p>The number of snapshots that are made depends on how often brandysnap is run. It creates a new snapshot every time (usually).</p>
<p>What is more interesting is how many snapshots are KEPT. This is determined by a series of specifications, or 'specs', such as</p>
<pre><code> 4d5,3w3,1m11</code></pre>
<p>which is a concise way of saying 'keep four snapshots a day from the last five days, then three a week for three weeks, then one a month for eleven months. If brandysnap has run successfully for the last year, then there will be at least 4x5 + 3x3 + 1x11 = 40 snapshots.</p>
<p>Most of the tricky stuff in brandysnap is in deciding which snapshots to keep.</p>
<p>Each spec is of the form</p>
<pre><code> <frequency><period><count></code></pre>
<p>or</p>
<pre><code> <minimum frequency> - <maximum frequency><period><count></code></pre>
<p>The 'frequency' is the number of snapshots to be kept in each period. It can be a single number from 1 to...whatever is reasonable. Or it can be a minimum-maximum range: for example <i>0-4</i> means 'keep between 0 and 4 snapshots in this period'.</p>
<p>Note that the frequency is not the number of snapshots that will be CREATED -- that is determined simply by how often brandysnap is run, and that will usually be down to the way that cron is configured.</p>
<p>The 'period' is a single letter indicating the time period. It can be one of</p>
<ul>
<li><p><b>h</b> - hour</p>
</li>
<li><p><b>d</b> - day</p>
</li>
<li><p><b>w</b> - week</p>
</li>
<li><p><b>m</b> - month</p>
</li>
<li><p><b>y</b> - year</p>
</li>
</ul>
<p>The period can be given in either upper or lower case.</p>
<p>The 'count' indicates the number of periods, as a number from 1 to as many as you like.</p>
<p>If the count is left out, the period is 'padded' to make up to the next period, working backwards in time from 'now'. For example,</p>
<pre><code> 4d,2w4</code></pre>
<p>will be interpreted as <b>4d7,2w4</b>. The 'day' specification is expanded to a week's worth of days to align with the next spec which is in weeks.</p>
<p>If the last spec has no count, it will be padded 'forever'. The number of snapshots will only be limited by the available disk space. And when the disk is full, the oldest snapshots will be deleted.</p>
<p>Snapshots also get deleted as time passes. If a day with four snapshots gets to be old enough to fall within a <b>2w4</b> spec, then the extra snapshots will be deleted.</p>
<p>More spec examples:</p>
<ul>
<li><p><b>1d</b> - just keep 1 backup every day, with no limit to the number of backups.</p>
</li>
<li><p><b>1h24,4d6,3w3,4m11</b> - one an hour for the first day, then 4 a day for the rest of the week then 3 a week for the rest of the month, then 4 a month to give a whole year of snapshots.</p>
</li>
<li><p><b>0-6d5,2-5w3,4m12</b> - keep up to 6 snapshots a day for five days, but consider days with no snapshots at all to be valid; then keep between 2 and 5 a week for three weeks, then keep snapshots for 12 months with 4 snapshots in each.</p>
</li>
<li><p></p>
</li>
</ul>
<h2 id="Managing-Snapshots-Manually">Managing Snapshots Manually</h2>
<p>Snapshots are stored on the destination, each in a separate directory named <i>template-timestamp</i>. For example,</p>
<pre><code> mightyboosh-20120515-100749
mightyboosh-20120617-145513
mightyboosh-20120726-145512
mightyboosh-20120823-145511
mightyboosh-20120914-145511</code></pre>
<p>Normally, you would leave the snapshots alone, allowing brandysnap to delete them at the appropriate time.</p>
<p>If you wish to mark a snapshot as 'special', just rename it by adding some text to the end of the directory name. Any text will do -- make it something meaningful. For example,</p>
<pre><code> mightyboosh-20120617-145513-before-upgrade</code></pre>
<p>brandysnap will process the snapshot as usual, but will never delete it. (In fact it will also tweak the priority calculations to make the 'special' snapshot more likely to be kept. In other words, any non-special snapshots in the same time period are more likely to be chosen for deletion.)</p>
<p>There is no way to mark a snapshot as 'unimportant, delete me first', but you can delete a snapshot manually if you want to.</p>
<h2 id="Definition-of-snapshot-vs-full-incremental-backups">Definition of 'snapshot' vs full/incremental backups</h2>
<p>Lots of snapshots don't make a file more secure: if the file hasn't changed, and is the same in all snapshots, then it is only stored once on the disk. If it gets corrupted for any reason, then it will be corrupted in all snapshots. (If the file is DELETED from one snapshot, it will still exist in the others, because of the way hard links work.)</p>
<p>Think of the whole set of snapshots as one backup, with multiple versions of files that have changed.</p>
<h2 id="Email-Notifications">Email Notifications</h2>
<p>Email messages can be sent if brandysnap fails. Emails are sent simply by piping them to the 'sendmail' program, which is present on most Linux systems as part of the local email server (exim, for example) and can be installed in the Cygwin environment as part of exim.</p>
<h2 id="Options">Options</h2>
<p>All options can be given either on the command line or in the configuration file. Command line options override configuration file ones (but see below regarding multiple options). They are case-insensitive.</p>
<p>On the command line, options must be preceded by one or two hyphens, and can be abbreviated as long as they do not become ambiguous. An 'equals' sign (<b>=</b>) is optional. For example:</p>
<pre><code> brandysnap --source xyz -verbose=1 --conf=bs1.conf -nocal</code></pre>
<p>In the configuration file the hyphens are optional, but options can still be abbreviated. Lines beginning with '#' are considered to be comments and are ignored.</p>
<p>Some options (such as <b>source</b> and <b>destination</b>) can be specified more than once. In this case, command line options are added to configuration file one. For example, if the configuration files includes <b>exclude foo</b> and <b>exclude bar</b>, and you put <b>--exclude thing</b> on the command line, all three items (<b>foo</b>, <b>bar</b>, and <b>thing</b>) will be excluded.</p>
<p><b>~</b> can be used to specify local files and directories e.g.</p>
<pre><code> --logfile = ~/brandysnap.log</code></pre>
<p>The <b>~</b> will be expanded to the home directory of the user who _runs_ brandysnap. <b>~</b> can also be used on remote directories, e.g. <b>[email protected]:~/documents</b>. In this case, the <b>~</b> will be expanded by rsync to mean the home directory of the user specified (or implied) before the <b>@</b> symbol, in this case <b>/home/chris/</b>. <b>~</b> can NOT be used in any of the <b>include</b>/<b>exclude</b> options.</p>
<h3 id="Contexts">Contexts</h3>
<p>For more complex set-ups, options in the configuration can be nested within 'contexts'. This allows options to made specific to a particular destination or source.</p>
<p>For example, this snippet from a configuration file:</p>
<pre><code> source /home/chris
destination /backups/one
<destination /backups/two/>
source /home/ann
exclude .cache
</destination>
source /home/fred
exclude tmp</code></pre>
<p>Contexts are begun with <code><destination dest-name></code> or <code><source source-name></code> and finished with <code></destination></code> or <code></source></code>. Each <code><...></code> must be on a line by itself.</p>
<p>Source contexts can be nested within destination contexts.</p>
<p>The example above has two destinations. <code>/home/chris</code> and <code>/home/fred</code> (excluding <code>tmp</code> from both) will be copied to <code>/backups/one</code>. <code>/home/ann</code> (excluding <code>.cache</code>) will be copied to <code>/backups/two</code>.</p>
<p>Only certain options are valid within each context. A destination context can contain these options:</p>
<pre><code> hbest dbest wbest mbest ybest
safe calendar strict
source template specs
include include-from exclude exclude-from filter
snapshot delete delete-cp
weekstart
rsync-cmd rsync-opts rsync-xopts remote-rsync-cmd
expire-old
bwlimit latest latest-copy
compress restart
allow-restart ldcount ldmin timeout-retries
all-failed some-failed
min-interval hostname
verbose loglevel debug</code></pre>
<p>A source context can contain these options:</p>
<pre><code> rsync-cmd rsync-opts rsync-xopts remote-rsync-cmd
include include-from exclude exclude-from filter
bwlimit
compress restart
allow-restart timeout-retries
min-interval hostname
verbose loglevel debug</code></pre>
<h1 id="OPTIONS">OPTIONS</h1>
<ul>
<li><p>Options marked with '!' in the following list are required.</p>
</li>
<li><p>Options marked with '*' in the following list can be specified more than once.</p>
</li>
</ul>
<h2 id="Main-options">Main options</h2>
<dl>
<dt id="config-file"><b>config <i>file</i></b> !</dt>
<dd>
<p>The name of a file to look in for further options. Configuration file options will be overridden by command-line ones, irrespective of where the <b>config</b> option appears on the command line.</p>
</dd>
<dt id="source-file-dir"><b>source <i>file/dir</i></b> *!</dt>
<dd>
<p>A local or remote file or directory to add to the snapshot. Examples:</p>
<pre><code> source ~/Documents
source /home
source [email protected]:~/Documents</code></pre>
<p>More than one source can be specified, in which case each source will be rsync'd, one at a time, to each destination in turn.</p>
<p>Sources can be given specific options with the following syntax:</p>
<pre><code> <source ~/>
exclude .cache
</source></code></pre>
<p>Rsync can not copy from a remote source to a remote destination, so any source/destination pairs which are both remote will be skipped.</p>
<p>Each source must be readable by the user who runs brandysnap.</p>
<p>If any files or directories within the source are not readable, brandysnap will carry on regardless.</p>
<p>See the section on remote authorisation.</p>
<p>By default, brandysnap uses the rsync options <b>--hard-links --numeric-ids --archive --one-file-system --timeout=300</b>, so the whole of each source will be copied recursively without following symbolic links. See the <b>rsync-opts</b> and <b>rsync-xopts</b> options for ways to change this.</p>
</dd>
<dt id="destination-dir"><b>destination <i>dir</i></b> *!</dt>
<dd>
<p>A local or remote directory for use as the snapshot destination. Examples:</p>
<pre><code> destination /backups/
dest [email protected]:/backups</code></pre>
<p>More than one destination can be specified (see <b>source</b>).</p>
<p>Destinations can be given specific options (including sources) with the following syntax:</p>
<pre><code> <destination [email protected]:/backups>
bwlimit = 2000
remote-rsync-cmd = sudo rsync
</destination></code></pre>
<p>Each destination must be writable by the user who runs brandysnap.</p>
<p>See the section on remote authorisation.</p>
</dd>
<dt id="template-name"><b>template <i>name</i></b> !</dt>
<dd>
<p>The directory name of each snapshot is of the form</p>
<pre><code> <template>-<timestamp></code></pre>
<p>See the <a href="#Snapshot-names">Snapshot names section</a> for more details.</p>
<p>Example:</p>
<pre><code> template docs</code></pre>
</dd>
<dt id="specs-string"><b>specs <i>string</i></b> !</dt>
<dd>
<p>The snapshot-keeping specifications. See the Keeping Snapshots section for full details.</p>
</dd>
<dt id="logfile-file"><b>logfile <i>file</i></b></dt>
<dd>
<p>The name of a file which will be used to log the output from brandysnap. Examples:</p>
<pre><code> logfile /var/log/brandysnap.log
logfile ~/bs-docs.log</code></pre>
<p>The user running brandysnap must have permission to create and write to the log file.</p>
</dd>
</dl>
<h2 id="Tuning-options">Tuning options</h2>
<dl>
<dt id="no-calendar"><b>[no]calendar</b></dt>
<dd>
<p>In calendar mode, hours start on the hours, days start at midnight, weeks start on Sunday (but see the <b>weekstart</b> option), months start on the 1st of the month, years start on the 1st of January. Padding is added where necessary to align periods with the calendar. When calendar mode is turned off, periods are not aligned and are contiguous, ending 'now'. See the [Calendar Mode section](#calendarMode) below for further details. (default: <b>calendar</b>)</p>
</dd>
<dt id="no-safe"><b>[no]safe</b></dt>
<dd>
<p>In safe mode, snapshots are only considered for deletion if the specified periods are 'complete' -- i.e. they have the required number of snapshots. If safe mode is turned off, all periods are considered complete, and extra snapshots in any of them will be deleted. See the [Safe Mode section](#safeMode) below for further details. (default: <b>safe</b>)</p>
<p>The <b>xbest</b> options can be used to tune the snapshot-matching algorithm which decides which snapshots should be deleted. The defaults assume that the latest snapshots within a period are the most valuable, and should be kept. Note these options only apply in calendar mode: in nocalendar mode, the oldest snapshot in a period is always preferred (otherwise snapshots would never be kept long enough to be considered by the next spec)</p>
</dd>
<dt id="hbest-0..59"><b>hbest <i>0..59</i></b></dt>
<dd>
<p><b>hbest</b> determines the favoured minute within an hour for an hourly specification. For example, to prefer hourly snapshots created in the middle of an hours, use <b>hbest 30</b>. (default: <b>59</b>)</p>
</dd>
<dt id="dbest-0..23.9"><b>dbest <i>0..23.9</i></b></dt>
<dd>
<p>Determines the favoured time within a day in hours. For example, to prefer daily snapshots created at 5pm, use <b>dbest 17</b>. (default: <b>23.9</b>)</p>
</dd>
<dt id="wbest-1..7"><b>wbest <i>1..7</i></b></dt>
<dd>
<p>Determines the favoured day within a week, with 1=Sunday, 7=Saturday. For example, to prefer weekly snapshots created on Friday, use <b>wbest 6</b>. (default: <b>1</b>)</p>
</dd>
<dt id="mbest-1..31"><b>mbest <i>1..31</i></b></dt>
<dd>
<p>Determines the favoured day within a month. For example, to prefer monthly snapshots created at the beginning of the month, use <b>mbest 1</b>. [This may be improved in the future to allow preferences such as 'the last Friday in the month'. If the value specified is greater than the number of days in a particular month, the last day of the month is used. To always select the last day of the month, use <b>mbest 31</b>. (default: <b>31</b>)</p>
</dd>
<dt id="ybest-1..366"><b>ybest <i>1..366</i></b></dt>
<dd>
<p>Determines the favoured day within a year. In leap years, the value <b>366</b> is automatically changed to <b>365</b>, so <b>366</b> always means 'the last day of the year'. For example, to prefer yearly snapshots in the middle of the year, use <b>ybest 180</b>. (default: <b>366</b>)</p>
</dd>
<dt id="min-interval-0"><b>min-interval <i>0..</i></b></dt>
<dd>
<p>Sets the minimum interval between snapshots, in minutes. This is useful on a client, such as a laptop, that is not running or not connected to the network all the time: cron can be used to schedule brandysnap frequently, and this option used to make sure that snapshots are only created every hour, say.</p>
</dd>
<dt id="weekstart-1..7"><b>weekstart <i>1..7</i></b></dt>
<dd>
<p>Sets the first day of week. If you consider that weeks start on Monday, use <b>weekstart 2</b>. <b>1</b>=Sunday, <b>7</b>=Saturday. (default: <b>1</b>)</p>
</dd>
</dl>
<h2 id="Helpful-options">Helpful options</h2>
<dl>
<dt id="help"><b>help</b></dt>
<dd>
<p>Prints out a brief summary of options, and then stops.</p>
</dd>
<dt id="version"><b>version</b></dt>
<dd>
<p>Prints out the brandysnap version number only and then stops.</p>
</dd>
<dt id="verbose-0..9"><b>verbose <i>0..9</i></b></dt>
<dd>
<p>This options sets the verbosity of the printed output, on a scale from <b>0</b> to <b>9</b>. Use higher values to see more about what brandysnap and rsync are doing. <b>verbose</b> can also be spelled <b>verbosity</b> (default: <b>3</b>)</p>
</dd>
<dt id="loglevel-0..9"><b>loglevel <i>0..9</i></b></dt>
<dd>
<p>Sets the verbosity level of output in the log file, on a scale from <b>0</b> to <b>9</b>. If no <b>logfile</b> is defined, this option is effectively set to <b>0</b>. (default: <b>3</b>)</p>
</dd>
<dt id="no-dry-run"><b>[no]dry-run</b></dt>
<dd>
<p>In <b>dry-run</b> mode, brandysnap goes through the motions, including checking options, sources, and destinations, as well as calling rsync with its --dry-run option, but doesn't actually create or delete any snapshots. The <b>dry-run</b> option is also passed through to rsync. <b>dry-run</b> can also be spelled <b>dryrun</b>. (default: <b>nodry-run</b>)</p>
</dd>
</dl>
<h2 id="Rsync-options">Rsync options</h2>
<dl>
<dt id="rsync-cmd-path"><b>rsync-cmd <i>path</i></b></dt>
<dd>
<p>The location of the rsync programme on your system. The default is just <b>rsync</b> which means brandysnap looks for rsync in your normal path. On some systems, you might need to set it to something else such as</p>
<pre><code> rsync-cmd /usr/bin/rsync</code></pre>
<p>(default: <b>rsync</b>)</p>
</dd>
<dt id="no-compress"><b>[no]compress</b></dt>
<dd>
<p>Enable rsync compression for remote transfers. Note that this only applies compression for transfer across the network: files are expanded again on the destination. (default: <b>compress</b>)</p>
<p>Note that compression is used for any 'remote' transfer, i.e. when the source and destination are not on the same computer. On a fast local network, you may want to use <b>--nocompress</b>.</p>
</dd>
<dt id="include-exclude-pattern"><b>include</b>/<exclude>/ <i>pattern</i>> *</dt>
<dd>
<p>These two options are passed through to rsync unchecked and unchanged. See the rsync documentation for details. (default: none)</p>
</dd>
<dt id="include-from-exclude-from-filename"><b>include-from</b>/<b>exclude-from <i>filename</i></b> *</dt>
<dd>
<p>The filename is checked: if the file exists and is readable, the option is passed on to rsync (but the contents of the file are not checked).</p>
<p>These files can be remote, so that they can be kept on the same computer as the source they refer to. For example:</p>
<pre><code> source: fred@host1:/home/fred
exclude-from: fred@host1:/home/fred/brandysnap.exclusions</code></pre>
<p>See the rsync documentation for details. (default: none)</p>
</dd>
<dt id="filter-rule-filename"><b>filter</b> <i>rule filename</i> *</dt>
<dd>
<p>The filter option is passed to rsync and checked in the same way as for include-from and exclude-from.</p>
<p>See the rsync documentation for details. (default: none)</p>
</dd>
<dt id="bwlimit-n"><b>bwlimit</b> <n></dt>
<dd>
<p>Band-width limit in kbps. Set it to 0 for no limit. (default: <b>0</b>)</p>
<p>This option can be set per destination or per source/destination combination to allow for each transfer being made by a different route. For example:</p>
<pre><code> <destination: /local/dir>
<source: /local/source>
# no band-width limit
</source>
<source: rsync://remote/source>
bwlimit: 1000
</source>
<destination></code></pre>
<p>Tip: keep the value low (e.g. 200) if connecting over wifi to avoid swamping the connection.</p>
</dd>
<dt id="rsync-opts-options"><b>rsync-opts <i>options</i></b></dt>
<dd>
<p>Options to pass to rsync, in addition to those that brandysnap will always use (i.e. --relative and --link-dest). Use this only if you know what you are doing. (default: -aHx --numeric-ids)</p>
</dd>
<dt id="rsync-xopts-options"><b>rsync-xopts <i>options</i></b></dt>
<dd>
<p>Extra options to pass to rsync. This is a convenience option to allow you to add to or override the standard options without having to remember what the standard options are. (default: none)</p>
</dd>
<dt id="timeout-retries-n"><b>timeout-retries <i>n</i></b></dt>
<dd>
<p>The number of times to retry rsync after a time-out error. This may be useful if the connection between the source and destination is unreliable. (default: 0)</p>
</dd>
</dl>
<h2 id="Email-Options">Email Options</h2>
<dl>
<dt id="email-to-address-Email-recipient-for-error-messages-no-default-.-Multiple-email-to-options-can-be-given-or-a-comma-separated-list-of-email-addresses-can-be-specified-on-a-single-option.-email-to-is-required-for-any-emails-to-be-sent"><b>email-to <i>address</i></b> Email recipient for error messages (no default). Multiple <b>email-to</b> options can be given, or a comma-separated list of email addresses can be specified on a single option. <b>email-to</b> is required for any emails to be sent.</dt>
<dd>
</dd>
<dt id="email-from-address"><b>email-from <i>address</i></b></dt>
<dd>
<p>Email address for From: header of email error messages. (default: current user)</p>
</dd>
<dt id="email-prog-server"><b>email-prog <i>server</i></b></dt>
<dd>
<p>The email program to run. The default is '/usr/sbin/sendmail -t -oi', which is installed on many Linux-based systems, and can be set up to run under Cygwin on Windows.</p>
</dd>
<dt id="email-if-all-any"><b>email-if <i>all|any</i></b></dt>
<dd>
<p>Send email if all or any destinations failed. (default: all)</p>
</dd>
<dt id="no-email-test"><b>[no]email-test</b></dt>
<dd>
<p>Just send a message to test the other email settings. Brandsysnap will not do any other processing. (default: no)</p>
</dd>
</dl>
<h2 id="Advanced-Options">Advanced Options</h2>
<dl>
<dt id="all-failed-keep-delete"><b>all-failed <i>keep/delete</i></b></dt>
<dd>
<p>What to do with the snapshot if none of the sources are copied successfully. <b><i>keep</i></b> will keep the incomplete snapshot and mark it as 'partial' in the metadata file. This means that it will not be considered as a proper snapshot when making future decisions about which snapshots to get rid of. If you specify <b><i>delete</i></b>, the incomplete snapshot will be deleted immediately, in the expectation that future snapshots will be more successful. See also <b>--some-failed</b>. (default: <b>delete</b>)</p>
</dd>
<dt id="no-delete"><b>[no]delete</b></dt>
<dd>
<p>Delete no-longer-required snapshots. If this option is turned off, brandysnap will create new snapshots but not delete any old ones. (default: <b>delete</b>)</p>
</dd>
<dt id="no-delete-cp"><b>[no]delete-cp</b></dt>
<dd>
<p>Include the 'current period' when considering which snapshots to delete. See the description of [current period](#currentPeriod) below. (default: <b>delete-cp</b>)</p>
</dd>
<dt id="no-expire-old"><b>[no]expire-old</b></dt>
<dd>
<p>Consider _all_ snapshots (oldest first) as expirable to make room when the destination is full. (default: <b>noexpire-old</b>)</p>
</dd>
<dt id="hostname"><b>hostname</b></dt>
<dd>
<p>Override the hostname or fully-qualified domain name that is used in the snapshot path. Normally, this is the host name of the computer running brandysnap if the source is local, or the FQDN of the source if it's remote.</p>
<p>This option is only useful if, for example, brandysnap is running from a live CD to backup files from a non-functioning machine: you would then supply the hostname of the dead computer along with the configuration file from it so that the snapshot matches the existing ones (and so that --link-dest works properly).</p>
<p>(default: the hostname of the source computer)</p>
</dd>
<dt id="no-latest"><b>[no]latest</b></dt>
<dd>
<p>If this option specified, an additional hard-linked copy of the new snapshot will be created called <template>-latest. This is designed for use with, for example, and online backup service which is configured to upload just the latest snapshot.</p>
<p>Note: if the destination is remote, brandysnap has to use ssh to run rsnapshot remotely: this may require extra configuration of permissions and ssh keys in order to allow brandysnap to run without prompting for passwords.</p>
<p>Note: latest snapshots can NOT be created on remote destinations when connecting via an rsync daemon.</p>
<p>(default: <b>nolatest</b>)</p>
</dd>
<dt id="no-latest-copy"><b>[no]latest-copy</b></dt>
<dd>
<p>This option specifies that the 'latest' snapshot (see above) should be created <b>without</b> using rsync's --link-dest option to hard-link it back to the just-created normal snapshot. In other words, the 'latest' snapshot will be a separate copy.</p>
<p>Note that if you change this option after a 'latest' snapshot has already been created, the choice of linking or copying will only apply to new or changed files in the snapshot. If you want to change the whole 'latest' snapshot, you will need to delete it and let brandysnap create it afresh.</p>
<p>This option is ignored if <b>--latest</b> is not also specified.</p>
<p>(default: <b>no-latest-copy</b>)</p>
</dd>
<dt id="ldcount-n"><b>ldcount <i>n</i></b></dt>
<dd>
<p>Specify the number of previous snapshots that rsync will search looking for identical files to hard-link to. Normally the default value of <b>1</b> is ideal. Set this value to <b>0</b> to turn off rsync's <b>--link-dest</b> option completely, but be aware that this will greatly increase the size of the new snapshot, and the time taken to create it (especially over the network). Values greater than <b>1</b> can be used in conjunction with [options yet to be implemented] to tune the behaviour of brandysnap. (default: <b>1</b>) The count ignores unfinished snapshots, and snapshots that are too small, as defined by <b>--ldcount</b>.</p>
</dd>
<dt id="ldmin-0.0..1.0"><b>ldmin 0.0..1.0</b></dt>
<dd>
<p>Sets the minimum size of snapshots, as a proportion of the average of existing finished snapshots, that will be considered for hard-linking. See the <b>--ldcount</b> option above. (default: <b>0.0</b>)</p>
<p>If you expect all your snapshots to be a similar size, with only a small proportion of that size changing between snapshots, then setting this to a fairly high value such as 0.8 will decrease the chances of wastefully resending lots of data.</p>
</dd>
<dt id="no-restart"><b>[no]restart</b></dt>
<dd>
<p>If a previous run of brandysnap was interrupted for any reason, use this option to re-do the same snapshot (simply by relying on rsync's ability to not copy files that have not changed). Any files in the source that have changed since the previous run _will_ be updated. If more than one destination is being used, rsync will be run for _all_ destinations, even if some of them completed successfully before. <b>--restart</b> implies <b>--snapshot</b> and <b>--min-interval=0</b>. (default: <b>norestart</b>)</p>
</dd>
<dt id="no-snapshot"><b>[no]snapshot</b></dt>
<dd>
<p>Create a new snapshot. If this option is turned off, no new snapshot will be created during this run of brandysnap but old snapshots may be deleted. (default: <b>snapshot</b>)</p>
</dd>
<dt id="some-failed-keep-delete"><b>some-failed <i>keep/delete</i></b></dt>
<dd>
<p>What to do with the snapshot if some of the sources are not copied successfully. See <b>--all-failed</b> for details. (default: <b>keep</b>)</p>
</dd>
<dt id="status"><b>status</b></dt>
<dd>
<p>Print a status report only, with no snapshots being created or deleted.</p>
</dd>
<dt id="no-strict"><b>[no]strict</b></dt>
<dd>
<p>Use strict mode -- see the [Strict Mode section](#strictMode). (default: <b>nostrict</b>)</p>
</dd>
</dl>
<h2 id="Development-options">Development options</h2>
<p>These options are for use by developers only.</p>
<dl>
<dt id="debug-section-section"><b>debug <i>section,section</i></b></dt>
<dd>
<p>Print and log debugging information. (default: <b>(none)</b>)</p>
</dd>
<dt id="test-n"><b>test <i>n</i></b></dt>
<dd>
<p>Run test case 'n'.</p>
</dd>
</dl>
<h1 id="FURTHER-DETAILS">FURTHER DETAILS</h1>
<h2 id="Calendar-mode">Calendar mode</h2>
<p>In 'calendar mode', which is the default, brandysnap works in terms of real weeks and months. Days always start at midnight, weeks at midnight on Sunday etc. (but see the <b>--weekstart</b> option).</p>
<p>In non-calendar mode, the specs are interpreted more simply, working backwards from the moment when brandysnap is run. There will be no gap between periods: days and weeks can start at any time, depending on when the previous spec ran out.</p>
<h2 id="Safe-mode">Safe mode</h2>
<p>In 'safe mode', which is the default, specs will only match against the list of existing snapshots if there are enough snapshots to satisfy the spec's definition. Incomplete specs will be skipped. This has the result that brandysnap is less likely to delete snapshots. This is designed to cater for situations when brandysnap has not run successfully as often as it should have, for whatever reason. For example, because of weekends or holidays, or because the destination wasn't available because an external USB drive wasn't connected (or two or more USB drives are being used in rotation). e.g if the spec is <b>4d5</b>, it's now Monday and brandysnap did not run at the weekend, then the days with fewer than 4 snapshots (i.e. Saturday and Sunday) will be skipped; counting the 5 days will start on Friday and work backwards from there. Safe mode can be turned off via the <b>--safe</b> option.</p>
<h2 id="Strict-mode">Strict mode</h2>
<p>In 'strict mode', which is not the default, brandysnap will not run if there are minor problems with the specs. Normally, it will display information about how it has interpreted the specs, and carry on.</p>
<h2 id="Weeks-and-months-and-years">Weeks and months and years</h2>
<p>The fact that months and years do not have whole or fixed numbers of weeks makes counting periods awkward. Brandysnap deals with this by skipping over the extra days, and only deleting their snapshots if they would have been deleted in a complete period.</p>
<h2 id="Status-report">Status report</h2>
<p>Brandysnap displays a status report on all existing snapshots at the end of each run.</p>
<h2 id="Snapshot-names">Snapshot names</h2>
<p>Each snapshot is a separate directory within the destination, with a name of the form</p>
<pre><code> <template>-<timestamp:YYYYMMDD-hhmmss></code></pre>
<p>where the 'template' is specified by the --template option. For example</p>
<pre><code> bs1-20110616-121159</code></pre>
<p>That format is fixed -- it is used to identify snapshots; any directory that doesn't match that pattern will be ignored.</p>
<h2 id="Interrupt-handling">Interrupt handling</h2>
<p>Brandysnap is designed to be robust: if it receives an interrupt signal, for example if the computer is shutting down, or the user has pressed ctrl-C, while rsync is running, it traps the signal and stops cleanly.</p>
<h2 id="Other-notes">Other notes</h2>
<ul>
<li><p>Brandysnap ignores 'minor' errors from rsync, which includes errors regarding permissions. So check the output to make sure that there are no 'Permission denied' messages. If there are, you may need to run brandysnap as root -- see xxx.</p>
</li>
</ul>
<h1 id="KNOWN-ISSUES">KNOWN ISSUES</h1>
<p>As of 29 August 2014 and version 0.2.19, the following issues and bugs are known.</p>
<ul>
<li><p>On the command line, rsync options --include, --exclude, --include-from, --exclude-from, and --filter are grouped together, rather than preserving their order. If you need to specify complex include/exclude/filter rules, put them in the configuration file.</p>
</li>
<li><p>Under certain circumstances, rsync can fail if the source contains files that are hard-linked together and for which you do not have read permission. This is fixed in rsync 3.0.9 and later. You can get round it by specifying <b>--rsync-opts</b> with the usual options but omitting <b>--hard-links</b> at the cost of using more disk space.</p>
</li>
<li><p>The fmtRange routine uses Date::Manip::Delta, which insists that February is four weeks and not one month. There may be other similar cosmetic irritations.</p>
</li>
</ul>
<h1 id="AUTHOR">AUTHOR</h1>
<p>Chris Dennis, [email protected]</p>
</body>
</html>