Updated documentation

This commit is contained in:
Nico Schottelius 2006-01-22 13:27:12 +01:00
parent aa49fcfed4
commit 03766af1d1
3 changed files with 147 additions and 28 deletions

View file

@ -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

View file

@ -262,8 +262,8 @@ div.exampleblock-content {
<h1>ccollect - Installing, Configuring and Using</h1>
<span id="author">Nico Schottelius</span><br />
<span id="email"><tt>&lt;<a href="mailto:nico-linux-ccollect__@__schottelius.org">nico-linux-ccollect__@__schottelius.org</a>&gt;</tt></span><br />
<span id="revision">version 0.2.2,</span>
for ccollect 0.2, Initial Version from 2005-01-13
<span id="revision">version 0.3.0,</span>
for ccollect 0.3, Initial Version from 2005-01-13
</div>
<div id="preamble">
<div class="sectionbody">
@ -276,7 +276,7 @@ using hardlinks and <tt>rsync</tt></p>
<div class="sectionbody">
<p>ccollect is a backup utitily written in the sh-scripting language.
It does not depend on a specific shell, only <tt>/bin/sh</tt> needs to be
bourne shell compatibel (like <em>dash</em>, <em>zsh</em> or <em>bash</em>).</p>
bourne shell compatibel (like <em>dash</em>, <em>ksh</em>, <em>zsh</em>, <em>bash</em>, &#8230;).</p>
<h3>1.1. Why you can only backup TO localhost</h3>
<p>While thinking about the design of ccollect, I thought about enabling
backup to <strong>remote</strong> hosts. Though this sounds like a nice feature
@ -296,10 +296,24 @@ All other backups are still secure.</p>
<h2>2. Requirements</h2>
<div class="sectionbody">
<h3>2.1. Installing ccollect</h3>
<p>For the installation, you need at least
- either <em>cp</em> and <em>chmod</em> or <em>install
- for more comfort: 'make</em>
- for rebuilding the generated documentation: additionally <em>asciidoc</em></p>
<p>For the installation, you need at least</p>
<ul>
<li>
<p>
either <tt>cp</tt> and <tt>chmod</tt> or <tt>install</tt>
</p>
</li>
<li>
<p>
for more comfort: <tt>make</tt>
</p>
</li>
<li>
<p>
for rebuilding the generated documentation: additionally <tt>asciidoc</tt>
</p>
</li>
</ul>
<h3>2.2. Using ccollect</h3>
<div class="title">Running ccollect requires the following tools installed:</div><ul>
<li>
@ -368,6 +382,23 @@ This number defines how many versions of this intervall to keep.</p>
4</tt></pre>
</div></div>
<p>This means to keep 28 daily backups, 12 monthly backups and 4 weekly.</p>
<h4>4.2.2. General pre- and post-execution</h4>
<p>If you add <em>$CCOLLECT_CONF/defaults/<tt>pre_exec</tt></em> or
<em>/etc/ccollect/defaults/<tt>pre_exec</tt></em> (same with <tt>post_exec</tt>), <tt>ccollect</tt>
will start <tt>pre_exec</tt> before the whole backup process and
<tt>post_exec</tt> after backup of all sources is done.</p>
<p>Example:</p>
<div class="listingblock">
<div class="content">
<pre><tt>[13:00] hydrogenium:~# mkdir -p /etc/ccollect/defaults/
[13:00] hydrogenium:~# echo '!/bin/sh' &gt; /etc/ccollect/defaults/pre_exec
[13:01] hydrogenium:~# echo '' &gt; /etc/ccollect/defaults/pre_exec
[13:01] hydrogenium:~# echo '!/bin/sh' &gt; /etc/ccollect/defaults/pre_exec
[13:01] hydrogenium:~# echo '' &gt;&gt; /etc/ccollect/defaults/pre_exec
[13:01] hydrogenium:~# echo 'df -h' &gt;&gt; /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</tt></pre>
</div></div>
<h3>4.3. Source configuration</h3>
<p>Each source configuration exists below <em>$CCOLLECT_CONF/sources/$name</em> or
<em>/etc/ccollect/sources/$name</em>.</p>
@ -376,7 +407,7 @@ This number defines how many versions of this intervall to keep.</p>
<ul>
<li>
<p>
<tt>source</tt> (a text file containing the rsync compatible path to backup)
<tt>source</tt> (a text file containing the <tt>rsync</tt> compatible path to backup)
</p>
</li>
<li>
@ -389,22 +420,32 @@ This number defines how many versions of this intervall to keep.</p>
<ul>
<li>
<p>
<tt>verbose</tt> whether to be verbose (passes -v to rsync)
<tt>verbose</tt> whether to be verbose (passes -v to <tt>rsync</tt>)
</p>
</li>
<li>
<p>
<tt>very_verbose</tt> be very verbose (-v also for mkdir, cp, rm)
<tt>very_verbose</tt> be very verbose (-v also for <tt>mkdir</tt>, <tt>cp</tt>, <tt>rm</tt>)
</p>
</li>
<li>
<p>
<tt>exclude</tt> exclude list for rsync. <em>\\n</em> seperated list.
<tt>exclude</tt> exclude list for <tt>rsync</tt>. newline (<em>\n</em>) seperated list.
</p>
</li>
<li>
<p>
`rsync_options' extra options to pass to rsync
<tt>rsync_options' extra options to pass to `rsync</tt>
</p>
</li>
<li>
<p>
<tt>pre_exec</tt> program to execute before backuping this source
</p>
</li>
<li>
<p>
<tt>post_exec</tt> program to execute after backuping this source
</p>
</li>
</ul>
@ -430,10 +471,10 @@ This number defines how many versions of this intervall to keep.</p>
/home/nico/vpn</tt></pre>
</div></div>
<h4>4.3.1. Detailled description of "source"</h4>
<p><tt>source</tt> describes a rsync compatible source (one line only).</p>
<p><tt>source</tt> describes a <tt>rsync</tt> compatible source (one line only).</p>
<p>For instance <em>backup_user@foreign_host:/home/server/video</em>.
To use the rsync protocol without the ssh-tunnel, use
<em>rsync::USER@HOST/SRC</em>. For more information have a look at rsync(1).</p>
To use the <tt>rsync</tt> protocol without the <tt>ssh</tt>-tunnel, use
<em>rsync::USER@HOST/SRC</em>. For more information have a look at <tt>rsync</tt>(1).</p>
<h4>4.3.2. Detailled description of "verbose"</h4>
<p><tt>verbose</tt> tells <tt>ccollect</tt> that the log should contain verbose messages.</p>
<p>If this file exists in the source specification <strong>-v</strong> will be passed to <tt>rsync</tt>.</p>
@ -498,6 +539,26 @@ to use for automatic backup over the rsync-protocol.</p>
<pre><tt> [23:42] hydrogenium:ccollect-0.2% cat conf/sources/test_rsync/rsync_options
--password-file=/home/user/backup/protected_password_file</tt></pre>
</div></div>
<h4>4.3.8. Detailled description of "pre_exec" and "post_exec"</h4>
<p>When you create <tt>pre_exec</tt> and / or <tt>post_exec</tt> below your source
configuration, <tt>ccollect</tt> will execute this command before,
respective after doing the backup for <strong>this specific</strong> source.
If you want to have pre-/post-exec before and after <strong>all</strong>
backups, see above for general configuration.</p>
<p>Example:</p>
<div class="listingblock">
<div class="content">
<pre><tt>[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</tt></pre>
</div></div>
</div>
<h2>5. Hints</h2>
<div class="sectionbody">
@ -574,6 +635,22 @@ waste resources, but your backup will be complete.</p>
</td>
</tr></table>
</div>
<h3>5.4. Using pre_/post_exec</h3>
<p>Your pre_/post_exec script does not need to be a script, you can also
use a link to</p>
<ul>
<li>
<p>
an existing program
</p>
</li>
<li>
<p>
an already written script
</p>
</li>
</ul>
<p>The only requirement is that it is executable.</p>
</div>
<h2>6. F.A.Q.</h2>
<div class="sectionbody">
@ -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 <tt>destination</tt>
to <em>source/exclude</em>. (Daniel Aubry reported this problem)</p>
<h3>6.3. Why does ccollect say "Permission denied" with my pre-/postexec script?</h3>
<p>The most common error is to not give your script the correct
permissions. Try <tt>chmod 0755 <em>/etc/ccollect/sources/yoursource/*_exec</em></tt>.</p>
</div>
<h2>7. Examples</h2>
<div class="sectionbody">
@ -668,8 +748,8 @@ srwali01:/etc/ccollect/sources# du -sh /mnt/hdbackup/wl6/*
</div>
<div id="footer">
<div id="footer-text">
Version 0.2.2<br />
Last updated 22-Jan-2006 10:49:24 CEST
Version 0.3.0<br />
Last updated 22-Jan-2006 13:26:51 CEST
</div>
</div>
</body>

View file

@ -1,7 +1,7 @@
ccollect - Installing, Configuring and Using
============================================
Nico Schottelius <nico-linux-ccollect__@__schottelius.org>
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