/doc/user-guide.sgml
Unknown | 2014 lines | 1612 code | 402 blank | 0 comment | 0 complexity | a2bc32ddbb304c40d440e5606dcfafc9 MD5 | raw file
Possible License(s): GPL-2.0
Large files files are truncated, but you can click here to view the full file
1<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [ 2 <!-- include version information so we don't have to hard code it 3 within the document --> 4 <!ENTITY % versiondata SYSTEM "version.ent"> %versiondata; 5 <!-- common, language independent entities --> 6 <!ENTITY % commondata SYSTEM "common.ent" > %commondata; 7 8 <!-- if you are translating this document, please notate the CVS 9 revision of the original developer's reference in cvs-en-rev --> 10 <!-- <!ENTITY cvs-en-rev "X.YZW"> --> 11 12 <!-- how to mark a section that needs more work --> 13 <!ENTITY FIXME "<em>FIXME:</em> "> 14 15]> 16 17<!-- Template of a configuration key description 18 19 Please, follow this template for *each* configuration key 20 this will allow us to make a nice appendix later, think of our 21 users ;-) 22 23<sect1 id="BM_MYCONFIGURATION_KEY"><tt>BM_MYCONFIGURATION_KEY</tt> 24 25<p> 26<em>Type: TYPE, default: <tt>DEFAULT</tt>.</em> 27 28<p> 29Description 30 31<p> 32Example: 33 34<example> 35</example> 36 37--> 38 39<debiandoc> 40 <book> 41 <title>&bmngr; &bmngr-version; User Guide 42 43 <author>Alexis Sukrieh 44 45 <version>&version; - &date-en; 46 47 <copyright> 48 <copyrightsummary> 49copyright © 2010 Alexis Sukrieh 50 </copyrightsummary> 51 52 <p> 53This user guide is free software; you may redistribute it and/or modify it 54under the terms of the GNU General Public License as published by the 55Free Software Foundation; either version 2, or (at your option) any 56later version. 57 <p> 58This is distributed in the hope that it will be useful, but 59<em>without any warranty</em>; without even the implied warranty of 60was merchantability or fitness for a particular purpose. See the GNU 61General Public License for more details. 62 <p> 63A copy of the GNU General Public License is available on the World Wide 64Web at <url id="&url-gpl;" name="the GNU web site">. You can also obtain 65it by writing to the &fsf-addr;. 66 67<toc detail="sect1"> 68 69<chapt id="about">About this manual 70 71<sect id="about-scope">Scope 72<p> 73&bmngr; is a system tool designed to handle backups. It is written with 74simplicity in mind. 75 76<p> 77If you want to handle a couple of tarballs, reading the 78default configuration file might be enough to understand the main design. 79On the other hand, if you want to know more about the global design of the 80program, how to write your own backup methods or even look at some real life 81examples, this guide is for you. 82 83<p> 84This document describes the main design of the software and gives information 85about supported configuration keys. All backup methods are described, with 86a sample configuration file as illustration. Whenever possible, advices and best 87practices are given. 88 89<p> 90This manual also describes every configuration variables supported in the 91version &bmngr-version;. 92 93<sect id="about-version">Version 94 95<p> 96This document is updated whenever a new release of &bmngr; is published. 97The current version covers all features and configuration details about version &bmngr-version;. 98 99<p> 100The first version of this document was written with the release 0.6 of &bmngr;. 101 102 103<sect id="about-authors">Authors 104<p> 105The first version of this document was made in late 2005, by Alexis Sukrieh and 106has been reviewed by Sven Joachim. 107 108<p> 109While the author of this document has tried hard to avoid typos and other 110errors, these do still occur. If you discover an error in this manual or if you 111want to give any comments, suggestions, or criticisms please create a new issue 112at https://github.com/sukria/Backup-Manager/issues 113 114<chapt id="configuration">Configuration files 115 116<p> 117<em>&bmngr;'s behaviour is defined in configuration files. You can run &bmngr; 118with different configuration files (at the same time or not). This chapter will 119cover all the configuration keys supported in version &bmngr-version; and will 120explain their meaning.</em> 121 122<sect id="design">Repository and Archives 123 124<p> 125&bmngr; stores <em>archives</em> it builds in a <em>repository</em>. 126<em>Archives</em> are built by using a <em>backup method</em>. 127 128<sect1 id="archive-repo">The Repository 129 130<!-- --> 131<sect2 id="BM_REPOSITORY_ROOT"><tt>BM_REPOSITORY_ROOT</tt> 132 133<p> 134<em>Type: string, default: <tt>/var/archives</tt>.</em> 135 136<p> 137The repository is the place in your filesystem 138where all archives are stored. 139This is a particular place for &bmngr;, it will be cleaned during backup 140sessions: archives older than the authorized lifetime will be purged. 141If the repository does not exist, it will be created at runtime. 142 143<p> 144Isolating the repository on a dedicated partition is a good idea. This can 145prevent the repository from eating all the disk space of the partition. 146With a bad configuration file, backup sessions can lead to huge archives, 147for many reasons, so take care. 148 149<p> 150Example: 151 152<example> 153export BM_REPOSITORY_ROOT="/var/archives" 154</example> 155 156<sect2 id="BM_REPOSITORY_SECURE"><tt>BM_REPOSITORY_SECURE</tt> 157 158<p> 159<em>Type: boolean, default: <tt>true</tt>.</em> 160 161<p> For security reasons, the repository can be accessible by a specific 162user/group pair. This will prevent the archives from being readable (and 163writable) by any user in the system. This mode is enabled by default (owned by 164<tt>root:root</tt>). 165 166<p> To enable this mode, set the configuration key <tt>BM_REPOSITORY_SECURE</tt> 167to <tt>yes</tt>, then update <tt>BM_REPOSITORY_USER</tt> and 168<tt>BM_REPOSITORY_GROUP</tt> to your needs. 169 170<p> 171You can also change the permission of the repository and the archives, that is 172possible with two configuration variables: <tt>BM_REPOSITORY_CHMOD</tt> and 173<tt>BM_ARCHIVE_CHMOD</tt>. 174 175<p> 176Example: 177 178<example> 179export BM_REPOSITORY_SECURE="true" 180export BM_REPOSITORY_USER="root" 181export BM_REPOSITORY_GROUP="root" 182export BM_REPOSITORY_CHMOD="770" 183export BM_ARCHIVE_CHMOD="660" 184</example> 185 186<sect1 id="encryption">Encryption 187<p> 188<em> 189If you cannot trust the place where you store your archives, you can choose to 190encrypt them so you are the only one who can read their content. 191That's a very good idea for archives you plan to upload to some remote place, 192or even for the archives you want to daily export on removable media. 193</em> 194 195<sect2 id="BM_ENCRYPTION_METHOD"><tt>BM_ENCRYPTION_METHOD</tt> 196<p> 197<em>Type: string, default: undefined.</em> 198<p> 199For &bmngr;, encryption is defined in one place in the configuration file. 200If the variable "<tt>BM_ENCRYPTION_METHOD</tt>" is not defined, no encryption occurs 201during the archive build process, if a method is defined there, then any 202archive built are encrypted through a pipeline with that method. 203 204<p> 205Be aware that encryption is supported for the methods "mysql", "pipe", 206"tarball" and "tarball-incremental" but only for those file types: 207tar, tar.gz, tar.bz2. 208 209<p> 210The only valid method supported for encrypting archives is "gpg". 211 212<p> 213&bmngr; will encrypt your archive through a pipeline in order not to write any 214byte of unencrypted data on the physical media. The encryption will be 215performed with a command line like the following: 216 217<example> 218<command> | gpg -r "$BM_ENCRYPTION_RECIPIENT" -e > archive.gpg 219</example> 220 221<p> 222To decrypt an archive built with GPG encryption, you have to be the owner of 223the private GPG key for which the encryption was made. 224 225Then issue the following: 226<example> 227$ gpg -d <archive.gpg> > archive 228</example> 229 230<p> 231GPG will then prompt you for the private key passphrase and will decrypt the 232content of the archive if the passphrase is valid. 233 234<p> 235Refer to the GPG documentation for more details of encryption. 236 237<sect2 id="BM_ENCRYPTION_RECIPIENT"><tt>BM_ENCRYPTION_RECIPIENT</tt> 238<p> 239<em>Type: string, default: undefined.</em> 240<p> 241As explained in the previous section, that variable should contain the GPG 242recipient for the encryption, eg: your GPG ID. 243 244<p> 245Examples of valid GPG ID: 246 247<example> 248export BM_ENCRYPTION_RECIPIENT="0x1EE5DD34" 249export BM_ENCRYPTION_RECIPIENT="Alexis Sukrieh" 250export BM_ENCRYPTION_RECIPIENT="sukria@sukria.net" 251</example> 252 253<sect1 id="archives">Archives 254 255<p> 256<em>Archives are produced by backup methods, they can be virtually anything, but 257will always be named like the following: <tt>prefix-name-date.filetype</tt>. An 258archive is a file that contains data, it can be compressed or not, in a binary 259form or not.</em> 260 261<sect2 id="BM_ARCHIVE_STRICTPURGE"><tt>BM_ARCHIVE_STRICTPURGE</tt> 262 263<p> 264<em>Type: boolean, default: <tt>true</tt>.</em> 265 266<p> 267As explained in the BM_REPOSITORY_ROOT section, every archive built by &bmngr; will 268be purged when their lifetime expires. In versions prior to 0.7.6, any archive 269were purged. 270<p> 271You can now choose to purge only the archive built in the scope of the 272configuration file, that is: archives prefixed with BM_ARCHIVE_PREFIX. 273 274<p> 275This is useful if you share the same BM_REPOSITORY_ROOT with different instances 276of &bmngr; that have different purging rules (eg: a BM_REPOSITORY_ROOT shared 277over NFS for multiple &bmngr; configuration). 278 279<p> 280Example: 281 282<example> 283export BM_ARCHIVE_STRICTPURGE="true" 284</example> 285 286<sect2 id="BM_ARCHIVE_NICE_LEVEL"><tt>BM_ARCHIVE_NICE_LEVEL</tt> 287 288<p> 289<em>Type: string, default: <tt>10</tt>.</em> 290 291<p> 292Backup Manager does handle several archive methods, which can use a lot of ressources 293(mostly CPU); although this can be acceptable if Backup Manager is run at night, on a 294always-running server, it can seriously slow-down a desktop computer. 295Indeed, most of the time, desktop users use anacron to run backup-manager when possible, 296and most of time this is when the desktop is actually used. 297 298<p> 299To enhance the desktop-experience when archives are built, 300you can adjust the niceness used for archive creation with this configuration variable. 301 302<p> 303To set a low priority to the archive creation processes, use a high number (max: 19). 304See the manpage of nice for details. 305 306<p> 307Example: 308 309<example> 310export BM_ARCHIVE_NICE_LEVEL="19" # recommanded for desktop users. 311</example> 312 313<sect2 id="BM_ARCHIVE_PURGEDUPS"><tt>BM_ARCHIVE_PURGEDUPS</tt> 314 315<p> 316<em>Type: boolean, default: <tt>true</tt>.</em> 317 318<p> 319If disk usage matters in your backup strategy, you might find useful to use 320&bmngr;'s duplicates purging feature. When an archive is generated, &bmngr; 321looks at the previous versions of this archive. If it finds that a previous 322archive is the same file as the one it has just built, the previous one is 323replaced by a symlink to the new one. This is useful if you don't want to have 324the same archive twice in the repository. 325 326<p> 327Example: 328 329<example> 330export BM_ARCHIVE_PURGEDUPS="true" 331 332host-etc.20051115.tar.gz 333host-etc.20051116.tar.gz -> /var/archives/host-etc.20051117.tar.gz 334host-etc.20051117.tar.gz 335</example> 336 337<sect2 id="BM_ARCHIVE_TTL"><tt>BM_ARCHIVE_TTL</tt> 338 339<p> 340<em>Type: integer, default: <tt>5</tt>.</em> 341 342<p> 343One of the main concepts behind the handling of the repository is to purge 344deprecated archives automatically. The purge session is always performed 345when you launch &bmngr;. During this phase, all archives older than the 346authorized lifetime are dropped. 347 348<p> 349Since version 0.7.3, &bmngr; purges only files it has created whereas in previous 350versions, it used to purge also other files within the repository. 351 352<p> 353Note that when using the incremental method for building archives, &bmngr; will 354handle differently master backups and incremental ones. The incremental backups 355will be purged like any other archives (when exceeding the authorized lifetime). 356On the ohter hand, deprecated master backups won't be purged unless there is a 357younger master backup in the repository. Then, even with a lifetime set to three 358days, a master backup will live more than three days, until a newer master 359backup is built. 360 361<p> 362Example: 363 364<example> 365export BM_ARCHIVE_TTL="5" 366</example> 367 368<sect2 id="BM_REPOSITORY_RECURSIVEPURGE"><tt>BM_REPOSITORY_RECURSIVEPURGE</tt> 369 370<p> 371<em>Type: boolean, default: <tt>false</tt>.</em> 372 373<p> 374On most setups, all the archives are stored in the top-level directory 375specified by the configuration key <tt>BM_REPOSITORY_ROOT</tt>. But it can make 376sense to have subdirectories, for instance to store archives uploaded from 377other hosts running &bmngr;. In this case, it is possible to ask &bmngr; to 378purge those directories too, by setting <tt>BM_REPOSITORY_RECURSIVEPURGE</tt> 379to <tt>true</tt>. 380 381<p> 382Please note that the <tt>BM_ARCHIVE_TTL</tt> value is global, so if you want to 383have different lifetimes for some archives, this is not the way to go. In this 384case you should save them outside <tt>BM_REPOSITORY_ROOT</tt> and write a cron 385job to do the purge (possibly calling <tt>backup-manager --purge</tt> with an 386alternate configuration file). 387 388<p> 389Example: 390 391<example> 392export BM_REPOSITORY_RECURSIVEPURGE="false" 393</example> 394 395<sect2 id="BM_ARCHIVE_PREFIX"><tt>BM_ARCHIVE_PREFIX</tt> 396 397<p> 398<em>Type: string, default: <tt>$HOSTNAME</tt>.</em> 399 400<p> 401This is the prefix used for naming archives. 402 403<p> 404Example: 405 406<example> 407export BM_ARCHIVE_PREFIX="$HOSTNAME" 408 409# echo $HOSTNAME 410ouranos 411# ls /var/archives 412ouranos-20051123.md5 413ouranos-usr-local-src.20051123.tar.gz 414ouranos-etc.20051123.tar.gz 415</example> 416 417<sect id="methods">Backup Methods 418 419<p> 420The core feature of &bmngr; is to make archives, for doing this, a 421<em>method</em> is used. Each method can require a set of configuration keys. 422We will describe here every method supported in the version &bmngr-version;. 423 424<p> 425The method you choose must be defined in the configuration key 426<tt>BM_ARCHIVE_METHOD</tt>. You can put here a list of all the different methods 427you want to use. Take care to put every configuration key needed by all the 428methods you choose. 429Note that you can also choose none of the proposed methods, if you don't want 430to build archives with this configuration file, then just put <tt>none</tt>. 431 432<p> 433A couple of other configuration keys may be needed depending on the method you 434choose. 435 436<p> 437Example: 438 439<example> 440export BM_ARCHIVE_METHOD="tarball-incremental mysql" 441</example> 442 443<sect1 id="tarball">Tarballs 444 445<sect2 id="tarball-desc">Description 446 447<p> 448<em>Method name: <tt>tarball</tt>, configuration key prefix: <tt>BM_TARBALL</tt>.</em> 449 450<p> 451If all you want to do is to handle a couple of tarballs of your file system, you 452can use this method. This method takes a list of directories 453and builds the corresponding tarballs. 454This method is the default one, this is the easiest to use, it just 455builds tarballs as you could do with your own tar script. Its main drawback is 456to eat a lot of disk space: archives can be big from a day to another, even if 457there are no changes in their content. See the <tt>tarball-incremental</tt> 458method if you want to optimize archives' size. 459 460<p> 461When building full backups (when not building incremental ones), &bmngr; will append 462the keyword "master" to the name of the archive. This is very useful when using 463the <tt>tarball-incremental</tt> method for seeing where the full backups are quickly. 464 465<p> 466A couple of options are available: the name format 467of the archive, the compression type (gzip, zip, bzip2, none) and the 468facility to dereference symlinks when building the tarball. 469 470<sect2 id="BM_TARBALL_NAMEFORMAT"><tt>BM_TARBALL_NAMEFORMAT</tt> 471<p> 472This configuration key defines how to perform the naming of the archive. Two 473values are possible: 474 475<list> 476<item><tt>long</tt>: the name will be made with the absolute path of the directory 477(eg: <tt>var-log-apache</tt> for <tt>/var/log/apache</tt>). 478<item><tt>short</tt>: the name will just contain the directory (eg: 479<tt>apache</tt> for <tt>/var/log/apache</tt>). 480</list> 481 482<p> 483Suggested value: <tt>long</tt>. 484 485<sect2 id="BM_TARBALL_FILETYPE"><tt>BM_TARBALL_FILETYPE</tt> 486 487<p> 488<em>Type: enum(tar, tar.gz, tar.bz2, tar.lz, zip, dar), default: <tt>tar.gz</tt>.</em> 489 490<p> 491Basically, this configuration key defines the filetype of the resulting archive. 492In a way, it defines which compressor to use (zip, gzip, dar or bzip2). 493Here are the supported values: <tt>tar</tt>, <tt>tar.gz</tt>, <tt>tar.bz2</tt>, 494<tt>zip</tt> and <tt>dar</tt>. 495Note that depending on the filetype you choose, you will have to 496make sure you have the corresponding compressor installed. 497 498<p> 499For the best compression rate, choose <tt>tar.bz2</tt> or <tt>tar.lz</tt>. 500 501<p> 502Since version 0.7.1, &bmngr; supports <em>dar</em> archives. This archiver 503provides some interesting features like the archive slicing. 504<p> 505Since version 0.7.5, &bmngr; supports <em>lzma</em> archives. 506 507<p> 508Make sure to statisfy dependencies according to the filetype you choose: 509 510<list> 511<item> tar.bz2 : needs "bzip2". 512<item> tar.lz : needs "lzma". 513<item> dar : needs "dar". 514<item> zip : needs "zip". 515</list> 516 517<sect2 id="BM_TARBALL_SLICESIZE"><tt>BM_TARBALL_SLICESIZE</tt> 518 519<p> 520<em>Type: string</em> 521 522<p> 523If you want to make sure your archives won't exceed a given size (for instance 2 524GB) you can use that configuration variable, but only if you are using the 525<tt>dar</tt> <tt>BM_TARBALL_FILETYPE</tt>. Indeed this feature is only supported 526by dar. 527 528<p> 529If you want to limit your archives size to 1 giga byte, use such a statement: 530 531<example> 532BM_TARBALL_SLICESIZE="1000M" 533</example> 534 535<p> 536Refer to the dar manpage for details about slices. 537 538<sect2 id="BM_TARBALL_EXTRA_OPTIONS"><tt>BM_TARBALL_EXTRA_OPTIONS</tt> 539 540<p> 541<em>Type: string</em> 542 543<p> 544If you want to provide extra options to "tar" or "dar" you may do so 545here. Leave blank unless you know what you are doing. 546 547<p> 548Example: to enable verbosity with tar (which would appeard in the logfiles), use this: 549 550<example> 551BM_TARBALL_EXTRA_OPTIONS="-v" 552</example> 553 554<sect2 id="BM_TARBALL_DUMPSYMLINKS"><tt>BM_TARBALL_DUMPSYMLINKS</tt> 555 556<p> 557<em>Type: boolean, default: <tt>true</tt>.</em> 558 559<p> 560It is possible, when generating the tarball (or the zip file) to dereference the 561symlinks. If you enable this feature, every symbolic link in the file system 562will be replaced in the archive by the file it points to. Use this feature with 563care, it can quickly lead to huge archives, or even worse: if you have a 564circular symlink somewhere, this will lead to an infinite archive! 565 566<p> 567In most of the cases, you should not use this feature. 568 569<sect2 id="BM_TARBALL_DIRECTORIES"><tt>BM_TARBALL_DIRECTORIES</tt> 570 571<p> 572<em>Type: space-separated list, default: <tt>null</tt>.</em> 573 574<p> 575Since version 0.7.3, this variable is replaced by the array BM_TARBALL_TARGETS[], 576it's still supported for backward compatibility though. 577You can use this variable for defining the locations to backup, but you must not 578use this variable if one or more of the paths you want to archive contain a space. 579 580<p> 581If you want to backup some targets that have spaces in their name (eg 582"Program Files"), you must not use this variable, but the array 583BM_TARBALL_TARGETS[] instead. 584 585<p> 586Example: 587 588<example> 589export BM_TARBALL_DIRECTORIES="/etc /home /var/log/apache" 590</example> 591 592<sect2 id="BM_TARBALL_TARGETS"><tt>BM_TARBALL_TARGETS</tt> 593 594<p> 595<em>Type: array, default: <tt>"/etc", "/boot"</tt>.</em> 596 597<p> 598This variable holds every place you want to backup. This is the recommanded 599variable to use for defining your backup targets (<tt>BM_TARBALL_DIRECTORIES</tt> is 600deprecated since version 0.7.3). 601 602<p> 603You can safely put items that contain spaces (eg: "Program Files") whereas you 604can't with <tt>BM_TARBALL_DIRECTORIES</tt>. 605 606<p> 607You can also put Bash patterns in BM_TARBALL_TARGETS[], it will be expanded at 608runtime to find the resulting targets. For instance : 609BM_TARBALL_TARGETS[0]="/home/*" will lead to backup every home's sub-directory. 610 611<p> 612Example 613 614<example> 615BM_TARBALL_TARGETS[0]="/etc" 616BM_TARBALL_TARGETS[1]="/home/*" 617BM_TARBALL_TARGETS[2]="/boot" 618BM_TARBALL_TARGETS[3]="/mnt/win/Program Files" 619</example> 620 621<sect2 id="BM_TARBALL_BLACKLIST"><tt>BM_TARBALL_BLACKLIST</tt> 622 623<p> 624<em>Type: space-separated list, default: <tt>"/proc /dev /sys /tmp"</tt>.</em> 625 626<p> 627It can be very useful to prevent some locations of your filesytem from being 628included in the archives. This is really useful when you use wildcards in 629BM_TARBALL_DIRECTORIES. Indeed, you may want to backup every top-level directory 630of your filesystem (<tt>/*</tt>) but without volatile locations like 631<tt>/tmp</tt>, <tt>/dev</tt> and <tt>/proc</tt>. 632 633<p> 634You can also use this variable for excluding every files of a given extension, 635like for instance mp3 or mpg files. 636 637<p> 638Example: 639 640<example> 641export BM_TARBALL_BLACKLIST="/tmp /dev /proc *.mp3 *.mpg" 642</example> 643 644<sect2 id="BM_TARBALL_OVER_SSH"><tt>BM_TARBALL_OVER_SSH</tt> 645<p> 646<em>Type: boolean, default: <tt>false</tt>.</em> 647<p> 648<strong>Dependency: <tt>BM_UPLOAD_SSH</tt></strong> 649 650<p> 651If you want to archive some remote locations from a server where &bmngr; is insalled, you can choose to 652build archives over SSH. This is useful if you don't want to install &bmngr; every where and setup some 653upload methods from all thoses servers to a central data storage server. 654This way, &bmngr; will build some archives directly over SSH and will store the resulting tarballs locally, 655as if it was built like any other archive. The resulting archive will be prefixed with the remote hostname 656instead of <tt>BM_ARCHIVE_PREFIX</tt>. 657 658<p> 659This feature requires that the following variables are set in the BM_UPLOAD_SSH section: 660<list> 661 <item><tt>BM_UPLOAD_SSH_USER</tt>: the user to use for connecting to the remote server. Note 662 that this user will run tar remotely, so take care to archive something this user can read! 663 <item><tt>BM_UPLOAD_SSH_KEY</tt>: as usal, the path to the private key to use for establishing the connection. 664 <item><tt>BM_UPLOAD_SSH_HOSTS</tt>: A list of hosts where to run the tarball builds. 665</list> 666 667<p> 668If you enable this feature, note that the resulting configuration file will have the following restrictions: 669<list> 670 <item>Remote tarball build only works with the <tt>tarball</tt> method, it will silently behaves the same 671 with <tt>tarball-incremental</tt>. 672 <item>You cannot use the remote build and the local one in the same configuration file. If you want to do both, 673 use two configuration files. 674</list> 675 676<p> 677Example: You have three hosts: host01, host02 and host03. You want to set up 678host01 as a data storage server, it has a big /var/archives partition. You want 679to archive "/etc", "/home" and "/var/log" on box02 and box03 and store the archives on 680host01. 681 682<example> 683[...] 684export BM_ARCHIVE_METHOD="tarball" 685 686export BM_TARBALL_OVER_SSH="true" 687export BM_TARBALL_FILETYPE="tar.bz2" 688export BM_TARBALL_DIRECTORIES="/etc /home /var/log" 689 690export BM_UPLOAD_SSH_USER="bamuser" 691export BM_UPLOAD_SSH_KEY="/home/bamuser/.ssh/id_dsa" 692export BM_UPLOAD_SSH_HOSTS="box02 box03" 693 694</example> 695 696Of course, for this to work correctly, <tt>`bamuser'</tt> should be a valid user on box02 697and box03; it must be allowed to connect to them with SSH key autentication and 698has to be able to read those directories. 699 700 701<sect1 id="tarballinc">Incremental tarballs 702<sect2 id="tarballinc-desc">Description 703 704<p> 705<em>Method name: <tt>tarball-incremental</tt>, configuration key prefix: 706<tt>BM_TARBALLINC</tt>.</em> 707 708<p> 709If you want to handle tarballs without wasting disk space, you should use this 710method. The concept of this method is simple: You choose a frequency when a full 711backup is made (exactly like the one made by the tarball mehod). All the days 712between two full backups, archives contain only the files that have changed from 713the previous archive. 714 715<p> 716For instance, let's say you want to backup /home with this method. Your /home 717directory is composed by two sub-directories: /home/foo and /home/bar. 718You choose a weekly frequency and say that monday will be the "fullbackup" day. 719Obviously, you will have a full tarball of /home on monday. 720Then, if a file changed inside /home/foo and if /home/bar 721remains unchanged, tuesday's archive will only contain the modified files of 722/home/foo. Using this method will save a lot of disk space. 723 724<p> 725To build incremental tarballs, &bmngr; uses tar's switch 726<tt>--listed-incremental</tt>. This will create a file for each target which 727will contain some statistics used by tar to figure out if a file should be 728backed up or not. 729When &bmngr; is run for the first time, this file doesn't exist, so the first 730tarballs made are always master backups. 731If the <em>incremental list</em> files get removed, the next backups won't be 732incremental. 733 734<p> 735Since version 0.7.3, it's possible to see at the first glance if a backup is 736a master or an incremental one: master backup have the keyword <tt>master</tt> 737appended to the date. 738When purging the repository, the master backups are not removed as the 739incremental ones. &bmngr; always keep a master backup that is older than 740incremental archives. 741 742<p> 743This method uses all the tarball's configuration keys and adds two more. One to 744define the kind of frequency, the other to choose on which day the full backups 745should be done. 746 747<sect2 id="BM_TARBALLINC_MASTERDATETYPE"><tt>BM_TARBALLINC_MASTERDATETYPE</tt> 748 749<p> 750<em>Type: enum(weekly, monthly), default: <tt>weekly</tt>.</em> 751 752<p> 753This is the type of frequency you want to use. If you choose <tt>weekly</tt>, 754you'll have to choose a day number between 0 and 6 for the 755BM_TARBALLINC_MASTERDATEVALUE configuration key, if you choose <tt>monthly</tt>, 756the day number will be between 1 and 31. 757 758 759<sect2 id="BM_TARBALLINC_MASTERDATEVALUE"><tt>BM_TARBALLINC_MASTERDATEVALUE</tt> 760 761<p> 762<em>Type: integer, default: <tt>1</tt>.</em> 763 764<p> 765The number of the day when making full backups. Note that its meaning directly 766depends on the <tt>BM_TARBALLINC_MASTERDATETYPE</tt>. 767For instance, 1 means <em>"monday"</em> if you 768choose a weekly frequency, but it means <em>"the first day of the month"</em> 769if you choose a monthly frequency. 770 771<sect1 id="mysql">MySQL databases 772<sect2 id="mysql-desc">Description 773 774<p> 775<em>Method name: <tt>mysql</tt>, configuration keys prefix: 776<tt>BM_MYSQL</tt>.</em> 777 778<p> 779This method provides a way to archive MySQL databases, the archives are made with 780mysqldump (SQL text files) and can be compressed. 781 782<p> 783In versions prior to 0.7.6, &bmngr; used to pass the MySQL client's password through 784the command line. As explained by the MySQL manual, that's a security issue as 785the password is then readable for a short time in the /proc directory (or using 786the ps command). 787 788<p> 789To close that vulnerability, the MySQL client password is not passed through 790the command line anymore, it is written in a configuration file located in the 791home directory of the user running &bmngr; : <tt>~/.my.cnf</tt>. 792 793<p> 794If that file doesn't exist at runtime, &bmngr; will create it and will then 795write the password provided in <tt>BM_MYSQL_ADMINPASS</tt> inside. 796 797<sect2 id="BM_MYSQL_DATABASES"><tt>BM_MYSQL_DATABASES</tt> 798 799<p> 800<em>Type: space-separated list, default: <tt>__ALL__</tt>.</em> 801<p> 802This is the list of databases you want to archive. 803You can put the keyword <tt>__ALL__</tt> if you like to backup every database without 804having to list them. 805<p> 806Example: 807 808<example> 809export BM_MYSQL_DATABASES="mysql mybase wordpress dotclear phpbb2" 810</example> 811 812<sect2 id="BM_MYSQL_SAFEDUMPS"><tt>BM_MYSQL_SAFEDUMPS</tt> 813<p> 814<em>Type: boolean, default: <tt>true</tt>.</em> 815 816<p> 817The best way to produce MySQL dumps is done by using mysqldump's <tt>--opt</tt> switch. 818This makes the dump directly usable with mysql (adds the drop table 819statements), locks tables during the dump generation and other cool things (see <tt>mysqldump</tt>). 820This is recommended for full-clean-safe backups, but needs a 821privileged user (for the lock permissions). 822 823<p> 824Example: 825 826<example> 827export BM_MYSQL_SAFEDUMPS="true" 828</example> 829 830 831<sect2 id="BM_MYSQL_ADMINLOGIN"><tt>BM_MYSQL_ADMINLOGIN</tt> 832 833<p> 834<em>Type: string, default: <tt>root</tt>.</em> 835 836<p> 837The MySQL login you want to use for connecting to the database. Make sure this login 838can read all the databases you've set in <tt>BM_MYSQL_DATABASES</tt>. 839 840<p> 841Example: 842 843<example> 844export BM_MYSQL_ADMINLOGIN="root" 845</example> 846 847<sect2 id="BM_MYSQL_ADMINPASS"><tt>BM_MYSQL_ADMINPASS</tt> 848 849<p> 850<em>Type: string, default: <tt>undefined</tt>.</em> 851<p> 852The MySQL client password. 853 854<p> 855If you have already made your own ~/.my.cnf configuration file, you don't have 856to set that variable. 857 858<p> 859If you don't know what is the <tt>~/.my.cnf</tt> configuration file, set the password, 860then &bmngr; will take care of creating the MySQL client configuration file. 861 862<p> 863Example: 864 865<example> 866export BM_MYSQL_ADMINPASS="MySecretPass" 867</example> 868 869 870<sect2 id="BM_MYSQL_HOST"><tt>BM_MYSQL_HOST</tt> 871 872<p> 873<em>Type: string, default: <tt>localhost</tt>.</em> 874 875<p> 876The database host where the databases are. 877 878<p> 879Example: 880 881<example> 882export BM_MYSQL_HOST="localhost" 883</example> 884 885<sect2 id="BM_MYSQL_PORT"><tt>BM_MYSQL_PORT</tt> 886 887<p> 888<em>Type: string, default: <tt>3306</tt>.</em> 889 890<p> 891The port on <tt>BM_MYSQL_HOST</tt> where the mysql server is listening. 892 893<p> 894Example: 895 896<example> 897export BM_MYSQL_PORT="3306" 898</example> 899 900<sect2 id="BM_MYSQL_FILETYPE"><tt>BM_MYSQL_FILETYPE</tt> 901 902<p> 903<em>Type: enum(gzip, bzip2), default: <tt>bzip2</tt>.</em> 904 905<p> 906The archive is made with mysqldump which renders SQL lines; the 907resulting text file can be compressed. 908If you want to compress the file, choose the compressor you want. 909Leave it blank if you want pure SQL files. 910 911<p> 912Example: 913 914<example> 915export BM_MYSQL_FILETYPE="bzip2" 916</example> 917 918<sect1 id="svn">Subversion repositories 919<sect2 id="svn-desc">Description 920 921<p> 922You can archive Subversion repositories with this method. The archive will be 923made with <tt>svnadmin</tt> and will contain XML data (text files). 924Like the mysql method, you can choose to compress it. 925 926<sect2 id="BM_SVN_REPOSITORIES"><tt>BM_SVN_REPOSITORIES</tt> 927 928<p> 929<em>Type: space-separated list</em> 930 931<p> 932This is the list of absolute paths to the SVN repositories to archive. 933 934<p> 935Example: 936 937<example> 938export BM_SVN_REPOSITORIES="/srv/svnroot/repo1 /srv/svnroot/repo2" 939</example> 940 941<sect2 id="BM_SVN_COMPRESSWITH"><tt>BM_SVN_COMPRESSWITH</tt> 942 943<p> 944<em>Type: enum(gzip, bzip2), default: <tt>bzip2</tt>.</em> 945 946<p> 947If you want to compress the resulting XML files, choose a compressor here. 948Leave this blank if you don't want any compression. 949 950<p> 951Example: 952 953<example> 954export BM_SVN_COMPRESSWITH="gzip" 955</example> 956 957<sect1 id="pipe">Generic methods 958<sect2 id="pipe-desc">Description 959 960<p> 961Even if most of the common needs are covered by the existing methods, there is always 962a case uncovered. &bmngr; provides a way for backing up anything, and can be used in such 963circumstances. 964 965<p> 966This method is called <tt>pipe</tt>, it is more complex to use but can virtually backup anything. 967The concept is simple, a pipe method is defined by the following items: 968 969<list> 970<item>A name (for naming the archive) 971<item>A command (that produces content on stdout) 972<item>A file type (txt, sql, dump, ...) 973<item>A compressor (gzip, bzip2) 974</list> 975 976<p> 977Those configuration keys are arrays, so you can implement as many pipe methods 978as you like. 979 980<p> 981For each pipe method defined, &bmngr; will launch the command given and redirect 982the content sent to stdout by this command to a file named with the name of the 983method and its filetype. Then, if the method uses a compressor, the file will 984be compressed. 985 986<sect2 id="pipe-example">Example 987<p> 988Example for archiving a remote MySQL database through SSH: 989 990<example> 991BM_PIPE_COMMAND[0]="ssh host -c \"mysqldump -ufoo -pbar base\"" 992BM_PIPE_NAME[0]="base" 993BM_PIPE_FILETYPE[0]="sql" 994BM_PIPE_COMPRESS[0]="gzip" 995</example> 996 997<p> 998Imagine you have a second pipe method to implement, for instance building 999a tarball trough SSH: 1000 1001<example> 1002BM_PIPE_COMMAND[1]="ssh host -c \"tar -c -z /home/user\"" 1003BM_PIPE_NAME[1]="host.home.user" 1004BM_PIPE_FILETYPE[1]="tar.gz" 1005BM_PIPE_COMPRESS[1]="" 1006</example> 1007 1008<p> 1009Note that we have incremented the array's index. 1010 1011<sect id="uploads">Upload Methods 1012 1013<sect1 id="uploads-desc">Description 1014<p> 1015<em>One of the most important thing to do when backing up file systems is to store 1016the archives on different places. The more different physical spaces you have, the better. 1017&bmngr; provides a way for achieving this goal : the upload methods. </em> 1018 1019<p> 1020There are different upload methods, each of them behaves differently and provides particular 1021features. In &bmngr; &bmngr-version; you can use FTP, SSH, RSYNC or Amazon S3 uploads. 1022 1023<p>In the same manner as for backup methods, you can choose to use as many 1024upload methods as you like. If you don't want to use this feature at all, just put 1025the keyword <tt>none</tt> in the configuration <tt>BM_UPLOAD_METHOD</tt>. 1026 1027<p> 1028Note that the FTP, SSH and S3 methods are dedicated to upload archives, 1029using those method depends on the use of at least one backup method. 1030 1031<p> 1032On the opposite, the RSYNC method uploads a directory to remote locations, 1033this directory can be your repository or whatever other location of your 1034file sytem. 1035 1036<sect1 id="uploads-global">Global configuration keys 1037<p> 1038The following configuration keys are global in the upload section: 1039 1040<sect2 id="BM_UPLOAD_HOSTS"><tt>BM_UPLOAD_HOSTS</tt> 1041<p> 1042<em>Type: space-separated list</em> 1043<p> 1044Each of the hosts defined in that list is used by all the upload methods 1045when establishing connections. For instance if you want to perform SSH uploads of 1046your archives and RSYNC upload of a location to the same host, put it in this list. 1047<p> 1048Example: 1049<example> 1050export BM_UPLOAD_HOSTS="mirror1.lan.mysite.net mirror2.lan.mysite.net" 1051</example> 1052 1053<sect2 id="BM_UPLOAD_DESTINATION"><tt>BM_UPLOAD_DESTINATION</tt> 1054<p> 1055<em>Type: string</em> 1056<p> 1057This is the absolute path of the directory in the remote hosts where to 1058put the files uploaded. 1059<p> 1060If you have installed installed &bmngr; on the remote host, 1061a good idea is to choose a sub-directory of the repository. 1062Then, during the remote host purge phase, your uploads will be 1063cleaned at the same time. 1064<p> 1065You can also define a destination dedicated to your host: 1066<tt>BM_UPLOAD_DESTINATION="/var/archives/$HOSTNAME"</tt> 1067 1068<p>Example: 1069 1070<p> 1071Let's say you want that all your uploads are performed on the host mirror2.lan.mysite.net, 1072in the sub-directory /var/archives/uploads 1073 1074<example> 1075export BM_UPLOAD_HOSTS="mirror2.lan.mysite.net" 1076export BM_UPLOAD_DESTINATION="/var/archives/uploads" 1077</example> 1078 1079<sect1 id="upload-ssh">SSH uploads 1080 1081<sect2 id="uploads-ssh-desc">Description 1082<p> 1083<em>Method name: <tt>ssh</tt>, goal: upload archives to remote hosts over SSH. 1084This method depends on a backup method. 1085</em> 1086 1087<p> 1088If you want to upload your archives on remote locations, you can use the SSH method. 1089This method is good if you like to use a secure tunnel between the two points of 1090the upload. 1091 1092<p> 1093The call to <tt>scp</tt> will be done with the identity of the user <tt>BM_UPLOAD_SSH_USER</tt>, 1094thus, you have to make sure this user can have access to the repository (take care to the secure mode). 1095 1096<sect2 id="BM_UPLOAD_SSH_USER"><tt>BM_UPLOAD_SSH_USER</tt> 1097<p> 1098<em>Type: string</em> 1099<p> 1100This is the user to use for performing the ssh connection. Make sure this user can access 1101repository. 1102<p> 1103Example: 1104<example> 1105export BM_UPLOAD_SSH_USER="bmngr" 1106</example> 1107 1108<sect2 id="BM_UPLOAD_SSH_KEY"><tt>BM_UPLOAD_SSH_KEY</tt> 1109<p> 1110<em>Type: string</em> 1111<p> 1112This is the path to the private key of the user BM_UPLOAD_SSH_USER. 1113<p> 1114Example: 1115<example> 1116export BM_UPLOAD_SSH_KEY="/home/bmngr/.ssh/id_dsa" 1117</example> 1118 1119<sect2 id="BM_UPLOAD_SSH_PORT"><tt>BM_UPLOAD_SSH_PORT</tt> 1120<p> 1121<em>Type: integer</em> 1122<p> 1123You may want to connect to remote hosts with a specific port. 1124Use this configuration key then. 1125<p> 1126Example: 1127<example> 1128export BM_UPLOAD_SSH_PORT="1352" 1129</example> 1130 1131<sect2 id="BM_UPLOAD_SSH_HOSTS"><tt>BM_UPLOAD_SSH_HOSTS</tt> 1132<p> 1133<em>Type: space-separated list</em> 1134<p> 1135Put here the list of hosts to use for SSH-only uploads. 1136Note that if you put some hosts in <tt>BM_UPLOAD_HOSTS</tt>, they will be used as well. 1137<p> 1138Example: 1139<example> 1140export BM_UPLOAD_SSH_HOSTS="mirror3.lan.mysite.net" 1141</example> 1142 1143<sect2 id="BM_UPLOAD_SSH_PURGE"><tt>BM_UPLOAD_SSH_PURGE</tt> 1144<p> 1145<em>Type: boolean</em> 1146<p> 1147If you set this boolean to "true", the remote archives will be purged before 1148the new ones are uploaded. The purging rules are the same as the ones &bmngr; 1149uses for local purging. If <tt>BM_UPLOAD_SSH_TTL</tt> is defined, this time to 1150live will be used, else <tt>BM_ARCHIVE_TTL</tt> will be used. 1151 1152<p> 1153Example: 1154<example> 1155export BM_UPLOAD_SSH_PURGE="true" 1156export BM_UPLOAD_SSH_TTL="10" 1157</example> 1158 1159<sect2 id="BM_UPLOAD_SSH_DESTINATION"><tt>BM_UPLOAD_SSH_DESTINATION</tt> 1160<p> 1161<em>Type: string</em> 1162<p> 1163Put here the destination for SSH-only uploads, this key overrides 1164<tt>BM_UPLOAD_DESTINATION</tt>. 1165<p> 1166Example: 1167<example> 1168export BM_UPLOAD_SSH_DESTINATION="/var/archives/scp-uploads" 1169</example> 1170 1171<sect1 id="upload-ssh-gpg"> Encrypted SSH uploads 1172<sect2 id="upload-ssh-gpg-desc"> Description 1173<p> 1174<em>Method name: <tt>ssh-gpg</tt>, goal: encrypt arcives using public 1175key encryption and upload the result to untrusted remote hosts 1176over SSH. This method depends on a backup method. </em> 1177 1178<p> 1179The upload using SSH can also be combined with public key encryption 1180provided by <tt>gpg</tt>. The archives will be encrypted using a 1181public key prior to sending them over the network, so on the remote 1182server your files are protected from inspection. 1183 1184<p> 1185This method can be used to protect your data from inspection on 1186untrusted remote servers. However, since the encrypted files are not 1187signed, this does not protect you from archive manipulation. So the 1188<em>md5</em> hases are still needed. 1189<p> 1190This method uses all of the configuartion keys of the <em>ssh</em> method. One 1191additional key is required. 1192<sect2 1193id="BM_UPLOAD_SSH_GPG_RECIPIENT"><tt>BM_UPLOAD_SSH_GPG_RECIPIENT</tt> 1194 1195<p> 1196<em>Type: string</em> 1197<p> 1198This parameter sets the recipient for which the archive is 1199encrypted. A valid specification is a short or long key id, or a 1200descriptive name, as explained in the <tt>gpg</tt> man page. The public key for 1201this identity must be in the key ring of the user running <tt>gpg</tt>, which 1202is the same as specified by <tt>BM_UPLOAD_SSH_USER</tt>. To test this 1203run the command <tt> gpg --list-keys ID </tt> as that user, where 1204<tt>ID</tt> is the ID as you give it to this parameter. If <tt>gpg</tt> 1205displays exactly one key, then you are fine. Refer to the <tt>gpg</tt> man page 1206for further details. 1207<p> 1208Example: 1209 1210<example> 1211export BM_UPLOAD_SSH_GPG_RECIPIENT="email@address.com" 1212export BM_UPLOAD_SSH_GPG_RECIPIENT="ECE009856" 1213</example> 1214 1215<sect1 id="upload-ftp">FTP uploads 1216<sect2 id="uploads-ftp-desc">Description 1217<p> 1218If security does not matter much on your lan (between the two points of the upload) you can choose to use the 1219FTP method. 1220One of the main pros of this method is that it can perform purging independently. You can safely use this method 1221for uploading files to a host where you just have an FTP account. 1222 1223<sect2 id="BM_UPLOAD_FTP_SECURE"><tt>BM_UPLOAD_FTP_SECURE</tt> 1224<p> 1225<em>Type: boolean, default: false.</em> 1226<p> 1227If this variable is set to true, all FTP transfers will be done over SSL. 1228<p> 1229Example: 1230<example> 1231export BM_UPLOAD_FTP_SECURE="true" 1232</example> 1233 1234 1235<sect2 id="BM_UPLOAD_FTP_PASSIVE"><tt>BM_UPLOAD_FTP_PASSIVE</tt> 1236<p> 1237<em>Type: boolean, default: true.</em> 1238<p> 1239If this variable is set to true, FTP transfers will be performed in passive mode, 1240which is mandatory in NATed/firewalled environments. 1241<p> 1242Example: 1243<example> 1244export BM_UPLOAD_FTP_PASSIVE="true" 1245</example> 1246 1247<sect2 id="BM_UPLOAD_FTP_TTL"><tt>BM_UPLOAD_FTP_TTL</tt> 1248<p> 1249<em>Type: integer, default: $BM_ARCHIVE_TTL</em> 1250<p> 1251Using different <em>time to live</em> values for local and remote archives can 1252be useful in certain situations. For instance, it's possible to install &bmngr; 1253locally, make it build archives, upload them to a remote FTP host and then purge 1254them locally (but not on the remote host). Doing this is possible with setting a 1255null value to the local TTL (BM_ARCHIVE_TTL) and a non-null value to 1256BM_UPLOAD_FTP_TTL. 1257<p> 1258Example: 1259<example> 1260# in your main conffile -- /etc/backup-manager.conf 1261export BM_ARCHIVE_TTL="0" 1262export BM_UPLOAD_FTP_TTL="5" 1263export BM_POST_BACKUP_COMMAND="/usr/sbin/backup-manager --purge" 1264 1265# in your cron job: 1266/usr/sbin/backup-manager 1267/usr/sbin/backup-manager --purge 1268 1269(Don't put the post-command in the main conffile or you'll face an infinite loop.) 1270</example> 1271 1272<sect2 id="BM_UPLOAD_FTP_USER"><tt>BM_UPLOAD_FTP_USER</tt> 1273<p> 1274<em>Type: string.</em> 1275<p> 1276Put here the FTP user to use for opening the connections. 1277<p> 1278Example: 1279<example> 1280export BM_UPLOAD_FTP_USER="bmngr" 1281</example> 1282 1283<sect2 id="BM_UPLOAD_FTP_PASSWORD"><tt>BM_UPLOAD_FTP_PASSWORD</tt> 1284<p> 1285<em>Type: string.</em> 1286<p> 1287Put here the password to use for authenticating the FTP session,(in plain text). 1288<p> 1289Example: 1290<example> 1291export BM_UPLOAD_FTP_PASSWORD="secret" 1292</example> 1293 1294<sect2 id="BM_UPLOAD_FTP_HOSTS"><tt>BM_UPLOAD_FTP_HOSTS</tt> 1295<p> 1296<em>Type: space-separated list</em> 1297<p> 1298Put here the list of hosts to use for FTP-only uploads. 1299Note that if you put some hosts in <tt>BM_UPLOAD_HOSTS</tt>, they will be used as well. 1300<p> 1301Example: 1302<example> 1303export BM_UPLOAD_FTP_HOSTS="mirror4.lan.mysite.net" 1304</example> 1305 1306<sect2 id="BM_UPLOAD_FTP_DESTINATION"><tt>BM_UPLOAD_FTP_DESTINATION</tt> 1307<p> 1308<em>Type: string</em> 1309<p> 1310Put here the destination for FTP-only uploads, this key overrides 1311<tt>BM_UPLOAD_DESTINATION</tt>. 1312<p> 1313Example: 1314<example> 1315export BM_UPLOAD_FTP_DESTINATION="/var/archives/ftp-uploads" 1316</example> 1317 1318<sect2 id="BM_UPLOAD_FTP_PURGE"><tt>BM_UPLOAD_FTP_PURGE</tt> 1319<p> 1320<em>Type: boolean, default: <tt>true</tt></em> 1321<p> 1322You can choose to purge deprecated archives before uploading new ones. 1323This purge is done over FTP and uses the configuration key <tt>BM_ARCHIVE_TTL</tt> in 1324the same manner as the local purge behaves (the FTP purge is not recursive though). 1325<p> 1326Example: 1327<example> 1328export BM_UPLOAD_FTP_PURGE="true" 1329</example> 1330 1331<sect1 id="upload-s3">Amazon S3 uploads 1332<sect2 id="uploads-s3-desc">Description 1333 1334<p> 1335Amazon's new Simple Storage Service (S3) is an Internet "web service" 1336that permits you to store unlimited blocks of data on their replicated 1337and managed systems. See http://aws.amazon.com for more 1338information. Registration is free and the rates are quite reasonable. 1339 1340<p> 1341Using the S3 upload method will permit your archives to be stored on 1342Amazon's S3 service. You must allocate a "bucket" to the exclusive use 1343of Backup Manager. Each of your created archives will be uploaded to 1344S3 and stored within this bucket in a key name that matches the name 1345of the archive. 1346 1347<p> 1348As with the other backup methods Backup Manager does not assist you in 1349restoring files from archives. You must retrieve archives from S3 1350using other mechanisms such as the S3Shell provided as an examle 1351command line utility by Amazon. 1352 1353<p> 1354Note that when using this upload method, the <tt>BM_UPLOAD_HOSTS</tt> variable is 1355ignored as the only valid host for S3 uploads in <tt>s3.amazon.com</tt>. 1356 1357<sect2 id="BM_UPLOAD_S3_DESTINATION"><tt>BM_UPLOAD_S3_DESTINATION</tt> 1358<p> 1359<em>Type: string.</em> 1360<p> 1361This option is required for the S3 upload method. This specifies the 1362bucket used to store backup data. If the bucket does not exist it will 1363be created as a private bucket. This key overrides 1364<tt>BM_UPLOAD_DESTINATION</tt>. Note that Amazon requires that bucket 1365names be globally unique. Be creative picking one. 1366<p> 1367Example: 1368<example> 1369export BM_UPLOAD_S3_DESTINATION="my_backup_bucket" 1370</example> 1371 1372<sect2 id="BM_UPLOAD_S3_ACCESS_KEY"><tt>BM_UPLOAD_S3_ACCESS_KEY</tt> 1373<p> 1374<em>Type: string.</em> 1375<p> 1376This option is required for the S3 upload method. After you have 1377registered Amazon will provide you an access key. You must use this 1378key to access your storage on S3. 1379<p> 1380Example: 1381<example> 1382export BM_UPLOAD_S3_ACCESS_KEY="a9sabkz0342dasv" 1383</example> 1384 1385<sect2 id="BM_UPLOAD_S3_SECRET_KEY"><tt>BM_UPLOAD_S3_SECRET_KEY</tt> 1386<p> 1387<em>Type: string.</em> 1388<p> 1389This option is required for the S3 upload method. After you have 1390registered Amazon will provide you a secret key. You must use this 1391key to write to your storage on S3. 1392<p> 1393Example: 1394<example> 1395export BM_UPLOAD_S3_SECRET_KEY="lkj2341askj123sa" 1396</example> 1397 1398<sect2 id="BM_UPLOAD_S3_PURGE"><tt>BM_UPLOAD_S3_PURGE</tt> 1399<p> 1400<em>Type: boolean, default: <tt>true</tt></em> 1401<p> 1402You can choose to purge deprecated archives before uploading new ones. 1403This purge is done over S3 and uses the configuration key <tt>BM_ARCHIVE_TTL</tt> in 1404the same manner as the local purge behaves (the S3 purge is not recursive though). 1405<p> 1406Example: 1407<example> 1408export BM_UPLOAD_S3_PURGE="true" 1409</example> 1410 1411<sect2 id="BM_UPLOAD_S3_TTL"><tt>BM_UPLOAD_S3_TTL</tt> 1412<p> 1413<em>Type: integer, default: $BM_ARCHIVE_TTL</em> 1414<p> 1415Using different <em>time to live</em> values for local and remote archives can 1416be useful in certain situations. For instance, it's possible to install &bmngr; 1417locally, make it build archives, upload them to S3 and then purge them locally 1418(but not on the remote host). Doing this is possible with setting a null value 1419to the local TTL (BM_ARCHIVE_TTL) and a non-null value to BM_UPLOAD_S3_TTL. 1420<p> 1421 1422<sect1 id="upload-rsync">RSYNC uploads 1423<sect2 id="upload-rsync-desc">Description 1424<p> 1425You may want to upload some parts of your file system to some remote hosts. 1426In these cases, archives are not needed, you just want to synchronize some 1427directories to remote places. This is where the RSYNC upload method is useful. 1428<p> 1429RSYNC uploads need a SSH user/key pair to behave correctly, thus there is a 1430dependency against the keys <tt>BM_UPLOAD_SSH_USER</tt> and <tt>BM_UPLOAD_SSH_KEY</tt>. 1431 1432<sect2 id="BM_UPLOAD_RSYNC_DIRECTORIES"><tt>BM_UPLOAD_RSYNC_DIRECTORIES</tt> 1433<p> 1434<em>Type: space-separated list</em> 1435<p> 1436Put here the list of local directories you want to upload with rsync. 1437<p> 1438Example: 1439<example> 1440export BM_UPLOAD_RSYNC_DIRECTORIES="/data/photos /data/videos /data/mp3" 1441</example> 1442 1443<sect2 id="BM_UPLOAD_RSYNC_HOSTS"><tt>BM_UPLOAD_RSYNC_HOSTS</tt> 1444<p> 1445<em>Type: space-separated list</em> 1446<p> 1447Put here the list of hosts to use for RSYNC-only uploads. 1448Note that if you put some hosts in <tt>BM_UPLOAD_HOSTS</tt>, they will be used as well. 1449<p> 1450Example: 1451<example> 1452export BM_UPLOAD_RSYNC_HOSTS="mirror5.lan.mysite.net" 1453</example> 1454 1455<sect2 id="BM_UPLOAD_RSYNC_DESTINATION"><tt>BM_UPLOAD_RSYNC_DESTINATION</tt> 1456<p> 1457<em>Type: string</em> 1458<p> 1459Put here the destination for RSYNC-only uploads, this key overrides 1460<tt>BM_UPLOAD_DESTINATION</tt>. 1461<p> 1462Example: 1463<example> 1464export BM_UPLOAD_RSYNC_DESTINATION="/var/archives/rsync-snapshots" 1465</example> 1466 1467<sect2 id="BM_UPLOAD_RSYNC_DUMPSYMLINKS"><tt>BM_UPLOAD_RSYNC_DUMPSYMLINKS</tt> 1468<p> 1469<em>Type: boolean, default: <tt>false</tt>.</em> 1470<p> 1471You can choose to dereference files pointed by symlinks in your RSYNC snapshots. 1472This feature should be used with care. 1473<p> 1474Example: 1475<example> 1476export BM_UPLOAD_RSYNC_DUMPSYMLINKS="false" 1477</example> 1478 1479<sect id="exports">Exports 1480<p> 1481<em> 1482Another way of storing your archives to a safe place is to use external media. 1483</em> 1484 1485<p> 1486In version &bmngr-version;, only CDs and DVDs are supported as external media, so we will discuss 1487in this section only the <tt>BM_BURNING</tt> features. 1488Other exports are expected to come in next versions though. 1489 1490<sect1 id="exports-burning">Burning CDR/DVD media 1491<p> 1492In the version &bmngr-version;, &bmngr; supports four different kinds of media: CDR, 1493CDRW and DVD+R(W) and DVD-R(W). 1494 1495<sect2 id="BM_BURNING_METHOD"><tt>BM_BURNING_METHOD</tt> 1496<p> 1497Set the key <tt>BM_BURNING_METHOD</tt> to the method corresponding to the media you want to burn: 1498 1499<list> 1500<item>CDR 1501<item>CDRW 1502<item>DVD 1503<item>DVD-RW 1504</list> 1505 1506<p> 1507In <em>non-interactive mode</em> (when backup-manager is not lauchned from a terminal), 1508any of these methods will try to put the whole archive repository in the media, if it does not 1509fit in the media, it will try to put only the archives built on the day, if that's not possible, 1510nothing will be burnt. 1511 1512<p> 1513In <em>interactive mode</em> (when backup-manager is launched from a terminal), 1514the whole repository will be burnt into as many media as needed. When a medium is 1515satured with archives, backup-manager will pause the process asking the user to put a new 1516media inside. 1517 1518<p> 1519The <tt>CDRW</tt> and <tt>DVD-RW</tt> methods will first blank the media, 1520so you can safely use these methods if you want to use the same medium several times. 1521 1522<p> 1523The <tt>CDR</tt> and <tt>DVD</tt> medthods won't blank the medium first 1524(DVD+RW media doesn't need blanking, it's possible to re-burn data on-the-fly 1525over such media).. 1526 1527<p> 1528DVD media are handled by the tool <tt>dvd+rw-tools</tt>, problems can occur in CRON environment with 1529<tt>dvd+rw-tools</tt> versions prior to <tt>6.1</tt>, make sure to have <tt>6.1</tt> 1530or later if you want to burn DVD media with Backup Manager. 1531 1532<p> 1533As usual, you can put <tt>none</tt> in order to disable the burning process. 1534 1535<p> 1536All those burning methods share the same configuration keys, so it's easy to 1537switch from a medium to another. 1538 1539<sect2 id="BM_BURNING_DEVICE"><tt>BM_BURNING_DEVICE</tt> 1540<p> 1541<em>Type: string, default: <tt>/dev/cdrom</tt>.</em> 1542<p> 1543This is mandatory for using the burning feature, it's the device 1544to use for mounting the media. It's needed by backup manager for 1545performing the MD5 checks and for other needs. 1546<p> 1547Example: 1548<example> 1549export BM_BURNING_DEVICE="/dev/cdrom" 1550</example> 1551 1552<sect2 id="BM_BURNING_DEVFORCED"><tt>BM_BURNING_DEVFORCED</tt> 1553<p> 1554<em>Type: string</em> 1555<p> 1556&bmngr; uses <tt>cdrecord</tt> for burning CDs. If when you run 1557<tt>cdrecord -scanbus</tt> you don't see your burning device, that means you will have to 1558force the device in ATA mode. 1559To tell &bmngr; to do so, just put here the path to your device, and a switch will be appended to the 1560cdrecord commandline like the following : <tt>cdrecrord ... dev=$BM_BURNING_DEVFORCED ...</tt>. 1561<p> 1562Leave this configuration key blank if you see your device with <tt>cdrecord -scanbus</tt>, 1563in this case, &bmngr; will use the default cdrecord device for burning CDR media. 1564<p> 1565Example: 1566<example> 1567export BM_BURNING_DEVFORCED="/dev/cdrom" 1568</example> 1569 1570<sect2 id="BM_BURNING_ISO_FLAGS"><tt>BM_BURNING_ISO_FLAGS</tt> 1571<p> 1572<em>Type: string, default: "-R -J"</em> 1573 1574<p> 1575Media burned with &bmngr; will be made using a Joliet disc image. 1576The flags defined in that variable will be …
Large files files are truncated, but you can click here to view the full file