<!doctype debiandoc system [
<!ENTITY version SYSTEM "VERSION">
<!ENTITY pdf '<url id="../backuponcd.pdf" name="PDF">'>
<!ENTITY history '<url id="../HISTORY" name="HISTORY">'>
<!ENTITY download '<url id="../backuponcd.tar.gz" name="download">'>
<!ENTITY global.rc SYSTEM "/etc/backuponcd/global.rc">
<!ENTITY excludelist SYSTEM "/usr/doc/backuponcd/samples/excludelist">
<!ENTITY simpleread SYSTEM "/usr/doc/backuponcd/samples/simple_read">
<!ENTITY burn.sh SYSTEM "/usr/local/sbin/backuponcd_toast.sh">
<!ENTITY cdrecord '<url id="http://www.fokus.gmd.de/research/cc/glone/employees/joerg.schilling/private/cdrecord.html" name="cdrecord">'>
<!ENTITY backuponcd 'BackupOnCd'>
]>

<debiandoc>
  <book>
    <titlepag>
      <title>Backups on CD</title>
      <author>
        <name>Holger Nassenstein</name>
        <email>backups@tuxoncd.de</email>
      </author>
      <version><date></version>
      <abstract>&backuponcd; <prgn>&version;</prgn> is a set of shell scripts which make gziped multi-volume
backups on CD-RW possible. It also makes the backup faster using &cdrecord;
in a parallel subshell and minimizes the amount of temporary needed disk space.
Currently provided: tar and afio.
It's not finished yet, but should be usefull.
This description is also available as &pdf; &reg; file.
See the &history; for details on release.
</abstract>
<copyright>
        <copyrightsummary>Published under the terms of <url id="http://www.gnu.org/copyleft/gpl.html" name="GNU GPL">, Version 2 or later by Holger Nassenstein.</copyrightsummary>
</copyright>

</titlepag>
    <toc detail="sect1">

    <chapt>
      <heading>Overview</heading>
      <sect id="usage">
	<heading>Usage</heading>
      <p>Just type <prgn>backuponcd -s (directory) -e (excludelist)</prgn>,
where <prgn>(directory)</prgn> is the full path to the directory which you want to archive
and <prgn>(excludelist)</prgn> is a grep-script.</p>

	<p>The output of <prgn>backuponcd -h</prgn> is:

	  <example>-s directory which is to archived
-e excludelist may be a empty file, usually a list of mountpoints,
   view example in /etc/backuponcd/excludelist
-a archiver (optional) overrides your setting (archiver=..)
   in /etc/backuponcd/global.rc
-rc global settings (optional).
    Overrides built in parameter "-rc /etc/backuponcd/global.rc".
    Must be full path to rc file.</example>
</p>
<p>If you want to generate a backup on a running system, some folders must be
excluded, have a look on an example exclude list (see <ref id="excludelist">).</p>
</sect>
      <sect id="whatdoesit">
	<heading>What does it do?</heading>
	<p>The script generates a backup providing tar or afio relative to 
<prgn>(directory)</prgn> and stores it temporary in the backuppath, depending on your 
settings in <ref id="global.rc">. The
archive can have any length, it is splitted into smaller pieces and burned while
the backup runs continuous. </p>
	<p>This is done by using pipes and burning multisession CDs, so don't
worry if the gzipped tarball of your system amounts 1.5 + Gbyte. In this case
you need 3 CDs with a media cost of 6$ if you use CD-RW.</p>
      </sect>
      <sect id="howitworks">
	<heading>How does it work?</heading>
	<p>Extracting an archive looks like this:
<example>cat /cdwriter/tar.gz.* | tar --compare --gzip --file=- | \\
tee -a /tmp/logfile</example>
while the filenames of the archive are <prgn>tar.gz.00</prgn>, <prgn>tar.gz.01</prgn>
and so on.</p>
	<p>A bit more complicated is reading a multisession backup:
<example>&simpleread;</example> 
The script is used as follows:
<example>~/bin/simple_read | tar --compare --gzip --file=- | \\
tee -a /tmp/logfile</example></p>
	<p>&backuponcd; comes with longer shell scripts which recognize
multi- and singlesession CD and type out better comments, know which volume
is inserted and so on.</p>
	<p>If you assume that burning does work similar you're right,
it does (see <ref id="details"> if you are interested).  </p>
      </sect>
    </chapt>
    <chapt id="quick">
      <heading>Quick Reference</heading>
      <sect id="installing">
	<heading>Installing &backuponcd;</heading>
	<p>Just extract the tarball. Copy the executables <prgn>/usr/local/sbin</prgn>
          and the folder <prgn>etc/backuponcd</prgn> to <prgn>/etc</prgn>. With the
          debian package you should have nothing to do.</p>
	<sect1>	
	  <heading>Dependencies</heading>
	  <p>On a debian system you need to have installed the following packages:
<example>
textutils
shellutils
fileutils
sed
awk
findutils
mount
cdrecord
mkisofs >> 1.8a
tar or
  afio
gzip
</example>
As you see everything is done with standard tools.</p>
	</sect1>
	<sect1>
	  <heading>Customizing (a must)</heading>
	  <p><list>
	      <item>

	  <p>With the settings &backuponcd; comes with, you need 400 Mbyte free disk 
          space under <prgn>/tmp/</prgn>. If free space doesn't fit you need to edit <ref id="global.rc">.</p>
	  <p>You have several options:
<list>
	      <item>
		<p>Change the variable <prgn>TMP="..."</prgn> to a directory where is enough disk space</p>
	      </item>
	      <item>
		<p>Enlarge the variable <prgn>tracks=</prgn> and decrease <prgn>tracksize=</prgn></p>
		<p>Note, that a so-called lead-out is needed for each track, the amount
of space on the disk is decreased by the count of tracks. For details have a look at
<url id="http://localhost/doc/cdrecord/README.multi" name="/usr/doc/cdrecord/README.multi">, 
or visit the homepage of &cdrecord;.
You can play with these settings, if one track doesn't fit on the CD it is
stored on the next CD.</p>
	      </item>
	      <item>
		<p>If free space is very small, you can force &backuponcd; to do the
burning <em>not</em> parallel to the backup. If you did that, only one <prgn>tracksize</prgn> space 
is needed. Edit <prgn>/sbin/backuponcd_toast.sh</prgn>, delete the
single ampersand at the end of the line:
<example>
( nice -n -10 mkisofs -R -J -L $vol $volid \\
$multiinfo $toast_dir | cdrecord -v $dev \\
$devdepend $blank fs=8m -multi - && rm \\
$toast_dir/* ) 2>> $logfile &
</example></p>
	      </item>
	      <item>
		<p>A better option: Get an old 850 Mbyte disk and mount it to <prgn>/tmp</prgn>.</p>
	      </item>
	    </list>
</p>
	      </item>

	      <item>
	  <p>Try out to change the variable <prgn>devdepend="speed=2 -eject"</prgn>
to <prgn>devdepend="speed=x"</prgn>, while speed is the speed of your cdwriter. Please email 
me if it works or not. A Philipps CDD 3600 does not read the trackinfo if the CD 
is not ejected after each track.
I think this toaster does a reset if the CD is ejected. You cannot run into trouble
by playing this setting, a failed backup is all what can happen.</p></item>
	      <item>
		<p>Edit the line <prgn>archiver=</prgn>, choose tar or afio. Note, that
find is <em>not</em> used if you choosed tar as archiver. The main disadvantage is,
that no filelist is generated. Tar often is used as followed:
<example>find . -not -type d | grep -v -f excludelist | \\
tee -a filelist | tar -cvz --file=archive.tar.gz \\
--files-from=-</example>
With the above line empty directorys and each directory found in <prgn>excludelist</prgn>
(ususally mountpoints) would <em>not</em> be archived. In my opinion this wouldn't be a
backup, so tar is used as below:
<example>tar -cvz -X $excludelist --file=- .</example>
It should be easy for you to edit <prgn>/sbin/backupond</prgn> if you don't like
this quality.
</p>
	      </item>
	      <item>
		<p>Edit <prgn>rawdevice=</prgn> and <prgn>mountpt=</prgn></p>
	      </item>
	    </list>
        </p>
	</sect1>
      </sect>
	<sect>
	  <heading>Enjoying</heading>
	  <p>See <ref id="usage"> for commandline options. Copy or move the file 
<ref id="excludelist"> to a place where you want and edit it, so that it fits 
to your system or the system which you want to backup.</p>
	  <p>The remaining is fun. Everything is done automaticly, the backup will get
compared, logliles and scripts are burned on the last CD. It should be easy
to do a restore with a system started from a floppy.
 </p>
	</sect>

    </chapt>
    <chapt id="details">
      <heading>Details</heading>
      <sect>
	<heading>The Burning Process</heading>
	<p>I think the easiest way to learn about this is to have a look 
on the source.</p>
	<p>If you don't understand how it works please don't email me. Learn
more about sh, tar, baseutils and cdrecord.</p>
         <p> Assume that tar is invoked as followed:
	  <example>mkfifo fifo
tar -cpvz -X $excludelist --file=fifo * &</example></p>
      </sect>
      <sect>
	<heading><prgn>toast.sh $params fifo</prgn></heading>
	<p><example>&burn.sh;</example></p>
      </sect>
    </chapt>
    <chapt id="settings">
      <heading>Important Options, Global Settings</heading>
      <sect id="excludelist">
	<heading><prgn>/usr/doc/backuponcd/samples/excludelist</prgn></heading>
	<p>This file must be named via the switch -e. Excludelist 
may be a empty file, but can't be missed.
<example>
&excludelist;
        </example></p>
      </sect>
      <sect id="global.rc">
	<heading><prgn>/etc/backuponcd/global.rc</prgn></heading>
	<p>
This file is normally known by a built in parameter which can 
	  be overridden by the switch <prgn>-rc</prgn> (see <ref id="usage">).
<example>&global.rc;
        </example></p>
	<p>Note: Change the internal stuff if you don't like the filenames <em>and</em>
        if you know what you are doing.</p>
      </sect>
    </chapt>
    <chapt id="download">
      <heading>Download / Contributes</heading>
      <p>Please email me if you have ideas or bug reports. I would enjoy if you
had fixes. Feel free to contribute</p>
      <p>&backuponcd; <prgn>&version;</prgn>  &download;</p>
    </chapt>
  </book>
</debiandoc>