chiark / gitweb /
@@ -3,6 +3,7 @@
[chiark-utils.git] / backup / iwjbackup.txt
1 iwjbackup.txt
2 documentation file
3 Copyright - AND NO WARRANTY - see notes at bottom of file for details.
4
5 This is a quick summary of the backup scripts, and some comments on
6 some of the config files: it's a bit patchy and might have the odd
7 ommission. The canonical source is the sources, as always :->
8
9
10 To run, the contents of /etc/chiark-backup should be:
11
12 warnings.*: files defining how many warnings you get as the system is
13 brought down to do backups. The defaults are fine.
14
15 settings.pl: generic config file: in particular, the name of the tape
16 device is set here.
17
18 tape.*: conventionally, each tape you're going to use in the backup
19 cycle has a tape number, a name and a config file.  The tape numbers
20 in use at Relativity are digit strings like `512'.  The name is a
21 combination of rotation set and volume number; rotation sets are
22 typically a single letter (`s', `t', `u', `v') at Relativity and
23 volumes a single digit (`0', `1', `2') at Relativity.  You need at
24 least two tapes as the system won't write a backup on the same tape it
25 wrote the last one to.
26
27 There are also conventionally incremental tapes whose names are a
28 fixed letter (`k' in the current scheme) followed by a rotation
29 letter.  At Relativity we have two of these, `ks' and `kt'.
30
31 Syntax of the tape.* files for full dump tapes:
32   filesystems X
33   next N
34   end
35
36 where N is the name of the next tape in the *full dump* sequence
37 (which should be circular; eg
38 v0->v1->v2->s0->s1->s1->t0->t1->t2->u0->u1->u2->v0->...
39 and X is a filesystem group name (typically the same as the volume
40 number).
41
42 Each defined filesystem group has a name and a config file
43 fsys.<name>.  These files define what is backed up and how.  The
44 filesystem `all' must also exist; it's used for incremental backups
45 (and it must exist even if you don't do incrementals).
46
47 In the fsys.* files:
48   Empty lines and lines starting '#' are comments and ignored.
49   Lines starting `excludedir' given regexps of things to exclude
50    (temp dirs, Netscape's cache, etc).
51   Lines starting `include' say to include another file when reading
52    this one.
53   Lines starting `prefix' give a command prefix necessary to
54    run things on a remote machine:
55      prefix <prefix-name> <command-part>
56   Other lines should be of the form
57     [<device name>:]<directory name> <backup-type>[,<options>]
58   for local backups, or
59     [<device name>:]<directory name> <backup-type>[,<options>] <prefix-name>
60   for remote backups.
61 The file (including any included files) must end with the word 'end'
62 on a line of its own.
63
64 Valid values for <backup-type> are `cpio' (uses cpio to produce
65 tar-format backups), `dump' (uses dump to dump entire filesystems;
66 <directory name> should be a mount-point for this), `zafio' (uses afio
67 to compress each file as it is backed up), and `ntfsimage' (for NTFS
68 volumes, requires device name).  Only `dump' type backups perform
69 incremental backups.
70
71 <options> is a comma-separated list of <option> or <option>=<value>.
72 The only currently support options are gz[i][=<compressionlevel>], to
73 indicate that the whole stream should be compressed with gzip.  The
74 compression level defaults to 1 if gz is specified by the level isn't.
75 gzi appliies only to the incrementals; gz applies to both unless gzi
76 is also specified.  compression level 0 means not to run gzip at all
77 and is the default if gz[i] is not mentioned.
78
79 expected-diffs is a config file to indicate which 
80 filesystems should *not* be backed up. The scripts do a config
81 check which involves checking that:
82  * all filesystems to be backed up are present
83  * all filesystems that are present are backed up
84 expected-diffs allows you to make exceptions to this; backing 
85 up your CDROM drive is a bit pointless, frex.
86 The format here is:
87 <prefixchar><mountpoint>
88
89 where <prefixchar> is ?, ! or nothing, and 
90 <mountpoint> is <prefix>:<mountpoint> for a remote fs or
91 <mountpoint> for a local one
92 (examples: "mnementh:/cdrom", "/cdrom").
93 If <prefixchar> is nothing, the scripts will complain if the fs
94 is mounted. If it is !, they will complain if it is not mounted.
95 If ? they won't complain either way (useful for devices that are
96 not always mounted, like /cdrom).
97
98
99 You may also create `bringup-hook', a script (or program) which will
100 be run by `bringup' at the end.
101
102
103 Useful scripts (all in /usr/bin):
104
105 backup-checkallused: this only does a check of the configuration
106 files.  It should give a cryptic summary of the configuration and
107 print 'configuration ok'. If not, fix your config files :->
108 You have to create the file /var/lib/chiark-backup/last-tape
109 containing the id of a tape; this helps backup-checkallused know where
110 to start iterating over tapes.  Any tapeid will do.  (But don't make
111 it the same as the one you want to back up to first.)
112
113 backup-loaded: this tells the scripts that a currently unlabelled tape
114 should be treated as tape X: eg:
115     backup-loaded b3
116 will cause it to treat it as tape `b3'.  NB: this won't override the
117 TAPEID label written on the tape; it's just for use with previously
118 unused tapes.  This applies only to the next time the backup scripts
119 are invoked.  You can say just
120     backup-loaded
121 to go back to the default behaviour, which is to fail if the tape has
122 no TAPEID.
123
124 backup-driver: this is the script to actually run to do a backup.  If
125 run from the command line, give it the argument 'test' - otherwise it
126 will attempt to run bringup to change runlevel, on the assumption that
127 it was run from inittab (see below).  The status report email will be
128 sent to whatever the unqualified local-part `dump-reports' points to.
129
130 backup-takedown: This is for running a reduced level of system
131 services during backups.  Usage: takedown <freq> where <freq> can be
132 `now', `soon' or nothing depending on number of warning messages
133 desired - these correspond to warnings.* files.
134
135 To use this you'll need to configure init:
136  * set up runlevel 5 to provide the level of services you want
137    (by tweaking the symlinks in /etc/rc5.d or equivalent)
138  * Add the following to /etc/inittab (tweak paths and VC number
139    if desired):
140
141   # Runlevel 5 is set up to run a reduced level of services during
142   # backups. (currently this means: no squid, no webserver, no newsserver)
143   # We also run the backup script automatically on entering runlevel 5:
144   dm:5:once:backup-driver </dev/tty8 >/dev/tty8 2>&1
145
146  * takedown can be run from the command line or via cron.
147
148 backup-whatsthis: a simple script to display the TAPEID of the current
149 tape and optionally list its contents.  This script is a bit of a hack
150 and may not be fully reliable:
151
152  Usage:
153  whatsthis [--list [n]]
154
155 WARNING: it's currently hardwired to assume `cpio' type backups
156 when listing; it could be trivially hardwired to assume `zafio' 
157 or with slightly more effort it could be done properly :->.
158
159
160 COPYRIGHT and LACK OF WARRANTY information
161
162 This file is part of chiark backup, a system for backing up GNU/Linux and
163 other UN*X-compatible machines, as used on chiark.greenend.org.uk.
164
165 chiark backup is:
166  Copyright (C) 1997-1998,2000-2001 Ian Jackson <ian@chiark.greenend.org.uk>
167  Copyright (C) 1999 Peter Maydell <pmaydell@chiark.greenend.org.uk>
168
169 This is free software; you can redistribute it and/or modify it under the
170 terms of the GNU General Public License as published by the Free Software
171 Foundation; either version 2, or (at your option) any later version.
172
173 This is distributed in the hope that it will be useful, but WITHOUT ANY
174 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
175 FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
176 details.
177
178 You should have received a copy of the GNU General Public License along
179 with this program; if not, write to the Free Software Foundation, Inc.,
180 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.