chiark / gitweb /
@@ -6,6 +6,8 @@
authorianmdlvl <ianmdlvl>
Mon, 8 Oct 2001 00:11:54 +0000 (00:11 +0000)
committerianmdlvl <ianmdlvl>
Mon, 8 Oct 2001 00:11:54 +0000 (00:11 +0000)
+  * Improved documentation.
+  * bringup-hook created.

TODO
backup/Makefile
backup/bringup
backup/examples/relativity/bringup-hook [new file with mode: 0755]
backup/iwjbackup.txt
debian/changelog

diff --git a/TODO b/TODO
index e2205a7..caf0e70 100644 (file)
--- a/TODO
+++ b/TODO
@@ -4,16 +4,11 @@ BACKUP
 essential before release
 ------------------------
 test
-configuration files sensibleness
-
-important before release
-------------------------
-documentation
-replace loaded with idformat
 
 would be nice someday
 ---------------------
+replace loaded with idformat
 read/writebuffer setuid --mlock
 whatisthis no cloneandhack
-whatisthis listing for cpio and dump archives
+whatisthis listing for zafio and dump archives
 configuration files autogenerator
index aefb186..16260e6 100644 (file)
@@ -65,6 +65,10 @@ install:             all
                $(INSTALL_SHARE) $(SHAREFILES) $(sharedir)
                $(INSTALL_SCRIPT) $(SHARESCRIPTS) $(sharedir)
 
+install-docs:
+               $(INSTALL_DIRECTORY) $(txtdocdir)
+               $(INSTALL_SHARE) iwjbackup.txt $(txtdocdir)/README
+
 install-examples:
                set -e; for e in $(EXAMPLES); do \
                        cd examples/$$e; \
index ff6107d..0aabd9f 100755 (executable)
@@ -28,5 +28,4 @@
 runlevel=`sed -ne '/^id:/ s/.*:\([0-9]\):.*/\1/p' /etc/inittab`
 telinit $runlevel
 
-# This switches to virtual console 11, but I don't think I want that -- PMM 
-#chvt 11
+test ! -f /etc/backup/bringup-hook
diff --git a/backup/examples/relativity/bringup-hook b/backup/examples/relativity/bringup-hook
new file mode 100755 (executable)
index 0000000..2d57080
--- /dev/null
@@ -0,0 +1,3 @@
+#!/bin/sh
+set -e
+chvt 11
index 3b09433..ff4d860 100644 (file)
-This is a quick summary of IWJ's backup scripts and my config files:
+iwjbackup.txt
+documentation file
+Copyright - AND NO WARRANTY - see notes at bottom of file for details.
+
+This is a quick summary of the backup scripts, and some comments on  and my config files:
 it's a bit patchy and might have the odd ommission. The canonical
 source is the sources, as always :->
 
 
 WARNING - this file is out of date !
 
-# iwjbackup.txt
-# Documentation file
-#
-# This file is part of chiark backup, a system for backing up GNU/Linux and
-# other UN*X-compatible machines, as used on chiark.greenend.org.uk.
-#
-# chiark backup is:
-#  Copyright (C) 1997-1998,2000-2001 Ian Jackson <ian@chiark.greenend.org.uk>
-#  Copyright (C) 1999 Peter Maydell <pmaydell@chiark.greenend.org.uk>
-#
-# This is free software; you can redistribute it and/or modify it under the
-# terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2, or (at your option) any later version.
-#
-# This is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
-# details.
-#
-# You should have received a copy of the GNU General Public License along
-# with this program; if not, write to the Free Software Foundation, Inc.,
-# 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-
-
-The three tarfiles in this directory should go in the following 
-places (the paths can probably be configured/hacked, but this is
-where they are on my system and on chiark):
-
-etc.tgz : /etc/chiark-backup/
-lib.tgz : /usr/local/lib/backup/
-var.tgz : /var/lib/chiark-backup/
-
-NOTE: these versions are not those used on chiark; they
-are somewhat modified by me (couple of extra features and
-lots of comments -- all errors in those are mine.)
-
-NB: you'll probably need to delete some of the files from
-var.tgz (in fact, I think you probably don't want any of
-them except maybe last-tape (which you want to change anyway).
-You'll also need to recompile readbuffer and writebuffer unless
-you're using SPARClinux :->
-
-Contents of /etc/chiark-backup/:
-warnings.*  : files defining how many warnings you get as the
-system is brought down to do backups. The defaults are fine.
-settings.pl : generic config file: in particular, the name of 
-the tape device is set here.
-tape.*  : each tape you're going to use in the backup cycle
-has a name and a config file. Here the tapes are named 'a'-'e',
-although longer names should be OK. You need at least two 
-tapes defined as the system won't write a backup on the same
-tape it wrote the last one to.
-
-Syntax of the tape.* files:
-filesystems X
-next N
-end
-
-where N is the next tape in the sequence (which should 
-be circular; I have a->b->c->d->e->a...) and X is a 
-filesystem-name (list of filesystems might work?).
-
-Each defined filesystem has a name and a config file
-fsys.<name>. These files define what is backed up and how.
-The filesystem 'all' must exist; it's used for incremental
-backups (and it must exist even if you don't do incrementals).
-I don't have any other filesystems defined as everything fits
-on one tape.
-
-Syntax of these files:
-Empty lines and lines starting '#' are comments and ignored.
-Lines starting 'excludedir' given regexps of things to exclude
-(temp dirs, Netscape's cache, etc). 
-Lines starting 'prefix' give a command prefix necessary to
-run things on a remote machine:
-prefix <prefix-name> <command-part>
-Other lines should be of the form
-<directory name>   <backup-type>
-for local backups, or 
-<directory name>   <backup-type>   <prefix-name>
-for remote backups.
-The file must end with the word 'end' on a line of its own.
-
-Valid values for <backup-type> are 'cpio' (uses cpio to produce
-tar-format backups), 'dump' (uses dump to dump entire filesystems;
-<directory name> should be a mount-point for this), and [if you
-use my version of the scripts] 'zafio' (uses afio to compress
-each file as it is backed up). Only 'dump' type backups permit
-incremental backups.
-
-Finally, expected-diffs is a config file to indicate which 
+
+To run, the contents of /etc/chiark-backup should be:
+
+warnings.*: files defining how many warnings you get as the system is
+brought down to do backups. The defaults are fine.
+
+settings.pl: generic config file: in particular, the name of the tape
+device is set here.
+
+tape.*: conventionally, each tape you're going to use in the backup
+cycle has a tape number, a name and a config file.  The tape numbers
+in use at Relativity are digit strings like `512'.  The name is a
+combination of rotation set and volume number; rotation sets are
+typically a single letter (`s', `t', `u', `v') at Relativity and
+volumes a single digit (`0', `1', `2') at Relativity.  You need at
+least two tapes as the system won't write a backup on the same tape it
+wrote the last one to.
+
+There are also conventionally incremental tapes whose names are a
+fixed letter (`k' in the current scheme) followed by a rotation
+letter.  At Relativity we have two of these, `ks' and `kt'.
+
+Syntax of the tape.* files for full dump tapes:
+  filesystems X
+  next N
+  end
+
+where N is the name of the next tape in the *full dump* sequence
+(which should be circular; eg
+v0->v1->v2->s0->s1->s1->t0->t1->t2->u0->u1->u2->v0->...
+and X is a filesystem group name (typically the same as the volume
+number).
+
+Each defined filesystem group has a name and a config file
+fsys.<name>.  These files define what is backed up and how.  The
+filesystem `all' must also exist; it's used for incremental backups
+(and it must exist even if you don't do incrementals).
+
+In the fsys.* files:
+  Empty lines and lines starting '#' are comments and ignored.
+  Lines starting `excludedir' given regexps of things to exclude
+   (temp dirs, Netscape's cache, etc).
+  Lines starting `include' say to include another file when reading
+   this one.
+  Lines starting `prefix' give a command prefix necessary to
+   run things on a remote machine:
+     prefix <prefix-name> <command-part>
+  Other lines should be of the form
+    <directory name>   <backup-type>
+  for local backups, or 
+    <directory name>   <backup-type>   <prefix-name>
+  for remote backups.
+The file (including any included files) must end with the word 'end'
+on a line of its own.
+
+Valid values for <backup-type> are `cpio' (uses cpio to produce
+tar-format backups), `dump' (uses dump to dump entire filesystems;
+<directory name> should be a mount-point for this), and `zafio' (uses
+afio to compress each file as it is backed up).  Only `dump' type
+backups perform incremental backups.
+
+expected-diffs is a config file to indicate which 
 filesystems should *not* be backed up. The scripts do a config
 check which involves checking that:
  * all filesystems to be backed up are present
@@ -113,33 +87,40 @@ where <prefixchar> is ?, ! or nothing, and
 If <prefixchar> is nothing, the scripts will complain if the fs
 is mounted. If it is !, they will complain if it is not mounted.
 If ? they won't complain either way (useful for devices that are
-not always mounted, like /cdrom). '?' is an enhancement only 
-present in my version of the scripts.
+not always mounted, like /cdrom).
+
+
+You may also create `bringup-hook', a script (or program) which will
+be run by `bringup' at the end.
 
-Useful scripts: (all in /usr/local/lib/backup)
-checkallused: this only does a check of the configuration files.
-It should give a cryptic summary of the configuration and print
-'configuration ok'. If not, fix your config files :->
 
-loaded: this tells the scripts that a currently unlabelled tape
+Useful scripts (all in /usr/bin):
+
+backup-checkallused: this only does a check of the configuration
+files.  It should give a cryptic summary of the configuration and
+print 'configuration ok'. If not, fix your config files :->
+
+backup-loaded: this tells the scripts that a currently unlabelled tape
 should be treated as tape X: eg:
-loaded b
-will cause it to treat it as tape 'b'. [NB: this won't override
-the TAPEID label written on the tape; it's just for use with
-previously unused tapes.]
-
-driver : this is the script to actually run to do a backup.
-If run from the command line, give it the argument 'test'
-[otherwise it will attempt to run bringup to change runlevel,
-on the assumption that it was run from inittab (see below)].
-You'll need to edit this script to send the status report email
-to somewhere right for your system.
-
-takedown : Run this if you want to run a reduced level of system
-services during backups. Usage:
-takedown <freq>
-where <freq> can be 'now', 'soon' or nothing depending on number
-of warning messages desired. [configured via warnings.* files.]
+    backup-loaded b3
+will cause it to treat it as tape `b3'.  NB: this won't override the
+TAPEID label written on the tape; it's just for use with previously
+unused tapes.  This applies only to the next time the backup scripts
+are invoked.  You can say just
+    backup-loaded
+to go back to the default behaviour, which is to fail if the tape has
+no TAPEID.
+
+backup-driver: this is the script to actually run to do a backup.  If
+run from the command line, give it the argument 'test' - otherwise it
+will attempt to run bringup to change runlevel, on the assumption that
+it was run from inittab (see below).  The status report email will be
+sent to whatever the unqualified local-part `dump-reports' points to.
+
+backup-takedown: This is for running a reduced level of system
+services during backups.  Usage: takedown <freq> where <freq> can be
+`now', `soon' or nothing depending on number of warning messages
+desired - these correspond to warnings.* files.
 
 To use this you'll need to configure init:
  * set up runlevel 5 to provide the level of services you want
@@ -147,23 +128,43 @@ To use this you'll need to configure init:
  * Add the following to /etc/inittab (tweak paths and VC number
    if desired):
 
-# Runlevel 5 is set up to run a reduced level of services during
-# backups. (currently this means: no squid, no webserver, no newsserver)
-# We also run the backup script automatically on entering runlevel 5:
-# (I/O goes to VC 7, which is also the X server, but never mind -- we
-# very seldom run X anyway :->)
-dm:5:once:/usr/local/lib/backup/driver </dev/tty7 >/dev/tty7 2>&1
+  # Runlevel 5 is set up to run a reduced level of services during
+  # backups. (currently this means: no squid, no webserver, no newsserver)
+  # We also run the backup script automatically on entering runlevel 5:
+  dm:5:once:/usr/local/lib/backup/driver </dev/tty8 >/dev/tty8 2>&1
 
  * takedown can be run from the command line or via cron.
 
-whatsthis: a simple script I hacked together to display the
-TAPEID of the current tape and optionally list its contents.
-Usage:
-whatsthis [--list [n]]
+backup-whatsthis: a simple script to display the TAPEID of the current
+tape and optionally list its contents.  This script is a bit of a hack
+and may not be fully reliable:
+
+ Usage:
+ whatsthis [--list [n]]
+
+WARNING: it's currently hardwired to assume `cpio' type backups
+when listing; it could be trivially hardwired to assume `zafio' 
+or with slightly more effort it could be done properly :->.
+
+
+COPYRIGHT and LACK OF WARRANTY information
+
+This file is part of chiark backup, a system for backing up GNU/Linux and
+other UN*X-compatible machines, as used on chiark.greenend.org.uk.
+
+chiark backup is:
+ Copyright (C) 1997-1998,2000-2001 Ian Jackson <ian@chiark.greenend.org.uk>
+ Copyright (C) 1999 Peter Maydell <pmaydell@chiark.greenend.org.uk>
+
+This is free software; you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2, or (at your option) any later version.
 
-WARNING: it's currently hardwired to assume 'cpio' type backups
-when listing; it could be trivially hardwired to assume 'zafio' 
-or with slightly more effort it could be done properly :->
+This is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+details.
 
-That's all I can think of for now -- comments and 
-questions to Peter Maydell <pmaydell@chiark.greenend.org.uk>
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
index 84787d2..d4c9be2 100644 (file)
@@ -6,6 +6,8 @@ chiark-utils (0.99.0-1) experimental; urgency=low
   * readbuffer/writebuffer command line arg for buffer size.
   * readbuffer/writebuffer share common code.
   * example config files from Relativity and chiark shipped.
+  * Improved documentation.
+  * bringup-hook created.
 
  --