chiark / gitweb /
No need for Makefile-etc now - we hope.
[chiark-utils.git] / backup / iwjbackup.txt
1 This is a quick summary of IWJ's backup scripts and my config files:
2 it's a bit patchy and might have the odd ommission. The canonical
3 source is the sources, as always :->
4
5
6 WARNING - this file is out of date !
7
8 # iwjbackup.txt
9 # Documentation file
10 #
11 # This file is part of chiark backup, a system for backing up GNU/Linux and
12 # other UN*X-compatible machines, as used on chiark.greenend.org.uk.
13 #
14 # chiark backup is:
15 #  Copyright (C) 1997-1998,2000-2001 Ian Jackson <ian@chiark.greenend.org.uk>
16 #  Copyright (C) 1999 Peter Maydell <pmaydell@chiark.greenend.org.uk>
17 #
18 # This is free software; you can redistribute it and/or modify it under the
19 # terms of the GNU General Public License as published by the Free Software
20 # Foundation; either version 2, or (at your option) any later version.
21 #
22 # This is distributed in the hope that it will be useful, but WITHOUT ANY
23 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
24 # FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
25 # details.
26 #
27 # You should have received a copy of the GNU General Public License along
28 # with this program; if not, write to the Free Software Foundation, Inc.,
29 # 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
30
31
32
33 The three tarfiles in this directory should go in the following 
34 places (the paths can probably be configured/hacked, but this is
35 where they are on my system and on chiark):
36
37 etc.tgz : /etc/backup/
38 lib.tgz : /usr/local/lib/backup/
39 var.tgz : /var/local/backup/
40
41 NOTE: these versions are not those used on chiark; they
42 are somewhat modified by me (couple of extra features and
43 lots of comments -- all errors in those are mine.)
44
45 NB: you'll probably need to delete some of the files from
46 var.tgz (in fact, I think you probably don't want any of
47 them except maybe last-tape (which you want to change anyway).
48 You'll also need to recompile readbuffer and writebuffer unless
49 you're using SPARClinux :->
50
51 Contents of /etc/backup/:
52 warnings.*  : files defining how many warnings you get as the
53 system is brought down to do backups. The defaults are fine.
54 settings.pl : generic config file: in particular, the name of 
55 the tape device is set here.
56 tape.*  : each tape you're going to use in the backup cycle
57 has a name and a config file. Here the tapes are named 'a'-'e',
58 although longer names should be OK. You need at least two 
59 tapes defined as the system won't write a backup on the same
60 tape it wrote the last one to.
61
62 Syntax of the tape.* files:
63 filesystems X
64 next N
65 end
66
67 where N is the next tape in the sequence (which should 
68 be circular; I have a->b->c->d->e->a...) and X is a 
69 filesystem-name (list of filesystems might work?).
70
71 Each defined filesystem has a name and a config file
72 fsys.<name>. These files define what is backed up and how.
73 The filesystem 'all' must exist; it's used for incremental
74 backups (and it must exist even if you don't do incrementals).
75 I don't have any other filesystems defined as everything fits
76 on one tape.
77
78 Syntax of these files:
79 Empty lines and lines starting '#' are comments and ignored.
80 Lines starting 'excludedir' given regexps of things to exclude
81 (temp dirs, Netscape's cache, etc). 
82 Lines starting 'prefix' give a command prefix necessary to
83 run things on a remote machine:
84 prefix <prefix-name> <command-part>
85 Other lines should be of the form
86 <directory name>   <backup-type>
87 for local backups, or 
88 <directory name>   <backup-type>   <prefix-name>
89 for remote backups.
90 The file must end with the word 'end' on a line of its own.
91
92 Valid values for <backup-type> are 'cpio' (uses cpio to produce
93 tar-format backups), 'dump' (uses dump to dump entire filesystems;
94 <directory name> should be a mount-point for this), and [if you
95 use my version of the scripts] 'zafio' (uses afio to compress
96 each file as it is backed up). Only 'dump' type backups permit
97 incremental backups.
98
99 Finally, expected-diffs is a config file to indicate which 
100 filesystems should *not* be backed up. The scripts do a config
101 check which involves checking that:
102  * all filesystems to be backed up are present
103  * all filesystems that are present are backed up
104 expected-diffs allows you to make exceptions to this; backing 
105 up your CDROM drive is a bit pointless, frex.
106 The format here is:
107 <prefixchar><mountpoint>
108
109 where <prefixchar> is ?, ! or nothing, and 
110 <mountpoint> is <prefix>:<mountpoint> for a remote fs or
111 <mountpoint> for a local one
112 (examples: "mnementh:/cdrom", "/cdrom").
113 If <prefixchar> is nothing, the scripts will complain if the fs
114 is mounted. If it is !, they will complain if it is not mounted.
115 If ? they won't complain either way (useful for devices that are
116 not always mounted, like /cdrom). '?' is an enhancement only 
117 present in my version of the scripts.
118
119 Useful scripts: (all in /usr/local/lib/backup)
120 checkallused: this only does a check of the configuration files.
121 It should give a cryptic summary of the configuration and print
122 'configuration ok'. If not, fix your config files :->
123
124 loaded: this tells the scripts that a currently unlabelled tape
125 should be treated as tape X: eg:
126 loaded b
127 will cause it to treat it as tape 'b'. [NB: this won't override
128 the TAPEID label written on the tape; it's just for use with
129 previously unused tapes.]
130
131 driver : this is the script to actually run to do a backup.
132 If run from the command line, give it the argument 'test'
133 [otherwise it will attempt to run bringup to change runlevel,
134 on the assumption that it was run from inittab (see below)].
135 You'll need to edit this script to send the status report email
136 to somewhere right for your system.
137
138 takedown : Run this if you want to run a reduced level of system
139 services during backups. Usage:
140 takedown <freq>
141 where <freq> can be 'now', 'soon' or nothing depending on number
142 of warning messages desired. [configured via warnings.* files.]
143
144 To use this you'll need to configure init:
145  * set up runlevel 5 to provide the level of services you want
146    (by tweaking the symlinks in /etc/rc5.d or equivalent)
147  * Add the following to /etc/inittab (tweak paths and VC number
148    if desired):
149
150 # Runlevel 5 is set up to run a reduced level of services during
151 # backups. (currently this means: no squid, no webserver, no newsserver)
152 # We also run the backup script automatically on entering runlevel 5:
153 # (I/O goes to VC 7, which is also the X server, but never mind -- we
154 # very seldom run X anyway :->)
155 dm:5:once:/usr/local/lib/backup/driver </dev/tty7 >/dev/tty7 2>&1
156
157  * takedown can be run from the command line or via cron.
158
159 whatsthis: a simple script I hacked together to display the
160 TAPEID of the current tape and optionally list its contents.
161 Usage:
162 whatsthis [--list [n]]
163
164 WARNING: it's currently hardwired to assume 'cpio' type backups
165 when listing; it could be trivially hardwired to assume 'zafio' 
166 or with slightly more effort it could be done properly :->
167
168 That's all I can think of for now -- comments and 
169 questions to Peter Maydell <pmaydell@chiark.greenend.org.uk>