Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 161 lines (103 sloc) 5.007 kb
d393bac @falconindy doc: Replace and update README with POD markup
authored
1 =head1 NAME
2
3 squashfu - an incremental backup solution
4
5 =head1 SYNOPSIS
6
7 I<squashfu> <action> [options]
8
9 =head1 DESCRIPTION
10
11 I<squashfu> is a Bash based backup utility that uses the flexibility of rsync, squashfs,
12 and aufs to create incremental backups and offer limited compression.
13
14 =head1 ACTIONS
15
16 =over
17
18 =item B<-B>
19
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
20 Runs a regular backup, using the config file at F</etc/squashfu>.
d393bac @falconindy doc: Replace and update README with POD markup
authored
21
22 =item B<-C>
23
24 Create a new squashed seed by merging old bins. This will leave you with a no more
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
25 than the number of bins specified by the I<MIN_BINS> setting in the config.
d393bac @falconindy doc: Replace and update README with POD markup
authored
26
27 =item B<-D> I<BIN>
28
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
29 Delete the incremental backup with the number I<BIN>. This is done interactively and you
d393bac @falconindy doc: Replace and update README with POD markup
authored
30 will have a chance to confirm before any files are deleted.
31
4f80e3e @falconindy doc: add -G option to README and usage()
authored
32 =item B<-G> I<path>
33
34 Directly restore a file or directory. This is an interactive operation and a list of
35 locations where the target is found will be presented.
36
d393bac @falconindy doc: Replace and update README with POD markup
authored
37 =item B<-Q>
38
39 Displays usage statistics, including the size of the compressed seed and each incremental
40 backup with its creation date and bin number.
41
42 =item B<-R>
43
44 Cookies will be persistent and reused for logins. If you specify this option, you must
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
45 also provide a cookie file path with the B<-C> option or in the config file.
d393bac @falconindy doc: Replace and update README with POD markup
authored
46
47 =item B<-U>
48
49 Unmount the squash and union. Although I<squashfu> will always check and unmount as
50 necessary before an operation, this is provided as a convenience.
51
52 =back
53
54 =head1 OPTIONS
55
56 =over
57
58 =item B<-c> F<PATH>
59
60 Specify an alternate config file as denoted by F<PATH>. The default config will still be
61 sourced, but options specified in this config will override the defaults. If your extra
62 config overrides the location of the backups, ensure that this config is always passed
63 for any operation.
64
65 =back
66
67 =head1 HOW IT WORKS
68
69
70 Goal: To create a backup solution which provides incremental backups and compression,
71 and which also provides an easy way to roll back.
72
73 Design:
74
75 A directory structure is created as follows (with some terminology included):
76
77 backup_root/
78 |- seed.sfs <-- squash, or seed
79 |- ro/ <-- squash mount point
80 |- rw/ <-- union mount point
81 |- .bins/ <-- incrementals
82 |-1/
83 | .....
84 | .....
85 | .....
86 | .....
87 | .....
88 |-n/
89
90 /var/
91 |- lib/
92 |- .squashfu.inv <-- bin inventory list (or binventory)
93
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
94 F<seed.sfs> is created from an initial backup and compressed using SquashFS, which is
d393bac @falconindy doc: Replace and update README with POD markup
authored
95 simply a read only filesystem which focuses on compression. It's mounted, using a
96 loopback device, on ro/.
97
98 At the time of the backup, the next available bin is determined, created, and logged
99 to an inventory sheet with a timestamp. A union is created with all the available bins,
100 mounted in reverse chronological order on top of the seed (newest to oldest) on rw/.
101 At this point, the union represents the state of your files at the end of the last
102 backup. The newest branch is marked as read/write, and rsync is called. Because this
103 top branch is the only writable location in the union, the files rsync generates with
104 the -u (update) flag are placed into this branch. The backup finishes, and the union
105 and seed are unmounted.
106
107 At this point, Squashfu ensures compliance with the user's settings of MAX_BINS. If
108 the current number of used bins exceeds this value, a new seed is generated. The
109 number of old incrementals merged into the new seed is determined by the difference
110 between MAX_BINS and MIN_BINS in the config file. In this way, you always have
111 MIN_BINS available to roll back to, but you're not forced to recompress your seed
112 at every backup -- an operation that may take a long time depending on how big
113 your backup source is.
114
115 If and when you want to roll back, execute Squashfu with the -R action, and supply
116 the number of bins you want to roll back. The bins are ordered chronologically,
117 and the oldest "number_of_bins - bins_to_rollback" are mounted on the union mount
118 point.
119
120 B<WARNING:>
121 You should not, under any circumstances, add or remove files contained in the bins,
122 nor should you alter your binventory's time stamps. Doing so many result in your cat
123 being set on fire or your backups being destroyed.
124
125 =head1 INSTALLATION
126
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
127 ~ On Arch Linux, build and install from the AUR.
d393bac @falconindy doc: Replace and update README with POD markup
authored
128
0556c90 @falconindy readme: cosmetic and grammatical improvements
authored
129 ~ On other distributions, use the included Makefile to run B<make install>, ensuring
130 that the I<DESTDIR> and I<MANPREFIX> are specified.
d393bac @falconindy doc: Replace and update README with POD markup
authored
131
132 ~ Read over each option in F</etc/squashfu.conf> and set it accordingly.
133
134 ~ Create your first backup with I<squashfu> B<-B> and validate that the backup was
135 created successfully.
136
137 ~ It may be a wise idea to make more changes, run a new backup and inspect the resulting
138 incremental.
139
140 =head1 FURTHER READING
141
142 L<http://en.wikipedia.org/wiki/Aufs>
143
144 L<http://en.wikipedia.org/wiki/UnionFS>
145
146 L<http://aufs.sourceforge.net/>
147
148 L<http://en.wikipedia.org/wiki/SquashFS>
149
150 L<http://en.wikipedia.org/wiki/Rsync>
151
152
153 =head1 SEE ALSO
154
155 B<aufs>(5), B<rsync>(1)
156
157 =head1 AUTHOR
158
159 Dave Reisner E<lt>d@falconindy.comE<gt>
160
Something went wrong with that request. Please try again.