'\" t
.TH RDUP-BACKUPS 7 "15 Dec 2008" "0.7.x" "rdup"

.SH NAME
rdup-backups \- introduction into making backups with rdup

.SH INTRODUCTION
\fBrdup\fR is a simple program that prints out a list of files and
directories that are changed changed on a filesystem. It is 
more sophisticated than for instance \fIfind\fR, because \fBrdup\fR
will find files that are removed or directories that are renamed.

A long time ago \fBrdup\fR included a bunch of shell and Perl scripts
that implemented a backup policy. These could be used in a pipeline
to perform a backup.
.PP
Currently \fBrdup\fR consists out of three basic utilities:
.TP
.B rdup
With \fBrdup\fR you create the filelist on which later programs in the
pipeline can work. With \fBrdup \fI\-c\fR the file's contents
is also echo-ed to stdout. See rdup(1) for more infomation.

.TP
.B rdup-tr
With \fBrdup-tr\fR you can transform (encrypt, compress, whatever...) the
files rdup delivers to you.

\fBrdup-tr\fR reads \fBrdup\fR input and will create \fBrdup \fI\-c\fR
output. See rdup-tr(1) for more information.

.TP 
.B rdup-up
With \fBrdup-up\fR you can update an existing directory structure with the
updates as described by rdup. 

\fBrdup-up\fR reads \fBrdup -c\fR input and will create the files,
symlinks, hardlinks and directories (and sockets, pipes and devices)
in the file system. See rdup-up(1) for more information.

.PP
So the general backup pipeline for \fBrdup\fR will look something like
this:

    create filelist  |  transform file content  |  update filesystem
    ( rdup           |  rdup-tr                 |  rdup-up )

Note that the same sequence is used for restoring. In both
cases you want to move files from location A to B. The only difference
is that the transformation is reversed when you restore.

There is a little shell script that can be used to create a hard
linked directory structure, this script \fBrdup-ln.sh\fR is installed
in '/usr/lib/rdup/'. The script looks back for previous backup and
then creates a hardlinked directory structure. By using this script
you create a YYYYMM/DD backup structure, where each YYYYMM/DD directory
contains a full view of your filesystem \fIat that date\fR. This script
very much depends on being able to use GNU date and GNU cp.

From the return code of this script you know what to do, if the exit code
is 0 an incremental backup needs to be made. If the exit code is 1 a
full backup is in order. An exit code of 2 means there was some kind of
error.

With these three (four) tools you can create your own backup solution, see
SNAPSHOT BACKUPS later in this document.

.SH TYPES OF OUTPUT     
\fBrdup\fR can create two types of output:
.PP
.TP
.B 1.
a list of pathnames and path attributes
.TP 
.B 2.
a list of pathnames and path attributes \fIand\fR the
files' contents
.PP

The latter is often called 'rdup \-c' output after the switch
(\-c) which enables this ouput. 'rdup \-c' output is
comparable to archive formats like tar or pax.

The first one is just called the normal or list output.

In rdup(1), rdup-tr(1) and rdup-up(1) it says what output
a command can create and what input it expects.


.SH BACKUPS AND RESTORES
For \fBrdup\fR there is \fIno\fR difference between backups and
restores. If you think about this for a minute you understand why.

Making a backup means copying a list of files somewhere else. Restoring
files is copying a list of files back to the place they came from. Same
difference. So \fBrdup\fR can be used for both, if you did any
transformation with \fBrdup-tr\fR during the backup you just need to
reverse those operations during the restore.

.SH BACKUPS
It is always best to backup to \fIanother\fR medium, be it a different
local harddisk or a NFS/CIFS mounted filesystem or use \-c switch
of rdup to copy the files and direcories to a remote server, ala rsync.

If you backup to a local disk you can just as well use \fBrsync\fR or
plain old tar, but if you store your files at somebody else's disk you
will need encryption. This is where you go beyond \fBrsync\fR and
\fBrdup\fR comes in. Rsync cannot do per-file encryption, sure you
can encrypt the network traffic with ssh, but at the remote side
your files are kept in plain view.
	 
If you implement remote backups, the easy route is to allow root
access on the backup medium. If the backup runs without root
access the created files will not have their original ownership.
For NFS this can be achieved by using \fBno_root_squash\fR, for
\fBssh\fR you could enable \fIPermitRootLogin\fR. Note that this
may be a security risk.

.SH SNAPSHOT BACKUPS
We need a little help here in the form of the \fBrdup-ln.sh\fR script.
Keep in mind that the following scripts can also be run remotely with
the help of \fBssh\fR.

The following script implements the algorithm of \fBrdup-simple\fR.

.RS
.nf
#!/bin/bash

# some tmp. file are saved in ~/.rdup. This directory must exist

DIR=/home	    # what to backup
BACKUP=/vol/backup
TODAY=$(date +%Y%m/%d)	# same as in rdup-ln.sh
LIST=~/.rdup/list-$HOSTNAME
STAMP=~/.rdup/timestamp-$HOSTNAME

# for remote backup, this has to run on the remote host!
/usr/lib/rdup/rdup-ln.sh $BACKUP/$HOSTNAME
RET=$?

case $RET in
    2|*)
	echo Error >&2
	exit 1
	;;
    1)
	# full dump, remove filelist and timestamp file
	rm $LIST $STAMP
	;;
    0)
	# inc dump
	# do nothing here
	;;
esac

# this is the place where you want to modify the commandline
#
# right now, nothing is translated we just use 'cat'

rdup -N $STAMP $LIST $DIR | rdup-tr -Pcat | rdup-up $BACKUP/$HOSTNAME/$TODAY

# Note that rdup-up expects rdup-c output, so if you leave out
# rdup-tr, you must tell rdup to generate the correct output
# rdup -c -N $STAMP $LIST $DIR | rdup-up $BACKUP/$HOSTNAME/$TODAY

# or do a remote backup
#rdup -N $STAMP $LIST $DIR | rdup-tr -Pcat | ssh root@remotehost \\
#	rdup-up $BACKUP/$HOSTNAME/$TODAY

.fi
.RE

.SH RESTORES
todo: restore stuff XXX
 ./rdup-tr -Pgzip -Popenssl,enc,-e,-des-cbc,-k,secret           

.SH ALSO SEE
rdup(1), rdup-tr(1), rdup-up(1) or http://www.miek.nl/projects/rdup/