From 03766af1d1aac147bab8a3bab614e84abad57699 Mon Sep 17 00:00:00 2001 From: Nico Schottelius Date: Sun, 22 Jan 2006 13:27:12 +0100 Subject: [PATCH] Updated documentation --- doc/CHANGES | 2 + doc/ccollect.html | 114 +++++++++++++++++++++++++++++++++++++++------- doc/ccollect.text | 59 +++++++++++++++++++----- 3 files changed, 147 insertions(+), 28 deletions(-) diff --git a/doc/CHANGES b/doc/CHANGES index c8dc09b..5802e09 100644 --- a/doc/CHANGES +++ b/doc/CHANGES @@ -1,6 +1,8 @@ 0.2 to 0.3: * added "very_verbose" * normal "verbose" is now less verbose + * added general 'pre_exec' and 'post_exec' support + * added source specfifc 'pre_exec' and 'post_exec' support 0.1 to 0.2: * Added plausibility check diff --git a/doc/ccollect.html b/doc/ccollect.html index 43bba87..3354076 100644 --- a/doc/ccollect.html +++ b/doc/ccollect.html @@ -262,8 +262,8 @@ div.exampleblock-content {

ccollect - Installing, Configuring and Using

Nico Schottelius
<nico-linux-ccollect__@__schottelius.org>
-version 0.2.2, -for ccollect 0.2, Initial Version from 2005-01-13 +version 0.3.0, +for ccollect 0.3, Initial Version from 2005-01-13
@@ -276,7 +276,7 @@ using hardlinks and rsync

ccollect is a backup utitily written in the sh-scripting language. It does not depend on a specific shell, only /bin/sh needs to be -bourne shell compatibel (like dash, zsh or bash).

+bourne shell compatibel (like dash, ksh, zsh, bash, …).

1.1. Why you can only backup TO localhost

While thinking about the design of ccollect, I thought about enabling backup to remote hosts. Though this sounds like a nice feature @@ -296,10 +296,24 @@ All other backups are still secure.

2. Requirements

2.1. Installing ccollect

-

For the installation, you need at least - - either cp and chmod or install - - for more comfort: 'make - - for rebuilding the generated documentation: additionally asciidoc

+

For the installation, you need at least

+
    +
  • +

    +either cp and chmod or install +

    +
    • +
  • +

    +for more comfort: make +

    +
    • +
  • +

    +for rebuilding the generated documentation: additionally asciidoc +

    +
    • +

2.2. Using ccollect

Running ccollect requires the following tools installed:
  • @@ -368,6 +382,23 @@ This number defines how many versions of this intervall to keep.

    4

This means to keep 28 daily backups, 12 monthly backups and 4 weekly.

+

4.2.2. General pre- and post-execution

+

If you add $CCOLLECT_CONF/defaults/pre_exec or +/etc/ccollect/defaults/pre_exec (same with post_exec), ccollect +will start pre_exec before the whole backup process and +post_exec after backup of all sources is done.

+

Example:

+
+
+
[13:00] hydrogenium:~# mkdir -p /etc/ccollect/defaults/
+[13:00] hydrogenium:~# echo '!/bin/sh' > /etc/ccollect/defaults/pre_exec
+[13:01] hydrogenium:~# echo '' > /etc/ccollect/defaults/pre_exec
+[13:01] hydrogenium:~# echo '!/bin/sh' > /etc/ccollect/defaults/pre_exec
+[13:01] hydrogenium:~# echo '' >> /etc/ccollect/defaults/pre_exec
+[13:01] hydrogenium:~# echo 'df -h' >> /etc/ccollect/defaults/pre_exec
+[13:01] hydrogenium:~# chmod 0755 /etc/ccollect/defaults/pre_exec
+[13:01] hydrogenium:~# cp /etc/ccollect/defaults/pre_exec /etc/ccollect/defaults/post_exec
+

4.3. Source configuration

Each source configuration exists below $CCOLLECT_CONF/sources/$name or /etc/ccollect/sources/$name.

@@ -376,7 +407,7 @@ This number defines how many versions of this intervall to keep.

  • -source (a text file containing the rsync compatible path to backup) +source (a text file containing the rsync compatible path to backup)

  • @@ -389,22 +420,32 @@ This number defines how many versions of this intervall to keep.

    • -verbose whether to be verbose (passes -v to rsync) +verbose whether to be verbose (passes -v to rsync)

    • -very_verbose be very verbose (-v also for mkdir, cp, rm) +very_verbose be very verbose (-v also for mkdir, cp, rm)

    • -exclude exclude list for rsync. \\n seperated list. +exclude exclude list for rsync. newline (\n) seperated list.

    • -`rsync_options' extra options to pass to rsync +rsync_options' extra options to pass to `rsync +

      +
      • +
    • +

      +pre_exec program to execute before backuping this source +

      +
      • +
    • +

      +post_exec program to execute after backuping this source

    @@ -430,10 +471,10 @@ This number defines how many versions of this intervall to keep.

    /home/nico/vpn

4.3.1. Detailled description of "source"

-

source describes a rsync compatible source (one line only).

+

source describes a rsync compatible source (one line only).

For instance backup_user@foreign_host:/home/server/video. -To use the rsync protocol without the ssh-tunnel, use -rsync::USER@HOST/SRC. For more information have a look at rsync(1).

+To use the rsync protocol without the ssh-tunnel, use +rsync::USER@HOST/SRC. For more information have a look at rsync(1).

4.3.2. Detailled description of "verbose"

verbose tells ccollect that the log should contain verbose messages.

If this file exists in the source specification -v will be passed to rsync.

@@ -498,6 +539,26 @@ to use for automatic backup over the rsync-protocol.

   [23:42] hydrogenium:ccollect-0.2% cat conf/sources/test_rsync/rsync_options
    --password-file=/home/user/backup/protected_password_file
+

4.3.8. Detailled description of "pre_exec" and "post_exec"

+

When you create pre_exec and / or post_exec below your source +configuration, ccollect will execute this command before, +respective after doing the backup for this specific source. +If you want to have pre-/post-exec before and after all +backups, see above for general configuration.

+

Example:

+
+
+
[13:09] hydrogenium:ccollect-0.3% cat conf/sources/with_exec/pre_exec
+#!/bin/sh
+
+# Show whats free before
+df -h
+[13:09] hydrogenium:ccollect-0.3% cat conf/sources/with_exec/post_exec
+#!/bin/sh
+
+# Show whats free after
+df -h
+

5. Hints

@@ -574,6 +635,22 @@ waste resources, but your backup will be complete.

+

5.4. Using pre_/post_exec

+

Your pre_/post_exec script does not need to be a script, you can also +use a link to

+ +

The only requirement is that it is executable.

6. F.A.Q.

@@ -588,6 +665,9 @@ comes from local harddisk or from a remote server. And it does not want to. When you backup from the local harddisk (which is perhaps not even a good idea when thinking of security) add the destination to source/exclude. (Daniel Aubry reported this problem)

+

6.3. Why does ccollect say "Permission denied" with my pre-/postexec script?

+

The most common error is to not give your script the correct +permissions. Try chmod 0755 /etc/ccollect/sources/yoursource/*_exec.

7. Examples

@@ -668,8 +748,8 @@ srwali01:/etc/ccollect/sources# du -sh /mnt/hdbackup/wl6/*
diff --git a/doc/ccollect.text b/doc/ccollect.text index 888f1e2..718338c 100644 --- a/doc/ccollect.text +++ b/doc/ccollect.text @@ -1,7 +1,7 @@ ccollect - Installing, Configuring and Using ============================================ Nico Schottelius -0.2.2, for ccollect 0.2, Initial Version from 2005-01-13 +0.3.0, for ccollect 0.3, Initial Version from 2005-01-13 :Author Initials: NS (pseudo) incremental backup @@ -12,7 +12,7 @@ Introduction ------------ ccollect is a backup utitily written in the sh-scripting language. It does not depend on a specific shell, only `/bin/sh` needs to be -bourne shell compatibel (like 'dash', 'zsh' or 'bash'). +bourne shell compatibel (like 'dash', 'ksh', 'zsh', 'bash', ...). Why you can only backup TO localhost @@ -40,9 +40,10 @@ Installing ccollect ~~~~~~~~~~~~~~~~~~~ For the installation, you need at least - - either 'cp' and 'chmod' or 'install - - for more comfort: 'make' - - for rebuilding the generated documentation: additionally 'asciidoc' + + - either `cp` and `chmod` or `install` + - for more comfort: `make` + - for rebuilding the generated documentation: additionally `asciidoc` Using ccollect @@ -149,9 +150,12 @@ Additionally a source may have the following files: - `verbose` whether to be verbose (passes -v to `rsync`) - `very_verbose` be very verbose (-v also for `mkdir`, `cp`, `rm`) - - `exclude` exclude list for `rsync`. '\\n' seperated list. + - `exclude` exclude list for `rsync`. newline ('\n') seperated list. - `rsync_options' extra options to pass to `rsync` + - `pre_exec` program to execute before backuping this source + - `post_exec` program to execute after backuping this source + Example: -------------------------------------------------------------------------------- [10:47] zaphodbeeblebrox:ccollect-0.2% ls -l conf/sources/testsource2 @@ -263,6 +267,28 @@ Example: --password-file=/home/user/backup/protected_password_file -------------------------------------------------------------------------------- +Detailled description of "pre_exec" and "post_exec" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When you create `pre_exec` and / or `post_exec` below your source +configuration, `ccollect` will execute this command before, +respective after doing the backup for *this specific* source. +If you want to have pre-/post-exec before and after *all* +backups, see above for general configuration. + +Example: +-------------------------------------------------------------------------------- +[13:09] hydrogenium:ccollect-0.3% cat conf/sources/with_exec/pre_exec +#!/bin/sh + +# Show whats free before +df -h +[13:09] hydrogenium:ccollect-0.3% cat conf/sources/with_exec/post_exec +#!/bin/sh + +# Show whats free after +df -h +-------------------------------------------------------------------------------- Hints ----- @@ -343,6 +369,16 @@ waste resources, but your backup will be complete. =============================================================================== +Using pre_/post_exec +~~~~~~~~~~~~~~~~~~~~ +Your pre_/post_exec script does not need to be a script, you can also +use a link to + + - an existing program + - an already written script + +The only requirement is that it is executable. + F.A.Q. ------ @@ -366,6 +402,12 @@ even a good idea when thinking of security) add the `destination` to 'source/exclude'. (Daniel Aubry reported this problem) +Why does ccollect say "Permission denied" with my pre-/postexec script? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The most common error is to not give your script the correct +permissions. Try `chmod 0755 '/etc/ccollect/sources/yoursource/*_exec'`. + + Examples -------- @@ -446,8 +488,3 @@ srwali01:/etc/ccollect/sources# du -sh /mnt/hdbackup/wl6/* 147M /mnt/hdbackup/wl6/taeglich.2005-12-08-14:42.312 147M /mnt/hdbackup/wl6/taeglich.2005-12-08-14:45.588 ------------------------------------------------------------------------- - - -pre/postexec: only when executable! -pre/postexec: link, script or executable -