$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//. 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 Please send me all bug reports, problems, greetings, experiences, etc.