Skip to content
This repository
Browse code

2005-12-19 Alexis Sukrieh <sukria@backup-manager.org>

	* INSTALL:
	  + bits about dependencies
	* NEWS:
	  + The 0.6 Changelog
	* doc/DISCLAIMER:
	  + Removed, not needed anymore.
	* doc/README:
	  + Bits about the available formats.
	* doc/user-guide.txt:
	  + Added the text version in the repository, so users
	    can have a light version of the guide with the release.
	* doc/version.ent:
	  + Revision: 1.0




git-svn-id: svn://svn.backup-manager.org/backup-manager/trunk@291 2e458433-d701-0410-9826-f9b593394a3c
  • Loading branch information...
commit 7cc9f09cedca40c14a885ecb524502b3c796bef1 1 parent 376ff5b
sukria authored
16 ChangeLog
... ... @@ -1,5 +1,21 @@
1 1 2005-12-19 Alexis Sukrieh <sukria@backup-manager.org>
2 2
  3 + * INSTALL:
  4 + + bits about dependencies
  5 + * NEWS:
  6 + + The 0.6 Changelog
  7 + * doc/DISCLAIMER:
  8 + + Removed, not needed anymore.
  9 + * doc/README:
  10 + + Bits about the available formats.
  11 + * doc/user-guide.txt:
  12 + + Added the text version in the repository, so users
  13 + can have a light version of the guide with the release.
  14 + * doc/version.ent:
  15 + + Revision: 1.0
  16 +
  17 +2005-12-19 Alexis Sukrieh <sukria@backup-manager.org>
  18 +
3 19 * New configuration key BM_UPLOAD_SSH_PORT
4 20 + backup-manager.conf.tpl
5 21 + doc/user-guide.sgml
8 INSTALL
... ... @@ -1,3 +1,8 @@
  1 +Dependencies:
  2 + If you want to enable the localisation, you need gettext.
  3 + Perl is needed for FTP and SSH uploads.
  4 + Everything else is written in Bash.
  5 +
1 6 How to install backup-manager
2 7
3 8 ~/backup-manager $
@@ -8,6 +13,7 @@ How to install backup-manager
8 13
9 14 You can then edit /etc/backup-manager.conf to fit your needs.
10 15
11   -see backup-manager(8) for details.
  16 +Refere to the user guide for details:
  17 +http://www.backup-manager.org/documentation/user-guide/
12 18
13 19
27 NEWS
... ... @@ -1,3 +1,30 @@
  1 +2005-12-19 (0.6) Alexis Sukrieh <sukria@backup-manager.org>
  2 + * New Features:
  3 + + New backup method "tarball-incremental" for building
  4 + incremental backups.
  5 + + New upload metyhod "rsync".
  6 + + Support for multiple backup methods in BM_ARCHIVE_METHOD
  7 + + Support for multiple upload methods in BM_UPLOAD_METHOD
  8 + + User Guide available in different formats (HTML, PDF)
  9 + * Changes:
  10 + + Booleans must be true/false values, yes/no are deprecated
  11 + (triggers warnings but backward compatible though).
  12 + + Configuration key "BM_BURNING" is deprecated, use "BM_BURNING_METHOD" instead.
  13 + * Bugs closed by this release:
  14 + + No error when the repository is not accessible by BM_UPLOAD_USER (bug #2)
  15 + + [BM_TARBALL_BLACKLIST] error handling multiple directories (bug #4)
  16 + + feature request: use of ports other than 22 for scp upload (bug #5)
  17 + + Backup-Manager can't umount an unmounted CD (bug #6)
  18 + + Write the user guide (bug #8)
  19 + + Support for multiple methods in BM_ARCHIVE_METHOD (bug #9)
  20 + + Function backup_method_rsync() uses BM_TARBALL confkeys (bug #10)
  21 + + Configuration keys BM_UPLOAD_USER/KEY/PASSWORD should be renamed (bug #11)
  22 + * Translations:
  23 + + Full translation in French.
  24 + + Full translation in German.
  25 + + Full translation in Spanish.
  26 + + Full translation in Vietnamese.
  27 +
1 28 2005-11-07 (0.5.9b) Alexis Sukrieh <sukria@sukria.net>
2 29
3 30 * New Features:
1  doc/DISCLAIMER
... ... @@ -1 +0,0 @@
1   -This is a Work In Progress
8 doc/README
... ... @@ -0,0 +1,8 @@
  1 +The text version of the user guide is provided here:
  2 +user-guide.txt
  3 +
  4 +If you want to use the HTML or PDF format, grab it from the Backup
  5 +Maneger website:
  6 +http://www.backup-manager.org/documentation/
  7 +
  8 +This has been written in SGML with the debiandoc tools.
1,247 doc/user-guide.txt
... ... @@ -0,0 +1,1247 @@
  1 +
  2 + Backup Manager 0.6 User Guide
  3 + -----------------------------
  4 +
  5 + Alexis Sukrieh
  6 +
  7 + 0.2 - 16 December, 2005
  8 +
  9 +
  10 +-------------------------------------------------------------------------------
  11 +
  12 +
  13 +Copyright Notice
  14 +----------------
  15 +
  16 + copyright (C) 2005 Alexis Sukrieh
  17 +
  18 + This user guide is free software; you may redistribute it and/or
  19 + modify it under the terms of the GNU General Public License as
  20 + published by the Free Software Foundation; either version 2, or (at
  21 + your option) any later version.
  22 +
  23 + This is distributed in the hope that it will be useful, but _without
  24 + any warranty_; without even the implied warranty of was
  25 + merchantability or fitness for a particular purpose. See the GNU
  26 + General Public License for more details.
  27 +
  28 + A copy of the GNU General Public License is available on the World
  29 + Wide Web at the GNU web site (http://www.gnu.org/copyleft/gpl.html).
  30 + You can also obtain it by writing to the Free Software Foundation,
  31 + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  32 +
  33 +
  34 +-------------------------------------------------------------------------------
  35 +
  36 +
  37 +Contents
  38 +--------
  39 +
  40 + 1. About this manual
  41 + 1.1. Scope
  42 + 1.2. Version
  43 + 1.3. Authors
  44 +
  45 + 2. Configuration files
  46 + 2.1. Repository and Archives
  47 + 2.1.1. The Repository
  48 + 2.1.2. Archives
  49 + 2.2. Backup Methods
  50 + 2.2.1. Tarballs
  51 + 2.2.2. Incremental tarballs
  52 + 2.2.3. MySQL databases
  53 + 2.2.4. Subversion repositories
  54 + 2.2.5. Generic methods
  55 + 2.3. Upload Methods
  56 + 2.3.1. Description
  57 + 2.3.2. Global configuration keys
  58 + 2.3.3. SSH uploads
  59 + 2.3.4. FTP uploads
  60 + 2.3.5. RSYNC uploads
  61 + 2.4. Exports
  62 + 2.4.1. Burning CDR/DVD media
  63 + 2.5. Advanced features
  64 + 2.5.1. Logging to syslog
  65 + 2.5.2. Writing external hooks
  66 +
  67 + 3. Using Backup Manager
  68 + 3.1. Command line
  69 + 3.1.1. Restrictions
  70 + 3.1.2. Options
  71 + 3.2. CRON integration
  72 +
  73 +
  74 +-------------------------------------------------------------------------------
  75 +
  76 +
  77 +1. About this manual
  78 +--------------------
  79 +
  80 +
  81 +1.1. Scope
  82 +----------
  83 +
  84 + Backup Manager is a system tool designed to handle backups. It is
  85 + written with simplicity in mind.
  86 +
  87 + If you want to handle a couple of tarballs, reading the default
  88 + configuration file might be enough to understand the main design. On
  89 + the other hand, if you want to know more about the global design of
  90 + the program, how to write your own backup methods or even look at some
  91 + real life examples, this guide is for you.
  92 +
  93 + This document describes the main design of the software and gives
  94 + information about supported configuration keys. All backup methods
  95 + are described, with a sample configuration file as illustration.
  96 + Whenever possible, advices and best practices are given.
  97 +
  98 + This manual also describes every configuration variables supported in
  99 + the version 0.6.
  100 +
  101 +
  102 +1.2. Version
  103 +------------
  104 +
  105 + This is the first version of this document, it was first released with
  106 + the release 0.6 of Backup Manager.
  107 +
  108 +
  109 +1.3. Authors
  110 +------------
  111 +
  112 + The first version of this document was made in late 2005, by Alexis
  113 + Sukrieh and has been reviewed by Sven Joachim.
  114 +
  115 + While the author of this document has tried hard to avoid typos and
  116 + other errors, these do still occur. If you discover an error in this
  117 + manual or if you want to give any comments, suggestions, or criticisms
  118 + please send an email to the development list,
  119 + backup-manager-devel@backup-manager.org, or submit a bug report
  120 + against the "Documentation" product, in the bug tracking system.
  121 +
  122 +
  123 +-------------------------------------------------------------------------------
  124 +
  125 +
  126 +2. Configuration files
  127 +----------------------
  128 +
  129 + _Backup Manager's behaviour is defined in configuration files. You
  130 + can run Backup Manager with different configuration files (at the same
  131 + time or not). This chapter will cover all the configuration keys
  132 + supported in version 0.6 and will explain their meaning._
  133 +
  134 +
  135 +2.1. Repository and Archives
  136 +----------------------------
  137 +
  138 + Backup Manager stores _archives_ it builds in a _repository_.
  139 + _Archives_ are built by using a _backup method_.
  140 +
  141 +2.1.1. The Repository
  142 +---------------------
  143 +
  144 +2.1.1.1. `BM_REPOSITORY_ROOT'
  145 +-----------------------------
  146 +
  147 + _Type: string, default: `/var/archives'._
  148 +
  149 + The repository is the place in your filesystem where all archives are
  150 + stored. This is a particular place for Backup Manager, it will be
  151 + cleaned during backup sessions: archives older than the authorized
  152 + lifetime will be purged. If the repository does not exist, it will be
  153 + created at runtime.
  154 +
  155 + Isolating the repository on a dedicated partition is a good idea.
  156 + This can prevent the repository from eating all the disk space of the
  157 + partition. With a bad configuration file, backup sessions can lead to
  158 + huge archives, for many reasons, so take care.
  159 +
  160 + Example:
  161 +
  162 + export BM_REPOSITORY_ROOT="/var/archives"
  163 +
  164 +2.1.1.2. `BM_REPOSITORY_SECURE'
  165 +-------------------------------
  166 +
  167 + _Type: boolean, default: `true'._
  168 +
  169 + For security reasons, the repository can be accessible by a specific
  170 + user/group pair. This will prevent the archives from being readable
  171 + (and writable) by any user in the system. This mode is enabled by
  172 + default (owned by `root:root').
  173 +
  174 + To enable this mode, set the configuration key `BM_REPOSITORY_SECURE'
  175 + to `yes', then update `BM_REPOSITORY_USER' and `BM_REPOSITORY_GROUP'
  176 + to your needs.
  177 +
  178 + Example:
  179 +
  180 + export BM_REPOSITORY_SECURE="true"
  181 + export BM_REPOSITORY_USER="root"
  182 + export BM_REPOSITORY_GROUP="root"
  183 +
  184 +2.1.2. Archives
  185 +---------------
  186 +
  187 + _Archives are produced by backup methods, they can be virtually
  188 + anything, but will always be named like the following:
  189 + `prefix-name-date.filetype'. An archive is a file that contains data,
  190 + it can be compressed or not, in a binary form or not._
  191 +
  192 +2.1.2.1. `BM_ARCHIVE_PURGEDUPS'
  193 +-------------------------------
  194 +
  195 + _Type: boolean, default: `true'._
  196 +
  197 + If disk usage matters in your backup strategy, you might find useful
  198 + to use Backup Manager's duplicates purging feature. When an archive
  199 + is generated, Backup Manager looks at the previous versions of this
  200 + archive. If it finds that a previous archive is the same file as the
  201 + one it has just built, the previous one is replaced by a symlink to
  202 + the new one. This is useful if you don't want to have the same
  203 + archive twice in the repository.
  204 +
  205 + Example:
  206 +
  207 + export BM_ARCHIVE_PURGEDUPS="true"
  208 +
  209 + host-etc.20051115.tar.gz
  210 + host-etc.20051116.tar.gz -> /var/archives/host-etc.20051117.tar.gz
  211 + host-etc.20051117.tar.gz
  212 +
  213 +2.1.2.2. `BM_ARCHIVE_TTL'
  214 +-------------------------
  215 +
  216 + _Type: integer, default: `5'._
  217 +
  218 + One of the main concepts behind the handling of the repository is to
  219 + purge deprecated archives automatically. The purge session is always
  220 + performed when you launch Backup Manager. During this phase, all
  221 + archives older than the authorized lifetime are dropped.
  222 +
  223 + Example:
  224 +
  225 + export BM_ARCHIVE_TTL="5"
  226 +
  227 +2.1.2.3. `BM_ARCHIVE_PREFIX'
  228 +----------------------------
  229 +
  230 + _Type: string, default: `$HOSTNAME'._
  231 +
  232 + This is the prefix used for naming archives.
  233 +
  234 + Example:
  235 +
  236 + export BM_ARCHIVE_PREFIX="$HOSTNAME"
  237 +
  238 + # echo $HOSTNAME
  239 + ouranos
  240 + # ls /var/archives
  241 + ouranos-20051123.md5
  242 + ouranos-usr-local-src.20051123.tar.gz
  243 + ouranos-etc.20051123.tar.gz
  244 +
  245 +
  246 +2.2. Backup Methods
  247 +-------------------
  248 +
  249 + The core feature of Backup Manager is to make archives, for doing
  250 + this, a _method_ is used. Each method can require a set of
  251 + configuration keys. We will describe here every method supported in
  252 + the version 0.6.
  253 +
  254 + The method you choose must be defined in the configuration key
  255 + `BM_ARCHIVE_METHOD'. You can put here a list of all the different
  256 + methods you want to use. Take care to put every configuration key
  257 + needed by all the methods you choose. Note that you can also choose
  258 + none of the proposed methods, if you don't want to build archives with
  259 + this configuration file, then just put `none'.
  260 +
  261 + A couple of other configuration keys may be needed depending on the
  262 + method you choose.
  263 +
  264 + Example:
  265 +
  266 + export BM_ARCHIVE_METHOD="tarball-incremental mysql"
  267 +
  268 +2.2.1. Tarballs
  269 +---------------
  270 +
  271 +2.2.1.1. Description
  272 +--------------------
  273 +
  274 + _Method name: `tarball', configuration key prefix: `BM_TARBALL'._
  275 +
  276 + If all you want to do is to handle a couple of tarballs of your file
  277 + system, you can use this method. This method takes a list of
  278 + directories and builds the corresponding tarballs. This method is the
  279 + default one, this is the easiest to use, it just builds tarballs as
  280 + you could do with your own tar script. Its main drawback is to eat a
  281 + lot of disk space: archives can be big from a day to another, even if
  282 + there are no changes in their content. See the `tarball-incremental'
  283 + method if you want to optimize archives' size.
  284 +
  285 + A couple of options are available: the name format of the archive, the
  286 + compression type (gzip, zip, bzip2, none) and the facility to
  287 + dereference symlinks when building the tarball.
  288 +
  289 +2.2.1.2. `BM_TARBALL_NAMEFORMAT'
  290 +--------------------------------
  291 +
  292 + This configuration key defines how to perform the naming of the
  293 + archive. Two values are possible:
  294 +
  295 + * `long': the name will be made with the absolute path of the
  296 + directory (eg: `var-log-apache' for `/var/log/apache').
  297 +
  298 + * `short': the name will just contain the directory (eg: `apache'
  299 + for `/var/log/apache').
  300 +
  301 + Suggested value: `long'.
  302 +
  303 +2.2.1.3. `BM_TARBALL_FILETYPE'
  304 +------------------------------
  305 +
  306 + _Type: enum(tar, tar.gz, tar.bz2, zip), default: `tar.gz'._
  307 +
  308 + Basically, this configuration key defines the filetype of the
  309 + resulting archive. In a way, it defines which compressor to use (zip,
  310 + gzip or bzip2). Here are the supported values: `tar', `tar.gz',
  311 + `tar.bz2', `zip'. Note that depending on the filetype you choose, you
  312 + will have to make sure you have the corresponding compressor.
  313 +
  314 + For the best compression rate, choose `tar.bz2'.
  315 +
  316 +2.2.1.4. `BM_TARBALL_DUMPSYMLINKS'
  317 +----------------------------------
  318 +
  319 + _Type: boolean, default: `true'._
  320 +
  321 + It is possible, when generating the tarball (or the zip file) to
  322 + dereference the symlinks. If you enable this feature, every symbolic
  323 + link in the file system will be replaced in the archive by the file it
  324 + points to. Use this feature with care, it can quickly lead to huge
  325 + archives, or even worse: if you have a circular symlink somewhere,
  326 + this will lead to an infinite archive!
  327 +
  328 + In most of the cases, you should not use this feature.
  329 +
  330 +2.2.1.5. `BM_TARBALL_DIRECTORIES'
  331 +---------------------------------
  332 +
  333 + _Type: space-separated list, default: `""'._
  334 +
  335 + You certainly want to backup something, don't you? So here is the
  336 + place where you put that precious list of locations.
  337 +
  338 + Example:
  339 +
  340 + export BM_TARBALL_DIRECTORIES="/etc /home /var/log/apache"
  341 +
  342 +2.2.2. Incremental tarballs
  343 +---------------------------
  344 +
  345 +2.2.2.1. Description
  346 +--------------------
  347 +
  348 + _Method name: `tarball-incremental', configuration key prefix:
  349 + `BM_TARBALLINC'._
  350 +
  351 + If you want to handle tarballs without wasting disk space, you should
  352 + use this method. The concept of this method is simple: You choose a
  353 + frequency when a full backup is made (exactly like the one made by the
  354 + tarball mehod). All the days between two full backups, archives
  355 + contain only the files that have changed from the previous archive.
  356 +
  357 + For instance, let's say you want to backup /home with this method.
  358 + Your /home directory is composed by two sub-directories: /home/foo and
  359 + /home/bar. You choose a weekly frequency and say that monday will be
  360 + the "fullbackup" day. Obviously, you will have a full tarball of
  361 + /home on monday. Then, if a file changed inside /home/foo and if
  362 + /home/bar remains unchanged, tuesday's archive will only contain the
  363 + modified files of /home/foo. Using this method will save a lot of
  364 + disk space.
  365 +
  366 + This method uses all the tarball's configuration keys and adds two
  367 + more. One to define the kind of frequency, the other to choose on
  368 + which day the full backups should be made.
  369 +
  370 +2.2.2.2. `BM_TARBALLINC_MASTERDATETYPE'
  371 +---------------------------------------
  372 +
  373 + _Type: enum(weekly, monthly), default: `weekly'._
  374 +
  375 + This is the type of frequency you want to use. If you choose
  376 + `weekly', you'll have to choose a day number between 1 and 7 for the
  377 + BM_TARBALLINC_MASTERDATEVALUE configuration key, if you choose
  378 + `monthly', the day number will be between 1 and 31.
  379 +
  380 +2.2.2.3. `BM_TARBALLINC_MASTERDATEVALUE'
  381 +----------------------------------------
  382 +
  383 + _Type: integer, default: `1'._
  384 +
  385 + The number of the day when making full backups. Note that its meaning
  386 + directly depends on the `BM_TARBALLINC_MASTERDATETYPE'. For instance,
  387 + 1 means _"monday"_ if you choose a weekly frequency, but it means
  388 + _"the first day of the month"_ if you choose a monthly frequency.
  389 +
  390 +2.2.3. MySQL databases
  391 +----------------------
  392 +
  393 +2.2.3.1. Description
  394 +--------------------
  395 +
  396 + _Method name: `mysql', configuration keys prefix: `BM_MYSQL'._
  397 +
  398 + This method provides a way to archive MySQL databases, the archives
  399 + are made with mysqldump (SQL text files) and can be compressed.
  400 +
  401 +2.2.3.2. `BM_MYSQL_DATABASES'
  402 +-----------------------------
  403 +
  404 + _Type: space-separated list, default: `mysql'._
  405 +
  406 + This is the list of databases you want to archive.
  407 +
  408 + Example:
  409 +
  410 + export BM_MYSQL_DATABASES="mysql mybase wordpress dotclear phpbb2"
  411 +
  412 +2.2.3.3. `BM_MYSQL_ADMINLOGIN'
  413 +------------------------------
  414 +
  415 + _Type: string, default: `root'._
  416 +
  417 + The MySQL login you want to use for connecting to the database. Make
  418 + sure this login can read all the databases you've set in
  419 + `BM_MYSQL_DATABASES'.
  420 +
  421 + Example:
  422 +
  423 + export BM_MYSQL_ADMINLOGIN="root"
  424 +
  425 +2.2.3.4. `BM_MYSQL_HOST'
  426 +------------------------
  427 +
  428 + _Type: string, default: `localhost'._
  429 +
  430 + The database host where the databases are.
  431 +
  432 + Example:
  433 +
  434 + export BM_MYSQL_HOST="localhost"
  435 +
  436 +2.2.3.5. `BM_MYSQL_PORT'
  437 +------------------------
  438 +
  439 + _Type: string, default: `3306'._
  440 +
  441 + The port on `BM_MYSQL_HOST' where the mysql server is listening.
  442 +
  443 + Example:
  444 +
  445 + export BM_MYSQL_PORT="3306"
  446 +
  447 +2.2.3.6. `BM_MYSQL_FILETYPE'
  448 +----------------------------
  449 +
  450 + _Type: enum(gzip, bzip2), default: `bzip2'._
  451 +
  452 + The archive is made with mysqldump which renders SQL lines; the
  453 + resulting text file can be compressed. If you want to compress the
  454 + file, choose the compressor you want. Leave it blank if you want pure
  455 + SQL files.
  456 +
  457 + Example:
  458 +
  459 + export BM_MYSQL_FILETYPE="bzip2"
  460 +
  461 +2.2.4. Subversion repositories
  462 +------------------------------
  463 +
  464 +2.2.4.1. Description
  465 +--------------------
  466 +
  467 + You can archive Subversion repositories with this method. The archive
  468 + will be made with `svnadmin' and will contain XML data (text files).
  469 + Like the mysql method, you can choose to compress it.
  470 +
  471 +2.2.4.2. `BM_SVN_REPOSITORIES'
  472 +------------------------------
  473 +
  474 + _Type: space-separated list_
  475 +
  476 + This is the list of absolute paths to the SVN repositories to archive.
  477 +
  478 + Example:
  479 +
  480 + export BM_SVN_REPOSITORIES="/srv/svnroot/repo1 /srv/svnroot/repo2"
  481 +
  482 +2.2.4.3. `BM_SVN_COMPRESSWITH'
  483 +------------------------------
  484 +
  485 + _Type: enum(gzip, bzip2), default: `bzip2'._
  486 +
  487 + If you want to compress the resulting XML files, choose a compressor
  488 + here. Leave this blank if you don't want any compression.
  489 +
  490 + Example:
  491 +
  492 + export BM_SVN_COMPRESSWITH="gzip"
  493 +
  494 +2.2.5. Generic methods
  495 +----------------------
  496 +
  497 +2.2.5.1. Description
  498 +--------------------
  499 +
  500 + Even if most of the common needs are covered by the existing methods,
  501 + there is always a case uncovered. Backup Manager provides a way for
  502 + backing up anything, and can be used in such circumstances.
  503 +
  504 + This method is called `pipe', it is more complex to use but can
  505 + virtually backup anything. The concept is simple, a pipe method is
  506 + defined by the following items:
  507 +
  508 + * A name (for naming the archive)
  509 +
  510 + * A command (that produces content on stdout)
  511 +
  512 + * A file type (txt, sql, dump, ...)
  513 +
  514 + * A compressor (gzip, bzip2)
  515 +
  516 + Those configuration keys are arrays, so you can implement as many pipe
  517 + methods as you like.
  518 +
  519 + For each pipe method defined, Backup Manager will launch the command
  520 + given and redirect the content sent to stdout by this command to a
  521 + file named with the name of the method and its filetype. Then, if the
  522 + method uses a compressor, the file will be compressed.
  523 +
  524 +2.2.5.2. Example
  525 +----------------
  526 +
  527 + Example for archiving a remote MySQL database through SSH:
  528 +
  529 + BM_PIPE_COMMAND[0]="ssh host -c \"mysqldump -ufoo -pbar base\""
  530 + BM_PIPE_NAME[0]="base"
  531 + BM_PIPE_FILETYPE[0]="sql"
  532 + BM_PIPE_COMPRESS[0]="gzip"
  533 +
  534 + Imagine you have a second pipe method to implement, for instance
  535 + building a tarball trough SSH:
  536 +
  537 + BM_PIPE_COMMAND[1]="ssh host -c \"tar -c -z /home/user\""
  538 + BM_PIPE_NAME[1]="host.home.user"
  539 + BM_PIPE_FILETYPE[1]="tar.gz"
  540 + BM_PIPE_COMPRESS[1]=""
  541 +
  542 + Note that we have incremented the array's index.
  543 +
  544 +
  545 +2.3. Upload Methods
  546 +-------------------
  547 +
  548 +2.3.1. Description
  549 +------------------
  550 +
  551 + _One of the most important thing to do when backing up file systems is
  552 + to store the archives on different places. The more different
  553 + physical spaces you have, the better. Backup Manager provides a way
  554 + for achieving this goal : the upload methods._
  555 +
  556 + There are different upload methods, each of them behaves differently
  557 + and provides particular features. In Backup Manager 0.6 you can use
  558 + FTP, SSH or RSYNC uploads.
  559 +
  560 + In the same manner as for backup methods, you can choose to use as
  561 + many upload methods as you like. If you don't want to use this
  562 + feature at all, just put the keyword `none' in the configuration
  563 + `BM_UPLOAD_METHOD'.
  564 +
  565 + Note that the FTP and SSH methods are dedicated to upload archives,
  566 + using those method depends on the use of at least one backup method.
  567 +
  568 + On the opposite, the RSYNC method uploads a directory to remote
  569 + locations, this directory can be your repository or whatever other
  570 + location of your file sytem.
  571 +
  572 +2.3.2. Global configuration keys
  573 +--------------------------------
  574 +
  575 + The following configuration keys are global in the upload section:
  576 +
  577 +2.3.2.1. `BM_UPLOAD_HOSTS'
  578 +--------------------------
  579 +
  580 + _Type: space-separated list_
  581 +
  582 + Each of the hosts defined in that list is used by all the upload
  583 + methods when establishing connections. For instance if you want to
  584 + perform SSH uploads of your archives and RSYNC upload of a location to
  585 + the same host, put it in this list.
  586 +
  587 + Example:
  588 +
  589 +export BM_UPLOAD_HOSTS="mirror1.lan.mysite.net mirror2.lan.mysite.net"
  590 +
  591 +2.3.2.2. `BM_UPLOAD_DESTINATION'
  592 +--------------------------------
  593 +
  594 + _Type: string_
  595 +
  596 + This is the absolute path of the directory in the remote hosts where
  597 + to put the files uploaded.
  598 +
  599 + If you have installed installed Backup Manager on the remote host, a
  600 + good idea is to choose a sub-directory of the repository. Then,
  601 + during the remote host purge phase, your uploads will be cleaned at
  602 + the same time.
  603 +
  604 + You can also define a destination dedicated to your host:
  605 + `BM_UPLOAD_DESTINATION="/var/archives/$HOSTNAME"'
  606 +
  607 + Example:
  608 +
  609 + Let's say you want that all your uploads are performed on the host
  610 + mirror2.lan.mysite.net, in the sub-directory /var/archives/uploads
  611 +
  612 + export BM_UPLOAD_HOSTS="mirror2.lan.mysite.net"
  613 + export BM_UPLOAD_DESTINATION="/var/archives/uploads"
  614 +
  615 +2.3.3. SSH uploads
  616 +------------------
  617 +
  618 +2.3.3.1. Description
  619 +--------------------
  620 +
  621 + _Method name: `ssh', goal: upload archives to remote hosts over SSH.
  622 + This method depends on a backup method._
  623 +
  624 + If you want to upload your archives on remote locations, you can use
  625 + the SSH method. This method is good if you like to use a secure
  626 + tunnel between the two points of the upload.
  627 +
  628 + The call to `scp' will be done with the identity of the user
  629 + `BM_UPLOAD_SSH_USER', thus, you have to make sure this user can have
  630 + access to the repository (take care to the secure mode).
  631 +
  632 +2.3.3.2. `BM_UPLOAD_SSH_USER'
  633 +-----------------------------
  634 +
  635 + _Type: string_
  636 +
  637 + This is the user to use for performing the ssh connection. Make sure
  638 + this user can access repository.
  639 +
  640 + Example:
  641 +
  642 + export BM_UPLOAD_SSH_USER="bmngr"
  643 +
  644 +2.3.3.3. `BM_UPLOAD_SSH_KEY'
  645 +----------------------------
  646 +
  647 + _Type: string_
  648 +
  649 + This is the path to the private key of the user BM_UPLOAD_SSH_USER.
  650 +
  651 + Example:
  652 +
  653 + export BM_UPLOAD_SSH_KEY="/home/bmngr/.ssh/id_dsa"
  654 +
  655 +2.3.3.4. `BM_UPLOAD_SSH_PORT'
  656 +-----------------------------
  657 +
  658 + _Type: integer_
  659 +
  660 + You may want to connect to remote hosts with a specific port. Use
  661 + this configuration key then.
  662 +
  663 + Example:
  664 +
  665 + export BM_UPLOAD_SSH_PORT="1352"
  666 +
  667 +2.3.3.5. `BM_UPLOAD_SSH_HOSTS'
  668 +------------------------------
  669 +
  670 + _Type: space-separated list_
  671 +
  672 + Put here the list of hosts to use for SSH-only uploads. Note that if
  673 + you put some hosts in `BM_UPLOAD_HOSTS', they will be used as well.
  674 +
  675 + Example:
  676 +
  677 + export BM_UPLOAD_SSH_HOSTS="mirror3.lan.mysite.net"
  678 +
  679 +2.3.3.6. `BM_UPLOAD_SSH_DESTINATION'
  680 +------------------------------------
  681 +
  682 + _Type: string_
  683 +
  684 + Put here the destination for SSH-only uploads, this key overrides
  685 + `BM_UPLOAD_DESTINATION'.
  686 +
  687 + Example:
  688 +
  689 + export BM_UPLOAD_SSH_DESTINATION="/var/archives/scp-uploads"
  690 +
  691 +2.3.4. FTP uploads
  692 +------------------
  693 +
  694 +2.3.4.1. Description
  695 +--------------------
  696 +
  697 + If security does not matter much on your lan (between the two points
  698 + of the upload) you can choose to use the FTP method. One of the main
  699 + pros of this method is that it can perform purging independently. You
  700 + can safely use this method for uploading files to a host where you
  701 + just have an FTP account.
  702 +
  703 +2.3.4.2. `BM_UPLOAD_FTP_USER'
  704 +-----------------------------
  705 +
  706 + _Type: string._
  707 +
  708 + Put here the FTP user to use for opening the connections.
  709 +
  710 + Example:
  711 +
  712 + export BM_UPLOAD_FTP_USER="bmngr"
  713 +
  714 +2.3.4.3. `BM_UPLOAD_FTP_PASSWORD'
  715 +---------------------------------
  716 +
  717 + _Type: string._
  718 +
  719 + Put here the `BM_UPLOAD_FTP_USER''s password to use (in plain text).
  720 +
  721 + Example:
  722 +
  723 + export BM_UPLOAD_FTP_USER="secret"
  724 +
  725 +2.3.4.4. `BM_UPLOAD_FTP_HOSTS'
  726 +------------------------------
  727 +
  728 + _Type: space-separated list_
  729 +
  730 + Put here the list of hosts to use for FTP-only uploads. Note that if
  731 + you put some hosts in `BM_UPLOAD_HOSTS', they will be used as well.
  732 +
  733 + Example:
  734 +
  735 + export BM_UPLOAD_FTP_HOSTS="mirror4.lan.mysite.net"
  736 +
  737 +2.3.4.5. `BM_UPLOAD_FTP_DESTINATION'
  738 +------------------------------------
  739 +
  740 + _Type: string_
  741 +
  742 + Put here the destination for FTP-only uploads, this key overrides
  743 + `BM_UPLOAD_DESTINATION'.
  744 +
  745 + Example:
  746 +
  747 + export BM_UPLOAD_FTP_DESTINATION="/var/archives/ftp-uploads"
  748 +
  749 +2.3.4.6. `BM_UPLOAD_FTP_PURGE'
  750 +------------------------------
  751 +
  752 + _Type: boolean, default: `true'_
  753 +
  754 + You can choose to purge deprecated archives before uploading new ones.
  755 + This purge is done over FTP and uses the configuration key
  756 + `BM_ARCHIVE_TTL' in the same manner as the local purge behaves (the
  757 + FTP purge is not recursive though).
  758 +
  759 + Example:
  760 +
  761 + export BM_UPLOAD_FTP_PURGE="true"
  762 +
  763 +2.3.5. RSYNC uploads
  764 +--------------------
  765 +
  766 +2.3.5.1. Description
  767 +--------------------
  768 +
  769 + You may want to upload some parts of your file system to some remote
  770 + hosts. In these cases, archives are not needed, you just want to
  771 + synchronize some directories to remote places. This is where the
  772 + RSYNC upload method is useful.
  773 +
  774 + RSYNC uploads need a SSH user/key pair to behave correctly, thus there
  775 + is a dependency against the keys `BM_UPLOAD_SSH_USER' and
  776 + `BM_UPLOAD_SSH_KEY'.
  777 +
  778 +2.3.5.2. `BM_UPLOAD_RSYNC_DIRECTORIES'
  779 +--------------------------------------
  780 +
  781 + _Type: space-separated list_
  782 +
  783 + Put here the list of local directories you want to upload with rsync.
  784 +
  785 + Example:
  786 +
  787 +export BM_UPLOAD_RSYNC_DIRECTORIES="/data/photos /data/videos /data/mp3"
  788 +
  789 +2.3.5.3. `BM_UPLOAD_RSYNC_HOSTS'
  790 +--------------------------------
  791 +
  792 + _Type: space-separated list_
  793 +
  794 + Put here the list of hosts to use for RSYNC-only uploads. Note that
  795 + if you put some hosts in `BM_UPLOAD_HOSTS', they will be used as well.
  796 +
  797 + Example:
  798 +
  799 + export BM_UPLOAD_RSYNC_HOSTS="mirror5.lan.mysite.net"
  800 +
  801 +2.3.5.4. `BM_UPLOAD_RSYNC_DESTINATION'
  802 +--------------------------------------
  803 +
  804 + _Type: string_
  805 +
  806 + Put here the destination for RSYNC-only uploads, this key overrides
  807 + `BM_UPLOAD_DESTINATION'.
  808 +
  809 + Example:
  810 +
  811 + export BM_UPLOAD_RSYNC_DESTINATION="/var/archives/rsync-snapshots"
  812 +
  813 +2.3.5.5. `BM_UPLOAD_RSYNC_DUMPSYMLINKS'
  814 +---------------------------------------
  815 +
  816 + _Type: boolean, default: `false'._
  817 +
  818 + You can choose to dereference files pointed by symlinks in your RSYNC
  819 + snapshots. This feature should be used with care.
  820 +
  821 + Example:
  822 +
  823 + export BM_UPLOAD_RSYNC_DUMPSYMLINKS="false"
  824 +
  825 +
  826 +2.4. Exports
  827 +------------
  828 +
  829 + _Another way of storing your archives to a safe place is to use
  830 + external media._
  831 +
  832 + In version 0.6, only CDs and DVDs are supported as external media, so
  833 + we will discuss in this section only the `BM_BURNING' features. Other
  834 + exports are expected to come in next versions though.
  835 +
  836 +2.4.1. Burning CDR/DVD media
  837 +----------------------------
  838 +
  839 + In the version 0.6, Backup Manager supports three different kinds of
  840 + media: CDR, CDRW and DVDR.
  841 +
  842 +2.4.1.1. `BM_BURNING_METHOD'
  843 +----------------------------
  844 +
  845 + Set the key `BM_BURNING_METHOD' to the method corresponding to the
  846 + media you want to burn:
  847 +
  848 + * CDR
  849 +
  850 + * CDRW
  851 +
  852 + * DVD
  853 +
  854 + Any of these methods will try to put the whole archive repository in
  855 + the media, if it does not fit in the media, it will try to put only
  856 + the archives built on the day, if that's not possible, nothing will be
  857 + burned.
  858 +
  859 + The CDRW and DVD methods will first blank the media, so you can safely
  860 + use these methods if you want to use the same media several times.
  861 +
  862 + As usual, you can put `none' in order to disable the burning process.
  863 +
  864 + All those burning methods share the same configuration keys, so it's
  865 + easy to switch from a medium to another.
  866 +
  867 +2.4.1.2. `BM_BURNING_DEVICE'
  868 +----------------------------
  869 +
  870 + _Type: string, default: `/dev/cdrom'._
  871 +
  872 + This is mandatory for using the burning feature, it's the device to
  873 + use for mounting the media. It's needed by backup manager for
  874 + performing the MD5 checks and for other needs.
  875 +
  876 + Example:
  877 +
  878 + export BM_BURNING_DEVICE="/dev/cdrom"
  879 +
  880 +2.4.1.3. `BM_BURNING_DEVFORCED'
  881 +-------------------------------
  882 +
  883 + _Type: string_
  884 +
  885 + Backup Manager uses `cdrecord' for burning CDs. If when you run
  886 + `cdrecord -scanbus' you don't see your burning device, that means you
  887 + will have to force the device in ATA mode. To tell Backup Manager to
  888 + do so, just put here the path to your device, and a switch will be
  889 + appended to the cdrecord commandline like the following : `cdrecrord
  890 + ... dev=$BM_BURNING_DEVFORCED ...'.
  891 +
  892 + Leave this configuration key blank if you see your device with
  893 + `cdrecord -scanbus', in this case, Backup Manager will use the default
  894 + cdrecord device for burning CDR media.
  895 +
  896 + Example:
  897 +
  898 + export BM_BURNING_DEVFORCED="/dev/cdrom"
  899 +
  900 +2.4.1.4. `BM_BURNING_MAXSIZE'
  901 +-----------------------------
  902 +
  903 + _Type: integer, default: `700'._
  904 +
  905 + This is where you define the maximum size (in megabytes) of the media
  906 + you will put in the device. Here is the list of the common sizes:
  907 +
  908 + * CDR/CDRW: 650, 700, 800
  909 +
  910 + * DVD: 4200
  911 +
  912 + When Backup Manager looks in the repository for burning data, it will
  913 + try to put the whole archive repository in the media. If the
  914 + summarized size of the repository does not fit in
  915 + `BM_BURNING_MAXSIZE', Backup Manager will then try to put only the
  916 + archives of the day.
  917 +
  918 + Example for a CD burner
  919 +
  920 + export BM_BURNING_METHOD="CDRW"
  921 + export BM_BURNING_MAXSIZE="700"
  922 +
  923 + Example for a DVD burner:
  924 +
  925 + export BM_BURNING_METHOD="DVD"
  926 + export BM_BURNING_MAXSIZE="4200"
  927 +
  928 +2.4.1.5. `BM_BURNING_CHKMD5'
  929 +----------------------------
  930 +
  931 + _Type: boolean, default: `true'._
  932 +
  933 + If this boolean is set to a true value, every MD5 sum will be checked
  934 + when the media is burned in order to make sure everything is ok.
  935 +
  936 + Note that you can choose to perform this checkup with the command
  937 + switch `--md5check'.
  938 +
  939 + Example:
  940 +
  941 + exports BM_BURNING_CHKMD5="true"
  942 +
  943 +
  944 +2.5. Advanced features
  945 +----------------------
  946 +
  947 + _A couple of advanced features are provided, they will be covered in
  948 + this section._
  949 +
  950 +2.5.1. Logging to syslog
  951 +------------------------
  952 +
  953 + If you want to log Backup Manager actions to syslog, you can enable
  954 + the internal logger, this is done with the configuration key
  955 + `BM_LOGGER'. You are also able to choose which syslog facility to use
  956 + thanks to the key `BM_LOGGER_FACILITY'.
  957 +
  958 +2.5.1.1. `BM_LOGGER'
  959 +--------------------
  960 +
  961 + _Type: boolean, default: `true'._
  962 +
  963 + If this boolean is set to true, Backup Manager will log everything to
  964 + syslog.
  965 +
  966 + Example:
  967 +
  968 + exports BM_LOGGER="true"
  969 +
  970 +2.5.1.2. `BM_LOGGER_FACILITY'
  971 +-----------------------------
  972 +
  973 + _Type: string, default: `user'._
  974 +
  975 + You can specify here a syslog facility to use, this can be useful if
  976 + you like to filter messages from Backup Manager to a special syslog
  977 + file.
  978 +
  979 + Example:
  980 +
  981 + exports BM_LOGGER_FACILITY="cron"
  982 +
  983 +2.5.2. Writing external hooks
  984 +-----------------------------
  985 +
  986 + You have the availability to write your own hooks if you want to
  987 + automate some special beaviours within the Backup Manager process.
  988 + You may like to mount over NFS your archive repository _before_ the
  989 + backup session and unmount it after, or you may like to launch your
  990 + own uploader script when the backup session is finished.
  991 +
  992 + In order to let you implement any solution you like, Backup Manager
  993 + provides two different hooks: the _pre-command_ and _post-command_
  994 + hooks.
  995 +
  996 +2.5.2.1. `BM_PRE_BACKUP_COMMAND'
  997 +--------------------------------
  998 +
  999 + _Type: string_
  1000 +
  1001 + Put here the path to a program (or a shell command) to launch before
  1002 + the backup session. If the command fails (exits with non zero value,
  1003 + or prints the keyword `false' on stdout) the backup session will stop.
  1004 + If the pre-command succeeds, the process can follow.
  1005 +
  1006 + Example with a basic shell command:
  1007 +
  1008 +export BM_PRE_BACKUP_COMMAND="mount -t nfs mirror.lan.net:/exports/backups /var/archives"
  1009 +
  1010 + Example with a custom script:
  1011 +
  1012 +export BM_PRE_BACKUP_COMMAND="/usr/local/bin/backup-prepare.pl $TODAY"
  1013 +
  1014 +2.5.2.2. `BM_POST_BACKUP_COMMAND'
  1015 +---------------------------------
  1016 +
  1017 + _Type: string_
  1018 +
  1019 + Put here the path to a program (or a shell command) to launch after
  1020 + the backup session. If the command fails (exits with non zero value,
  1021 + or prints the keyword `false' on stdout) Backup Manager will exit with
  1022 + an error code (and will log to syslog the post-command failure if the
  1023 + logger is enabled).
  1024 +
  1025 + Example with a basic shell command:
  1026 +
  1027 + export BM_PRE_BACKUP_COMMAND="umount /var/archives"
  1028 +
  1029 + Example with a custom script:
  1030 +
  1031 +export BM_PRE_BACKUP_COMMAND="/usr/local/bin/backup-cleanup.pl $TODAY"
  1032 +
  1033 +
  1034 +-------------------------------------------------------------------------------
  1035 +
  1036 +
  1037 +3. Using Backup Manager
  1038 +-----------------------
  1039 +
  1040 + _Now that you know in details how to write your configuration files,
  1041 + let's see how to use Backup Manager._
  1042 +
  1043 +
  1044 +3.1. Command line
  1045 +-----------------
  1046 +
  1047 +3.1.1. Restrictions
  1048 +-------------------
  1049 +
  1050 + In version 0.6, Backup Manager can only be used by `root', as it has
  1051 + be designed as a systemwide tool.
  1052 +
  1053 + $ backup-manager
  1054 + backup-manager must be run as root.
  1055 +
  1056 + If you want to launch it from the command line, you first have to use
  1057 + the `root' account.
  1058 +
  1059 + $ su
  1060 + Password:
  1061 + # backup-manager -h
  1062 + /usr/sbin/backup-manager [options]
  1063 +
  1064 + Output:
  1065 + --help|-h : Print this short help message.
  1066 + --verbose|-v : Print what happens on STDOUT.
  1067 + --no-warnings : Disable warnings.
  1068 +
  1069 + Single actions:
  1070 + --upload|-u : Just upload the files of the day.
  1071 + --burn|-b : Just burn the files of the day.
  1072 + --md5check|-m : Just test the md5 sums.
  1073 + --purge|-p : Just purge old archives.
  1074 +
  1075 + Behaviour:
  1076 + --conffile|-c file : Choose an alternate config file.
  1077 + --force|-f : Force overwrite of existing archives.
  1078 +
  1079 + Unwanted actions:
  1080 + --no-upload : Disable the upload process.
  1081 + --no-burn : Disable the burning process.
  1082 + --no-purge : Disable the purge process.
  1083 + ouranos:/home/sukria#
  1084 +
  1085 + As you can see in the example above, using the `-h' switch (or
  1086 + `--help') gives a short help message and prints all supported command
  1087 + switches. We will cover in this section each of them.
  1088 +
  1089 +3.1.2. Options
  1090 +--------------
  1091 +
  1092 + The following switches can be used for altering Backup Manager's
  1093 + behaviour.
  1094 +
  1095 +3.1.2.1. `--version'
  1096 +--------------------
  1097 +
  1098 + Prints on stdout the Backup Manager version installed on the system
  1099 + and exit.
  1100 +
  1101 + Example:
  1102 +
  1103 + # backup-manager --version
  1104 + Backup Manager 0.6
  1105 +
  1106 +3.1.2.2. `--verbose' or `-v'
  1107 +----------------------------
  1108 +
  1109 + Using this switch will enabled the verbose mode. All actions are
  1110 + reported on stdout.
  1111 +
  1112 + Example:
  1113 +
  1114 +# backup-manager -v
  1115 +Getting lock for backup-manager 10605 with /etc/backup-manager.conf: ok
  1116 +Cleaning /var/archives
  1117 +Entering directory /var/archives/lost+found.
  1118 +[...]
  1119 +
  1120 +3.1.2.3. `--no-warnings'
  1121 +------------------------
  1122 +
  1123 + When a non-critical problem occurs (an error occured but the backup
  1124 + process can follow) Backup Manager will print a warning message (and
  1125 + will log it if the logger is enabled). If you don't want to see
  1126 + warning messages, you can append this switch on the command line.
  1127 +
  1128 +3.1.2.4. `--conffile' or `-c'
  1129 +-----------------------------
  1130 +
  1131 + Backup Manager relies on configuration files, by default, the file
  1132 + `/etc/backup-manager.conf' is used but you can choose to run it with a
  1133 + different one. This is done by using the following syntax :
  1134 +
  1135 + # backup-manager -c <FILE>
  1136 +
  1137