$Id: README,v 1.20 2004/01/14 01:19:36 anarcat Exp $

Readme file for the Backup Shell
================================

bksh is a simple (some would say trivial) program designed to be used
as a shell by ssh or rsh-like programs. All it does it to copy its
standard input to a restricted set of backup files.

It was made to allow administrators to create backup servers in
potentially hostile environments without allowing full shell access to
the server or the client.

Features
-----------------

- tape only or file & tape backups (compile-time config)
- automatic file rotation allows keeping a history of backups
- configurable number of files kept (static compile-time or dynamic)
- allows naming of backup files on command line
- works as a restricted shell to limit access to server
- very simple and short ANSI C code, easy to audit

Usage Example
-----------------

If the "backup" user on the server "machine" has bksh set as its shell:

client# dump -f - -0 / | ssh backup@machine root_0.dmp -t5

will put the backup in /home/backup/incoming/client/root_0.dmp, and
will keep at most 5 copies of the file (named root_0.dmp.1,
root_0.dmp.2, etc). The -t flag must be *after* the backup name
because of the way ssh sends the arguments to the shell.

The backup.sh shell script (provided along with the source) does this
for you. It facilitates automated backup of filesystems using dump and
bksh. This simple call will make a full backup (level 0 dump) of /usr
to a backup host defined in the shell script:

client# backup.sh 0 /usr

backup.sh also has support for client on-the-fly gzip(1) or bzip(1)
compression, using the -z or -b flag:

client# backup.sh -z 4 /var

See the script's usage (-h) for examples.

This of course can be started from a crontab, like this:

#minute hour    mday    month   wday    command
5       5       *       *       *	/root/scripts/backup.sh -z 0 / /var /usr

Operation details
-----------------

bksh is restricted to a single directory ($HOME/incoming, defined at
compile-time) and classifies the backups based on the SSH_CLIENT
variable inherited from sshd: incoming/<ip>/. If run from rsh, it puts
all the backup files in the same directory, incoming/.

The name of the backup file is taken from the command line, so it
allows the user to identify its backups (e.g. var.dmp, usr.tgz,
src-10.02.2001.zip). A basename(1)-like process is applied to the
pathname so it's impossible to use slashes and ".." to fool bksh.

If the backup file already exists, bksh will "rotate" the files in a
manner similar to newsyslog, up to a maximum of MAX_BAKS (defined at
compile time) or given by the -t switch (possibly disabled at compile
time).

bksh also allows backup to /dev/sa0 and /dev/nsa0, for direct on-tape
backups, in which case the other restrictions (mandatory HOME &
SSH_CLIENT variables, file rotation) are ignored.

For more information, read the source, which should be simple enough.

Compatibility
-----------------

Compile-tested on:

FreeBSD 4.x and 5.x
Debian GNU/Linux "sid" (unstable)
Mac OS X 10.2 ("Jaguar")

Extensively used on:

FreeBSD 4.8
Mac OS X 10.2

License
-----------------

This work is distributed under the Gnu Public License (GPL), except
the basename.c file which was taken from the basename.c files from
FreeBSD and therefore under the BSD license.

Author
-----------------

The Anarcat <anarcat@anarcat.ath.cx>

Please send me all bug reports, problems, greetings, experiences, etc.
