Fail if the BACKUP_DIR doesn't exist

[software/bacap.git] / README

diff --git a/README b/README
index 878f3dd592f7a2bc6a5f05cff7bc37a6def9abdb..7b8f0dd48b8520e0afa1ba42de37096051e881c6 100644 (file)
--- a/README
+++ b/README
@@ -35,8 +35,8 @@ remember: **It's very simple** =)
 
 
 
 
 
 

-Instalation
-===========
+Installation
+============

 
 Doing something very complex in ~100 SLOC_ is not easy, unless you're standing
 in the shoulders of giants. I'm standing in the shoulders of rsync_ mainly, so
 
 Doing something very complex in ~100 SLOC_ is not easy, unless you're standing
 in the shoulders of giants. I'm standing in the shoulders of rsync_ mainly, so


@@ -70,13 +70,19 @@ file. Configuration files are searched in this places:
 1. ``/etc/bacaprc``
 2. ``/etc/bacap/bacaprc``
 3. ``bacaprc`` in the same directory as the ``bacap`` script
 1. ``/etc/bacaprc``
 2. ``/etc/bacap/bacaprc``
 3. ``bacaprc`` in the same directory as the ``bacap`` script

+4. Optional parameter passed as argument to the script
+5. ``$CONFIG_PATH/$HOST/bacaprc``

 
 Order is important, since all files are read (if possible) and values in the
 last configuration file read overwrites old values. The script takes an optional
 
 Order is important, since all files are read (if possible) and values in the
 last configuration file read overwrites old values. The script takes an optional

-parameter, which is another location to look for a configuration file. The
-configuration file passed as argument will be read last, and an error will be
-printed if can't be found (no error is issued if any of the other configuration
-files are missing).
+parameter, which is another location to look for a configuration file. If the
+configuration file passed as argument can't be found, an error will be printed
+(no error is issued if any of the other configuration files are missing).
+Also, config options could be specified on a per host basis by creating a
+``bacaprc`` file in ``$CONFIG_PATH/$HOST``. As a side effect of this,
+configuration file(s) are read initially and each time the script backups a new
+host. So the configuration file(s) are read at least two times even if you
+backup one host.

 
 The configuration file is a Bash_ script too, and these are the default values:
 
 
 The configuration file is a Bash_ script too, and these are the default values:
 


@@ -91,7 +97,7 @@ configuration file)::
 
        mkdir -p $CONFIG_PATH
 
 
        mkdir -p $CONFIG_PATH
 

-The create a directory for each host you want to backup there, the directory
+Then create a directory for each host you want to backup there, the directory

 name should be the name of the host (as you would use to connect to it using
 ssh_). For now let's say we will only backup ``localhost``::
 
 name should be the name of the host (as you would use to connect to it using
 ssh_). For now let's say we will only backup ``localhost``::
 


@@ -104,7 +110,7 @@ line for each path to backup in that host. Let's say we want to backup only
 ``/etc`` and ``/home``::
 
        echo /etc > $CONFIG_PATH/$LOCALHOST/paths
 ``/etc`` and ``/home``::
 
        echo /etc > $CONFIG_PATH/$LOCALHOST/paths

-       echo /home > $CONFIG_PATH/$LOCALHOST/paths
+       echo /home >> $CONFIG_PATH/$LOCALHOST/paths

 
 But sometimes there are things there that you don't want to backup, in that
 case you can create a file named ``excludes`` too, and write which paths you
 
 But sometimes there are things there that you don't want to backup, in that
 case you can create a file named ``excludes`` too, and write which paths you


@@ -114,20 +120,13 @@ backup rata's home::
 
        echo /home/rata/ > $CONFIG_PATH/$LOCALHOST/excludes
 
 
        echo /home/rata/ > $CONFIG_PATH/$LOCALHOST/excludes
 

+Also, if you don't want to exclude files matching some pattern, you can create
+a file named ``includes`` with the patterns you want to include (you can use
+anything supported by the ``--include-from`` rsync_ option)
+

 That's pretty much it. If you want to add other hosts, just create the host
 directory and the needed host configuration files.
 
 That's pretty much it. If you want to add other hosts, just create the host
 directory and the needed host configuration files.
 

-You may want to automate it using *cron*. I will not include a *cron* tutorial
-here, but if you are completely lost, you can add this line to ``/etc/crontab``
-to make a daily backup at 6:30::
-
-       25 6 * * * root /path/to/bacap
-
-If you are a Debian_ user, you can also simply install the script in
-``/etc/cron.daily`` (or make a symlink or something similar) and you are set.
-
-.. _Debian: http://www.debian.org/
-

 
 
 Usage
 
 
 Usage


@@ -148,6 +147,72 @@ A symbolic link is created at the end of the backup, with the name
 
 
 
 
 
 

+Tips
+====
+
+Here are a few tips on how to configure Bacap_ for several common scenarios.
+
+Automating backups using cron
+-----------------------------
+
+You probably want to automate your backup using *cron*. I will not include
+a *cron* tutorial here, but if you are completely lost, you can add this line to
+``/etc/crontab`` to make a daily backup at 6:30::
+
+       30 6 * * * root /path/to/bacap
+
+If you are a Debian_ user, you can also simply install the script in
+``/etc/cron.daily`` (or make a symlink or something similar) and you are set.
+
+.. _Debian: http://www.debian.org/
+
+
+Providing a ssh_ key
+--------------------
+
+When doing a backup of a remote host, you probably want ssh_ to be able to
+login without providing a password. To do so, you can generate a ssh_ key using
+``ssh-keygen``, copy the public key to the target's
+``/root/.ssh/authorized_keys`` using ``ssh-copy-id root@host`` (or the user
+that runs the backup) and set the Bacap_ configuration variable ``RSYNC_RSH``
+to something like::
+
+       RSYNC_RSH="ssh -i /path/to/priv-key -o NumberOfPasswordPrompts=0"
+
+The ``-o NumberOfPasswordPrompts=0`` is not necessary, but you would appreciate
+it if something is wrong with your key, since if you don't use it, rsync_ will
+hang asking for a password.
+
+Also, you may consider using ``StrictHostKeyChecking=no`` ssh option if you
+backup hosts with dynamic IP address.
+
+
+Backup local networks nodes (or nodes with a fast connection)
+-------------------------------------------------------------
+
+When the bandwidth is not tight, you probably want to ensure ssh_ doesn't use
+compression::
+
+       RSYNC_RSH="ssh -o Compression=no"
+
+And if your network is trusted, you probably don't need very strong encryption
+either::
+
+       RSYNC_RSH="ssh -o Compression=no -c arcfour"
+
+
+Listing differences between 2 snapshots
+---------------------------------------
+
+If you want to see what have actually changed between two backups you can run
+rsync_ with your usual flags plus ``-nv --delete``. For example if you just use
+``-a``, to see the differences between ``lolaus/2010-07-11`` and
+``lolaus/2010-07-12`` you can run::
+
+        rsync -nav --delete lolaus/2010-07-11/ lolaus/2010-07-12/
+
+
+

 Similar alternatives
 ====================
 
 Similar alternatives
 ====================