From 5be70e1e6615ac811f61b760548022239141ac7b Mon Sep 17 00:00:00 2001 From: ianmdlvl Date: Mon, 8 Oct 2001 00:11:54 +0000 Subject: [PATCH] @@ -6,6 +6,8 @@ + * Improved documentation. + * bringup-hook created. --- TODO | 9 +- backup/Makefile | 4 + backup/bringup | 3 +- backup/examples/relativity/bringup-hook | 3 + backup/iwjbackup.txt | 265 ++++++++++++------------ debian/changelog | 2 + 6 files changed, 145 insertions(+), 141 deletions(-) create mode 100755 backup/examples/relativity/bringup-hook diff --git a/TODO b/TODO index e2205a7..caf0e70 100644 --- 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 diff --git a/backup/Makefile b/backup/Makefile index aefb186..16260e6 100644 --- a/backup/Makefile +++ b/backup/Makefile @@ -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; \ diff --git a/backup/bringup b/backup/bringup index ff6107d..0aabd9f 100755 --- a/backup/bringup +++ b/backup/bringup @@ -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 index 0000000..2d57080 --- /dev/null +++ b/backup/examples/relativity/bringup-hook @@ -0,0 +1,3 @@ +#!/bin/sh +set -e +chvt 11 diff --git a/backup/iwjbackup.txt b/backup/iwjbackup.txt index 3b09433..ff4d860 100644 --- a/backup/iwjbackup.txt +++ b/backup/iwjbackup.txt @@ -1,102 +1,76 @@ -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 -# Copyright (C) 1999 Peter Maydell -# -# 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.. 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 -Other lines should be of the form - -for local backups, or - -for remote backups. -The file must end with the word 'end' on a line of its own. - -Valid values for are 'cpio' (uses cpio to produce -tar-format backups), 'dump' (uses dump to dump entire filesystems; - 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.. 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 + Other lines should be of the form + + for local backups, or + + for remote backups. +The file (including any included files) must end with the word 'end' +on a line of its own. + +Valid values for are `cpio' (uses cpio to produce +tar-format backups), `dump' (uses dump to dump entire filesystems; + 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 is ?, ! or nothing, and If 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 -where 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 where 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 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 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 + Copyright (C) 1999 Peter Maydell + +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 +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. diff --git a/debian/changelog b/debian/changelog index 84787d2..d4c9be2 100644 --- a/debian/changelog +++ b/debian/changelog @@ -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. -- -- 2.30.2