README
1$Id: README,v 1.20 2004/01/14 01:19:36 anarcat Exp $
2
3Readme file for the Backup Shell
4================================
5
6bksh is a simple (some would say trivial) program designed to be used
7as a shell by ssh or rsh-like programs. All it does it to copy its
8standard input to a restricted set of backup files.
9
10It was made to allow administrators to create backup servers in
11potentially hostile environments without allowing full shell access to
12the server or the client.
13
14Features
15-----------------
16
17- tape only or file & tape backups (compile-time config)
18- automatic file rotation allows keeping a history of backups
19- configurable number of files kept (static compile-time or dynamic)
20- allows naming of backup files on command line
21- works as a restricted shell to limit access to server
22- very simple and short ANSI C code, easy to audit
23
24Usage Example
25-----------------
26
27If the "backup" user on the server "machine" has bksh set as its shell:
28
29client# dump -f - -0 / | ssh backup@machine root_0.dmp -t5
30
31will put the backup in /home/backup/incoming/client/root_0.dmp, and
32will keep at most 5 copies of the file (named root_0.dmp.1,
33root_0.dmp.2, etc). The -t flag must be *after* the backup name
34because of the way ssh sends the arguments to the shell.
35
36The backup.sh shell script (provided along with the source) does this
37for you. It facilitates automated backup of filesystems using dump and
38bksh. This simple call will make a full backup (level 0 dump) of /usr
39to a backup host defined in the shell script:
40
41client# backup.sh 0 /usr
42
43backup.sh also has support for client on-the-fly gzip(1) or bzip(1)
44compression, using the -z or -b flag:
45
46client# backup.sh -z 4 /var
47
48See the script's usage (-h) for examples.
49
50This of course can be started from a crontab, like this:
51
52#minute hour mday month wday command
535 5 * * * /root/scripts/backup.sh -z 0 / /var /usr
54
55Operation details
56-----------------
57
58bksh is restricted to a single directory ($HOME/incoming, defined at
59compile-time) and classifies the backups based on the SSH_CLIENT
60variable inherited from sshd: incoming/<ip>/. If run from rsh, it puts
61all the backup files in the same directory, incoming/.
62
63The name of the backup file is taken from the command line, so it
64allows the user to identify its backups (e.g. var.dmp, usr.tgz,
65src-10.02.2001.zip). A basename(1)-like process is applied to the
66pathname so it's impossible to use slashes and ".." to fool bksh.
67
68If the backup file already exists, bksh will "rotate" the files in a
69manner similar to newsyslog, up to a maximum of MAX_BAKS (defined at
70compile time) or given by the -t switch (possibly disabled at compile
71time).
72
73bksh also allows backup to /dev/sa0 and /dev/nsa0, for direct on-tape
74backups, in which case the other restrictions (mandatory HOME &
75SSH_CLIENT variables, file rotation) are ignored.
76
77For more information, read the source, which should be simple enough.
78
79Compatibility
80-----------------
81
82Compile-tested on:
83
84FreeBSD 4.x and 5.x
85Debian GNU/Linux "sid" (unstable)
86Mac OS X 10.2 ("Jaguar")
87
88Extensively used on:
89
90FreeBSD 4.8
91Mac OS X 10.2
92
93License
94-----------------
95
96This work is distributed under the Gnu Public License (GPL), except
97the basename.c file which was taken from the basename.c files from
98FreeBSD and therefore under the BSD license.
99
100Author
101-----------------
102
103The Anarcat <anarcat@anarcat.ath.cx>
104
105Please send me all bug reports, problems, greetings, experiences, etc.
106