Add Flattr button to HTML README output

[software/bacap.git] / README

diff --git a/README b/README
index c15200c97064fada6d8602b799e3590df8c3147b..1fa86b1ce2f202b2693c2977a92eb3a433bf4b0a 100644 (file)
--- a/README
+++ b/README
@@ -1,6 +1,13 @@
 .. -*- restructuredtext -*-
 
 
+.. raw:: html
+
+   <div style="width: 220px; height: 270px; float: right; margin-left: 1em; margin-top: 1em">
+   <iframe width="220" height="270" style="border: none; outline: none" src="http://tools.flattr.net/widgets/thing.html?thing=1141801"></iframe>
+   </div>
+
+
 ==========================================
 Bacap - The extremely simple backup script
 ==========================================
@@ -35,8 +42,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
@@ -97,7 +104,7 @@ configuration file)::
 
        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``::
 
@@ -110,7 +117,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
-       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
@@ -120,20 +127,13 @@ backup rata's home::
 
        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.
 
-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
@@ -154,6 +154,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
 ====================