PageRenderTime 50ms CodeModel.GetById 29ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 1ms

/doc/user-guide.sgml

http://github.com/sukria/Backup-Manager
Unknown | 2014 lines | 1612 code | 402 blank | 0 comment | 0 complexity | a2bc32ddbb304c40d440e5606dcfafc9 MD5 | raw file

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>&nbsp;">
  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 &copy; 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&lt;command&gt; | 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 &lt;archive.gpg&gt; > 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