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