]> git.alrj.org Git - brioche.git/blob - README.html
9d951511af3dce9e255cf8ebe36c9758dc8cd1b3
[brioche.git] / README.html
1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
7 <title>Brioche Backup</title>
8 <meta name="author" content="Amand Tihon" />
9 <meta name="date" content="Jan 5th, 2008" />
10 <meta name="copyright" content="GNU GPL, see copyright file." />
11 <style type="text/css">
12
13 /*
14 :Author: David Goodger (goodger@python.org)
15 :Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
16 :Copyright: This stylesheet has been placed in the public domain.
17
18 Default cascading style sheet for the HTML output of Docutils.
19
20 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
21 customize this style sheet.
22 */
23
24 /* used to remove borders from tables and images */
25 .borderless, table.borderless td, table.borderless th {
26   border: 0 }
27
28 table.borderless td, table.borderless th {
29   /* Override padding for "table.docutils td" with "! important".
30      The right padding separates the table cells. */
31   padding: 0 0.5em 0 0 ! important }
32
33 .first {
34   /* Override more specific margin styles with "! important". */
35   margin-top: 0 ! important }
36
37 .last, .with-subtitle {
38   margin-bottom: 0 ! important }
39
40 .hidden {
41   display: none }
42
43 a.toc-backref {
44   text-decoration: none ;
45   color: black }
46
47 blockquote.epigraph {
48   margin: 2em 5em ; }
49
50 dl.docutils dd {
51   margin-bottom: 0.5em }
52
53 /* Uncomment (and remove this text!) to get bold-faced definition list terms
54 dl.docutils dt {
55   font-weight: bold }
56 */
57
58 div.abstract {
59   margin: 2em 5em }
60
61 div.abstract p.topic-title {
62   font-weight: bold ;
63   text-align: center }
64
65 div.admonition, div.attention, div.caution, div.danger, div.error,
66 div.hint, div.important, div.note, div.tip, div.warning {
67   margin: 2em ;
68   border: medium outset ;
69   padding: 1em }
70
71 div.admonition p.admonition-title, div.hint p.admonition-title,
72 div.important p.admonition-title, div.note p.admonition-title,
73 div.tip p.admonition-title {
74   font-weight: bold ;
75   font-family: sans-serif }
76
77 div.attention p.admonition-title, div.caution p.admonition-title,
78 div.danger p.admonition-title, div.error p.admonition-title,
79 div.warning p.admonition-title {
80   color: red ;
81   font-weight: bold ;
82   font-family: sans-serif }
83
84 /* Uncomment (and remove this text!) to get reduced vertical space in
85    compound paragraphs.
86 div.compound .compound-first, div.compound .compound-middle {
87   margin-bottom: 0.5em }
88
89 div.compound .compound-last, div.compound .compound-middle {
90   margin-top: 0.5em }
91 */
92
93 div.dedication {
94   margin: 2em 5em ;
95   text-align: center ;
96   font-style: italic }
97
98 div.dedication p.topic-title {
99   font-weight: bold ;
100   font-style: normal }
101
102 div.figure {
103   margin-left: 2em ;
104   margin-right: 2em }
105
106 div.footer, div.header {
107   clear: both;
108   font-size: smaller }
109
110 div.line-block {
111   display: block ;
112   margin-top: 1em ;
113   margin-bottom: 1em }
114
115 div.line-block div.line-block {
116   margin-top: 0 ;
117   margin-bottom: 0 ;
118   margin-left: 1.5em }
119
120 div.sidebar {
121   margin: 0 0 0.5em 1em ;
122   border: medium outset ;
123   padding: 1em ;
124   background-color: #ffffee ;
125   width: 40% ;
126   float: right ;
127   clear: right }
128
129 div.sidebar p.rubric {
130   font-family: sans-serif ;
131   font-size: medium }
132
133 div.system-messages {
134   margin: 5em }
135
136 div.system-messages h1 {
137   color: red }
138
139 div.system-message {
140   border: medium outset ;
141   padding: 1em }
142
143 div.system-message p.system-message-title {
144   color: red ;
145   font-weight: bold }
146
147 div.topic {
148   margin: 2em }
149
150 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
151 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
152   margin-top: 0.4em }
153
154 h1.title {
155   text-align: center }
156
157 h2.subtitle {
158   text-align: center }
159
160 hr.docutils {
161   width: 75% }
162
163 img.align-left {
164   clear: left }
165
166 img.align-right {
167   clear: right }
168
169 ol.simple, ul.simple {
170   margin-bottom: 1em }
171
172 ol.arabic {
173   list-style: decimal }
174
175 ol.loweralpha {
176   list-style: lower-alpha }
177
178 ol.upperalpha {
179   list-style: upper-alpha }
180
181 ol.lowerroman {
182   list-style: lower-roman }
183
184 ol.upperroman {
185   list-style: upper-roman }
186
187 p.attribution {
188   text-align: right ;
189   margin-left: 50% }
190
191 p.caption {
192   font-style: italic }
193
194 p.credits {
195   font-style: italic ;
196   font-size: smaller }
197
198 p.label {
199   white-space: nowrap }
200
201 p.rubric {
202   font-weight: bold ;
203   font-size: larger ;
204   color: maroon ;
205   text-align: center }
206
207 p.sidebar-title {
208   font-family: sans-serif ;
209   font-weight: bold ;
210   font-size: larger }
211
212 p.sidebar-subtitle {
213   font-family: sans-serif ;
214   font-weight: bold }
215
216 p.topic-title {
217   font-weight: bold }
218
219 pre.address {
220   margin-bottom: 0 ;
221   margin-top: 0 ;
222   font-family: serif ;
223   font-size: 100% }
224
225 pre.literal-block, pre.doctest-block {
226   margin-left: 2em ;
227   margin-right: 2em }
228
229 span.classifier {
230   font-family: sans-serif ;
231   font-style: oblique }
232
233 span.classifier-delimiter {
234   font-family: sans-serif ;
235   font-weight: bold }
236
237 span.interpreted {
238   font-family: sans-serif }
239
240 span.option {
241   white-space: nowrap }
242
243 span.pre {
244   white-space: pre }
245
246 span.problematic {
247   color: red }
248
249 span.section-subtitle {
250   /* font-size relative to parent (h1..h6 element) */
251   font-size: 80% }
252
253 table.citation {
254   border-left: solid 1px gray;
255   margin-left: 1px }
256
257 table.docinfo {
258   margin: 2em 4em }
259
260 table.docutils {
261   margin-top: 0.5em ;
262   margin-bottom: 0.5em }
263
264 table.footnote {
265   border-left: solid 1px black;
266   margin-left: 1px }
267
268 table.docutils td, table.docutils th,
269 table.docinfo td, table.docinfo th {
270   padding-left: 0.5em ;
271   padding-right: 0.5em ;
272   vertical-align: top }
273
274 table.docutils th.field-name, table.docinfo th.docinfo-name {
275   font-weight: bold ;
276   text-align: left ;
277   white-space: nowrap ;
278   padding-left: 0 }
279
280 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
281 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
282   font-size: 100% }
283
284 ul.auto-toc {
285   list-style-type: none }
286
287 </style>
288 </head>
289 <body>
290 <div class="document" id="brioche-backup">
291 <h1 class="title">Brioche Backup</h1>
292 <table class="docinfo" frame="void" rules="none">
293 <col class="docinfo-name" />
294 <col class="docinfo-content" />
295 <tbody valign="top">
296 <tr><th class="docinfo-name">Author:</th>
297 <td>Amand Tihon</td></tr>
298 <tr><th class="docinfo-name">Contact:</th>
299 <td>&lt;<a class="reference external" href="mailto:amand.tihon&#64;alrj.org">amand.tihon&#64;alrj.org</a>&gt;</td></tr>
300 <tr><th class="docinfo-name">Version:</th>
301 <td>1.0</td></tr>
302 <tr><th class="docinfo-name">Date:</th>
303 <td>Jan 5th, 2008</td></tr>
304 <tr><th class="docinfo-name">Copyright:</th>
305 <td>GNU GPL, see copyright file.</td></tr>
306 </tbody>
307 </table>
308 <!-- HTML version generated with rst2html -t README > README.html -->
309 <div class="section" id="abstract">
310 <h1>Abstract</h1>
311 <p>Brioche is yet another backup shell script. Its main features are</p>
312 <ul class="simple">
313 <li>Full and differential backups</li>
314 <li>LVM snapshots</li>
315 <li>Xen+paravirt oriented (somehow)</li>
316 <li>Soon: Upload to a distant FTP server.</li>
317 </ul>
318 </div>
319 <div class="section" id="rationale">
320 <h1>Rationale</h1>
321 <p>Large numbers of backup solutions are freely available today, but when playing
322 with incremental or differential backups, most of them rely on some filesystem
323 capabilities, like <em>hard-linking</em>. If the only remote location available to
324 store the backups is an FTP server, this is not a solution.
325 Brioche relies on GNU tar's <tt class="docutils literal"><span class="pre">--listed-incremental</span></tt> option to create <em>real</em>
326 differential <a class="footnote-reference" href="#diff" id="id1">[1]</a> archives.</p>
327 <p>A second feature that makes Brioche interresting is the ability to use LVM
328 snapshots. In the case of a Xen setup where the domUs use logical volumes as
329 partitions, Brioche is able to backup everything from the dom0.</p>
330 <table class="docutils footnote" frame="void" id="diff" rules="none">
331 <colgroup><col class="label" /><col /></colgroup>
332 <tbody valign="top">
333 <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Each differential backup is based upon the last <em>full</em> backup, unlike
334 incremental, which are based upon the last (full or incremental) backup.</td></tr>
335 </tbody>
336 </table>
337 </div>
338 <div class="section" id="getting-brioche">
339 <h1>Getting Brioche</h1>
340 <p>You can download the tarball from <a class="reference external" href="http://www.alrj.org/projects/brioche">http://www.alrj.org/projects/brioche</a>
341 or get the latest development version with the following git command:</p>
342 <pre class="literal-block">
343 git clone http://git.alrj.org/brioche.git
344 </pre>
345 </div>
346 <div class="section" id="installation">
347 <h1>Installation</h1>
348 <p>Copy the three files <tt class="docutils literal"><span class="pre">brioche</span></tt>, <tt class="docutils literal"><span class="pre">brioche.conf</span></tt> and <tt class="docutils literal"><span class="pre">briochetab</span></tt> where
349 you like, and set the <tt class="docutils literal"><span class="pre">CONFIG_FILE</span></tt> variable in the <tt class="docutils literal"><span class="pre">brioche</span></tt> script
350 accordingly. If needed, run <tt class="docutils literal"><span class="pre">chmod</span> <span class="pre">+x</span> <span class="pre">/path/to/brioche</span></tt>.</p>
351 </div>
352 <div class="section" id="using-brioche">
353 <h1>Using Brioche</h1>
354 <div class="section" id="configuration">
355 <h2>Configuration</h2>
356 <p>Edit the file <tt class="docutils literal"><span class="pre">brioche.conf</span></tt> to suit your needs. Each option is commented
357 inline and will be detailed here.</p>
358 <dl class="docutils">
359 <dt>BACKUPTAB</dt>
360 <dd>Full absolute path to the briochetab file. This file describes which logical
361 volumes and partitions must be backed up. Its format is explained in the
362 <a class="reference internal" href="#defining-backups">Defining backups</a> section.</dd>
363 <dt>MAILTO</dt>
364 <dd>When the job is done, Brioche will send a summary of the operations by email.
365 You can set it to any value that your <tt class="docutils literal"><span class="pre">mail</span></tt> command understands.</dd>
366 </dl>
367 <dl class="docutils" id="repodir">
368 <dt>REPODIR</dt>
369 <dd>Brioche will store all the generated archives in this directory.Note that
370 before doing a full backup, Brioche will move all previous archives into an
371 &quot;undo&quot; subdirectory, which will be removed only if the backup is successful.
372 Make sure there's enough free space on the device where REPODIR is located.</dd>
373 <dt>USAGE_WARN</dt>
374 <dd>The report email will include a warning if the space used on REPODIR goes
375 beyond the given threshold. The value must be an integer.</dd>
376 <dt>COMPRESS</dt>
377 <dd>This directive allows to specify the compression method to apply to the
378 archives. Possible values are &quot;gz&quot;, &quot;bz2&quot; and &quot;lzma&quot;. <strong>Warning</strong> : lzma may
379 not be available with older versions of GNU tar.</dd>
380 <dt>TAR_OPTS</dt>
381 <dd>Additionnal options that you may want to pass to tar. A typical value could
382 be <tt class="docutils literal"><span class="pre">&quot;--one-filesystem</span> <span class="pre">-S&quot;</span></tt>. The first option will skip all other mointpoints
383 (very usefull if you have /dev, /proc, /sys or REPODIR mounted under a device
384 that must be archived). The second one will try to deal with sparse files.</dd>
385 <dt>SNAPSHOT_MOUNTPOINT</dt>
386 <dd>Sets the directory where the temporary LVM snapshots must be mounted.</dd>
387 <dt>SNAPSHOT_NAME</dt>
388 <dd>The name to use for the snapshot volumes.</dd>
389 <dt>SNAPSHOT_SIZE</dt>
390 <dd>Set the size of the snapshot volume. The same suffix than for lvcreate(8)
391 are available.</dd>
392 <dt>USE_FTP</dt>
393 <dd>Still TODO.</dd>
394 </dl>
395 </div>
396 <div class="section" id="defining-backups">
397 <h2>Defining backups</h2>
398 <p>The backups are defined in the file <tt class="docutils literal"><span class="pre">birochetab</span></tt>. Here is a typical example
399 for a Xen config where cottman is the dom0 and syrtis, kadarin, valeron are
400 domUs</p>
401 <pre class="literal-block">
402 # Partition or LV           Snapshot    Host name     Volume name
403 # ---------------------------------------------------------------
404 /                           no          cottman       root
405 /usr                        no          cottman       usr
406
407 /dev/vg00/valeron-root      yes         valeron       root
408
409 /dev/vg00/kadarin-root      yes         kadarin       root
410 /dev/vg00/kadarin-home      yes         kadarin       home
411
412 /dev/vg00/syrtis-root       yes         syrtis        root
413 /dev/vg00/syrtis-home       yes         syrtis        home
414 /dev/vg00/syrtis-usr        yes         syrtis        usr
415 /dev/vg00/syrtis-var        yes         syrtis        var
416 </pre>
417 <p>Blank lines, or lines beginning with # are ignored.</p>
418 <p>The first column defines the directory or logical volume to backup. In this
419 example,the first two lines are plain directories, while the other ones point
420 to LVM devices.</p>
421 <p>The second column specify if the backup should be taken from an LVM snapshot or
422 not. It <strong>must</strong> be set to &quot;no&quot; for the backup of a directory and to &quot;yes&quot; for
423 the backup of a logical volume.</p>
424 <p>The last two columns are more or less cosmetic, and define where the archive
425 files will be stored, and how they'll be named. The destination directory will
426 be created under the <a class="reference internal" href="#repodir">REPODIR</a>, and its name will be the value on the third
427 column. Inside this directory, archive files will be named from the value given
428 in the fourth column. For instance, a full and a differential backup for
429 valeron would lead to the following structure</p>
430 <pre class="literal-block">
431 user:/REPODIR$ ls -l valeron/
432 total 356544
433 -rw-r--r-- 1 root root 363545613 Jan  3 03:10 root.full.20090103.tar.bz2
434 -rw-r--r-- 1 root root    504722 Jan  3 03:10 root.full.snar
435 -rw-r--r-- 1 root root    504725 Jan  4 04:06 root.incr.20090104.snar
436 -rw-r--r-- 1 root root    160542 Jan  4 04:06 root.incr.20090104.tar.bz2
437 </pre>
438 </div>
439 <div class="section" id="running-brioche">
440 <h2>Running Brioche</h2>
441 <p>Brioche understands the following arguments:</p>
442 <table class="docutils option-list" frame="void" rules="none">
443 <col class="option" />
444 <col class="description" />
445 <tbody valign="top">
446 <tr><td class="option-group">
447 <kbd><span class="option">-f</span>, <span class="option">--full</span></kbd></td>
448 <td>Do a full backup (by default, brioche will do a differential).</td></tr>
449 <tr><td class="option-group">
450 <kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
451 <td>Show a very limited help.</td></tr>
452 </tbody>
453 </table>
454 <p>When everything is ready, execute the <tt class="docutils literal"><span class="pre">brioche</span></tt> script as root. The
455 script is pretty verbose, so don't panic if you see lots of lines scrolling in
456 your terminal. By default, Brioche will try to make differential backups, but
457 will gracefully fall back and do a full backup if none is available.</p>
458 <p>If all is fine, it can be added in the system crontab. Here's a suggestion for
459 weekly full backup on Sunday, with differential during the weekdays</p>
460 <pre class="literal-block">
461 # Daily incremental backup
462 30  3  *  *  1-6  /usr/local/bin/brioche &gt; /var/log/backup.`date &quot;+%a&quot;`.log 2&gt;&amp;1
463 # Weekly full backup on Sunday
464 30  3  *  *  0  /usr/local/bin/brioche -f &gt; /var/log/backup.`date &quot;+%a&quot;`.log 2&gt;&amp;1
465 </pre>
466 <p>The output of the script will be saved in /var/log/backup.DOW.log with DOW
467 being the abbreviated day of the week (see man date(1) for the format).</p>
468 </div>
469 </div>
470 <div class="section" id="bug-reporting">
471 <h1>Bug reporting</h1>
472 <p>There's no bugtracker for this project, your bug reports should be sent to the
473 author : Amand Tihon &lt;<a class="reference external" href="mailto:amand.tihon&#64;alrj.org">amand.tihon&#64;alrj.org</a>&gt;. Please include as much information
474 as possible in your report.</p>
475 </div>
476 <div class="section" id="references">
477 <h1>References</h1>
478 <ul class="simple">
479 <li>GNU tar documentation : <a class="reference external" href="http://www.gnu.org/software/tar/manual/">http://www.gnu.org/software/tar/manual/</a></li>
480 <li>LVM documentation and links : <a class="reference external" href="http://sourceware.org/lvm2/">http://sourceware.org/lvm2/</a></li>
481 </ul>
482 </div>
483 </div>
484 <div class="footer">
485 <hr class="footer" />
486 Generated on: 2009-01-05 19:27 UTC.
487
488 </div>
489 </body>
490 </html>