pod-man-pages-20051015
authorRuss Allbery <rra@stanford.edu>
Sat, 15 Oct 2005 16:00:57 +0000 (16:00 +0000)
committerDerrick Brashear <shadow@dementia.org>
Sat, 15 Oct 2005 16:00:57 +0000 (16:00 +0000)
FIXES 19268

add pod generation of man pages

166 files changed:
Makefile.in
configure.in
doc/man-pages/Makefile.in [new file with mode: 0644]
doc/man-pages/generate-pod [new file with mode: 0755]
doc/man-pages/pod/afs_intro.pod [new file with mode: 0644]
doc/man-pages/pod/afsd.pod [new file with mode: 0644]
doc/man-pages/pod/afsmonitor.pod [new file with mode: 0644]
doc/man-pages/pod/backup.pod [new file with mode: 0644]
doc/man-pages/pod/backup_adddump.pod [new file with mode: 0644]
doc/man-pages/pod/backup_addhost.pod [new file with mode: 0644]
doc/man-pages/pod/backup_addvolentry.pod [new file with mode: 0644]
doc/man-pages/pod/backup_addvolset.pod [new file with mode: 0644]
doc/man-pages/pod/backup_apropos.pod [new file with mode: 0644]
doc/man-pages/pod/backup_dbverify.pod [new file with mode: 0644]
doc/man-pages/pod/backup_deldump.pod [new file with mode: 0644]
doc/man-pages/pod/backup_deletedump.pod [new file with mode: 0644]
doc/man-pages/pod/backup_delhost.pod [new file with mode: 0644]
doc/man-pages/pod/backup_delvolentry.pod [new file with mode: 0644]
doc/man-pages/pod/backup_delvolset.pod [new file with mode: 0644]
doc/man-pages/pod/backup_diskrestore.pod [new file with mode: 0644]
doc/man-pages/pod/backup_dump.pod [new file with mode: 0644]
doc/man-pages/pod/backup_dumpinfo.pod [new file with mode: 0644]
doc/man-pages/pod/backup_help.pod [new file with mode: 0644]
doc/man-pages/pod/backup_interactive.pod [new file with mode: 0644]
doc/man-pages/pod/backup_jobs.pod [new file with mode: 0644]
doc/man-pages/pod/backup_kill.pod [new file with mode: 0644]
doc/man-pages/pod/backup_labeltape.pod [new file with mode: 0644]
doc/man-pages/pod/backup_listdumps.pod [new file with mode: 0644]
doc/man-pages/pod/backup_listhosts.pod [new file with mode: 0644]
doc/man-pages/pod/backup_listvolsets.pod [new file with mode: 0644]
doc/man-pages/pod/backup_quit.pod [new file with mode: 0644]
doc/man-pages/pod/backup_readlabel.pod [new file with mode: 0644]
doc/man-pages/pod/backup_restoredb.pod [new file with mode: 0644]
doc/man-pages/pod/backup_savedb.pod [new file with mode: 0644]
doc/man-pages/pod/backup_scantape.pod [new file with mode: 0644]
doc/man-pages/pod/backup_setexp.pod [new file with mode: 0644]
doc/man-pages/pod/backup_status.pod [new file with mode: 0644]
doc/man-pages/pod/backup_volinfo.pod [new file with mode: 0644]
doc/man-pages/pod/backup_volrestore.pod [new file with mode: 0644]
doc/man-pages/pod/backup_volsetrestore.pod [new file with mode: 0644]
doc/man-pages/pod/bos.pod [new file with mode: 0644]
doc/man-pages/pod/bos_addhost.pod [new file with mode: 0644]
doc/man-pages/pod/bos_addkey.pod [new file with mode: 0644]
doc/man-pages/pod/bos_adduser.pod [new file with mode: 0644]
doc/man-pages/pod/bos_apropos.pod [new file with mode: 0644]
doc/man-pages/pod/bos_create.pod [new file with mode: 0644]
doc/man-pages/pod/bos_delete.pod [new file with mode: 0644]
doc/man-pages/pod/bos_exec.pod [new file with mode: 0644]
doc/man-pages/pod/bos_getdate.pod [new file with mode: 0644]
doc/man-pages/pod/bos_getlog.pod [new file with mode: 0644]
doc/man-pages/pod/bos_getrestart.pod [new file with mode: 0644]
doc/man-pages/pod/bos_help.pod [new file with mode: 0644]
doc/man-pages/pod/bos_install.pod [new file with mode: 0644]
doc/man-pages/pod/bos_listhosts.pod [new file with mode: 0644]
doc/man-pages/pod/bos_listkeys.pod [new file with mode: 0644]
doc/man-pages/pod/bos_listusers.pod [new file with mode: 0644]
doc/man-pages/pod/bos_prune.pod [new file with mode: 0644]
doc/man-pages/pod/bos_removehost.pod [new file with mode: 0644]
doc/man-pages/pod/bos_removekey.pod [new file with mode: 0644]
doc/man-pages/pod/bos_removeuser.pod [new file with mode: 0644]
doc/man-pages/pod/bos_restart.pod [new file with mode: 0644]
doc/man-pages/pod/bos_salvage.pod [new file with mode: 0644]
doc/man-pages/pod/bos_setauth.pod [new file with mode: 0644]
doc/man-pages/pod/bos_setcellname.pod [new file with mode: 0644]
doc/man-pages/pod/bos_setrestart.pod [new file with mode: 0644]
doc/man-pages/pod/bos_shutdown.pod [new file with mode: 0644]
doc/man-pages/pod/bos_start.pod [new file with mode: 0644]
doc/man-pages/pod/bos_startup.pod [new file with mode: 0644]
doc/man-pages/pod/bos_status.pod [new file with mode: 0644]
doc/man-pages/pod/bos_stop.pod [new file with mode: 0644]
doc/man-pages/pod/bos_uninstall.pod [new file with mode: 0644]
doc/man-pages/pod/bosserver.pod [new file with mode: 0644]
doc/man-pages/pod/buserver.pod [new file with mode: 0644]
doc/man-pages/pod/butc.pod [new file with mode: 0644]
doc/man-pages/pod/dlog.pod [new file with mode: 0644]
doc/man-pages/pod/dpass.pod [new file with mode: 0644]
doc/man-pages/pod/fileserver.pod [new file with mode: 0644]
doc/man-pages/pod/fms.pod [new file with mode: 0644]
doc/man-pages/pod/fs.pod [new file with mode: 0644]
doc/man-pages/pod/fs_apropos.pod [new file with mode: 0644]
doc/man-pages/pod/fs_checkservers.pod [new file with mode: 0644]
doc/man-pages/pod/fs_checkvolumes.pod [new file with mode: 0644]
doc/man-pages/pod/fs_cleanacl.pod [new file with mode: 0644]
doc/man-pages/pod/fs_copyacl.pod [new file with mode: 0644]
doc/man-pages/pod/fs_diskfree.pod [new file with mode: 0644]
doc/man-pages/pod/fs_examine.pod [new file with mode: 0644]
doc/man-pages/pod/fs_exportafs.pod [new file with mode: 0644]
doc/man-pages/pod/fs_flush.pod [new file with mode: 0644]
doc/man-pages/pod/fs_flushmount.pod [new file with mode: 0644]
doc/man-pages/pod/fs_flushvolume.pod [new file with mode: 0644]
doc/man-pages/pod/fs_getcacheparms.pod [new file with mode: 0644]
doc/man-pages/pod/fs_getcellstatus.pod [new file with mode: 0644]
doc/man-pages/pod/fs_getclientaddrs.pod [new file with mode: 0644]
doc/man-pages/pod/fs_getserverprefs.pod [new file with mode: 0644]
doc/man-pages/pod/fs_help.pod [new file with mode: 0644]
doc/man-pages/pod/fs_listacl.pod [new file with mode: 0644]
doc/man-pages/pod/fs_listcells.pod [new file with mode: 0644]
doc/man-pages/pod/fs_listquota.pod [new file with mode: 0644]
doc/man-pages/pod/fs_lsmount.pod [new file with mode: 0644]
doc/man-pages/pod/fs_messages.pod [new file with mode: 0644]
doc/man-pages/pod/fs_mkmount.pod [new file with mode: 0644]
doc/man-pages/pod/fs_newcell.pod [new file with mode: 0644]
doc/man-pages/pod/fs_quota.pod [new file with mode: 0644]
doc/man-pages/pod/fs_rmmount.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setacl.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setcachesize.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setcell.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setclientaddrs.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setquota.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setserverprefs.pod [new file with mode: 0644]
doc/man-pages/pod/fs_setvol.pod [new file with mode: 0644]
doc/man-pages/pod/fs_storebehind.pod [new file with mode: 0644]
doc/man-pages/pod/fs_sysname.pod [new file with mode: 0644]
doc/man-pages/pod/fs_whereis.pod [new file with mode: 0644]
doc/man-pages/pod/fs_whichcell.pod [new file with mode: 0644]
doc/man-pages/pod/fs_wscell.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_apropos.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_clear.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_dump.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_help.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_lslog.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_lsset.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_setlog.pod [new file with mode: 0644]
doc/man-pages/pod/fstrace_setset.pod [new file with mode: 0644]
doc/man-pages/pod/kadb_check.pod [new file with mode: 0644]
doc/man-pages/pod/kas.pod [new file with mode: 0644]
doc/man-pages/pod/kas_apropos.pod [new file with mode: 0644]
doc/man-pages/pod/kas_create.pod [new file with mode: 0644]
doc/man-pages/pod/kas_delete.pod [new file with mode: 0644]
doc/man-pages/pod/kas_examine.pod [new file with mode: 0644]
doc/man-pages/pod/kas_forgetticket.pod [new file with mode: 0644]
doc/man-pages/pod/kas_help.pod [new file with mode: 0644]
doc/man-pages/pod/kas_interactive.pod [new file with mode: 0644]
doc/man-pages/pod/kas_list.pod [new file with mode: 0644]
doc/man-pages/pod/kas_listtickets.pod [new file with mode: 0644]
doc/man-pages/pod/kas_noauthentication.pod [new file with mode: 0644]
doc/man-pages/pod/kas_quit.pod [new file with mode: 0644]
doc/man-pages/pod/kas_setfields.pod [new file with mode: 0644]
doc/man-pages/pod/kas_setpassword.pod [new file with mode: 0644]
doc/man-pages/pod/kas_statistics.pod [new file with mode: 0644]
doc/man-pages/pod/kas_stringtokey.pod [new file with mode: 0644]
doc/man-pages/pod/kas_unlock.pod [new file with mode: 0644]
doc/man-pages/pod/kaserver.pod [new file with mode: 0644]
doc/man-pages/pod/kdb.pod [new file with mode: 0644]
doc/man-pages/pod/klog.pod [new file with mode: 0644]
doc/man-pages/pod/knfs.pod [new file with mode: 0644]
doc/man-pages/pod/kpasswd.pod [new file with mode: 0644]
doc/man-pages/pod/kpwvalid.pod [new file with mode: 0644]
doc/man-pages/pod/pts.pod [new file with mode: 0644]
doc/man-pages/pod/pts_adduser.pod [new file with mode: 0644]
doc/man-pages/pod/pts_apropos.pod [new file with mode: 0644]
doc/man-pages/pod/pts_chown.pod [new file with mode: 0644]
doc/man-pages/pod/pts_creategroup.pod [new file with mode: 0644]
doc/man-pages/pod/pts_createuser.pod [new file with mode: 0644]
doc/man-pages/pod/pts_delete.pod [new file with mode: 0644]
doc/man-pages/pod/pts_examine.pod [new file with mode: 0644]
doc/man-pages/pod/pts_help.pod [new file with mode: 0644]
doc/man-pages/pod/pts_listentries.pod [new file with mode: 0644]
doc/man-pages/pod/pts_listmax.pod [new file with mode: 0644]
doc/man-pages/pod/pts_listowned.pod [new file with mode: 0644]
doc/man-pages/pod/pts_membership.pod [new file with mode: 0644]
doc/man-pages/pod/pts_removeuser.pod [new file with mode: 0644]
doc/man-pages/pod/pts_rename.pod [new file with mode: 0644]
doc/man-pages/pod/pts_setfields.pod [new file with mode: 0644]
doc/man-pages/pod/pts_setmax.pod [new file with mode: 0644]

index 851bd33..e6d1b81 100644 (file)
@@ -340,6 +340,11 @@ login: cmd comerr kauth rxkad pam sia tsm41 sgistuff aklog
                echo Skipping login for ${SYS_NAME} ; \
        fi
 
+man-pages:
+       if test -d "doc/man-pages" ; then \
+               cd doc/man-pages ${COMPILE_PART2} ; \
+       fi
+
 #
 # _depinstall targets - only build and install headers/sources that are needed by libafs/libuafs
 #
@@ -566,13 +571,13 @@ jafsadm: libjafsadm
 finale: project cmd comerr afsd butc tbutc @ENABLE_KERNEL_MODULE@ libuafs audit kauth log package \
        ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \
        venus update xstat afsmonitor dauth rxdebug libafsrpc \
-       libafsauthent shlibafsrpc shlibafsauthent libadmin login
+       libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages
        ${COMPILE_PART1} finale ${COMPILE_PART2}
 
 finale_nolibafs: project cmd comerr afsd butc tbutc libuafs audit kauth log package \
        ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \
        venus update xstat afsmonitor dauth rxdebug libafsrpc \
-       libafsauthent shlibafsrpc shlibafsauthent libadmin login
+       libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages
        ${COMPILE_PART1} finale ${COMPILE_PART2}
 
 # Use washtool to ensure MakefileProto is current and obj/libafs exists.
@@ -807,6 +812,7 @@ distclean: clean
        src/wsadmin.src/Makefile \
        src/xstat/Makefile  \
        src/helper-splint.sh
+       if test -d doc/man-pages ; then rm -f doc/man-pages/Makefile ; fi
 
 pristine: distclean
        /bin/rm -f src/config/afsconfig.h.in configure configure-libafs aclocal.m4
index 8be34e7..a6ca110 100644 (file)
@@ -5,8 +5,15 @@ AC_CONFIG_HEADER(src/config/afsconfig.h)
 AC_PROG_CC
 OPENAFS_CONFIGURE_COMMON
 
+if test -d 'doc/man-pages' ; then
+    MAN_MAKEFILE=doc/man-pages/Makefile
+else
+    MAN_MAKEFILE=
+fi
+
 AC_OUTPUT(             \
 Makefile               \
+${MAN_MAKEFILE} \
 src/afs/Makefile \
 src/afsd/Makefile \
 src/afsmonitor/Makefile \
diff --git a/doc/man-pages/Makefile.in b/doc/man-pages/Makefile.in
new file mode 100644 (file)
index 0000000..bcad3ea
--- /dev/null
@@ -0,0 +1,199 @@
+# Makefile for AFS man pages
+
+srcdir=@srcdir@
+include @TOP_OBJDIR@/src/config/Makefile.config
+
+MAN1 = \
+       afs_intro.1             \
+       fs.1                    \
+       fs_apropos.1            \
+       fs_checkservers.1       \
+       fs_checkvolumes.1       \
+       fs_cleanacl.1           \
+       fs_copyacl.1            \
+       fs_diskfree.1           \
+       fs_examine.1            \
+       fs_exportafs.1          \
+       fs_flush.1              \
+       fs_flushmount.1         \
+       fs_flushvolume.1        \
+       fs_getcacheparms.1      \
+       fs_getcellstatus.1      \
+       fs_getclientaddrs.1     \
+       fs_getserverprefs.1     \
+       fs_help.1               \
+       fs_listacl.1            \
+       fs_listcells.1          \
+       fs_listquota.1          \
+       fs_lsmount.1            \
+       fs_messages.1           \
+       fs_mkmount.1            \
+       fs_newcell.1            \
+       fs_quota.1              \
+       fs_rmmount.1            \
+       fs_setacl.1             \
+       fs_setcachesize.1       \
+       fs_setcell.1            \
+       fs_setclientaddrs.1     \
+       fs_setquota.1           \
+       fs_setserverprefs.1     \
+       fs_setvol.1             \
+       fs_storebehind.1        \
+       fs_sysname.1            \
+       fs_whereis.1            \
+       fs_whichcell.1          \
+       fs_wscell.1             \
+       klog.1                  \
+       kpasswd.1               \
+       kpwvalid.1              \
+       pts.1                   \
+       pts_adduser.1           \
+       pts_apropos.1           \
+       pts_chown.1             \
+       pts_creategroup.1       \
+       pts_createuser.1        \
+       pts_delete.1            \
+       pts_examine.1           \
+       pts_help.1              \
+       pts_listentries.1       \
+       pts_listmax.1           \
+       pts_listowned.1         \
+       pts_membership.1        \
+       pts_removeuser.1        \
+       pts_rename.1            \
+       pts_setfields.1         \
+       pts_setmax.1
+
+MAN8 = \
+       afsd.8                  \
+       afsmonitor.8            \
+       backup.8                \
+       backup_adddump.8        \
+       backup_addhost.8        \
+       backup_addvolentry.8    \
+       backup_addvolset.8      \
+       backup_apropos.8        \
+       backup_dbverify.8       \
+       backup_deldump.8        \
+       backup_deletedump.8     \
+       backup_delhost.8        \
+       backup_delvolentry.8    \
+       backup_delvolset.8      \
+       backup_diskrestore.8    \
+       backup_dump.8           \
+       backup_dumpinfo.8       \
+       backup_help.8           \
+       backup_interactive.8    \
+       backup_jobs.8           \
+       backup_kill.8           \
+       backup_labeltape.8      \
+       backup_listdumps.8      \
+       backup_listhosts.8      \
+       backup_listvolsets.8    \
+       backup_quit.8           \
+       backup_readlabel.8      \
+       backup_restoredb.8      \
+       backup_savedb.8         \
+       backup_scantape.8       \
+       backup_setexp.8         \
+       backup_status.8         \
+       backup_volinfo.8        \
+       backup_volrestore.8     \
+       backup_volsetrestore.8  \
+       bos.8                   \
+       bos_addhost.8           \
+       bos_addkey.8            \
+       bos_adduser.8           \
+       bos_apropos.8           \
+       bos_create.8            \
+       bos_delete.8            \
+       bos_exec.8              \
+       bos_getdate.8           \
+       bos_getlog.8            \
+       bos_getrestart.8        \
+       bos_help.8              \
+       bos_install.8           \
+       bos_listhosts.8         \
+       bos_listkeys.8          \
+       bos_listusers.8         \
+       bos_prune.8             \
+       bos_removehost.8        \
+       bos_removekey.8         \
+       bos_removeuser.8        \
+       bos_restart.8           \
+       bos_salvage.8           \
+       bos_setauth.8           \
+       bos_setcellname.8       \
+       bos_setrestart.8        \
+       bos_shutdown.8          \
+       bos_start.8             \
+       bos_startup.8           \
+       bos_status.8            \
+       bos_stop.8              \
+       bos_uninstall.8         \
+       bosserver.8             \
+       buserver.8              \
+       butc.8                  \
+       dlog.8                  \
+       dpass.8                 \
+       fileserver.8            \
+       fms.8                   \
+       fstrace.8               \
+       fstrace_apropos.8       \
+       fstrace_clear.8         \
+       fstrace_dump.8          \
+       fstrace_help.8          \
+       fstrace_lslog.8         \
+       fstrace_lsset.8         \
+       fstrace_setlog.8        \
+       fstrace_setset.8        \
+       kadb_check.8            \
+       kas.8                   \
+       kas_apropos.8           \
+       kas_create.8            \
+       kas_delete.8            \
+       kas_examine.8           \
+       kas_forgetticket.8      \
+       kas_help.8              \
+       kas_interactive.8       \
+       kas_list.8              \
+       kas_listtickets.8       \
+       kas_noauthentication.8  \
+       kas_quit.8              \
+       kas_setfields.8         \
+       kas_setpassword.8       \
+       kas_statistics.8        \
+       kas_stringtokey.8       \
+       kas_unlock.8            \
+       kaserver.8              \
+       kdb.8                   \
+       knfs.8
+
+all: $(MAN1) $(MAN8)
+
+%.1: $(srcdir)/pod/%.pod
+       pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 $< $@
+
+%.8: $(srcdir)/pod/%.pod
+       pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 $< $@
+
+clean:
+       rm -f *.1 *.8
+
+dest: $(MAN1) $(MAN8)
+       mkdir -p $(DEST)/man/man1 $(DEST)/man/man8
+       set -e; for M in $(MAN1) ; do \
+           $(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \
+       done
+       set -e; for M in $(MAN8) ; do \
+           $(INSTALL) -c -m 0644 $$M $(DEST)/man/man8/$$M ; \
+       done
+
+install: $(MAN1) $(MAN8)
+       mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man8
+       set -e; for M in $(MAN1) ; do \
+           $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \
+       done
+       set -e; for M in $(MAN8) ; do \
+           $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \
+       done
diff --git a/doc/man-pages/generate-pod b/doc/man-pages/generate-pod
new file mode 100755 (executable)
index 0000000..706d14d
--- /dev/null
@@ -0,0 +1,178 @@
+#!/usr/bin/perl -w
+#
+# Parser for files obtained via
+# lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt
+
+use strict;
+my $DEBUG = 0;
+my $RAW = 0;
+
+my %hash;
+my %options;
+
+######################################################################
+## Input Section:
+######################################################################
+
+my $del = $/;
+undef $/;
+my $text = <STDIN>;
+$/ = $del;
+
+my $sections = 'Purpose|Synopsis|Description|Cautions|Options|Output|Examples|Privilege\ Required|Related\ Information|References';
+
+$text =~ s/^.*\[7\]\s*(.+?)\n//xs;
+
+$hash{Command} = $1;
+my $Cmd_fam = "backup|bos|fs|kas|pts|uss|vos";
+$Cmd_fam .= '|' . (split(" ", $hash{Command}))[0];
+
+while ($text !~ /^\s+$/xs) {
+  $text =~ s/($sections)(.*?)(\n\s*(?:$sections)\n\s*|$)/$3/xs;
+  $hash{$1} = $2;
+}
+
+$hash{'Related Information'} =~ s/\s*(.+?)\s*___________.*$/$1/xs;
+
+
+
+if (! $RAW) {
+  ######################################################################
+  ## Clean-up Section:
+  ######################################################################
+
+  # make C<pts adduser> out of pts adduser:
+  $hash{Description} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Description});
+  $hash{Options}     =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Options});
+
+  # strip leading and trailing whitespace:
+  my $pattern = '^\s*(.*?)\s*$';
+  foreach (keys(%hash)) {
+    $hash{$_} =~ s/$pattern/$1/sxg;
+    $hash{$_} =~ s/\n\ +/\n/sxg;
+    $hash{$_} =~ s/((?:$Cmd_fam)\s?\w*)(\s)reference(\s)page/L<$1(1)>$2reference$3page/g;
+    $hash{$_} =~ s/the(\s)(\w+(?:\s\w+)?)(\s)reference(\s)page/the$1L<$2(1)>$3reference$4page/g;
+    $hash{$_} =~ s/(\(?\b(?:$Cmd_fam)\)?\s?\w*)(\s)command/C<$1>$2command/g;
+    $hash{$_} =~ s/the(\s)(\w+)(\s)command/the$1C<$2>$3command/g;
+    $hash{$_} =~ s/\n\*\ /\n\n=item \*\n\n/g;
+    $hash{$_} =~ s/\n\+\ /\n\n=item \*\n\n/g;
+    $hash{$_} =~ s"(\s)((?:/\w+)+)"$1B<$2>"g if($_ ne "Synopsis");
+    $hash{$_} =~ s/(superuser\s)root/$1B<root>/g;
+    $hash{$_} =~ s/(unprivileged\s(?:identity|user)\s)anonymous/$1B<anonymous>/g;
+    $hash{$_} =~ s/system\:administrators/B<system:administrators>/g;
+    $hash{$_} =~ s/(\s)(\w)(\s)\((\w+)\)(\s)/$1B<$2>$3(B<$4>)$5/g;
+  }
+
+  ######################################################################
+  ## POD-ify Section:
+  ######################################################################
+
+  # Make B<-group> out of -group:
+  $hash{Synopsis}    =~ s/(\s|^|\[)(-\w+)\b/$1B<$2>/g if ($hash{Synopsis});
+  $hash{Description} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Description});
+  $hash{Options}     =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Options});
+  $hash{Output}      =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Output});
+  $hash{Cautions}      =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Cautions});
+  $hash{'Privilege Required'}      =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{'Privilege Required'});
+
+  $hash{Description} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Description});
+  $hash{Options} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Options});
+  $hash{Output} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Output});
+  $hash{'Privilege Required'} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{'Privilege Required'});
+  $hash{Cautions} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Cautions});
+
+  $hash{Synopsis} =~ s/<([^>]*?)>\^\+/I<$1> [I<$1> ...]/g if ($hash{Synopsis});
+  $hash{Synopsis} =~ s/( |\n)<(.*?)>/$1I<$2>/g if ($hash{Synopsis});
+  $text = $hash{Synopsis};
+  while ($text && $text =~ /B<-\w+> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?/s) {
+    $text =~ s/B<(-\w+)> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?//s;
+    if ($2) {
+      $options{$1} = ' '.$2;
+    } else {
+      $options{$1} = "";
+    }
+  }
+
+  $hash{Options} =~ s/(?:\n|^)B<([^>]*?)>\ \n/\n=item B<$1>$options{$1}\n\n/sxg if ($hash{Options});
+
+  $hash{Examples} =~ s/\n\s*%(.*?)(?:\n|$)/\n\nB<\ \ \ $1>\n/sxg if ($hash{Examples});
+
+  $hash{'Related Information'} =~ s/\[\d+\](.*?)\s*\n/L<$1(1)>,\n/msxg if ($hash{'Related Information'});
+  $hash{'Related Information'} =~ s/\[\d+\](.*)\s*/L<$1(1)>/msxg if ($hash{'Related Information'});
+  $hash{'Related Information'} =~ s/(\w+)\s+(\w+)/$1_$2/msxg if ($hash{'Related Information'});
+
+  foreach (keys(%hash)) {
+    $hash{$_} =~ s/((?:\n\n=item\ \*\n(?:\n.+$)+)+)/\n\n=over$1\n\n=back/mxg;
+  }
+
+
+};
+
+
+######################################################################
+## Output Section:
+######################################################################
+
+my $file;
+($file = $hash{Command} . ".pod") =~ s/\s/_/g;
+
+my $FH;
+if ($DEBUG) {
+  $FH = *STDOUT
+} else {
+  open(FILE, "> $file") || die("Could not open $file\n");
+  $FH = *FILE;
+}
+
+print $FH "=head1 NAME\n\n";
+print $FH "$hash{Command} - $hash{Purpose}\n\n";
+
+if (exists $hash{Synopsis}) {
+  print $FH "=head1 SYNOPSIS\n\n";
+  print $FH "$hash{Synopsis}\n\n";
+}
+
+print $FH "=head1 DESCRIPTION\n\n";
+print $FH "$hash{Description}\n\n";
+
+if (exists $hash{Options}) {
+  print $FH "=head1 OPTIONS\n\n";
+  print $FH "=over 4\n";
+  print $FH "$hash{Options}\n\n";
+  print $FH "=back\n\n";
+}
+
+if (exists $hash{Output}) {
+  print $FH "=head1 OUTPUT\n\n";
+  print $FH "$hash{Output}\n\n";
+}
+
+if (exists $hash{Examples}) {
+  print $FH "=head1 EXAMPLES\n\n";
+  print $FH "$hash{Examples}\n\n";
+}
+
+if (exists $hash{'Privilege Required'}) {
+  print $FH "=head1 PRIVILEGE REQUIRED\n\n";
+  print $FH "$hash{'Privilege Required'}\n\n";
+}
+
+if (exists $hash{Cautions}) {
+  print $FH "=head1 CAVEATS\n\n";
+  print $FH "$hash{Cautions}\n\n";
+}
+
+print $FH "=head1 COPYRIGHT\n\n";
+print $FH "IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.\n\n";
+print $FH "Converted from html to pod by Alf Wachsmann <alfw\@slac.stanford.edu>, 2003,\n";
+print $FH "and Elizabeth Cassell <e_a_c\@mailsnare.net>, 2004,\n";
+print $FH "Stanford Linear Accelerator Center, a department of Stanford University.\n\n";
+
+if (exists $hash{'Related Information'}) {
+  print $FH "=head1 SEE ALSO\n\n";
+  print $FH "$hash{'Related Information'}\n\n";
+  print $FH "=cut\n";
+}
+
+close(FILE) unless $DEBUG;
+
diff --git a/doc/man-pages/pod/afs_intro.pod b/doc/man-pages/pod/afs_intro.pod
new file mode 100644 (file)
index 0000000..43d43c9
--- /dev/null
@@ -0,0 +1,570 @@
+=head1 NAME
+
+afs_intro - Introduction to AFS commands
+
+=head1 DESCRIPTION
+
+AFS provides many commands that enable users and system administrators
+to use and customize its features. Many of the commands belong to the
+following categories, called command suites.
+
+=over
+
+=item B<backup>
+
+Interface for configuring and operating the AFS Backup System
+
+=item B<bos>
+
+Interface to the Basic Overseer (BOS) Server for administering
+server processes and configuration files
+
+=item B<fs>
+
+Interface for administering access control lists (ACLs), the
+Cache Manager, and other miscellaneous file system functions
+
+=item B<fstrace>
+
+Interface for tracing Cache Manager operations when debugging
+problems
+
+=item B<kas>
+
+Interface to the Authentication Server for administering
+security and authentication information
+
+=item B<pts>
+
+Interface to the Protection Server for administering AFS ID and
+group membership information
+
+=item B<uss>
+
+Interface for automated administration of user accounts
+
+=item B<vos>
+
+Interface to the Volume Server and Volume Location (VL) Server
+for administering volumes
+
+=back
+
+In addition, there are several commands that do not belong to suites.
+
+=head2 AFS Command Syntax
+
+AFS commands that belong to suites have the following structure:
+
+B<command_suite> B<operation_code> B<-switch> I<value> [I<value> ...]  [B<-flag>]
+
+=head2 Command Names
+
+Together, the B<command_suite> and B<operation_code> make up the command
+name.
+
+The B<command_suite> specifies the group of related commands to which the
+command belongs, and indicates which command interpreter and server
+process perform the command. AFS has several command suites, including
+B<bos>, B<fs>, B<kas>, B<package>, B<pts>, B<scout>, B<uss> and B<vos>. Some of these suites
+have an interactive mode in which the issuer omits the B<command_suite>
+portion of the command name.
+
+The B<operation_code> tells the command interpreter and server process
+which action to perform. Most command suites include several operation
+codes. The IBM AFS Administration Reference describes each operation
+code in detail, and the IBM AFS Administration Guide describes how to
+use them in the context of performing administrative tasks.
+
+Several AFS commands do not belong to a suite and so their names do
+not have a B<command_suite> portion. Their structure is otherwise similar
+to the commands in the suites.
+
+=head1 OPTIONS
+
+The term option refers to both arguments and flags, which are
+described in the following sections.
+
+=head2 Arguments
+
+One or more arguments can follow the command name. Arguments specify
+the entities on which to act while performing the command (for
+example, which server machine, server process, or file). To minimize
+the potential for error, provide a command's arguments in the order
+prescribed in its syntax definition.
+
+Each argument has two parts, which appear in the indicated order:
+
+=over
+
+=item *
+
+The switch specifies the argument's type and is preceded by a
+hyphen ( B<-> ). For instance, the switch B<-server> usually indicates
+that the argument names a server machine. Switches can often be
+omitted, subject to the rules outlined in L</"Conditions for
+Omitting Switches">.
+
+=item *
+
+The I<value> names a particular entity of the type specified by the
+preceding switch. For example, the proper value for a B<-server>
+switch is a server machine name like B<fs3.abc.com>. Unlike switches
+(which have a required form), values vary depending on what the
+issuer wants to accomplish. Values appear surrounded by angle
+brackets (B<E<lt> E<gt>>) in command descriptions and the online help to show
+that they are user-supplied variable information.
+
+=back
+
+Some arguments accept multiple values, as indicated by trailing ellipsis
+( B<...> ) in the command descriptions and online help. How many of a
+command's arguments take multiple values, and their ordering with
+respect to other arguments, determine when it is acceptable to omit
+switches. See L</"Conditions for Omitting Switches">.
+
+Some commands have optional as well as required arguments; the command
+descriptions and online help show optional arguments in square
+brackets ([ ]).
+
+=head2 Flags
+
+Some commands have one or more flags, which specify the manner in
+which the command interpreter and server process perform the command,
+or what kind of output it produces. Flags are preceded by hyphens like
+switches, but they take no values. Although the command descriptions
+and online help generally list a command's flags after its arguments,
+there is no prescribed order for flags. They can appear anywhere on
+the command line following the operation code, except in between the
+parts of an argument. Flags are always optional.
+
+=head2 An Example Command
+
+The following example illustrates the different parts of a command
+that belongs to an AFS command suite.
+
+   bos getdate -server fs1.abc.com -file ptserver kaserver 
+
+where
+
+=over
+
+=item *
+
+B<bos> is the command suite. The BOS Server executes most of the
+commands in this suite.
+
+=item *
+
+B<getdate> is the operation code. It tells the BOS Server on the
+specified server machine (in this case B<fs1.abc.com>) to report the
+modification dates of binary files in the local B</usr/afs/bin>
+directory.
+
+=item *
+
+B<-server> B<fs1.abc.com> is one argument, with B<-server> as the switch
+and B<fs1.abc.com> as the value. This argument specifies the server
+machine on which BOS Server is to collect and report binary dates.
+
+=item *
+
+B<-file> B<ptserver> B<kaserver> is an argument that takes multiple values.
+The switch is B<-file> and the values are B<ptserver> and B<kaserver>. This
+argument tells the BOS Server to report the modification dates on
+the files B</usr/afs/bin/kaserver> and B</usr/afs/bin/ptserver>.
+
+=back
+
+=head2 Rules for Entering AFS Commands
+
+Enter each AFS command on a single line (press B<E<lt>ReturnE<gt>> only at the
+end of the command). Some commands in this document appear broken
+across multiple lines, but that is for legibility only.
+
+Use a space to separate each element on a command line from its
+neighbors. Spaces rather than commas also separate multiple values of
+an argument.
+
+In many cases, the issuer of a command can reduce the amount of typing
+necessary by using one or both of the following methods:
+
+=over
+
+=item *
+
+Omitting switches
+
+=item *
+
+Using accepted abbreviations for operation codes, switches (if
+they are included at all), and some types of values
+
+=back
+
+The following sections explain the conditions for omitting or
+shortening parts of the command line. It is always acceptable to type
+a command in full, with all of its switches and no abbreviations.
+
+=head3 Conditions for Omitting Switches
+
+It is always acceptable to type the switch part of an argument, but in
+many cases it is not necessary. Specifically, switches can be omitted
+if the following conditions are met.
+
+=over
+
+=item *
+
+All of the command's required arguments appear in the order
+prescribed by the syntax statement
+
+=item *
+
+No switch is provided for any argument
+
+=item *
+
+There is only one value for each argument (but note the important
+exception discussed in the following paragraph)
+
+=back
+
+Omitting switches is possible only because there is a prescribed order
+for each command's arguments. When the issuer does not include
+switches, the command interpreter relies instead on the order of
+arguments; it assumes that the first element after the operation code
+is the command's first argument, the next element is the command's
+second argument, and so on. The important exception is when a
+command's final required argument accepts multiple values. In this
+case, the command interpreter assumes that the issuer has correctly
+provided one value for each argument up through the final one, so any
+additional values at the end belong to the final argument.
+
+The following list describes the rules for omitting switches from the
+opposite perspective: an argument's switch must be provided when any
+of the following conditions apply.
+
+=over
+
+=item *
+
+The command's arguments do not appear in the prescribed order
+
+=item *
+
+An optional argument is omitted but a subsequent optional argument
+is provided
+
+=item *
+
+A switch is provided for a preceding argument
+
+=item *
+
+More than one value is supplied for a preceding argument (which
+must take multiple values, of course); without a switch on the
+current argument, the command interpreter assumes that the current
+argument is another value for the preceding argument
+
+=back
+
+=head3 An Example of Omitting Switches
+
+Consider again the example command from L</"An Example Command">.
+
+   bos getdate -server fs1.abc.com -file ptserver kaserver
+
+This command has two required arguments: the server machine name
+(identified by the B<-server> switch) and binary file name (identified by
+the B<-file> switch). The second argument accepts multiple values. By
+complying with all three conditions, the issuer can omit the switches:
+
+   bos getdate fs1.abc.com ptserver kaserver
+
+Because there are no switches, the C<bos> command interpreter relies on
+the order of arguments. It assumes that the first element following
+the operation code, B<fs1.abc.com>, is the server machine name, and that
+the next argument, B<ptserver>, is a binary file name. Then, because the
+command's second (and last) argument accepts multiple values, the
+command interpreter correctly interprets B<kaserver> as an additional
+value for it.
+
+On the other hand, the following is not acceptable because it violates
+the first two conditions in L</"Conditions for Omitting Switches">: even
+though there is only one value per argument, the arguments do not
+appear in the prescribed order, and a switch is provided for one
+argument but not the other.
+
+   bos getdate ptserver -server fs1.abc.com
+
+=head2 Rules for Using Abbreviations and Aliases
+
+This section explains how to abbreviate operation codes, option names,
+server machine names, partition names, and cell names. It is not
+possible to abbreviate other types of values.
+
+=head3 Abbreviating Operation Codes
+
+It is acceptable to abbreviate an operation code to the shortest form
+that still distinguishes it from the other operation codes in its suite.
+
+For example, it is acceptable to shorten bos install to bos i because
+there are no other operation codes in the bos command suite that begin
+with the letter i. In contrast, there are several bos operation codes
+that start with the letter s, so the abbreviations must be longer to
+remain unambiguous:
+
+C<bos sa> for C<bos salvage>
+
+C<bos seta> for C<bos setauth>
+
+C<bos setc> for C<bos setcellname>
+
+C<bos setr> for C<bos setrestart>
+
+C<bos sh> for C<bos shutdown>
+
+C<bos start> for C<bos start>
+
+C<bos startu> for C<bos startup>
+
+C<bos stat> for C<bos status>
+
+C<bos sto> for C<bos stop>
+
+In addition to abbreviations, some operation codes have an I<alias>, a
+short form that is not derived by abbreviating the operation code to
+its shortest unambiguous form. For example, the alias for the C<fs
+setacl> command is C<fs sa>, whereas the shortest unambiguous abbreviation
+is C<fs seta>.
+
+There are two usual reasons an operation code has an alias:
+
+=over
+
+=item *
+
+Because the command is frequently issued, it is convenient to have
+a form shorter than the one derived by abbreviating. The C<fs setacl>
+command is an example.
+
+=item *
+
+Because the command's name has changed, but users of previous
+versions of AFS know the former name. For example, C<bos listhosts>
+has the alias C<bos getcell>, its former name. It is acceptable to
+abbreviate aliases to their shortest unambiguous form (for
+example, C<bos getcell> to C<bos getc>).
+
+=back
+
+Even if an operation code has an alias, it is still acceptable to use
+the shortest unambiguous form. Thus, the C<fs setacl> command has three
+acceptable forms: C<fs setacl> (the full form), C<fs seta> (the shortest
+abbreviation), and C<fs sa> (the alias).
+
+=head3 Abbreviating Switches and Flags
+
+It is acceptable to shorten a switch or flag to the shortest form that
+distinguishes it from the other switches and flags for its operation
+code. It is often possible to omit switches entirely, subject to the
+conditions listed in L</"Conditions for Omitting Switches">.
+
+=head3 Abbreviating Server Machine Names
+
+AFS server machines must have fully-qualified Internet-style host
+names (for example, B<fs1.abc.com>), but it is not always necessary to
+type the full name on the command line. AFS commands accept
+unambiguous shortened forms, but depend on the cell's name service
+(such as the Domain Name Service) or a local host table to resolve a
+shortened name to the fully-qualified equivalent when the command is
+issued.
+
+Most commands also accept the dotted decimal form of the machine's IP
+address as an identifier.
+
+=head3 Abbreviating Partition Names
+
+Partitions that house AFS volumes must have names of the form
+B</vicep>I<x> or B</vicep>I<xx>, where the variable final portion is one or
+two lowercase letters. By convention, the first server partition
+created on a file server machine is called B</vicepa>, the second
+B</vicepb>, and so on. The IBM AFS Quick Beginnings explains how to
+configure and name a file server machine's partitions in
+preparation for storing AFS volumes on them.
+
+When issuing AFS commands, you can abbreviate a partition name using
+any of the following forms:
+
+   /vicepa     =     vicepa      =      a      =      0
+   /vicepb     =     vicepb      =      b      =      1
+
+After B</vicepz> (for which the index is 25) comes
+
+   /vicepaa    =     vicepaa     =      aa     =      26
+   /vicepab    =     vicepab     =      ab     =      27
+
+and so on through
+
+   /vicepiv    =     vicepiv     =      iv     =      255
+
+=head3 Abbreviating Cell Names
+
+A cell's full name usually matches its Internet domain name (such
+as B<stateu.edu> for the State University or B<abc.com> for ABC Corporation).
+Some AFS commands accept unambiguous shortened forms, usually with
+respect to the local B</usr/vice/etc/CellServDB> file but sometimes
+depending on the ability of the local name service to resolve the
+corresponding domain name.
+
+=head2 Displaying Online Help for AFS Commands
+
+To display online help for AFS commands that belong to suites, use the
+C<help> and C<apropos> operation codes. A B<-help> flag is also available on
+almost every AFS command.
+
+The online help entry for a command consists of two or three lines:
+
+=over
+
+=item *
+
+The first line names the command and briefly describes what it
+does
+
+=item *
+
+If the command has aliases, they appear on the next line
+
+=item *
+
+The final line, which begins with the string C<Usage:>, lists the
+command's options in the prescribed order; online help entries use
+the same typographical symbols (brackets and so on) as this
+documentation.
+
+=back
+
+If no operation code is specified, the B<help> operation code displays
+the first line (short description) for every operation code in the
+suite:
+
+   command_suite  help
+
+If the issuer specifies one or more operation codes, the help
+operation code displays each command's complete online entry (short
+description, alias if any, and syntax):
+
+   command_suite help operation_code [operation_code ...]
+
+The B<-help> flag displays a command's syntax but not the short
+description or alias:
+
+   command_name -help
+
+The B<apropos> operation code displays the short description of any
+command in a suite whose operation code or short description includes
+the specified keyword:
+
+   command_suite apropos "help string"
+
+The following example command displays the complete online help entry
+for the C<fs setacl> command:
+
+    fs help setacl 
+   fs setacl: set access control list
+   aliases: sa
+   Usage: fs setacl B<-dir> <directory>+ B<-acl> <access list entries>+
+   [-clear] [-negative] [-id] [-if] [-help]
+
+To see only the syntax statement, use the B<-help> flag:
+
+    fs setacl B<-help>
+   Usage: fs setacl B<-dir> <directory>+ B<-acl> <access list entries>+
+   [-clear] [-negative] [-id] [-if] [-help]
+
+In the following example, a user wants to display the quota for her
+home volume. She knows that the relevant command belongs to the C<fs>
+suite, but cannot remember the operation code. She uses C<quota> as the
+keyword:
+
+    fs apropos quota
+   listquota: list volume quota
+   quota: show volume quota usage
+   setquota: set volume quota
+
+The following illustrates the error message that results if no command
+name or short description contains the keyword:
+
+    fs apropos "list quota"
+   Sorry, no commands found
+
+=head1 PRIVILEGE REQUIRED
+
+Many AFS commands require one or more types of administrative
+privilege. See the reference page for each command.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<afsd(1)>,
+L<afsmonitor(1)>,
+L<backup(1)>,
+L<bos(1)>,
+L<bosserver(1)>,
+L<buserver(1)>,
+L<butc(1)>,
+L<dlog(1)>,
+L<dpass(1)>,
+L<fileserver(1)>,
+L<fms(1)>,
+L<fs(1)>,
+L<fstrace(1)>,
+L<ftpd_AFS_version(1)>,
+L<inetd_AFS_version(1)>,
+L<kadb_check(1)>,
+L<kas(1)>,
+L<kaserver(1)>,
+L<kdb(1)>,
+L<klog(1)>,
+L<knfs(1)>,
+L<kpasswd(1)>,
+L<kpwvalid(1)>,
+L<package(1)>,
+L<package(1)>,
+L<package_test(1)>,
+L<pagsh(1)>,
+L<prdb_check(1)>,
+L<pts(1)>,
+L<ptserver(1)>,
+L<rcp_AFS_version(1)>,
+L<rsh_AFS_version(1)>,
+L<runntp(1)>,
+L<rxdebug(1)>,
+L<salvager(1)>,
+L<scout(1)>,
+L<sys(1)>,
+L<tokens(1)>,
+L<translate_et(1)>,
+L<unlog(1)>,
+L<up(1)>,
+L<upclient(1)>,
+L<upserver(1)>,
+L<uss(1)>,
+L<vldb_check(1)>,
+L<vlserver(1)>,
+L<volinfo(1)>,
+L<volserver(1)>,
+L<vos(1)>,
+L<xfs_size_check(1)>,
+L<xstat_cm_test(1)>,
+L<xstat_fs_test(1)>
+
+=cut
diff --git a/doc/man-pages/pod/afsd.pod b/doc/man-pages/pod/afsd.pod
new file mode 100644 (file)
index 0000000..01c1efe
--- /dev/null
@@ -0,0 +1,597 @@
+=head1 NAME
+
+afsd - Initializes the Cache Manager and starts related daemons.
+
+=head1 SYNOPSIS
+
+afsd [B<-blocks> I<1024 byte blocks in cache>]
+[B<-files> I<files in cache>]
+[B<-rootvol> I<name of AFS root volume>]
+[B<-stat> I<number of stat entries>]
+[B<-memcache>]  [B<-cachedir> I<cache directory>]
+[B<-mountdir> I<mount location>]
+[B<-daemons> I<number of daemons to use>]
+[B<-nosettime>]  [B<-verbose>]  [B<-rmtsys>]  [B<-debug>]
+[B<-chunksize> I<log(2) of chunk size>]
+[B<-dcache> I<number of dcache entries>]
+[B<-volumes> I<number of volume entries>]
+[B<-biods> I<number of bkg I/O daemons (aix vm)>]
+[B<-prealloc> I<number of 'small' preallocated blocks>]
+[B<-confdir> I<configuration directory>]
+[B<-logfile> I<Place to keep the CM log>]
+[B<-waitclose>]  [B<-shutdown>]  [B<-enable_peer_stats>]
+[B<-enable_process_stats>]  [B<-help>]
+
+This command does not use the syntax conventions of the AFS command
+suites. Provide the command name and all option names in full.
+
+=head1 DESCRIPTION
+
+The C<afsd> command initializes the Cache Manager on an AFS client
+machine by transferring AFS-related configuration information into
+kernel memory and starting several daemons. More specifically, the
+C<afsd> command performs the following actions:
+
+=over
+
+=item *
+
+Sets a field in kernel memory that defines the machine's cell
+membership. Some Cache Manager-internal operations and system
+calls consult this field to learn which cell to execute in. (The
+AFS command interpreters refer to the B</usr/vice/etc/ThisCell> file
+instead.) This information is transferred into the kernel from the
+B</usr/vice/etc/ThisCell> file and cannot be changed until the C<afsd>
+program runs again.
+
+=item *
+
+Places in kernel memory the names and Internet addresses of the
+database server machines in the local cell and (optionally)
+foreign cells. The appearance of a cell's database server machines
+in this list enables the Cache Manager to contact them and to
+access files in the cell. Omission of a cell from this list, or
+incorrect information about its database server machines, prevents
+the Cache Manager from accessing files in it.
+
+The list of database server machines is transferred into the
+kernel from the B</usr/vice/etc/CellServDB> file. After
+initialization, use the C<fs newcell> command to change the
+kernel-resident list without having to reboot.
+
+=item *
+
+Mounts the root of the AFS filespace on a directory on the
+machine's local disk, according to either the first field in the
+B</usr/vice/etc/cacheinfo> file (the default) or the C<afsd> command's
+B<-mountdir> argument. The conventional value is B</afs>.
+
+=item *
+
+Determines which volume to mount at the root of the AFS file tree.
+The default is the volume B<root.afs>; use the B<-rootvol> argument to
+override it. Although the base (read/write) form of the volume
+name is the appropriate value, the Cache Manager has a bias for
+accessing the read-only version of the volume (by convention,
+B<root.afs.readonly>) if it is available.
+
+=item *
+
+Configures the cache on disk (the default) or in machine memory if
+the B<-memcache> argument is provided. In the latter case, the C<afsd>
+program allocates space in machine memory for caching, and the
+Cache Manager uses no disk space for caching even if the machine
+has a disk.
+
+=item *
+
+Defines the name of the local disk directory devoted to caching,
+when the B<-memcache> argument is not used. If necessary, the C<afsd>
+program creates the directory (its parent directory must already
+exist). It does not remove the directory that formerly served this
+function, if one exists.
+
+The second field in the B</usr/vice/etc/cacheinfo> file is the source
+for this name, and the standard value is the B</usr/vice/cache>
+directory. Use the B<-cachedir> argument to override the value in the
+B<cacheinfo> file.
+
+=item *
+
+Sets the size of the cache. The default source for the value is
+the third field in the B</usr/vice/etc/cacheinfo> file, which
+specifies a number of kilobytes.
+
+For a memory cache, the following arguments to the C<afsd> command
+override the value in the B<cacheinfo> file:
+
+=over
+
+=item *
+
+The B<-blocks> argument, to specify a different number of
+kilobyte blocks.
+
+=item *
+
+The B<-dcache> and B<-chunksize> arguments together, to set both
+the number of dcache entries and the chunk size (see below
+for definition of these parameters). In this case, the C<afsd>
+program derives cache size by multiplying the two values.
+Using this combination is not recommended, as it requires the
+issuer to perform the calculation beforehand to determine the
+resulting cache size.
+
+=item *
+
+The B<-dcache> argument by itself. In this case, the C<afsd>
+program derives cache size by multiplying the value specified
+by the B<-dcache> argument by the default memory cache chunk
+size of eight kilobytes. Using this argument is not
+recommended, as it requires the issuer to perform the
+calculation beforehand to determine the resulting cache size.
+
+=back
+
+For satisfactory memory cache performance, the specified value
+must leave enough memory free to accommodate all other processes
+and commands that can run on the machine. If the value exceeds the
+amount of memory available, the C<afsd> program exits without
+initializing the Cache Manager and produces the following message
+on the standard output stream:
+
+afsd: memCache allocation failure at I<number> KB
+
+where I<number> is how many kilobytes were allocated just before the
+failure.
+
+For a disk cache, use the B<-blocks> argument to the C<afsd> command to
+override the value in the B<cacheinfo> file. The value specified in
+either way sets an absolute upper limit on cache size; values
+provided for other arguments (such as B<-dcache> and B<-chunksize>)
+never result in a larger cache. The C<afsd> program rejects any
+setting larger than 95% of the partition size, and exits after
+generating an error message on the standard output stream, because
+the cache implementation itself requires a small amount of disk
+space and overfilling the partition can cause the client machine
+to panic.
+
+To change the size of a disk cache after initialization without
+rebooting, use the C<fs setcachesize> command; the setting persists
+until the C<afsd> command runs again or the C<fs setcachesize> command
+is reissued. The C<fs setcachesize> command does not work for memory
+caches.
+
+=item *
+
+Sets the size of each cache I<chunk>, and by implication the amount
+of data that the Cache Manager requests at a time from the File
+Server (how much data per fetch RPC, since AFS uses partial file
+transfer).
+
+For a disk cache, a chunk is a B<V>I<n> file and this parameter sets the
+maximum size to which each one can expand; the default is 64 KB.
+For a memory cache, each chunk is a collection of contiguous
+memory blocks; the default is size is 8 KB.
+
+To override the default chunk size for either type of cache, use
+the B<-chunksize> argument to provide an integer to be used as an
+exponent of two; see the B<Options> section for details. For a memory
+cache, if total cache size divided by chunk size leaves a
+remainder, the C<afsd> program rounds down the number of dcache
+entries, resulting in a slightly smaller cache.
+
+=item *
+
+Sets the number of chunks in the cache. For a memory cache, the
+number of chunks is equal to the cache size divided by the chunk
+size. For a disk cache, the number of chunks (B<V>I<n> files) is set to
+the largest of the following unless the B<-files> argument is used to
+set the value explicitly:
+
+=over
+
+=item *
+
+100
+
+=item *
+
+1.5 times the result of dividing cache size by chunk size
+(I<cachesize>/I<chunksize> * 1.5)
+
+=item *
+
+The result of dividing cachesize by 10 KB (I<cachesize>/10240)
+
+=back
+
+=item *
+
+Sets the number of I<dcache entries> allocated in machine memory for
+storing information about the chunks in the cache.
+
+For a disk cache, the B</usr/vice/cache/CacheItems> file contains one
+entry for each B<V>I<n> file. By default, one half the number of these
+entries (but not more that 2,000) are duplicated as dcache entries
+in machine memory for quicker access.
+
+For a memory cache, there is no B<CacheItems> file so all information
+about cache chunks must be in memory as dcache entries. Thus,
+there is no default number of dcache entries for a memory cache;
+instead, the C<afsd> program derives it by dividing the cache size by
+the chunk size.
+
+To set the number of dcache entries, use the B<-dcache> argument; the
+specified value can exceed the default limit of 2,000. Using this
+argument is not recommended for either type of cache. Increasing
+the number of dcache entries for a disk cache sometimes improves
+performance (because more entries are retrieved from memory rather
+than from disk), but only marginally. Using this argument for a
+memory cache requires the issuer to calculate the cache size by
+multiplying this value by the chunk size.
+
+=item *
+
+Sets the number of I<stat> entries available in machine memory for
+caching status information about cached AFS files. The default is
+300; use the B<-stat> argument to override the default.
+
+=item *
+
+Randomly selects a file server machine in the local cell as the
+source for the correct time. Every five minutes thereafter, the
+local clock is adjusted (if necessary) to match the file server
+machine's clock.
+
+Use the B<-nosettime> flag to prevent the C<afsd> command from selecting
+a time standard. This is recommended only on file server machines
+that are also acting as clients. File server machines maintain the
+correct time using the Network Time Protocol Daemon instead.
+
+=back
+
+In addition to setting cache configuration parameters, the C<afsd>
+program starts the following daemons. (On most system types, these
+daemons appear as nameless entries in the output of the UNIX C<ps>
+command.)
+
+=over
+
+=item *
+
+One I<callback> daemon, which handles callbacks. It also responds to
+the File Server's periodic probes, which check that the client
+machine is still alive.
+
+=item *
+
+One I<maintenance> daemon, which performs the following tasks:
+
+=over
+
+=item *
+
+Garbage collects obsolete data (for example, expired tokens)
+from kernel memory
+
+=item *
+
+Synchronizes files
+
+=item *
+
+Refreshes information from read-only volumes once per hour
+
+=item *
+
+Does delayed writes for NFS clients if the machine is running
+the NFS/AFS Translator
+
+=back
+
+=item *
+
+One I<cache-truncation> daemon, which flushes the cache when free
+space is required, by writing cached data and status information
+to the File Server.
+
+=item *
+
+One I<server connection> daemon, which sends a probe to the File
+Server every few minutes to check that it is still accessible. It
+also synchronizes the machine's clock with the clock on a
+randomly-chosen file server machine, unless the B<-nosettime> flag is
+used. There is always one server connection daemon.
+
+=item *
+
+One or more I<background> daemons that improve performance by
+pre-fetching files and performing background (delayed) writes of
+saved data into AFS.
+
+The default number of background daemons is two, enough to service
+at least five simultaneous users of the machine. To increase the
+number, use the B<-daemons> argument. A value greater than six is not
+generally necessary.
+
+=item *
+
+On some system types, one I<Rx listener> daemon, which listens for
+incoming RPCs.
+
+=item *
+
+On some system types, one I<Rx event> daemon, which reviews the Rx
+system's queue of tasks and performs them as appropriate. Most
+items in the queue are retransmissions of failed packets.
+
+=item *
+
+On machines that run AIX with virtual memory (VM) integration, one
+or more I<VM> daemons (sometimes called I<I/O> daemons, which transfer
+data between disk and machine memory. The number of them depends
+on the setting of the B<-biods> and B<-daemons> arguments:
+
+=over
+
+=item *
+
+If the B<-biods> argument is used, it sets the number of VM
+daemons.
+
+=item *
+
+If only the B<-daemons> argument is used, the number of VM
+daemons is twice the number of background daemons.
+
+=item *
+
+If neither argument is used, there are five VM daemons.
+
+=back
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-blocks>
+
+Specifies the number of kilobyte blocks to be made available
+for caching in the machine's cache directory (for a disk cache)
+or memory (for a memory cache), overriding the default defined
+in the third field of the B</usr/vice/etc/cacheinfo> file. For a
+disk cache, the value cannot exceed 95% of the space available
+in the cache partition. If using a memory cache, do not combine
+this argument with the B<-dcache> argument, since doing so can
+possibly result in a chunk size that is not an exponent of 2.
+
+=item B<-files>
+
+Specifies the number of B<V>I<n> files to create in the cache
+directory for a disk cache, overriding the default that is
+calculated as described in the B<Description> section. Each B<V>I<n>
+file accommodates a chunk of data, and can grow to a maximum
+size of 64 KB by default. Do not combine this argument with the
+B<-memcache> argument.
+
+=item B<-rootvol>
+
+Names the read/write volume corresponding to the root directory
+for the AFS file tree (which is usually the B</afs> directory).
+This value overrides the default of the B<root.afs> volume.
+
+=item B<-stat>
+
+Specifies the number of entries to allocate in the machine's
+memory for recording status information about the AFS files in
+the cache. This value overrides the default of 300.
+
+=item B<-memcache>
+
+Initializes a memory cache rather than a disk cache. Do not
+combine this flag with the B<-files> argument.
+
+=item B<-cachedir>
+
+Names the local disk directory to be used as the cache. This
+value overrides the default defined in the second field of the
+B</usr/vice/etc/cacheinfo> file.
+
+=item B<-mountdir>
+
+Names the local disk directory on which to mount the root of
+the AFS filespace. This value overrides the default defined in
+the first field of the B</usr/vice/etc/cacheinfo> file. If a value
+other than the B</afs> directory is used, the machine cannot
+access the filespace of cells that do use that value.
+
+=item B<-daemons>
+
+Specifies the number of background daemons to run on the
+machine. These daemons improve efficiency by doing prefetching
+and background writing of saved data. This value overrides the
+default of 2, which is adequate for a machine serving up to
+five users. Values greater than B<6> are not generally more
+effective than B<6>.
+
+B<Note>: On AIX machines with integrated virtual memory (VM), the
+number of VM daemons is set to twice the value of this
+argument, if it is provided and the B<-biods> argument is not. If
+both arguments are omitted, there are five VM daemons.
+
+=item B<-nosettime>
+
+Prevents the Cache Manager from synchronizing its clock with
+the clock on a server machine selected at random, by checking
+the time on the server machine every five minutes. Use this
+flag only on a machine that is already using another time
+synchronization protocol (for example, a server machine that is
+running the B<runntp> process).
+
+=item B<-verbose>
+
+Generates a detailed trace of the C<afsd> program's actions on the
+standard output stream.
+
+=item B<-rmtsys>
+
+Initializes an additional daemon to execute AFS-specific system
+calls on behalf of NFS client machines. Use this flag only if
+the machine is an NFS/AFS translator machine serving users of
+NFS client machines who execute AFS commands.
+
+=item B<-debug>
+
+Generates a highly detailed trace of the C<afsd> program's actions
+on the standard output stream. The information is useful mostly
+for debugging purposes.
+
+=item B<-chunksize>
+
+Sets the size of each cache chunk. The integer provided, which
+must be from the range B<0> to B<30>, is used as an exponent on the
+number 2. It overrides the default of 16 for a disk cache (2^16
+is 64 KB) and 13 for a memory cache (2^13 is 8 KB). A value of
+B<0> or less, or greater than B<30>, sets chunk size to the
+appropriate default. Values less than B<10> (which sets chunk size
+to a 1 KB) are not recommended. Combining this argument with
+the B<-dcache> argument is not recommended because it requires
+that the issuer calculate the cache size that results.
+
+=item B<-dcache>
+
+Sets the number of dcache entries in memory, which are used to
+store information about cache chunks. For a disk cache, this
+overrides the default, which is 50% of the number of B<V>I<n> files
+(cache chunks). For a memory cache, this argument effectively
+sets the number of cache chunks, but its use is not
+recommended, because it requires the issuer to calculate the
+resulting total cache size (derived by multiplying this value
+by the chunk size). Do not combine this argument with the
+B<-blocks> argument, since doing so can possibly result in a chunk
+size that is not an exponent of 2.
+
+=item B<-volumes>
+
+Specifies the number of memory structures to allocate for
+storing volume location information. The default value is 50.
+
+=item B<-biods>
+
+Sets the number of VM daemons dedicated to performing I/O
+operations on a machine running a version of AIX with virtual
+memory (VM) integration. If both this argument and the B<-daemons>
+argument are omitted, the default is five. If this argument is
+omitted but the B<-daemons> argument is provided, the number of VM
+daemons is set to twice the value of the B<-daemons> argument.
+
+B<Note>: Provide this argument only on a machine that runs AIX with VM
+integration.
+
+=item B<-prealloc>
+
+Specifies the number of pieces of memory to preallocate for the
+Cache Manager's internal use. The default initial value is 400,
+but the Cache Manager dynamically allocates more memory as it
+needs it.
+
+=item B<-confdir>
+
+Names a directory other than the B</usr/vice/etc> directory from
+which to fetch the B<cacheinfo>, B<ThisCell>, and B<CellServDB>
+configuration files.
+
+=item B<-logfile>
+
+Is obsolete and has no real effect. It specifies an alternate
+file in which to record a type of trace that the Cache Manager
+no longer generates; the default value is B</usr/vice/etc/AFSLog>.
+
+=item B<-waitclose>
+
+Has no effect on the operation of the Cache Manager. The
+behavior it affected in previous versions of the Cache Manager,
+to perform synchronous writes to the File Server, is now the
+default behavior. To perform asynchronous writes in certain
+cases, use the C<fs storebehind> command.
+
+=item B<-shutdown>
+
+Shuts down the Cache Manager, but not in the most effective
+possible way. Do not use this flag.
+
+=item B<-enable_peer_stats>
+
+Activates the collection of Rx statistics and allocates memory
+for their storage. For each connection with a specific UDP port
+on another machine, a separate record is kept for each type of
+RPC (FetchFile, GetStatus, and so on) sent or received. To
+display or otherwise access the records, use the Rx Monitoring
+API.
+
+=item B<-enable_process_stats>
+
+Activates the collection of Rx statistics and allocates memory
+for their storage. A separate record is kept for each type of
+RPC (FetchFile, GetStatus, and so on) sent or received,
+aggregated over all connections to other machines. To display
+or otherwise access the records, use the Rx Monitoring API.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The C<afsd> command is normally included in the machine's AFS
+initialization file, rather than typed at the command shell prompt.
+For most disk caches, the appropriate form is
+
+ /usr/vice/etc/afsd
+
+
+The following command is appropriate when enabling a machine to act as
+an NFS/AFS Translator machine serving more than five users.
+
+ /usr/vice/etc/afsd -daemons 4 -rmtsys
+
+The following command initializes a memory cache and sets chunk size
+to 16 KB (2^14).
+
+ /usr/vice/etc/afsd -memcache -chunksize 14
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+Do not use the B<-shutdown> parameter. It does not shutdown the Cache
+Manager effectively. Instead, halt Cache Manager activity by using the
+standard UNIX C<umount> command to unmount the AFS root directory (by
+convention, B</afs>). The machine must then be rebooted to reinitialize
+the Cache Manager.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CacheItems(1)>,
+L<CellServDB_client_version(1)>,
+L<ThisCell_client_version(1)>,
+L<Vn(1)>,
+L<cacheinfo(1)>
+
+=cut
diff --git a/doc/man-pages/pod/afsmonitor.pod b/doc/man-pages/pod/afsmonitor.pod
new file mode 100644 (file)
index 0000000..19f73cf
--- /dev/null
@@ -0,0 +1,432 @@
+=head1 NAME
+
+afsmonitor - Monitors File Servers and Cache Managers
+
+=head1 SYNOPSIS
+
+afsmonitor [B<initcmd>]  [B<-config> I<configuration file>]
+[B<-frequency> I<poll frequency, in seconds>]
+[B<-output> I<storage file name>]  [B<-detailed>]
+[B<-debug> I<turn debugging output on to the named file>]
+[B<-fshosts> I<list of file servers to monitor> ...]
+[B<-cmhosts> I<list of cache managers to monitor> ...]
+[B<-buffers> I<number of buffer slots>]  [B<-help>]
+
+afsmonitor [B<i>]  [B<-co> I<configuration file>]
+[B<-fr> I<poll frequency, in seconds>]
+[B<-o> I<storage file name>]  [B<-det>]
+[B<-deb> I<turn debugging output on to the named file>]
+[B<-fs> I<list of file servers to monitor> ...]
+[B<-cm> I<list of cache managers to monitor> ...]
+[B<-b> I<number of buffer slots>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<afsmonitor> command initializes a program that gathers and displays
+statistics about specified File Server and Cache Manager operations.
+It allows the issuer to monitor, from a single location, a wide range
+of File Server and Cache Manager operations on any number of machines
+in both local and foreign cells.
+
+There are 271 available File Server statistics and 570 available Cache
+Manager statistics, listed in the appendix about C<afsmonitor> statistics
+in the IBM AFS Administration Guide. By default, the command displays
+all of the relevant statistics for the file server machines named by
+the B<-fshosts> argument and the client machines named by the B<-cmhosts>
+argument. To limit the display to only the statistics of interest,
+list them in the configuration file specified by the B<-config> argument.
+In addition, use the configuration file for the following purposes:
+
+=over
+
+=item *
+
+To set threshold values for any monitored statistic. When the
+value of a statistic exceeds the threshold, the C<afsmonitor> command
+displays it in reverse video. There are no default threshold
+values.
+
+=item *
+
+To invoke a program or script automatically when a statistic
+exceeds its threshold. The AFS distribution does not include any
+such scripts.
+
+=item *
+
+To list the file server and client machines to monitor, instead of
+using the B<-fshosts> and B<-cmhosts> arguments.
+
+=back
+
+For a description of the configuration file, see the B<afsmonitor
+Configuration File> reference page
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<initcmd>
+
+Accommodates the command's use of the AFS command parser, and
+is optional.
+
+=item B<-config> I<configuration file>
+
+Names the configuration file which lists the machines to
+monitor, statistics to display, and threshold values, if any. A
+partial pathname is interpreted relative to the current working
+directory. Provide this argument if not providing the B<-fshosts>
+argument, B<-cmhosts> argument, or neither. For instructions on
+creating this file, see the preceding B<Description> section, and
+the section on the C<afsmonitor> program in the IBM AFS
+Administration Guide.
+
+=item B<-frequency> I<poll frequency, in seconds>
+
+Specifies in seconds how often the C<afsmonitor> program probes
+the File Servers and Cache Managers. Valid values range from B<1>
+to B<86400> (which is 24 hours); the default value is B<60>. This
+frequency applies to both File Servers and Cache Managers, but
+the C<afsmonitor> program initiates the two types of probes, and
+processes their results, separately. The actual interval
+between probes to a host is the probe frequency plus the time
+required for all hosts to respond.
+
+=item B<-output> I<storage file name>
+
+Names the file to which the C<afsmonitor> program writes all of
+the statistics that it collects. By default, no output file is
+created. See the section on the C<afsmonitor> command in the IBM
+AFS Administration Guide for information on this file.
+
+=item B<-detailed>
+
+Formats the information in the output file named by B<-output>
+argument in a maximally readable format. Provide the B<-output>
+argument along with this one.
+
+=item B<-fshosts> I<list of file servers to monitor> ...
+
+Names one or more machines from which to gather File Server
+statistics. For each machine, provide either a fully qualified
+host name, or an unambiguous abbreviation (the ability to
+resolve an abbreviation depends on the state of the cell's name
+service at the time the command is issued). This argument can
+be combined with the B<-cmhosts> argument, but not with the
+B<-config> argument.
+
+=item B<-cmhosts> I<list of cache managers to monitor> ...
+
+Names one or more machines from which to gather Cache Manager
+statistics. For each machine, provide either a fully qualified
+host name, or an unambiguous abbreviation (the ability to
+resolve an abbreviation depends on the state of the cell's name
+service at the time the command is issued). This argument can
+be combined with the B<-fshosts> argument, but not with the
+B<-config> argument.
+
+=item B<-buffers> I<number of buffer slots>
+
+Is nonoperational and provided to accommodate potential future
+enhancements to the program.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The C<afsmonitor> program displays its data on three screens:
+
+=over
+
+=item *
+
+C<System Overview>: This screen appears automatically when the
+C<afsmonitor> program initializes. It summarizes separately for File
+Servers and Cache Managers the number of machines being monitored
+and how many of them have I<alerts> (statistics that have exceeded
+their thresholds). It then lists the hostname and number of alerts
+for each machine being monitored, indicating if appropriate that a
+process failed to respond to the last probe.
+
+=item *
+
+C<File Server>: This screen displays File Server statistics for each
+file server machine being monitored. It highlights statistics that
+have exceeded their thresholds, and identifies machines that
+failed to respond to the last probe.
+
+=item *
+
+C<Cache Managers>: This screen displays Cache Manager statistics for
+each client machine being monitored. It highlights statistics that
+have exceeded their thresholds, and identifies machines that
+failed to respond to the last probe.
+
+=back
+
+Fields at the corners of every screen display the following
+information:
+
+=over
+
+=item *
+
+In the top left corner, the program name and version number.
+
+=item *
+
+In the top right corner, the screen name, current and total page
+numbers, and current and total column numbers. The page number
+(for example, p. 1 of 3) indicates the index of the current page
+and the total number of (vertical) pages over which data is
+displayed. The column number (for example, c. 1 of 235) indicates
+the index of the current leftmost column and the total number of
+columns in which data appears. (The symbol >>> indicates that
+there is additional data to the right; the symbol <<< indicates
+that there is additional data to the left.)
+
+=item *
+
+In the bottom left corner, a list of the available commands. Enter
+the first letter in the command name to run that command. Only the
+currently possible options appear; for example, if there is only
+one page of data, the C<next> and C<prev> commands, which scroll the
+screen up and down respectively, do not appear. For descriptions
+of the commands, see the following section about navigating the
+display screens.
+
+=item *
+
+In the bottom right corner, the C<probes> field reports how many
+times the program has probed File Servers (C<fs>), Cache Managers
+(C<cm>), or both. The counts for File Servers and Cache Managers can
+differ. The C<freq> field reports how often the program sends probes.
+
+=back
+
+=head1 Navigating the afsmonitor Display Screens
+
+As noted, the lower left hand corner of every display screen displays
+the names of the commands currently available for moving to alternate
+screens, which can either be a different type or display more
+statistics or machines of the current type. To execute a command,
+press the lowercase version of the first letter in its name. Some
+commands also have an uppercase version that has a somewhat different
+effect, as indicated in the following list.
+
+=over
+
+=item B<cm>
+
+Switches to the C<Cache Managers> screen. Available only on the
+C<System Overview> and C<File Servers> screens.
+
+=item B<fs>
+
+Switches to the C<File Servers> screen. Available only on the
+C<System Overview> and the C<Cache Managers> screens.
+
+=item B<left>
+
+Scrolls horizontally to the left, to access the data columns
+situated to the left of the current set. Available when the <<<
+symbol appears at the top left of the screen. Press uppercase B<L>
+to scroll horizontally all the way to the left (to display the
+first set of data columns).
+
+=item B<next>
+
+Scrolls down vertically to the next page of machine names.
+Available when there are two or more pages of machines and the
+final page is not currently displayed. Press uppercase B<N> to
+scroll to the final page.
+
+=item B<oview>
+
+Switches to the C<System Overview> screen. Available only on the
+C<Cache Managers> and C<File Servers> screens.
+
+=item B<prev>
+
+Scrolls up vertically to the previous page of machine names.
+Available when there are two or more pages of machines and the
+first page is not currently displayed. Press uppercase B<P> to
+scroll to the first page.
+
+=item B<right>
+
+Scrolls horizontally to the right, to access the data columns
+situated to the right of the current set. This command is
+available when the >>> symbol appears at the upper right of the
+screen. Press uppercase B<R> to scroll horizontally all the way to
+the right (to display the final set of data columns).
+
+=back
+
+=head1 The System Overview Screen
+
+The C<System Overview> screen appears automatically as the C<afsmonitor>
+program initializes. This screen displays the status of as many File
+Server and Cache Manager processes as can fit in the current window;
+scroll down to access additional information.
+
+The information on this screen is split into File Server information
+on the left and Cache Manager information on the right. The header for
+each grouping reports two pieces of information:
+
+=over
+
+=item *
+
+The number of machines on which the program is monitoring the
+indicated process
+
+=item *
+
+The number of alerts and the number of machines affected by them
+(an I<alert> means that a statistic has exceeded its threshold or a
+process failed to respond to the last probe)
+
+=back
+
+A list of the machines being monitored follows. If there are any
+alerts on a machine, the number of them appears in square brackets to
+the left of the hostname. If a process failed to respond to the last
+probe, the letters C<PF> (probe failure) appear in square brackets to the
+left of the hostname.
+
+=head1 The File Servers Screen
+
+The C<File Servers> screen displays the values collected at the most
+recent probe for File Server statistics.
+
+A summary line at the top of the screen (just below the standard
+program version and screen title blocks) specifies the number of
+monitored File Servers, the number of alerts, and the number of
+machines affected by the alerts.
+
+The first column always displays the hostnames of the machines running
+the monitored File Servers.
+
+To the right of the hostname column appear as many columns of
+statistics as can fit within the current width of the display screen
+or window; each column requires space for 10 characters. The name of
+the statistic appears at the top of each column. If the File Server on
+a machine did not respond to the most recent probe, a pair of dashes
+(--) appears in each column. If a value exceeds its configured
+threshold, it is highlighted in reverse video. If a value is too large
+to fit into the allotted column width, it overflows into the next row
+in the same column.
+
+=head1 The Cache Managers Screen
+
+The Cache Managers screen displays the values collected at the most
+recent probe for Cache Manager statistics.
+
+A summary line at the top of the screen (just below the standard
+program version and screen title blocks) specifies the number of
+monitored Cache Managers, the number of alerts, and the number of
+machines affected by the alerts.
+
+The first column always displays the hostnames of the machines running
+the monitored Cache Managers.
+
+To the right of the hostname column appear as many columns of
+statistics as can fit within the current width of the display screen
+or window; each column requires space for 10 characters. The name of
+the statistic appears at the top of each column. If the Cache Manager
+on a machine did not respond to the most recent probe, a pair of
+dashes (--) appears in each column. If a value exceeds its configured
+threshold, it is highlighted in reverse video. If a value is too large
+to fit into the allotted column width, it overflows into the next row
+in the same column.
+
+=head1 Writing to an Output File
+
+Include the B<-output> argument to name the file into which the
+C<afsmonitor> program writes all of the statistics it collects. The
+output file can be useful for tracking performance over long periods
+of time, and enables the administrator to apply post-processing
+techniques that reveal system trends. The AFS distribution does not
+include any post-processing programs.
+
+The output file is in ASCII format and records the same information as
+the File Server and Cache Manager display screens. Each line in the
+file uses the following format to record the time at which the
+C<afsmonitor> program gathered the indicated statistic from the Cache
+Manager (C<CM>) or File Server (C<FS>) running on the machine called
+I<host_name>. If a probe failed, the error code B<-1> appears in the
+I<statistic> field.
+
+I<time>  I<host_name>  CM|FS   I<statistic>
+
+If the administrator usually reviews the output file manually, rather
+than using it as input to an automated analysis program or script,
+including the B<-detail> flag formats the data in a more easily readable
+form.
+
+=head1 EXAMPLES
+
+For examples of commands, display screens, and configuration files,
+see the section about the C<afsmonitor> program in the IBM AFS
+Administration Guide.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 CAVEATS
+
+The following software must be accessible to a machine where the
+C<afsmonitor> program is running:
+
+=over
+
+=item *
+
+The AFS B<xstat> libraries, which the C<afsmonitor> program uses to
+gather data
+
+=item *
+
+The B<curses> graphics package, which most UNIX distributions provide
+as a standard utility
+
+=back
+
+The C<afsmonitor> screens format successfully both on so-called dumb
+terminals and in windowing systems that emulate terminals. For the
+output to looks its best, the display environment needs to support
+reverse video and cursor addressing. Set the TERM environment variable
+to the correct terminal type, or to a value that has characteristics
+similar to the actual terminal type. The display window or terminal
+must be at least 80 columns wide and 12 lines long.
+
+The C<afsmonitor> program must run in the foreground, and in its own
+separate, dedicated window or terminal. The window or terminal is
+unavailable for any other activity as long as the C<afsmonitor> program
+is running. Any number of instances of the C<afsmonitor> program can run
+on a single machine, as long as each instance runs in its own
+dedicated window or terminal. Note that it can take up to three
+minutes to start an additional instance.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<afsmonitor_Configuration_File(1)>,
+L<fstrace(1)>,
+L<scout(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup.pod b/doc/man-pages/pod/backup.pod
new file mode 100644 (file)
index 0000000..2653fc3
--- /dev/null
@@ -0,0 +1,306 @@
+=head1 NAME
+
+backup - Introduction to the C<backup> command suite
+
+=head1 DESCRIPTION
+
+The commands in the C<backup> command suite are the administrative
+interface to the AFS Backup System. There are several categories of
+commands in the suite:
+
+=over
+
+=item *
+
+Commands to copy data from AFS volumes to tape or a backup data
+file, and to restore it to the file system: C<backup diskrestore>,
+C<backup dump>, C<backup volrestore>, and C<backup volsetrestore>
+
+=item *
+
+Commands to administer the records in the Backup Database: C<backup
+adddump>, C<backup addhost>, C<backup addvolentry>, C<backup addvolset>,
+C<backup deldump>, C<backup deletedump>, C<backup delhost>, C<backup
+delvolentry>, C<backup delvolset>, C<backup dumpinfo>, C<backup listdumps>,
+C<backup listhosts>, C<backup listvolsets>, C<backup scantape>, C<backup
+setexp>, and C<backup volinfo>
+
+=item *
+
+Commands to write and read tape labels: C<backup labeltape> and
+C<backup readlabel>
+
+=item *
+
+Commands to list and change the status of backup operations and
+the machines performing them: C<(backup) jobs>, C<(backup) kill>, and
+C<backup status>
+
+=item *
+
+Commands to enter and leave interactive mode: C<backup (interactive)>
+and C<(backup) quit>
+
+=item *
+
+Commands to check for and repair corruption in the Backup
+Database: C<backup dbverify>, C<backup restoredb>, and C<backup savedb>
+
+=item *
+
+Commands to obtain help: C<backup apropos> and C<backup help>
+
+=back
+
+The C<backup> command interpreter interacts with two other processes:
+
+=over
+
+=item *
+
+The Backup Server (B<buserver>) process. It maintains the Backup
+Database, which stores most of the administrative information used
+by the Backup System. In the standard configuration, the Backup
+Server runs on each database server machine in the cell, and uses
+AFS's distributed database technology, Ubik, to synchronize its
+copy of the database with the copies on the other database server
+machines.
+
+=item *
+
+The Backup Tape Coordinator (B<butc>) process. A separate instance of
+the process controls each tape device or backup data file used to
+dump or restore data. The Tape Coordinator runs on a Tape
+Coordinator machine, which is an AFS server or client machine that
+has one or more tape devices attached, or has sufficient disk
+space to accommodate one or more backup data files on its local
+disk.
+
+Each Tape Coordinator must be registered in the Backup Database
+and in the B</usr/afs/backup/tapeconfig> configuration file on the
+Tape Coordinator machine's local disk, and information in the two
+places must be consistent for proper Backup System performance.
+The optional B</usr/afs/backup/CFG>I<_device_name> for each Tape
+Coordinator records information used to automate its operation.
+
+=back
+
+In addition to the standard command line interface, the C<backup> command
+suite provides an I<interactive> interface, which has several useful
+features described on the C<backup (interactive)> reference page. Three
+of the commands in the suite are available only in interactive mode:
+C<(backup) jobs>, C<(backup) kill>, and C<(backup) quit>.
+
+=head1 OPTIONS
+
+The following options are available on many commands in the C<backup>
+suite. The reference page for each command also lists them, but they
+are described here in greater detail.
+
+=over 4
+
+=item B<-cell> I<cell name> 
+
+Names the cell in which to run the command. It is acceptable to
+abbreviate the cell name to the shortest form that
+distinguishes it from the other entries in the
+B</usr/vice/etc/CellServDB> file on the local machine. If the
+B<-cell> argument is omitted, the command interpreter determines
+the name of the local cell by reading the following in order:
+
+=over
+
+=item 1.
+
+The value of the AFSCELL environment variable
+
+=item 2.
+
+The local B</usr/vice/etc/ThisCell> file
+
+=back
+
+Do not combine the B<-cell> and B<-localauth> options. A command on
+which the B<-localauth> flag is included always runs in the local
+cell (as defined in the server machine's local
+B</usr/afs/etc/ThisCell> file), whereas a command on which the
+B<-cell> argument is included runs in the specified foreign cell.
+
+The B<-cell> argument is not available on commands issued in
+interactive mode. The cell defined when the C<backup> command
+interpreter enters interactive mode applies to all commands
+issued during the interactive session.
+
+
+=item B<-help>
+
+Prints a command's online help message on the standard output
+stream. Do not combine this flag with any of the command's
+other options; when it is provided, the command interpreter
+ignores all other options, and only prints the help message.
+
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with
+the highest key version number in the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents the ticket, which never expires, to the Backup Server,
+Volume Server and Volume Location (VL) Server during mutual
+authentication.
+
+Use this flag only when issuing a command on a server machine;
+client machines do not usually have a B</usr/afs/etc/KeyFile>
+file. The issuer of a command that includes this flag must be
+logged on to the server machine as the local superuser B<root>.
+The flag is useful for commands invoked by an unattended
+application program, such as a process controlled by the UNIX
+B<cron> utility or by a cron entry in the machine's
+B</usr/afs/local/BosConfig> file. It is also useful if an
+administrator is unable to authenticate to AFS but is logged in
+as the local superuser B<root>.
+
+Do not combine the B<-cell> and B<-localauth> options. A command on
+which the B<-localauth> flag is included always runs in the local
+cell (as defined in the server machine's local
+B</usr/afs/etc/ThisCell> file), whereas a command on which the
+B<-cell> argument is included runs in the specified foreign cell.
+
+The B<-localauth> argument is not available on commands issued in
+interactive mode. The local identity and AFS tokens with which
+the C<backup> command interpreter enters interactive mode apply to
+all commands issued during the interactive session.
+
+=item B<-portoffset> I<TC port offset> 
+
+Specifies the port offset number of the Tape Coordinator that
+is to execute the C<backup> command. The port offset number
+uniquely identifies a pairing of a Tape Coordinator (B<butc>)
+process and tape device or C<backup> data file.
+
+The C<backup> command interpreter and Tape Coordinator process
+communicate via a UDP socket, or port. Before issuing a C<backup>
+command that involves reading or writing a tape, the backup
+operator must start a B<butc> process that controls the
+appropriate tape device and listens for requests sent to its
+port number. If a Backup System machine has multiple tape
+devices attached, they can perform backup operations
+simultaneously because each device has its own associated B<butc>
+process and port offset number.
+
+The Backup System associates a tape capacity and file mark size
+with each port offset (as defined in the B<tapeconfig> file). For
+a compressing tape device, the capacity and file mark values
+differ for compression and non-compression modes, so the two
+modes have distinct port offset numbers.
+
+The Backup Database can store up to 58,511 port offsets, so the
+legal values for this argument are the integers B<0> through
+B<58510>. If the issuer omits the argument, it defaults to B<0>. (The
+limit of 58,511 port offsets results from the fact that UDP
+socket numbers are identified by a 16-bit integer, and the
+lowest socket number used by the Backup System is 7025. The
+largest number that a 16-bit integer can represent is 65,535.
+Subtracting 7,025 yields 58,510. The addition of port offset 0
+(zero) increases the maximum to 58,511.)
+
+Although it is possible to define up to 58,511 port offset
+numbers for a cell, it is not possible to run 58,511 tape
+devices simultaneously, due to the following limits:
+
+
+=over
+
+=item *
+
+The maximum number of dump or restore operations that can run
+simultaneously is 64.
+
+=item *
+
+The maximum number of tape devices that can work together on
+a restore operation is 128 (that is the maximum number of
+values that can be provided for the B<-portoffset> argument to
+the C<backup diskrestore>, C<backup volrestore>, or C<backup
+volsetrestore> command).
+
+=back
+
+The Backup System does not reserve UDP sockets. If another
+application is already using the Tape Coordinator's socket when
+it tries to start, the B<butc> process fails and the following
+error message appears at the shell prompt:
+
+  bind: Address already in use
+  rxi_GetUDPSocket: bind failed
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue any C<backup> command that accesses the Backup Database only,
+the issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running. To issue any C<backup> command 
+that accesses volume data, the issuer must appear in the
+B<UserList> file on every Backup Server machine, every Volume Location
+(VL) Server machine, and every file server machine that houses
+affected volumes. By convention, a common B<UserList> file is distributed
+to all database server and file server machines in the cell. See the
+chapter on privileged users in the IBM AFS Administration Guide for
+more information on this type of privilege.
+
+If the B<-localauth> flag is included, the user must instead be logged on
+as the local superuser root on the server machine where the C<backup> command is issued.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<CFG_device_name(1)>,
+L<CellServDB_client_version(1)>,
+L<KeyFile(1)>,
+L<ThisCell_client_version(1)>,
+L<ThisCell_server_version(1)>,
+L<UserList(1)>,
+L<tapeconfig(1)>,
+L<backup_adddump(1)>,
+L<backup_addhost(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_dbverify(1)>,
+L<backup_deldump(1)>,
+L<backup_deletedump(1)>,
+L<backup_delhost(1)>,
+L<backup_delvolentry(1)>,
+L<backup_delvolset(1)>,
+L<backup_diskrestore(1)>,
+L<backup_dump(1)>,
+L<backup_dumpinfo(1)>,
+L<backup_help(1)>,
+L<backup_interactive(1)>,
+L<backup_jobs(1)>,
+L<backup_kill(1)>,
+L<backup_labeltape(1)>,
+L<backup_listdumps(1)>,
+L<backup_listhosts(1)>,
+L<backup_listvolsets(1)>,
+L<backup_quit(1)>,
+L<backup_readlabel(1)>,
+L<backup_restoredb(1)>,
+L<backup_savedb(1)>,
+L<backup_scantape(1)>,
+L<backup_setexp(1)>,
+L<backup_status(1)>,
+L<backup_volinfo(1)>,
+L<backup_volrestore(1)>,
+L<backup_volsetrestore(1)>,
+L<buserver(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_adddump.pod b/doc/man-pages/pod/backup_adddump.pod
new file mode 100644 (file)
index 0000000..ad88332
--- /dev/null
@@ -0,0 +1,202 @@
+=head1 NAME
+
+backup adddump - Defines a dump level in the dump hierarchy
+
+=head1 SYNOPSIS
+
+backup adddump B<-dump> I<dump level name> [I<dump level name> ...] [B<-expires> I<expiration date> ...]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup addd B<-d>  I<dump level name> [I<dump level name> ...] [B<-e> I<expiration date> ...]  [B<-l>]
+[B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup adddump> command creates one or more dump levels in the dump
+hierarchy stored in the Backup Database, and optionally assigns an
+expiration date to each one. All of the dump levels in the Backup
+Database collectively constitute the dump hierarchy.
+
+Use the B<-expires> argument to associate an expiration date with each
+dump level. When the Backup System subsequently creates a dump at the
+dump level, it uses the specified value to derive the dump's
+expiration date, which it records on the label of the tape (or backup
+data file). The Backup System refuses to overwrite a tape until after
+the latest expiration date of any dump that the tape contains, unless
+the C<backup labeltape> command is used to relabel the tape. If a dump
+level does not have an expiration date, the Backup System treats dumps
+created at the level as expired as soon as it creates them.
+
+(Note that the Backup System does not automatically remove a dump's
+record from the Backup Database when the dump reaches its expiration
+date, but only if the tape that contains the dump is recycled or
+relabeled. To remove expired and other obsolete dump records, use the
+C<backup deletedump> command.)
+
+Define either an absolute or relative expiration date:
+
+=over
+
+=item *
+
+An absolute expiration date defines the month/day/year (and,
+optionally, hour and minutes) at which a dump expires. If the
+expiration date predates the dump creation time, the Backup System
+immediately treats the dump as expired.
+
+=item *
+
+A relative date defines the number of years, months, or days (or a
+combination of the three) after the dump's creation that it
+expires. When the Backup System creates a dump at the dump level,
+it calculates an actual expiration date by adding the relative
+date to the start time of the dump operation.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+
+=item B<-dump> I<dump level name> [I<dump level name> ...]
+
+Names each dump level to add to the dump hierarchy. Precede
+full dump level names with a slash (for example, B</full>).
+Indicate an incremental dump level by preceding it with an
+ordered list of the dump levels directly above it in the
+hierarchy (its parent dump levels); use the slash as a
+separator. The parent dump levels must already exist. For
+example, the dump levels B</full> and B</full/incremental1> must
+exist when the incremental dump level
+B</full/incremental1/incremental2> is created.
+
+Dump level names can have any number of levels, but cannot
+exceed 256 characters in length, including the slashes. The
+maximum length for any single level (the text between slashes)
+is 28 characters, not including the preceding slash.
+
+All alphanumeric characters are allowed in dump level names. Do
+not use the period (.), however, because it is the separator
+between the volume set name and dump level name in the dump
+name assigned automatically by the C<backup dump> command. It is
+best not to include other metacharacters either; if using them,
+enclose them in double quotes (" ") when issuing the C<backup
+adddump> command outside interactive mode.
+
+
+=item B<-expires> I<expiration date> ...
+
+Defines the absolute or relative expiration date to associate
+with each dump level named by the B<-dump> argument. Absolute
+expiration dates have the following format:
+
+[B<at>] {B<NEVER> | I<mm/dd/yyyy> [I<hh:MM>] }
+
+where the optional word B<at> is followed either by the string
+B<NEVER>, which indicates that dumps created at the dump level
+never expire, or by a date value with a required portion (I<mm>
+for month, I<dd> for day, and I<yyyy> for year) and an optional
+portion (I<hh> for hours and I<MM> for minutes).
+
+Omit the I<hh>:I<MM> portion to use the default of midnight (00:00
+hours), or provide a value in 24-hour format (for example,
+B<20:30> is 8:30 p.m.). Valid values for the year range from B<1970>
+to B<2037>; higher values are not valid because the latest
+possible date in the standard UNIX representation is in
+February 2038. The command interpreter automatically reduces
+later dates to the maximum value.
+
+Relative expiration dates have the following format:
+
+[B<in>] [I<years>B<y>] [I<months>B<m>] [I<days>B<d>]
+
+where the optional word B<in> is followed by at least one of a
+number of years (maximum B<9999>) followed by the letter B<y>, a
+number of months (maximum B<12>) followed by the letter B<m>, or a
+number of days (maximum B<31>) followed by the letter B<d>. If
+providing more than one of the three, list them in the
+indicated order. If the date that results from adding the
+relative expiration value to a dump's creation time is later
+than the latest possible date in the UNIX time representation,
+the Backup System automatically reduces it to that date.
+
+=over
+
+=item B<Note>: 
+
+A plus sign follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition to be associated with each dump level specified by the
+B<-dump> argument.
+
+=back
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command defines a full dump called B</1999> with a relative
+expiration date of one year:
+
+    backup adddump -dump /1999 -expires in 1y
+
+The following command defines an incremental dump called
+B</sunday1/monday1> with a relative expiration date of 13 days:
+
+    backup adddump -dump /sunday1/monday1 -expires in 13d
+
+The following command defines two dump incremental dump levels,
+B</Monthly/Week1> and B</Monthly/Week2>. Their parent, the full dump level
+B</Monthly>, must already exist. The expiration date for both levels is
+12:00 a.m. on 1 January 2000.
+
+    backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_deldump(1)>,
+L<backup_deletedump(1)>,
+L<backup_listdumps(1)>,
+L<backup_setexp(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_addhost.pod b/doc/man-pages/pod/backup_addhost.pod
new file mode 100644 (file)
index 0000000..108d96a
--- /dev/null
@@ -0,0 +1,118 @@
+=head1 NAME
+
+backup addhost - Adds a Tape Coordinator entry to the Backup Database
+
+=head1 SYNOPSIS
+
+backup addhost B<-tapehost> I<tape machine name> [B<-portoffset> I<TC port offset>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup addh B<-t> I<tape machine name>  [B<-p> I<TC port offset>]
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup addhost> command creates a Tape Coordinator entry in the
+Backup Database. The entry records
+
+=over
+
+=item *
+
+The host name of the Tape Coordinator machine where the Tape
+Coordinator (B<butc>) process runs, as specified with the B<-tapehost>
+argument.
+
+=item *
+
+The Tape Coordinator's port offset number, as specified with the
+B<-portoffset> argument. An entry for the port offset must also
+appear in the B</usr/afs/backup/tapeconfig> file on the Tape
+Coordinator machine, where it is mapped to a UNIX device name (for
+a tape device) or pathname (for a backup data file).
+
+=back
+
+Each Tape Coordinator must have its own port offset number, and the
+command fails if a Backup Database entry already exists for the
+requested port offset number. To display existing Tape Coordinator
+entries, use the C<backup listhosts> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-tapehost> I<tape machine name>
+
+Specifies the fully-qualified hostname of the machine for which
+to create a Tape Coordinator entry in the Backup Database. The
+machine must have an entry in either the cell's naming service
+(such as the Domain Name Service) or the host file (B</etc/hosts>
+or equivalent) on the machine where the command is issued.
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the Tape Coordinator's port offset number. Provide an
+integer from the range B<0> through B<58510>, or omit this argument
+to use the default value of B<0> (zero). The value must match the
+port offset number recorded for the same combination of Tape
+Coordinator and tape device or file in the
+B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine
+named by the B<-tapehost> argument.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile file>. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command creates an entry in the Backup Database that
+assigns port offset number 4 to a Tape Coordinator running on the
+machine B<backup1.abc.com>:
+
+    backup addhost -tapehost backup1.abc.com -portoffset 4
+
+The following command creates a Backup Database entry that assigns
+port offset number 0 to a Tape Coordinator on the machine
+B<backup3.abc.com>:
+
+    backup addhost backup3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_delhost(1)>,
+L<backup_listhosts(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_addvolentry.pod b/doc/man-pages/pod/backup_addvolentry.pod
new file mode 100644 (file)
index 0000000..5839881
--- /dev/null
@@ -0,0 +1,203 @@
+=head1 NAME
+
+backup addvolentry - Defines a volume entry in a volume set
+
+=head1 SYNOPSIS
+
+backup addvolentry B<-name> I<volume set name>  B<-server> I<machine name>
+B<-partition> I<partition name>
+B<-volumes> I<volume name (regular expression)>
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup addvole B<-n> I<volume set name>  B<-s> I<machine name> B<-p> I<partition name>
+B<-v> I<volume name (regular expression)>
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup addvolentry> command adds a volume entry definition to the
+existing volume set named by the B<-name> argument. A volume entry
+definition can match one or more volumes, depending on the combination
+of the B<-server>, B<-partition>, and B<-volumes> arguments.
+
+For the B<-server> and B<-partition> arguments, provide either
+
+=over
+
+=item *
+
+The name of one machine or partition
+
+=item *
+
+The metacharacter expression B<.*> (period and asterisk), which
+matches every machine name or partition name in the Volume
+Location Database (VLDB).
+
+=back
+
+For the B<-volumes> argument, specify a combination of alphanumeric
+characters and one or more metacharacters to wildcard part or all of
+the volume name. The B<Options> section lists the acceptable
+metacharacters.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name>
+
+Names the volume set to which to add this volume entry
+definition. The volume set must already exist (use the C<backup
+addvolset> command to create it).
+
+=item B<-server>
+
+Defines the set of one or more file server machines that house
+the volumes in the volume entry. Provide either one
+fully-qualified hostname (such as B<fs1.abc.com>) or the
+metacharacter expression B<.*> (period and asterisk), which
+matches all machine names in the VLDB.
+
+=item B<-partition>
+
+Defines the set of one or more partitions that house the
+volumes in the volume entry. Provide either one complete
+partition name (such as B</vicepa>) or the metacharacter
+expression B<.*> (period and asterisk), which matches all
+partition names.
+
+=item B<-volumes>
+
+Defines the set of one or more volumes included in the volume
+entry. Specify the volumes by name, by using any combination of
+regular alphanumeric characters and one or more of the
+following metacharacter expressions:
+
+=over
+
+=item B<.>
+
+The period matches any single character.
+
+=item B<*>
+
+The asterisk matches zero or more instances of the
+preceding character. Combine it with any other
+alphanumeric character or metacharacter.
+
+=item B<[ ]>
+
+Square brackets around a list of characters match a
+single instance of any of the characters, but no other
+characters; for example, B<[abc]> matches a single B<a> or B<b> or
+B<c>, but not B<d> or B<A>. This expression can be combined with
+the asterisk.
+
+=item B<^>
+
+The caret, when used as the first character in a
+square-bracketed set, designates a match with any single
+character I<except> the characters that follow it; for
+example, B<[^a]> matches any single character except
+lowercase B<a>. This expression can be combined with the
+asterisk.
+
+=item B<\>
+
+A backslash preceding any of the metacharacters in this
+list makes it match its literal value only. For example,
+the expression B<\.> (backslash and period) matches a single
+period, B<\*> a single asterisk, and B<\\> a single backslash.
+Such expressions can be combined with the asterisk (for
+example, B<\.*> matches any number of periods).
+
+=back
+
+Perhaps the most common metacharacter expression is the period
+followed by an asterisk (B<.*>). This expression matches any
+string of any length, because the period matches any character
+and the asterisk means any number of that character. As
+mentioned, it is the only acceptable metacharacter expression
+for the B<-server> and B<-partition> arguments. In a volume
+definition it can stand alone (in which case it matches every
+volume listed in the VLDB), or can combine with regular
+characters. The following example matches any volume name that
+begins with the string B<user> and ends with B<backup>:
+
+B<user.*backup>
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command adds a volume entry to the volume set called
+B<sys>. The entry matches all volumes on any machine or partition whose
+names begin with the string B<sun4x_56> followed by a period:
+
+  backup> addvolentry sys .* .* sun4x_56\..*
+
+The following command adds a volume entry to the volume set called
+fs2, to match all volumes on the /vicepb partition of file server
+machine fs2.abc.com. Because it is issued at the shell prompt, double
+quotes surround the metacharacters in the -volumes argument. (The
+command is shown here on two lines only for legibility reasons.)
+
+  backup addvolentry -name fs2 -server fs2.abc.com \
+                     -partition /vicepb -volumes ".*"
+
+The chapter in the IBM AFS Administration Guide about configuring the
+AFS Backup System presents additional examples as well as advice on
+grouping volumes.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+It is best to issue this command in interactive mode. If issuing it at
+the shell prompt, enclose any strings containing metacharacters in
+double quotes, or escape the metacharacters with other delimiters, to
+prevent the shell from interpreting them. Adding volume entries to a
+temporary volume set is possible only within the interactive session
+in which the volume set was created.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolset(1)>,
+L<backup_delvolentry(1)>,
+L<backup_delvolset(1)>,
+L<backup_listvolsets(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_addvolset.pod b/doc/man-pages/pod/backup_addvolset.pod
new file mode 100644 (file)
index 0000000..7c86bc6
--- /dev/null
@@ -0,0 +1,114 @@
+=head1 NAME
+
+backup addvolset - Creates a new (empty) volume set
+
+=head1 SYNOPSIS
+
+backup addvolset B<-name> I<volume set name> [B<-temporary>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup addvols B<-n> I<volume set name> [B<-t>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup addvolset> command creates a new volume set, by default
+adding it to the Backup Database. It is best that the volume set's
+name indicate the volume set's contents; for example, define the
+volume entries in the user volume set to match all user volumes. The
+volume set name must be unique within the Backup Database of the local
+cell.
+
+After issuing this command, issue the C<backup addvolentry> command to
+define the volume entries in the volume set.
+
+Sometimes it is convenient to create volume sets without recording
+them permanently in the Backup Database, for example when using the
+C<backup volsetrestore> command to restore a group of volumes that were
+not necessarily backed up together. To create a I<temporary> volume set,
+include the B<-temporary> flag. A temporary volume set exists only during
+the lifetime of the current interactive session, so the flag is
+effective only when used during an interactive session (opened by
+issuing the C<backup interactive> command). If it is included when the
+command is issued at the regular command shell prompt, the command
+appears to succeed, but the volume set is not created. As noted, a
+temporary volume set ceases to exist when the current interactive
+session ends, or use the C<backup delvolset> command to delete it before
+that.
+
+One advantage of temporary volume sets is that the C<backup addvolset>
+command, and any C<backup addvolentry> commands subsequently used to add
+volume entries to it, complete more quickly than for regular volume
+sets, because no records are created in the Backup Database.
+
+=head1 OPTIONS
+
+=over 4
+
+
+=item B<-name> I<volume set name>
+
+Names the new volume set. The name can include up to 31 of any
+character other than the period. Avoid other metacharacters as
+well.
+
+
+=item B<-temporary>
+
+Creates a volume set that exists only within the context of the
+current interactive session. It is not added to the Backup
+Database.
+
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command creates a volume set called sys:
+
+    backup addvolset sys
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolentry(1)>,
+L<backup_delvolentry(1)>,
+L<backup_delvolset(1)>,
+L<backup_listvolsets(1)>,
+L<backup_volsetrestore(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_apropos.pod b/doc/man-pages/pod/backup_apropos.pod
new file mode 100644 (file)
index 0000000..ac69496
--- /dev/null
@@ -0,0 +1,72 @@
+=head1 NAME
+
+backup apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+backup apropos B<-topic> I<help string>  [B<-help>]
+
+backup ap B<-t> I<help string>  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup apropos> command displays the first line of the online help
+entry for any C<backup> command that has in its name or short description
+the string specified by the B<-topic> argument.
+
+To display the syntax for a command, use the C<backup help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+
+=item B<-topic> I<help string>
+
+Specifies the keyword string to match, in lowercase letters
+only. If the string is more than a single word, surround it
+with double quotes (" ") or other delimiters.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of a command's online help entry names it and briefly
+describes its function. This command displays the first line for any
+C<backup> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following example lists all C<backup> commands that include the word
+B<tape> in their names or short descriptions:
+
+   backup apropos tape
+   labeltape: label a tape
+   readlabel: read the label on tape
+   scantape: dump information recovery from tape
+   status: get tape coordinator status
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_help(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_dbverify.pod b/doc/man-pages/pod/backup_dbverify.pod
new file mode 100644 (file)
index 0000000..e089b76
--- /dev/null
@@ -0,0 +1,144 @@
+=head1 NAME
+
+backup dbverify - Checks the integrity of the Backup Database
+
+=head1 SYNOPSIS
+
+backup dbverify [B<-detail>]  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup db [B<-d>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup dbverify> command checks the integrity of the Backup
+Database. The command's output indicates whether the Backup Database
+is damaged (data is corrupted) or not. If the Backup Database is
+undamaged, it is safe to continue using it. If it is corrupted,
+discontinue any backup operations until it is repaired.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-detail>
+
+Reports the number of orphaned blocks found, any
+inconsistencies, and the name of the server machine running the
+Backup Server that is checking its copy of the database.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command displays one of the following two messages:
+
+=over
+
+=item B<Database OK>
+
+The database is undamaged and can be used.
+
+=item B<Database not OK>
+
+The database is damaged. You can use the C<backup savedb> command
+to repair many kinds of corruption as it creates a backup copy.
+For more detailed instructions, see the IBM AFS Administration
+Guide chapter about performing backup operations.
+
+=back
+
+The B<-detail> flag provides additional information:
+
+=over
+
+=item *
+
+The number of I<orphan blocks> found. These are ranges of memory that
+the Backup Server preallocated in the database but cannot use.
+Orphan blocks do not interfere with database access, but do waste
+disk space. To free the unusable space, dump the database to tape
+by using the C<backup savedb> command, and then restore it by using
+the C<backup restoredb> command.
+
+=item *
+
+Any inconsistencies in the database, such as invalid hostnames for
+Tape Coordinator machines.
+
+=item *
+
+The name of the database server machine on which the Backup
+Database was checked, designated as the Database checker. For a
+detailed trace of the verification operation, see the
+B</usr/afs/logs/BackupLog> file on the indicated machine. You can use
+the C<bos getlog> command to display it.
+
+=back
+
+=head1 EXAMPLES
+
+The following command confirms that the Backup Database is undamaged:
+
+   backup dbverify
+   Database OK
+
+The following command confirms that the Backup Database is undamaged
+and that it has no orphan blocks or invalid Tape Coordinator entries.
+The Backup Server running on the machine B<db1.abc.com> checked its copy
+of the Database.
+
+   backup dbverify -detail
+   Database OK
+   Orphan blocks 0
+   Database checker was db1.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+While this command runs, no other backup operation can access the
+Backup Database; the other commands do not run until this command
+completes. Avoid issuing this command when other backup operations are
+likely to run. The C<backup savedb> command repairs some types of
+corruption.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BackupLog(1)>,
+L<bos_getlog(1)>,
+L<backup(1)>,
+L<backup_restoredb(1)>,
+L<backup_savedb(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_deldump.pod b/doc/man-pages/pod/backup_deldump.pod
new file mode 100644 (file)
index 0000000..bbd8c06
--- /dev/null
@@ -0,0 +1,78 @@
+=head1 NAME
+
+backup deldump - Deletes a dump level from the Backup Database
+
+=head1 SYNOPSIS
+
+backup deldump B<-dump> I<dump level name>  [B<-localauth>]
+[B<-cell> I<cell name>]  [B<-help>]
+
+backup deld B<-d> I<dump level name>  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup deldump> command deletes the indicated dump level and all of
+its child dump levels from the dump hierarchy in the Backup Database.
+Use the C<backup listdumps> command to display the dump hierarchy.
+
+=head1 OPTIONS
+
+=over 4
+
+
+=item B<-dump> I<dump level name>
+
+Specifies the complete pathname of the dump level to delete.
+
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command deletes the dump level B</sunday1/monday1> from the
+dump hierarchy, along with any of its child dump levels.
+
+    backup deldump /sunday1/monday1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_adddump(1)>,
+L<backup_listdumps(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_deletedump.pod b/doc/man-pages/pod/backup_deletedump.pod
new file mode 100644 (file)
index 0000000..ad3fff3
--- /dev/null
@@ -0,0 +1,212 @@
+=head1 NAME
+
+backup deletedump - Deletes one or more dump records from the Backup Database
+
+=head1 SYNOPSIS
+
+backup deletedump [B<-dumpid> I<dump id> [I<dump id> ...]]  [B<-from> I<date time> ...] 
+[B<-to> I<date time> ...] [B<-localauth>] [B<-cell> I<cell name>]  [B<-help>]
+
+backup dele [B<-d> I<dump id> [I<dump id> ...]]  [B<-f> I<date time> [I<date time> ...]] 
+[B<-t> I<date time> [I<date time> ...]] [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup deletedump> command deletes one or more dump records from
+the Backup Database. Either use the B<-dumpid> argument to specify the
+dump ID number of one or more dumps, or use the B<-from> and B<-to>
+arguments to delete the records for all regular dumps created during
+the time period bracketed by the specified values.
+
+Use this command to remove dump records that are incorrect (possibly
+because a dump operation was interrupted or failed), or that
+correspond to dumps that are expired or otherwise no longer needed.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dumpid> I<dump id> [I<dump id> ...]
+
+Specifies the dump ID of each dump record to delete. The
+corresponding dumps must be initial dumps; it is not possible
+to delete appended dump records directly, but only by deleting
+the record of their associated initial dump. Using this
+argument is the only way to delete records of Backup Database
+dumps (created with the C<backup savedb> command).
+
+Provide either this argument or the B<-to> (and optionally B<-from>)
+argument.
+
+=item B<-from> I<date time> ...
+
+Specifies the beginning of a range of dates; the record for any
+dump created during the indicated period of time is deleted.
+
+Omit this argument to indicate the default of midnight (00:00
+hours) on 1 January 1970 (UNIX time zero), or provide a date
+value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>]. The month (I<mm>), day
+(I<dd>), and year (I<yyyy>) are required. The hour and minutes
+(I<hh>:I<MM>) are optional, but if provided must be in 24-hour format
+(for example, the value B<14:36> represents 2:36 p.m.). If
+omitted, the time defaults to midnight (00:00 hours).
+
+The B<-to> argument must be provided along with this one.
+
+=over
+
+=item B<Note:>
+
+A ... follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition.
+
+=back
+
+=item B<-to> I<date time> ...
+
+Specifies the end of a range of dates; the record of any dump
+created during the range is deleted from the Backup Database.
+
+Provide either the value B<NOW> to indicate the current date and
+time, or a date value in the same format as for the B<-from>
+argument. Valid values for the year (I<yyyy>) range from B<1970> to
+B<2037>; higher values are not valid because the latest possible
+date in the standard UNIX representation is in February 2038.
+The command interpreter automatically reduces any later date to
+the maximum value.
+
+If the time portion (I<hh>:I<MM>) is omitted, it defaults to 59
+seconds after midnight (00:00:59 hours). Similarly, the C<backup>
+command interpreter automatically adds 59 seconds to any time
+value provided. In both cases, adding 59 seconds compensates
+for how the Backup Database and C<backup dumpinfo> command
+represent dump creation times in hours and minutes only. For
+example, the Database records a creation timestamp of 20:55 for
+any dump operation that begins between 20:55:00 and 20:55:59.
+Automatically adding 59 seconds to a time thus includes the
+records for all dumps created during that minute.
+
+Provide either this argument, or the B<-dumpid> argument. This
+argument is required if the B<-from> argument is provided.
+
+B<Caution>: Specifying the value B<NOW> for this argument when the
+B<-from> argument is omitted deletes all dump records from the
+Backup Database (except for Backup Database dump records
+created with the C<backup savedb> command).
+
+=over
+
+=item B<Note:>
+
+A ... follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition.
+
+=back
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+
+=item B<-cell>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+At the conclusion of processing, the output lists the dump IDs of all
+dump records deleted in the following format:
+
+   The following dumps were deleted:
+      dump ID 1
+      dump ID 2
+      etc.
+
+=head1 EXAMPLES
+
+The following command deletes the dump record with dump ID 653777462,
+and for any appended dumps associated with it:
+
+   backup deletedump -dumpid 653777462
+   The following dumps were deleted:
+      653777462
+
+The following command deletes the Backup Database record of all dumps
+created between midnight on 1 January 1997 and 23:59:59 hours on 31
+December 1997:
+
+   backup deletedump -from 01/01/1997 -to 12/31/1997
+   The following dumps were deleted:
+      598324045
+      598346873
+         ...
+         ...
+      653777523
+      653779648
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+The only way to remove the dump record for an appended dump is to
+remove the record for its initial dump, and doing so removes the
+records for all of the initial dump's associated appended dumps.
+
+The only way to remove the record for a Backup Database dump (created
+with the C<backup savedb> command) is to specify its dump ID number with
+the B<-dumpid> argument. Using the B<-from> and B<-to> arguments never removes
+database dump records.
+
+Removing records of a dump makes it impossible to restore data from
+the corresponding tapes or from any dump that refers to the deleted
+dump as its parent, directly or indirectly. That is, restore
+operations must begin with the full dump and continue with each
+incremental dump in order. If the records for a specific dump are
+removed, it is not possible to restore data from later incremental
+dumps unless the deleted records are restored by running the C<backup
+scantape> command with the B<-dbadd> flag.
+
+If a dump set contains any dumps that were created outside the time
+range specified by the B<-from> and B<-to> arguments, the command does not
+delete any of the records associated with the dump set, even if some
+of them represent dumps created during the time range.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dumpinfo(1)>,
+L<backup_scantape(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_delhost.pod b/doc/man-pages/pod/backup_delhost.pod
new file mode 100644 (file)
index 0000000..f842843
--- /dev/null
@@ -0,0 +1,93 @@
+=head1 NAME
+
+backup delhost - Deletes a Tape Coordinator entry from the Backup Database
+
+=head1 SYNOPSIS
+
+backup delhost B<-tapehost> I<tape machine name> [B<-portoffset> I<TC port offset>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup delh B<-t> I<tape machine name>  [B<-p> I<TC port offset>]
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup delhost> command deletes the indicated Tape Coordinator
+entry from the Backup Database. It is then impossible to submit backup
+operations to that Tape Coordinator, even if it is still running. To
+keep configuration information consistent, also remove the
+corresponding entry from the B</usr/afs/backup/tapeconfig> file on the
+Tape Coordinator machine.
+
+To list the Tape Coordinator machines and port offsets defined in the
+Backup Database, issue the C<backup listhosts> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-tapehost> I<tape machine name>
+
+Specifies the hostname of the machine housing the Tape
+Coordinator to delete.
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator to
+delete. If omitted, it defaults to B<0>. If provided, it is an
+integer between B<0> (zero) and B<58510>, and must match the port
+offset number assigned to the same combination of Tape
+Coordinator and tape device or file in the
+B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine
+indicated by the B<-tapehost> argument.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command deletes the Backup Database entry for the Tape
+Coordinator with port offset 2 on the Tape Coordinator machine
+B<backup3.abc.com>:
+
+   backup delhost -tapehost backup3.abc.com -portoffset 2
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addhost(1)>,
+L<backup_listhosts(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_delvolentry.pod b/doc/man-pages/pod/backup_delvolentry.pod
new file mode 100644 (file)
index 0000000..f1f3826
--- /dev/null
@@ -0,0 +1,93 @@
+=head1 NAME
+
+backup delvolentry - Deletes a volume entry from a volume set
+
+=head1 SYNOPSIS
+
+backup delvolentry B<-name> I<volume set name>  B<-entry> I<volume set index>
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup delvole  B<-n> I<volume set name>  B<-e> I<volume set index>
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup delvolentry> command deletes the indicated volume entry from
+the volume set specified with the B<-name> argument. Use the B<-entry>
+argument to identify the volume entry by its index number. To display
+the index numbers, use the C<backup listvolsets> command.
+
+If there are any remaining volume entries with index numbers higher
+than the deleted entry, their indexes are automatically decremented to
+eliminate any gaps in the indexing sequence.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<volume set name>
+
+Names the volume set from which to delete a volume entry.
+
+=item B<-entry> I<volume set index>
+
+Specifies the index number of the volume entry to delete. Use
+the C<backup listvolsets> command to display the index numbers for
+a volume set's volume entries.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command deletes the fourth volume entry from the volume
+set called B<sys>:
+
+   backup delvolentry -name sys -entry 4
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Deleting volume entries from a temporary volume set is possible only
+within the interactive session in which the volume set was created.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_delvolset(1)>,
+L<backup_listvolsets(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_delvolset.pod b/doc/man-pages/pod/backup_delvolset.pod
new file mode 100644 (file)
index 0000000..025e3ab
--- /dev/null
@@ -0,0 +1,83 @@
+=head1 NAME
+
+backup delvolset - Deletes one or more volume sets from the Backup Database
+
+=head1 SYNOPSIS
+
+backup delvolset B<-name> I<volume set name> [I<volume set name> ...]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup delvols B<-n> I<volume set name> [I<volume set name> ...]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup delvolset> command deletes each volume set named by the
+B<-name> argument, and the volume entries each contains, from the Backup
+Database. The C<backup listvolsets> command lists the volume sets (and
+their volume entries) currently defined in the Backup Database.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<volume set name> [I<volume set name> ...]
+
+Names each volume set to delete.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command deletes the volume set called user and all
+volume entries in it:
+
+   backup delvolset user
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Deleting a temporary volume set is possible only within the
+interactive session in which it was created. Exiting the interactive
+session also destroys the temporary volume set automatically.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_delvolentry(1)>,
+L<backup_listvolsets(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_diskrestore.pod b/doc/man-pages/pod/backup_diskrestore.pod
new file mode 100644 (file)
index 0000000..31bbdef
--- /dev/null
@@ -0,0 +1,280 @@
+=head1 NAME
+
+backup diskrestore - Restores the entire contents of a partition
+
+=head1 SYNOPSIS
+
+backup diskrestore B<-server> I<machine to restore>
+B<-partition> I<partition to restore>
+[B<-portoffset> I<TC port offset> [I<TC port offset> ...]]
+[B<-newserver> I<destination machine>]
+[B<-newpartition> I<destination partition>]
+[B<-extension> I<new volume name extension>]
+[B<-n>]  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup di B<-s> I<machine to restore> B<-pa> I<partition to restore>
+[B<-po> I<TC port offset> [I<TC port offset> ...]]  [B<-news> I<destination machine>]
+[B<-newp> I<destination partition>]  [B<-e> I<new volume name extension>]
+[B<-n>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup diskrestore> command restores all of the volumes for which
+the Volume Location Database (VLDB) lists a read/write site on the
+partition specified with the B<-server> and B<-partition> arguments. It is
+useful if a disk or machine failure corrupts or destroys the data on
+an entire partition. (To restore any read-only or backup volumes that
+resided on the partition, use the C<vos release> and C<vos backup> commands,
+respectively, after restoring the read/write version.)
+
+If restoring only selected volumes to a single site, it is usually
+more efficient to use the C<backup volrestore> command. To restore
+multiple volumes to many different sites, use the C<backup volsetrestore> command.
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG>I<_device_name> file on the Tape Coordinator machine
+associated with the specified port offset, then the Backup System
+restores data from the backup data file listed for that port offset in
+the Tape Coordinator's B</usr/afs/backup/tapeconfig> file, instead of
+from tape. For the sake of clarity, the following text refers to tapes
+only, but the Backup System handles backup data files in much the same
+way.)
+
+The Backup System determines whether the read/write or backup version
+of each volume was dumped more recently, and restores the dumps of
+that version, starting with the most recent full dump. It resets the
+creation timestamp of each restored volume to the date and time at
+which it begins restoring the volume (the creation timestamp appears
+in the Creation field of the output from the C<vos examine> and C<vos
+listvol> commands).
+
+If all of the full and incremental dumps of all relevant volumes were
+not written on compatible tape devices, use the B<-portoffset> argument
+to list multiple port offset numbers in the order in which the tapes
+are needed (first list the port offset for the full dump, second the
+port offset for the level 1 incremental dump, and so on). This implies
+that the full dumps of all relevant volumes must have been written to
+a type of tape that the first Tape Coordinator can read, the level 1
+incremental dumps to a type of tape the second Tape Coordinator can
+read, and so on. If dumps are on multiple incompatible tape types, use
+the C<backup volrestore> command to restore individual volumes, or the
+C<backup volsetrestore> command after defining groups of volumes that
+were dumped to compatible tape types. For further discussion, see the
+IBM AFS Administration Guide.
+
+By default, the Backup System restores the contents of the specified
+partition to that same partition. To restore the contents to an
+alternate site, combine the following options as indicated. The Backup
+System removes each volume from the original site, if it still exists,
+and records the change of site in the VLDB.
+
+=over
+
+=item *
+
+To restore to a different partition on the same file server
+machine, provide the B<-newpartition> argument.
+
+=item *
+
+To restore to the partition with the same name on a different file
+server machine, provide the B<-newserver> argument.
+
+=item *
+
+To restore to a completely different site, combine the B<-newserver>
+and B<-newpartition> arguments.
+
+=back
+
+By default, the Backup System overwrites the contents of existing
+volumes with the restored data. To create a new volume to house the
+restored data instead, use the B<-extension> argument. The Backup System
+creates the new volume at the site designated by the B<-newserver> and
+B<-newpartition> arguments if they are used or the B<-server> and B<-partition>
+arguments otherwise. It derives the volume name by adding the
+extension to the read/write base name listed in the VLDB, and creates
+a new VLDB entry. The command does not affect the existing volume in
+any way. However, if a volume with the specified extension also
+already exists, the command overwrites it.
+
+To print out a list of the tapes containing the needed dumps, without
+actually performing the restore operation, include the B<-n> flag along
+with the other options to be used on the actual command.
+
+The Tape Coordinator's default response to this command is to access
+the first tape it needs by invoking the B<MOUNT> instruction in the local
+B<CFG>I<_device_name> file, or by prompting the backup operator to insert
+the tape if there is no B<MOUNT> instruction. However, if the B<AUTOQUERY
+NO> instruction appears in the B<CFG>I<_device_name> file, or if the issuer
+of the C<butc> command included the B<-noautoquery> flag, the Tape
+Coordinator instead expects the tape to be in the device already. If
+it is not, or is the wrong tape, the Tape Coordinator invokes the
+B<MOUNT> instruction or prompts the operator. It also invokes the B<MOUNT>
+instruction or prompts for any additional tapes needed to complete the
+restore operation; the backup operator must arrange to provide them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine to restore>
+
+Names the file server machine that the VLDB lists as the site
+of the volumes that need to be restored.
+
+=item B<-partition> I<partition to restore>
+
+Names the partition that the VLDB lists as the site of the
+volumes that need to be restored.
+
+=item B<-portoffset> I<TC port offset> [I<TC port offset> ...]
+
+Specifies one or more port offset numbers (up to a maximum of
+128), each corresponding to a Tape Coordinator to use in the
+operation. If there is more than one value, the Backup System
+uses the first one when restoring the full dump of each volume,
+the second one when restoring the level 1 incremental dump of
+each volume, and so on. It uses the final value in the list
+when restoring dumps at the corresponding depth in the dump
+hierarchy and at all lower levels.
+
+Provide this argument unless the default value of 0 (zero) is
+appropriate for all dumps. If B<0> is just one of the values in
+the list, provide it explicitly in the appropriate order.
+
+=item B<-newserver> I<destination machine>
+
+Names an alternate file server machine to which to restore the
+volumes. If this argument is omitted, the volumes are restored
+to the file server machine named by the B<-server> argument.
+
+=item B<-newpartition> I<destination partition>
+
+Names an alternate partition to which to restore the data. If
+this argument is omitted, the volumes are restored to the
+partition named by the B<-partition> argument.
+
+=item B<-extension> I<new volume name extension>
+
+Creates a new volume for each volume being restored, to house
+the restored data. The Backup System derives the new volume's
+name by appending the specified string to the read/write base
+name listed in the VLDB, and creates a new VLDB volume entry.
+The Backup System preserves the contents of the volumes on the
+partition, if any still exist. Any string other than B<.readonly>
+or B<.backup> is acceptable, but the combination of the base name
+and extension cannot exceed 22 characters in length. To use a
+period to separate the extension from the name, specify it as
+the first character of the string (as in B<.rst>, for example).
+
+=item B<-n>
+
+Displays a list of the tapes necessary to perform the requested
+restore, without actually performing the operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If a tape error occurs during the restore operation, the Tape
+Coordinator displays the following messages:
+
+   Restore operation on volume name failed due to tape error
+   Do you want to continue (y/n)?
+
+where I<name> is the name of the volume that was being restored when the
+tape error occurred. Enter the value B<y> to continue the operation
+without restoring the indicated volume or the value B<n> to terminate the
+operation. In the latter case, the operator can then attempt to
+determine the cause of the tape error.
+
+If the issuer includes the B<-n> flag with the command, the following
+string appears at the head of the list of the tapes necessary to
+perform the restore operation:
+
+   Tapes needed:
+
+=head1 EXAMPLES
+
+The following command restores the volumes for which the VLDB lists a
+read/write site on the B</vicepd> partition of the machine B<fs5.abc.com>.
+The Tape Coordinator associated with port offset 3 performs the
+operation.
+
+   backup diskrestore -server fs5.abc.com -partition /vicepd -portoffset 3
+
+The following command restores the volumes for which the VLDB lists a
+read/write site on the B</vicepb> partition of the machine B<fs1.abc.com> to
+a new site: the B</vicepa> partition on the machine B<fs3.abc.com>. The Tape
+Coordinator associated with port offset 0 performs the operation. (The
+command appears here on two lines only for legibility.)
+
+   backup diskrestore  -server fs1.abc.com -partition /vicepb   \
+                       -newserver fs3.abc.com -newpartition /vicepa
+
+The following command lists the tapes required to restore the volumes
+for which the VLDB lists a read/write site on the B</vicepm> partition of
+the machine B<fs4.abc.com>:
+
+   backup diskrestore -server fs4.abc.com -partition /vicepm -n
+   Tapes needed:
+   user.sunday1.1
+   user.sunday1.2
+   user.monday1.1
+   user.tuesday1.1
+   user.wednesday1.1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is
+running, and on every file server machine that houses an affected
+volume. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser B<root>.
+
+=head1 CAVEATS
+
+If issuing this command to recover data after a disk crash or other
+damage, be sure not to issue the C<vos syncserv> command first. Doing so
+destroys the VLDB record of the volumes that resided on the partition.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dump(1)>,
+L<backup_volrestore(1)>,
+L<backup_volsetrestore(1)>,
+L<butc(1)>,
+L<vos_backup(1)>,
+L<vos_examine(1)>,
+L<vos_listvol(1)>,
+L<vos_release(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_dump.pod b/doc/man-pages/pod/backup_dump.pod
new file mode 100644 (file)
index 0000000..3abed19
--- /dev/null
@@ -0,0 +1,547 @@
+=head1 NAME
+
+backup dump - Creates a dump (dumps a volume set at a particular dump level)
+
+=head1 SYNOPSIS
+
+backup dump [B<-volumeset> I<volume set name>]  [B<-dump> I<dump level name>]
+[B<-portoffset> I<TC port offset>]  [B<-at> I<Date/time to start dump> ...]
+[B<-append>]  [B<-n>]  [B<-file> I<load file>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup dump [B<-v> I<volume set name>]  [B<-d> I<dump level name>]
+[B<-p> I<TC port offset>]  [B<-at> I<Date/time to start dump> ...]
+[B<-ap>]  [B<-n>]  [B<-f> I<load file>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup dump> command either dumps the volume set specified by the
+B<-volumeset> argument at the dump level specified by the B<-dump> argument
+and creates a Backup Database dump record about it, or executes the
+dump instructions listed in the file named by the B<-file> argument. The
+Tape Coordinator indicated by the B<-portoffset> argument (or on each
+command in the file) executes the operation.
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG>I<_device_name> file on the Tape Coordinator machine
+associated with the specified port offset, then the Backup System
+dumps data to the backup data file listed for that port offset in the
+Tape Coordinator's B</usr/afs/backup/tapeconfig> file, rather than to
+tape. For the sake of clarity, the following text refers to tapes
+only, but the Backup System handles backup data files in much the same
+way.)
+
+The term I<dumping> refers to copying a collection of data to tape or a
+backup data file, and the resulting collection is termed a I<dump>. The
+set of tapes that contain one or more dumps is called a I<dump set>. The
+first dump in a dump set is its I<initial dump>, and any dumps
+subsequently added to the dump set (by use of the B<-append> argument)
+are I<appended dumps>. Creating appended dumps is optional, and appended
+dumps can be of different volume sets, and at different dump levels,
+than the initial dump.
+
+A I<full dump>, created at a full dump level in the dump hierarchy,
+contains all of the data that existed at the time of the dump in the
+volumes belonging to the volume set. An I<incremental dump>, created at
+an incremental dump level, contains only data that has changed since
+the volume set was dumped at the incremental level's I<parent dump level>
+(the dump level immediately above the incremental level in the
+hierarchy), which can be a full or incremental level. More
+specifically, an incremental dump includes only the files and
+directories that have modification timestamps later than the I<clone
+date> of the volume included at the parent dump level. For backup and
+read-only volumes, the clone date is the time at which the volume was
+cloned from its read/write source before being included in the parent
+dump; for read/write volumes, it represents the time at which the
+volume was locked for inclusion in the parent dump. The clone date
+appears in the I<clone date> field of the output from the C<backup volinfo>
+command. As an example, an incremental dump at the
+B</full/week1/thursday> level includes only files and directories that
+have changed since the volume set was dumped at the B</full/week1> level.
+
+=head2 Initiating different types of dump operations
+
+To initiate a dump operation that is to start as soon as the relevant
+Tape Coordinator is available, provide only the B<-volumeset>, B<-dump>,
+B<-portoffset>, and optionally B<-append> options. To schedule a single
+C<backup dump> command to execute in the future, also include the B<-at>
+argument to specify the start time.
+
+To append a dump to an existing dump set, include the B<-append> flag.
+The Backup System imposes the following conditions on appended dumps:
+
+=over
+
+=item *
+
+If writing to tape, the Tape Coordinator checks that it is the
+final one in a dump set for which there are complete and valid
+tape and dump records in the Backup Database. If not, it rejects
+the tape and requests an acceptable one. The operator can use the
+B<-dbadd> argument to the C<backup scantape> command to insert the
+necessary records into the database.
+
+=item *
+
+The most recent dump on the tape or in the backup data file must
+have completed successfully.
+
+=item *
+
+The dump set must begin with an initial dump that is recorded in
+the Backup Database. If there are no dumps on the tape, then the
+Backup System treats the dump operation as an initial dump and
+imposes the relevant requirements (for example, checks the AFS
+tape name if appropriate).
+
+=back
+
+To schedule multiple dump operations, list the operations in the file
+named by the B<-file> argument. Optionally include the B<-at> argument to
+specify when the C<backup> command interpreter reads the file; otherwise
+it reads it immediately. Do not combine the B<-file> argument with the
+command's first three arguments or the B<-append> or B<-n> flags. The
+commands in the file can include any of the C<backup dump> command's
+arguments, including the B<-at> argument to schedule them to run even
+later in the future.
+
+To generate a list of the volumes included in a dump, without actually
+dumping them, combine the B<-n> flag with the options to be used on the
+actual command.
+
+=head2 How the Backup System executes a dump operation
+
+Before beginning a dump operation, the Backup System verifies that
+there is a Backup Database entry for the volume set, dump level, and
+port offset. If the command is correctly formed and issued in
+interactive mode, it is assigned a job number and added to the jobs
+list. List jobs in interactive mode by using the C<(backup) jobs>
+command; terminate them with the C<(backup) kill> command.
+
+After obtaining the list of volumes to dump from the Volume Location
+(VL) Server, the Backup System sorts the list by site (server and
+partition). It groups volumes from the same site together in the dump
+to minimize the number of times the operator must change tapes during
+restore operations.
+
+The dependence of an incremental dump on its parent means that a valid
+parent dump must already exist for the Backup System to create its
+child incremental dump. If the Backup System does not find a record of
+a dump created at the immediate parent dump level, it looks in the
+Backup Database for a dump created at one level higher in the
+hierarchy, and so on, up to the full dump level if necessary. It
+creates an incremental dump at the level one below the lowest valid
+parent dump set that it finds. If it fails to find even a full dump,
+it dumps the volume set at the full dump level.
+
+If the Backup System is unable to access a volume during a dump
+operation, it skips the volume and dumps the remaining volumes from
+the volume set. Possible reasons a volume is inaccessible include
+server machine or process outages, or that the volume was moved
+between the time the Volume Location (VL) Server generated the list of
+sites for the volume in the volume set and the time the Backup System
+actually attempts to dump the data in it. After the first dumping
+pass, the Backup System attempts to dump each volume it skipped. If it
+still cannot dump a volume and the B<ASK NO> instruction does not appear
+in the B<CFG>I<_device_name> file, it queries the operator as to whether it
+needs to attempt to dump the volume again, omit the volume from the
+dump, or halt the dump operation altogether. When prompted, the
+operator can attempt to solve whatever problem prevented the Backup
+System from accessing the volumes. If the B<ASK NO> instruction appears
+in the B<CFG>I<_device_name> file, the Backup System omits the volume from
+the dump.
+
+Before scheduling a dump operation, the Backup System verifies that
+the date specified by the B<-at> argument is in the future, and checks
+the validity of the volume set, dump level and port offset as for a
+regular dump operation. It checks the validity of the parameters again
+just before actually running the scheduled operation.
+
+Before writing an initial dump to a tape that does not have a
+permanent name on the label, the Backup System checks that the AFS
+tape name on the label is acceptable. If desired, disable name
+checking by including the B<NAME_CHECK NO> instruction in the
+B<CFG>I<_device_name> file.
+
+If AFS tape name checking is enabled, the Backup System accepts the
+following three types of values for the AFS tape name. If the name on
+the label does not conform, the Backup System obtains a tape with an
+acceptable label by invoking the B<MOUNT> instruction in the
+B<CFG>I<_device_name> file or prompting the operator.
+
+=over
+
+=item 1.
+
+A name of the form I<volume_set_name>.I<dump_level_name>.I<tape_index>,
+where I<volume_set_name> matches the value of the B<-volumeset>
+argument, I<dump_level_name> matches the last element in the pathname
+value of the B<-dump> argument, and I<tape_index> reflects the tape's
+place in a multitape dump set. As an example, the first tape in a
+dump set for which the initial dump is of volume set user at the
+dump level B</sunday2/monday> has AFS tape name B<user.monday.1>. If the
+label records this type of AFS tape name, the Backup System
+retains the AFS tape name and writes the dump to the tape.
+
+=item 2.
+
+The string C<E<lt>NULLE<gt>>, which usually indicates that a backup operator
+has used the C<backup labeltape> command to write a label on the
+tape, but did not include the B<-name> argument to assign an AFS tape
+name. Presumably, the operator did include the B<-pname> argument to
+assign a permanent name. If the label records a C<E<lt>NULLE<gt>> value, the
+Backup System constructs and records on the label the appropriate
+AFS tape name, and writes the dump on the tape.
+
+=item 3.
+
+No value at all, because the tape has never been labeled or used
+in the Backup System. As when the AFS tape name is C<E<lt>NULLE<gt>>, the
+Backup System constructs and records on the label the appropriate
+AFS tape name, and writes the dump on the tape.
+
+=back
+
+To determine how much data it can write to a tape, the Tape
+Coordinator reads the capacity recorded on the tape's label (placed
+there by including the B<-size> argument to the C<backup labeltape> command).
+If the label's capacity field is empty, the Tape Coordinator
+uses the capacity recorded for the specified port offset in the local
+B<tapeconfig> file. If the capacity field in the B<tapeconfig> file is also
+empty, the Tape Coordinator uses the maximum capacity of 2 TB.
+
+During a dump operation, the Tape Coordinator tracks how much data it
+has written and stops shortly before it reaches what it believes is
+the tape's capacity. If it is in the middle of writing the data for a
+volume when it reaches that point, it writes a special marker that
+indicates an interrupted volume and continues writing the volume on
+the next tape. It can split a volume this way during both an initial
+and an appended dump, and the fact that the volume resides on multiple
+tapes is automatically recorded in the Backup Database.
+
+If the tape is actually larger than the expected capacity, then the
+Tape Coordinator simply does not use the excess tape. If the tape is
+smaller than the expected capacity, the Tape Coordinator can reach the
+end-of-tape (EOT) unexpectedly while it is writing data. If the Tape
+Coordinator is in the middle of the writing data from a volume, it
+obtains a new tape and rewrites the entire contents of the interrupted
+volume to it. The data from the volume that was written to the
+previous tape remains there, but is never used.
+
+The Backup System allows recycling of tapes (writing a new dump set
+over an old dump set that is no longer needed), but imposes the
+following conditions:
+
+=over
+
+=item *
+
+All dumps in the old dump set must be expired. The Backup System
+always checks expiration dates, even when name checking is
+disabled.
+
+=item *
+
+If the tape to be recycled does not have a permanent name and name
+checking is enabled, then the AFS tape name derived from the new
+initial dump's volume set name and dump level name must match the
+AFS tape name already recorded on the label.
+
+=item *
+
+The tape cannot already have data on it that belongs to the dump
+currently being performed, because that implies that the operator
+or automated tape device has not removed the previous tape from
+the drive, or has mistakenly reinserted it. The Tape Coordinator
+generates the following message and attempts to obtain another
+tape:
+
+   Can't overwrite tape containing the dump in progress
+
+=item *
+
+The tape cannot contain data from a parent dump of the current
+(incremental) dump, because overwriting a parent dump makes it
+impossible to restore data from the current dump. The Tape
+Coordinator generates the following message and attempts to obtain
+another tape:
+
+   Can't overwrite the parent dump parent_name (parent_dump_ID)
+
+=back
+
+To recycle a tape before all dumps on it have expired or if the AFS
+tape name is wrong, use the C<backup labeltape> command to overwrite the
+tape's label and remove all associated tape and dump records from the
+Backup Database.
+
+The Tape Coordinator's default response to this command is to access
+the first tape by invoking the B<MOUNT> instruction in the
+B<CFG>I<_device_name> file, or by prompting the backup operator to insert
+the tape if there is no B<MOUNT> instruction. However, if the B<AUTOQUERY
+NO> instruction appears in the B<CFG>I<_device_name> file, or if the issuer
+of the butc command included the B<-noautoquery> flag, the Tape
+Coordinator instead expects the tape to be in the device already. If
+it is not, the Tape Coordinator invokes the B<MOUNT> instruction or
+prompts the operator. It also invokes the B<MOUNT> instruction or prompts
+for any additional tapes needed to complete the dump operation; the
+issuer must arrange to provide them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-volumeset> I<volume set name>
+
+Names the volume set to dump. The B<-dump> argument must be
+provided along with this one; do not combine them with the
+B<-file> argument. If using a temporary volume set, the C<vos dump>
+command must be issued within the interactive session in which
+the C<backup addvolset> command was issued with the B<-temporary>
+flag.
+
+=item B<-dump> I<dump level name>
+
+Specifies the complete pathname of the dump level at which to
+dump the volume set. The B<-volumeset> argument must be provided
+along with this one; do not combine them with the B<-file>
+argument.
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator
+handling the tapes for this operation. It must be provided
+unless the default value of 0 (zero) is appropriate; do not
+combine it with the B<-file> argument.
+
+=item B<-at> I<Date/time to start dump> ...
+
+Specifies the date and time in the future at which to run the
+command, or to read the file named by the B<-file> argument.
+Provide a value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>], where the
+month (I<mm>), day (I<dd>), and year (I<yyyy>) are required. Valid
+values for the year range from B<1970> to B<2037>; higher values are
+not valid because the latest possible date in the standard UNIX
+representation is in February 2038. The Backup System
+automatically reduces any later date to the maximum value.
+
+The hour and minutes (I<hh>:I<MM>) are optional, but if provided must
+be in 24-hour format (for example, the value B<14:36> represents
+2:36 p.m.). If omitted, the time defaults to midnight (00:00
+hours).
+
+As an example, the value B<04/23/1999 20:20> schedules the command
+for 8:20 p.m. on 23 April 1999.
+
+=over
+
+=item B<Note:>
+
+A ... follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition.
+
+=back
+
+=item B<-append>
+
+Appends the dump onto the end of a tape that already contains
+data from another dump. However, if the tape is not in fact
+part of an existing dump set, the Backup System creates a new
+dump set using the parameters of this dump. If the tape is not
+the last tape in the dump set, the Tape Coordinator prompts for
+insertion of the appropriate tape. Do not combine this argument
+with the B<-file> argument.
+
+=item B<-n>
+
+Displays the names of volumes to be included in the indicated
+dump, without actually performing the dump operation. Do not
+combine this argument with the B<-file> argument.
+
+=item B<-file> I<load file>
+
+Specifies the local disk or AFS pathname of a file containing
+C<backup> commands. The Backup System reads the file immediately,
+or at the time specified by the B<-at> argument if it is provided.
+A partial pathname is interpreted relative to the current
+working directory.
+
+Place each C<backup dump> command on its own line in the indicated
+file, using the same syntax as for the command line, but
+without the word B<backup> at the start of the line. Each command
+must include a value for the B<-volumeset> and B<-dump> arguments,
+and for the B<-portoffset> argument unless the default value of 0
+is appropriate. Commands in the file can also include any of
+the C<backup dump> command's optional options. In the following
+example file, the first command runs as soon as the Backup
+System reads the file, whereas the other commands are
+themselves scheduled; the specified date and time must be later
+than the date and time at which the Backup System reads the
+file.
+
+   dump user /sunday1/wednesday -port 1
+   dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999
+   dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append
+
+Do not combine this argument with the B<-volumeset>, B<-dump>,
+B<-portoffset>, B<-append>, or B<-n> options.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command interpreter first generates a list of the volumes to be
+included in the dump by matching the entries in the volume set against
+the volumes listed in the Volume Location Database (VLDB). It prints
+the list following the header:
+
+   Preparing to dump the following volumes:
+
+The following message then indicates that the command interpreter has
+passed the dump request to the appropriate Tape Coordinator for
+processing:
+
+   Starting dump.
+
+If the issuer includes the B<-n> flag, the output is of the following
+form:
+
+   Starting dump of volume set 'volume set' (dump set 'dump level')
+   Total number of volumes : number dumped
+   Would have dumped the following volumes:
+   list_of_volumes
+
+where list_of_volumes identifies each volume by name and volume ID
+number.
+
+If the Tape Coordinator is unable to access a volume, it prints an
+error message in its window and records the error in its log and error
+files.
+
+=head1 EXAMPLES
+
+The following command dumps the volumes in the volume set called user
+at the dump level B</full/sunday2/monday>. The issuer places the
+necessary tapes in the device with port offset 5.
+
+   backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
+   Preparing to dump the following volumes:
+   user.jones.backup   387623900
+   user.pat.backup     486219245
+   user.smith.backup   597315841
+          .                .
+          .                .
+   Starting dump.
+
+The following command displays the list of volumes to be dumped when
+the user dumps the B<sys_sun> volume set at the B</full> dump level.
+
+   backup dump -volumeset sys_sun -dump /full -n
+   Starting dump of volume set 'sys_sun' (dump set '/full')
+   Total number of volumes: 24
+   Would have dumped the following volumes:
+   sun4x_56      124857238
+   sun4x_56.bin  124857241
+       .            .
+       .            .
+   sun4x_55      124857997
+       .            .
+       .            .
+
+The following command schedules a dump of the volumes in the volume
+set B<user> at the dump level B</sunday2/monday1> for 11:00 p.m. on 14 June
+1999. The appropriate Tape Coordinator has port offset 0 (zero), so
+that argument is omitted.
+
+   backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is
+running, and on every file server machine that houses an affected
+volume. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser B<root>.
+
+=head1 CAVEATS
+
+If a dump operation is interrupted or fails for any reason, data from
+all volumes written to tape before the interrupt are valid can be used
+in a restore operation. The Backup Database includes an entry for the
+failed dump and for each volume that was successfully dumped. See the
+IBM AFS Administration Guide for information on dealing with
+interrupted dumps.
+
+If dumping to tape rather than a backup data file, it is best to use
+only compatible tape devices (ones that can read the same type of
+tape). Using compatible devices greatly simplifies restore operations.
+The B<-portoffset> argument to the C<backup diskrestore> and C<backup
+volsetrestore> commands accepts multiple port offset numbers, but the
+Backup System uses the first listed port offset when restoring all
+full dumps, the second port offset when restoring all level 1 dumps,
+and so on. At the very least, use compatible tape devices to perform
+dumps at each level. If compatible tape devices are not used, the
+C<backup volrestore> command must be used to restore one volume at a
+time.
+
+Valid (unexpired) administrative tokens must be available to the
+C<backup> command interpreter both when it reads the file named by the
+B<-file> argument and when it runs each operation listed in the file.
+Presumably, the issuer is scheduling dumps for times when no human
+operator is present, and so must arrange for valid tokens to be
+available on the local machine. One option is to issue all commands
+(or run all scripts) on file server machines and use the B<-localauth>
+flag on the C<backup> and C<vos> commands. To protect against improper
+access to the machine or the tokens, the machine must be physically
+secure (perhaps even more protected than a Tape Coordinator machine
+monitored by a human operator during operation). Also, if an
+unattended dump requires multiple tapes, the operator must properly
+configure a tape stacker or jukebox and the device configuration file.
+
+When the command is issued in regular (non-interactive) mode, the
+command shell prompt does not return until the dump operation
+completes. To avoid having to open additional connections, issue the
+command in interactive mode, especially when including the B<-at>
+argument to schedule dump operations.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_adddump(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_diskrestore(1)>,
+L<backup_labeltape(1)>,
+L<backup_volrestore(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_dumpinfo.pod b/doc/man-pages/pod/backup_dumpinfo.pod
new file mode 100644 (file)
index 0000000..53420d1
--- /dev/null
@@ -0,0 +1,427 @@
+=head1 NAME
+
+backup dumpinfo - Displays a dump record from the Backup Database
+
+=head1 SYNOPSIS
+
+backup dumpinfo [B<-ndumps> I<no. of dumps>]  [B<-id> I<dump id>]
+[B<-verbose>]  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help> ]
+
+backup dumpi [B<-n> I<no. of dumps>]  [B<-i> I<dump id>]
+[B<-v>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup dumpinfo> command formats and displays the Backup Database
+record for the specified dumps. To specify how many of the most recent
+dumps to display, starting with the newest one and going back in time,
+use the B<-ndumps> argument. To display more detailed information about a
+single dump, use the B<-id> argument. To display the records for the 10
+most recent dumps, omit both the B<-ndumps> and B<-id> arguments.
+
+The B<-verbose> flag produces very detailed information that is useful
+mostly for debugging purposes. It can be combined only with the B<-id>
+argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-ndumps> I<no. of dumps>
+
+Displays the Backup Database record for each of the specified
+number of dumps that were most recently performed. If the
+database contains fewer dumps than are requested, the output
+includes the records for all existing dumps. Do not combine
+this argument with the B<-id> or B<-verbose> options; omit all
+options to display the records for the last 10 dumps.
+
+=item B<-id> I<dump id>
+
+Specifies the dump ID number of a single dump for which to
+display the Backup Database record. Precede the I<dump id> value
+with the B<-id> switch; otherwise, the command interpreter
+interprets it as the value of the B<-ndumps> argument. Combine
+this argument with the B<-verbose> flag, but not with the B<-ndumps>
+argument; omit all options to display the records for the last
+10 dumps.
+
+=item B<-verbose>
+
+Provides more detailed information about the dump specified
+with the B<-id> argument, which must be provided along with it. Do
+not combine this flag with the B<-ndumps> argument.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the B<-ndumps> argument is provided, the output presents the following
+information in table form, with a separate line for each dump:
+
+=over
+
+=item B<dumpid>
+
+The dump ID number.
+
+=item B<parentid>
+
+The dump ID number of the dump's parent dump. A value of 0
+(zero) identifies a full dump.
+
+=item B<lv>
+
+The depth in the dump hierarchy of the dump level used to
+create the dump. A value of 0 (zero) identifies a full dump, in
+which case the value in the C<parentid> field is also 0. A value
+of 1 or greater indicates an incremental dump made at the
+corresponding level in the dump hierarchy.
+
+=item B<created>
+
+The date and time at which the Backup System started the dump
+operation that created the dump.
+
+=item B<nt>
+
+The number of tapes that contain the data in the dump. A value
+of 0 (zero) indicates that the dump operation was terminated or
+failed. Use the C<backup deletedump> command to remove such
+entries.
+
+=item B<nvols>
+
+The number of volumes from which the dump includes data. If a
+volume spans tapes, it is counted twice. A value of 0 (zero)
+indicates that the dump operation was terminated or failed; the
+value in the nt field is also 0 in this case.
+
+=item B<dump name>
+
+The dump name in the form
+
+I<volume_set_name>.I<dump_level_name> (I<initial_dump_ID>)
+
+where I<volume_set_name> is the name of the volume set, and
+I<dump_level_name> is the last element in the dump level pathname
+at which the volume set was dumped.
+
+The I<initial_dump_ID>, if displayed, is the dump ID of the
+initial dump in the dump set to which this dump belongs. If
+there is no value in parentheses, the dump is the initial dump
+in a dump set that has no appended dumps.
+
+=back
+
+If the B<-id> argument is provided alone, the first line of output begins
+with the string C<Dump> and reports information for the entire dump in
+the following fields:
+
+=over
+
+=item B<id>
+
+The dump ID number.
+
+=item B<level>
+
+The depth in the dump hierarchy of the dump level used to
+create the dump. A value of 0 (zero) identifies a full dump. A
+value of 1 (one) or greater indicates an incremental dump made
+at the specified level in the dump hierarchy.
+
+=item B<volumes>
+
+The number of volumes for which the dump includes data.
+
+=item B<created>
+
+The date and time at which the dump operation began.
+
+=back
+
+If an XBSA server was the backup medium for the dump (rather than a
+tape device or backup data file), the following line appears next:
+
+Backup Service: I<XBSA_program>: Server: I<hostname>
+
+where I<XBSA_program> is the name of the XBSA-compliant program and
+I<hostname> is the name of the machine on which the program runs.
+
+Next the output includes an entry for each tape that houses volume
+data from the dump. Following the string C<Tape>, the first two lines of
+each entry report information about that tape in the following fields:
+
+=over
+
+=item B<name>
+
+The tape's permanent name if it has one, or its AFS tape name
+otherwise, and its tape ID number in parentheses.
+
+=item B<nVolumes>
+
+The number of volumes for which this tape includes dump data.
+
+=item B<created>
+
+The date and time at which the Tape Coordinator began writing
+data to this tape.
+
+=back
+
+Following another blank line, the tape-specific information concludes
+with a table that includes a line for each volume dump on the tape.
+The information appears in columns with the following headings:
+
+=over
+
+=item B<Pos>
+
+The relative position of each volume in this tape or file. On a
+tape, the counter begins at position 2 (the tape label occupies
+position 1), and increments by one for each volume. For volumes
+in a backup data file, the position numbers start with 1 and do
+not usually increment only by one, because each is the ordinal
+of the 16 KB offset in the file at which the volume's data
+begins. The difference between the position numbers therefore
+indicates how many 16 KB blocks each volume's data occupies.
+For example, if the second volume is at position 5 and the
+third volume in the list is at position 9, that means that the
+dump of the second volume occupies 64 KB (four 16-KB blocks) of
+space in the file.
+
+=item B<Clone time>
+
+For a backup or read-only volume, the time at which it was
+cloned from its read/write source. For a Read/Write volume, it
+is the same as the dump creation date reported on the first
+line of the output.
+
+=item B<Nbytes>
+
+The number of bytes of data in the dump of the volume.
+
+=item B<Volume>
+
+The volume name, complete with C<.backup> or C<.readonly> extension
+if appropriate.
+
+=back
+
+If both the B<-id> and B<-verbose> options are provided, the output is
+divided into several sections:
+
+=over
+
+=item *
+
+The first section, headed by the underlined string C<Dump>, includes
+information about the entire dump. The fields labeled C<id>, C<level>,
+C<created>, and C<nVolumes> report the same values (though in a
+different order) as appear on the first line of output when the
+B<-id> argument is provided by itself. Other fields of potential
+interest to the backup operator are:
+
+=over
+
+=item B<Group id>
+
+The dump's I<group ID number>, which is recorded in the
+dump's Backup Database record if the B<GROUPID> instruction
+appears in the Tape Coordinator's
+B</usr/afs/backup/CFG_>I<tcid> file when the dump is created.
+
+=item B<maxTapes>
+
+The number of tapes that contain the dump set to which
+this dump belongs.
+
+=item B<Start Tape Seq>
+
+The ordinal of the tape on which this dump begins in the
+set of tapes that contain the dump set.
+
+=back
+
+=item *
+
+For each tape that contains data from this dump, there follows a
+section headed by the underlined string C<Tape>. The fields labeled
+C<name>, C<written>, and C<nVolumes> report the same values (though in a
+different order) as appear on the second and third lines of output
+when the B<-id> argument is provided by itself. Other fields of
+potential interest to the backup operator are:
+
+=over
+
+=item B<expires>
+
+The date and time when this tape can be recycled, because
+all dumps it contains have expired.
+
+=item B<nMBytes Data and nBytes Data>
+
+Summed together, these fields represent the total amount
+of dumped data actually from volumes (as opposed to
+labels, filemarks, and other markers).
+
+=item B<KBytes Tape Used>
+
+The number of kilobytes of tape (or disk space, for a
+backup data file) used to store the dump data. It is
+generally larger than the sum of the values in the
+C<nMBytes> Data and C<nBytes> Data fields, because it includes
+the space required for the label, file marks and other
+markers, and because the Backup System writes data at 16
+KB offsets, even if the data in a given block doesn't
+fill the entire 16 KB.
+
+=back
+
+=item *
+
+For each volume on a given tape, there follows a section headed by
+the underlined string C<Volume>. The fields labeled C<name>, C<position>,
+C<clone>, and C<nBytes> report the same values (though in a different
+order) as appear in the table that lists the volumes in each tape
+when the B<-id> argument is provided by itself. Other fields of
+potential interest to the backup operator are:
+
+=over
+
+=item B<id>
+
+The volume ID.
+
+=item B<tape>
+
+The name of the tape containing this volume data.
+
+=back
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays information about the last five dumps:
+
+    backup dumpinfo -ndumps 5
+      dumpid   parentid lv created          nt nvols dump name
+   924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
+   924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
+   924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
+   924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
+   925033000          0 0  04/25/1999 05:36  2    73 sys.week
+
+The following example displays a more detailed record for a single
+dump.
+
+    backup dumpinfo -id 922097346
+   Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
+   Tape: name monday.user.backup (922097346)
+   nVolumes 1, created 03/22/1999 05:09
+    Pos       Clone time   Nbytes Volume
+      1 03/22/1999 04:43 27787914 user.pat.backup
+
+The following example displays even more detailed information about
+the dump displayed in the previous example (dump ID 922097346). This
+example includes only one exemplar of each type of section (C<Dump>,
+C<Tape>, and C<Volume>):
+
+    backup dumpinfo -id 922097346 -verbose
+   Dump
+   ----
+   id = 922097346
+   Initial id = 0
+   Appended id = 922099568
+   parent = 0
+   level = 0
+   flags = 0x0
+   volumeSet = user
+   dump path = /monday1
+   name = user.monday1
+   created = Mon Mar 22 05:09:06 1999
+   nVolumes = 1
+   id  = 0
+   tapeServer =
+   format= user.monday1.%d
+   maxTapes = 1
+   Start Tape Seq = 1
+   name = pat
+   instance =
+   cell =
+   Tape
+   ----
+   tape name = monday.user.backup
+   AFS tape name = user.monday1.1
+   flags = 0x20
+   written = Mon Mar 22 05:09:06 1999
+   expires = NEVER
+   kBytes Tape Used = 121
+   nMBytes Data = 0
+   nBytes  Data = 19092
+   nFiles = 0
+   nVolumes = 1
+   seq = 1
+   tapeid = 0
+   useCount = 1
+   dump = 922097346
+   Volume
+   ------
+   name = user.pat.backup
+   flags = 0x18
+   id = 536871640
+   server =
+   partition = 0
+   nFrags = 1
+   position = 2
+   clone = Mon Mar 22 04:43:06 1999
+   startByte = 0
+   nBytes = 19092
+   seq = 0
+   dump = 922097346
+   tape = user.monday1.1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_deletedump(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_help.pod b/doc/man-pages/pod/backup_help.pod
new file mode 100644 (file)
index 0000000..72858bb
--- /dev/null
@@ -0,0 +1,95 @@
+=head1 NAME
+
+backup help - Displays the syntax of specified C<backup> commands or lists functional
+descriptions of all C<backup> commands
+
+=head1 SYNOPSIS
+
+backup help  [B<-topic> I<help string> [I<help string> ...]]  [B<-help>]
+
+backup h [B<-t> I<help string> [I<help string> ...]]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup help> command displays the complete online help entry (short
+description and syntax statement) for each operation code specified by
+the B<-topic> argument. If the B<-topic> argument is omitted, the output
+includes the first line (name and short description) of the online
+help entry for every C<backup> command.
+
+To list every C<backup> command whose name or short description includes
+a specified keyword, use the C<backup apropos> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> I<help string> [I<help string> ...]
+
+Indicates each command for which to display the complete online
+help entry. Omit the C<backup> part of the command name, providing
+only the operation code (for example, specify C<dump>, not C<backup
+dump>). If this argument is omitted, the output briefly
+describes every C<backup> command.
+
+=item B<-help> 
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The online help entry for each C<backup> command consists of the
+following two or three lines:
+
+=over
+
+=item *
+
+The first line names the command and briefly describes its
+function.
+
+=item *
+
+The second line lists aliases for the command, if any.
+
+=item *
+
+The final line, which begins with the string C<Usage>, lists the
+command's options in the prescribed order. Online help entries use
+the same symbols (for example, brackets) as the reference pages in
+this document.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the online help entry for the C<backup
+dump> command:
+
+   backup help dump
+   backup dump: start dump
+   Usage: backup dump -volumeset <volume set name> -dump <dump level name>
+   [-portoffset <TC port offset>]  [-at <Date/time to start dump>+]
+   [-append]  [-n]  [-file <load file>]  [-help]
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_apropos(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_interactive.pod b/doc/man-pages/pod/backup_interactive.pod
new file mode 100644 (file)
index 0000000..e6e5b48
--- /dev/null
@@ -0,0 +1,121 @@
+=head1 NAME
+
+backup interactive - Enters interactive mode
+
+=head1 SYNOPSIS
+
+backup [interactive]  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup [i]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup interactive> initiates an interactive session for issuing
+C<backup> commands. As indicated in the syntax statement, the operation
+code (C<interactive>) is optional.
+
+Several features of interactive mode distinguish it from regular mode:
+
+=over
+
+=item *
+
+In interactive mode, the C<backupE<gt>> prompt replaces the system
+(shell) prompt. The operator enters only a command's operation
+code (omitting the command suite name, C<backup>).
+
+=item *
+
+If the B<-localauth> flag or the B<-cell> argument is included on the
+C<backup (interactive)> command, the settings apply to all commands
+issued during that interactive session. The issuer does not need
+to type them on every command. Another consequence is that the
+flag and argument do not appear in the syntax statement generated
+by the C<help> subcommand or B<-help> flag on an individual command
+issued at the C<backupE<gt>> prompt.
+
+=item *
+
+The C<(backup) jobs> and C<(backup) kill> commands are available only in
+interactive mode. It is not possible to track and terminate backup
+operations as cleanly in non-interactive mode.
+
+=item *
+
+It is not necessary to enclose strings that include metacharacters
+in double quotes or other delimiters.
+
+=item *
+
+The C<backup> command interpreter establishes a connection to the
+Backup Server, Volume Server and Volume Location (VL) Server
+processes as it enters interactive mode, and uses the same
+connection for all commands during the session. Execution time can
+therefore be faster than in non-interactive mode, in which the
+command interpreter must establish a new connection for each
+command.
+
+=back
+
+To exit an interactive session, issue the C<(backup) quit> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth> 
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help> 
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows how the B<-localauth> flag and B<-cell> argument
+do not appear when the C<help dump> subcommand is issued in interactive
+mode.
+
+    backup
+   backup> help dump
+   dump: start dump
+   Usage: dump [-volumeset <volume set name>] [-dump <dump level name>]
+   [-portoffset <TC port offset>] [-at <Date/time to start dump>+]
+   [-append ] [-n ] [-file <load file>] [-help ]
+
+=head1 PRIVILEGE REQUIRED
+
+None. However, C<backup> commands that require privilege in regular mode
+still require it in interactive mode.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_jobs(1)>,
+L<backup_kill(1)>,
+L<backup_quit(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_jobs.pod b/doc/man-pages/pod/backup_jobs.pod
new file mode 100644 (file)
index 0000000..4068393
--- /dev/null
@@ -0,0 +1,229 @@
+=head1 NAME
+
+backup jobs - Lists pending and running operations in interactive mode
+
+=head1 SYNOPSIS
+
+jobs  [B<-help>]
+
+j [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<(backup) jobs> command lists the job ID number and status of each
+B<backup> operation running or pending in the current interactive
+session.
+
+This command can be issued in interactive mode only. If the issuer of
+the C<backup (interactive)> command included the B<-localauth> flag, the
+B<-cell> argument, or both, those settings apply to this command also.
+
+To terminate operations that appear in the output, issue the C<(backup)
+kill> command and identify the operation to cancel with the job ID
+number from this command's output.
+
+To check the status of a Tape Coordinator, rather than of a certain
+operation, use the C<backup status> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output always includes the expiration date and time of the tokens
+that the C<backup> command interpreter is using during the current
+interactive session, in the following format:
+
+I<date>   I<time>: TOKEN EXPIRATION
+
+If the execution date and time specified for a scheduled dump
+operation is later than I<date time>, then its individual line (as
+described in the following paragraphs) appears below this line to
+indicate that the current tokens will not be available to it.
+
+If the issuer of the C<backup> command included the B<-localauth> flag when
+entering interactive mode, the line instead reads as follows:
+
+:  TOKEN NEVER EXPIRES
+
+The entry for a scheduled dump operation has the following format:
+
+Job I<job_ID>:  I<timestamp>:  dump  I<volume_set>  I<dump_level>
+
+where
+
+=over
+
+=item B<I<job_ID>>
+
+Is a job identification number assigned by the Backup System.
+
+=item B<I<timestamp>>
+
+Indicates the date and time the dump operation is to begin, in
+the format I<month>/I<date>/I<year> I<hours>:I<minutes> (in 24-hour format)
+
+=item B<I<volume_set>>
+
+Indicates the volume set to dump.
+
+=item B<I<dump_level>>
+
+Indicates the dump level at which to perform the dump
+operation.
+
+=back
+
+The line for a pending or running operation of any other type has the
+following format:
+
+Job I<job_ID>:  I<operation>  I<status>
+
+where
+
+=over
+
+=item B<I<job_ID>>
+
+Is a job identification number assigned by the Backup System.
+
+=item B<I<operation>>
+
+Identifies the operation the Tape Coordinator is performing,
+which is initiated by the indicated command:
+
+=over
+
+=item B<C<Dump> (I<dump name>)>
+
+Initiated by the C<backup dump> command. The I<dump name> has
+the following format:
+
+I<volume_set_name>.I<dump_level_name>
+
+=item B<C<Restore>>
+
+Initiated by the C<backup diskrestore>, C<backup volrestore>,
+or C<backup volsetrestore> command.
+
+=item B<C<Labeltape> (I<tape_label>)>
+
+Initiated by the C<backup labeltape> command. The I<tape_label>
+is the name specified by the C<backup labeltape> command's
+B<-name> or B<-pname> argument.
+
+=item B<C<Scantape>>
+
+Initiated by the C<backup scantape> command.
+
+=item B<C<SaveDb>>
+
+Initiated by the C<backup savedb> command.
+
+=item B<C<RestoreDb>>
+
+Initiated by the C<backup restoredb> command.
+
+=back
+
+=item B<I<status>>
+
+Indicates the job's current status in one of the following
+messages. If no message appears, the job is either still
+pending or has finished.
+
+=over
+
+=item B<I<number> Kbytes, volume I<volume_name>>
+
+For a running dump operation, indicates the number of
+kilobytes copied to tape or a backup data file so far,
+and the volume currently being dumped.
+
+=item B<I<number> Kbytes, restore.volume>
+
+For a running restore operation, indicates the number of
+kilobytes copied into AFS from a tape or a backup data
+file so far.
+
+=item B<[abort requested]>
+
+The C<(backup) kill> command was issued, but the termination
+signal has yet to reach the Tape Coordinator.
+
+=item B<[abort sent]>
+
+The operation is canceled by the C<(backup) kill> command.
+Once the Backup System removes an operation from the
+queue or stops it from running, it no longer appears at
+all in the output from the command.
+
+=item B<[butc contact lost]>
+
+The C<backup> command interpreter cannot reach the Tape
+Coordinator. The message can mean either that the Tape
+Coordinator handling the operation was terminated or
+failed while the operation was running, or that the
+connection to the Tape Coordinator timed out.
+
+=item B<[done]>
+
+The Tape Coordinator has finished the operation.
+
+=item B<[drive wait]>
+
+The operation is waiting for the specified tape drive to
+become free.
+
+=item B<[operator wait]>
+
+The Tape Coordinator is waiting for the backup operator
+to insert a tape in the drive.
+
+=back
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows that two restore operations and one dump
+operation are running (presumably on different Tape Coordinators) and
+that the C<backup> command interpreter's tokens expire on 22 April 1999
+at 10:45 am:
+
+   backup> jobs
+   Job 1: Restore, 1306 Kbytes, restore.volume
+   Job 2: Dump (user.sunday1), 34 Kbytes, volume user.pat.backup
+   Job 3: Restore, 2498 Kbytes, restore.volume
+          04/22/1999 10:45: TOKEN EXPIRATION
+
+=head1 PRIVILEGE REQUIRED
+
+None. However, queuing any operation requires privilege, and it is
+possible to issue this command only within the interactive session in
+which the jobs are queued.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_interactive(1)>,
+L<backup_kill(1)>,
+L<backup_quit(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_kill.pod b/doc/man-pages/pod/backup_kill.pod
new file mode 100644 (file)
index 0000000..223bdff
--- /dev/null
@@ -0,0 +1,165 @@
+=head1 NAME
+
+backup kill - Terminates a pending or running operation
+
+=head1 SYNOPSIS
+
+kill B<-id> I<job ID or dump set name> [B<-help>]
+
+k B<-i> I<job ID or dump set name>  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<(backup) kill> command dequeues a Backup System operation that is
+pending, or terminates an operation that is running, in the current
+interactive session. It is available only in interactive mode. If the
+issuer of the C<backup (interactive)> command included the B<-localauth>
+flag, the B<-cell> argument, or both, then those settings apply to this
+command also.
+
+To terminate a dump operation, specify either the dump name
+(I<volume_set_name>.I<dump_level_name>) or its job ID number, which appears
+in the output from the C<(backup) jobs> command. To terminate any other
+type of operation, provide the job ID number.
+
+The effect of terminating an operation depends on the type and current
+state of the operation:
+
+=over
+
+=item *
+
+If an operation is still pending, the Tape Coordinator removes it
+from the queue with no other lasting effects.
+
+=item *
+
+If the Tape Coordinator is unable to process the termination
+signal before an operation completes, it simply confirms the
+operation's completion. The operator must take the action
+necessary to undo the effects of the incorrect operation.
+
+=item *
+
+If a tape labeling operation is running, the effect depends on
+when the Tape Coordinator receives the termination signal. The
+labeling operation is atomic, so it either completes or does not
+begin at all. Use the C<backup readlabel> command to determine if the
+labeling operation completed, and reissue the C<backup labeltape>
+command to overwrite the incorrect label if necessary.
+
+=item *
+
+If a tape scanning operation is running, it terminates with no
+other effects unless the B<-dbadd> flag was included on the C<backup>
+command. In that case, the Backup System possibly has already
+written new Backup Database records to represent dumps on the
+scanned tape. If planning to restart the scanning operation, first
+locate and remove the records created during the terminated
+operation: a repeated C<backup scantape> operation exits
+automatically when it finds that a record that it needs to create
+already exists.
+
+=item *
+
+If a dump operation is running, all of the volumes written to the
+tape or backup data file before the termination signal is received
+are complete and usable. If the operation is restarted, the Backup
+System performs all the dumps again from scratch, and assigns a
+new dump ID number. If writing the new dumps to the same tape or
+file, the operator must relabel it first if the interrupted dump
+is not expired. If writing the new dump to a different tape or
+file, the operator can remove the dump record associated with the
+interrupted dump to free up space in the database.
+
+=item *
+
+If a restore operation is running, completely restored volumes are
+online and usable. However, it is unlikely that many volumes are
+completely restored, given that complete restoration usually
+requires data from multiple tapes. If the termination signal comes
+before the Backup System has accessed all of the necessary tapes,
+each volume is only partially written and is never brought online.
+It is best to restart the restore operation from scratch to avoid
+possible inconsistencies. See also the L</"CAVEATS"> section.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-id> I<job ID or dump set name>
+
+Identifies the backup operation to terminate. Provide one of
+two types of values:
+
+=over
+
+=item *
+
+The operation's job ID number, as displayed in the output of
+the C<(backup) jobs> command.
+
+=item *
+
+For a dump operation, either the job ID number or a dump name
+of the form I<volume_set_name>.I<dump_level_name>, where
+I<volume_set_name> is the name of the volume set being dumped
+and I<dump_level_name> is the last element in the dump level
+pathname at which the volume set is being dumped. The dump
+name appears in the output of the C<(backup) jobs> command along
+with the job ID number.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command terminates the operation with job ID 5:
+
+   backup> kill 5
+
+The following command terminates the dump operation called
+B<user.sunday1>:
+
+   backup> kill user.sunday1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the privilege required to initiate the operation
+being cancelled. Because this command can be issued only within the
+interactive session during which the operation was initiated, the
+required privilege is essentially guaranteed.
+
+=head1 CAVEATS
+
+It is best not to issue the C<(backup) kill> command against restore
+operations. If the termination signal interrupts a restore operation
+as the Backup System is overwriting an existing volume, it is possible
+to lose the volume entirely (that is, to lose both the contents of the
+volume as it was before the restore and any data that was restored
+before the termination signal arrived). The data being restored still
+exists on the tape, but some data can be lost permanently.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_interactive(1)>,
+L<backup_jobs(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_labeltape.pod b/doc/man-pages/pod/backup_labeltape.pod
new file mode 100644 (file)
index 0000000..a3f4ae0
--- /dev/null
@@ -0,0 +1,228 @@
+=head1 NAME
+
+backup labeltape - Creates the magnetic label on a tape
+
+=head1 SYNOPSIS
+
+backup labeltape [B<-name> I<AFS tape name, defaults to NULL>]
+[B<-size> I<tape size in Kbytes, defaults to size in tapeconfig>]
+[B<-portoffset> I<TC port offset>]
+[B<-pname> I<permanent tape name>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup la [B<-n> I<AFS tape name, defaults to NULL>]
+[B<-s> I<tape size in Kbytes, defaults to size in tapeconfig>]
+[B<-po> I<TC port offset>]  [B<-pn> I<permanent tape name>]
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup labeltape> command creates a magnetic label, readable by the
+Backup System, at the beginning of a tape. The label records the
+tape's name (either a I<permanent name>, or an I<AFS tape name> that
+reflects the tape's contents in a prescribed format) and its capacity.
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file on the Tape Coordinator machine
+associated with the specified port offset, then the C<backup> command
+writes label information to the first 16 KB block in the backup data
+file listed for that port offset in the Tape Coordinator's
+B</usr/afs/backup/tapeconfig> file, rather than at the beginning of a
+tape. For the sake of clarity, the following text refers to tapes
+only, but the Backup System handles backup data files in much the same
+way.)
+
+Relabeling a tape that already contains AFS backup data effectively
+makes the data unusable, because the command removes the Backup
+Database record of the complete dump set of which the tape is a part.
+Use this command to enable recycling of a tape that contains unexpired
+dumps that are not actually still needed.
+
+To write a permanent name on the label, include the B<-pname> argument to
+specify a string of up to 32 characters. The permanent name persists
+until the B<-pname> argument is again included on the C<backup labeltape>
+command, regardless of the tape's contents and of how often the tape
+is otherwise relabeled or recycled. Include this argument or the B<-name>
+argument, but not both. If this argument is included, the AFS tape
+name is set to C<E<lt>NULLE<gt>>. The permanent name is set to C<E<lt>NULLE<gt>> if this
+argument is omitted and no permanent name already exists.
+
+The issuer must ensure that a permanent name is unique among the tapes
+used for AFS backup in the cell, because the C<backup> command
+interpreter does not verify that another tape does not already have
+the same permanent name. When a tape has a permanent name, the Backup
+System uses it instead of the AFS tape name in most prompts and when
+referring to the tape in output from C<backup> commands. The permanent
+name appears in the C<tape name> field of the output from the C<backup
+readlabel> command.
+
+To write an AFS tape name on the label, provide a value for the B<-name>
+argument in the required format described in the L</"OPTIONS"> section.
+Include the B<-name> argument or the B<-pname> argument, but not both. If
+this argument is omitted, the AFS tape name is set to C<E<lt>NULLE<gt>>, but the
+Backup System automatically assigns the appropriate name when the tape
+is used in a future C<backup dump> or C<backup savedb> operation. The AFS
+tape name appears in the AFS C<tape name> field of the output from the
+C<backup readlabel> and C<backup scantape> commands.
+
+The C<backup> command interpreter does not accept the B<-name> argument if
+the tape already has a permanent name. To erase a tape's permanent
+name, provide a null value to the B<-pname> argument by issuing the
+following command:
+
+   % backup labeltape -pname ""
+
+To record the tape's capacity on the label, specify a number of
+kilobytes as the B<-size> argument. If the argument is omitted the first
+time a tape is labeled, the Backup System records the default tape
+capacity recorded for the specified port offset in the
+B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine.
+Subsequently, the value in the size field persists until the B<-size>
+argument is again included on the C<backup labeltape> command.
+
+To determine how much data can be written to a tape during a C<backup
+dump> or C<backup savedb> operation, the Tape Coordinator reads the
+capacity recorded on the tape's label (or uses the value associated
+with its port offset in the B</usr/afs/backup/tapeconfig> file, if the
+tape was never labeled). For further description, see the L<backup_dump(1)>
+reference page.
+
+The Tape Coordinator's default response to this command is to access
+the tape by invoking the B<MOUNT> instruction in the local
+B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
+operator to insert the tape if there is no B<MOUNT> instruction. However,
+if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
+or if the issuer of the C<butc> command included the B<-noautoquery> flag,
+the Tape Coordinator instead expects the tape to be in the device
+already. If it is not, the Tape Coordinator invokes the B<MOUNT>
+instruction or prompts the operator.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<AFS tape name, defaults to NULL>
+
+Specifies the AFS tape name to record on the label. Include
+this argument or the B<-pname> argument, but not both. If this
+argument is omitted, the AFS tape name is set to C<E<lt>NULLE<gt>>. If
+this argument is provided, it must have the following format:
+
+I<volume_set_name>.I<dump_level_name>.I<tape_index>
+
+for the tape to be acceptable for use in a future C<backup dump>
+operation. The I<volume_set_name> must match the volume set name
+of the initial dump to be written to the tape, I<dump_level_name>
+must match the last element of the dump level pathname at which
+the volume set will be dumped, and I<tape_index> indicates the
+order of the tape in the dump set (indexing begins with B<1>). To
+disable this type of name checking, include the B<NAME_CHECK NO>
+instruction in the B<CFG_>I<device_name> file.
+
+For the tape to be acceptable for use in a future C<backup savedb>
+operation, the value specified for the B<-name> argument must have
+the following format:
+
+I<Ubik_db_dump>.I<tape_index>
+
+where I<tape_index> indicates the order of the tape in the set of
+tapes that house the Backup Database dump; indexing begins with
+1 (one).
+
+=item B<-size> I<tape size in Kbytes, defaults to size in tapeconfig>
+
+Specifies the tape capacity to record on the label. Provide an
+integer value followed by a letter that indicates units, with
+no intervening space. A unit value of B<k> or B<K> indicates
+kilobytes, B<m> or B<M> indicates megabytes, and B<g> or B<G> indicates
+gigabytes. If the units letter is omitted, the default is
+kilobytes.
+
+If this argument is omitted the first time a tape is labeled,
+the Backup System records the capacity that is associated with
+the specified port offset in the B</usr/afs/backup/tapeconfig>
+file on the Tape Coordinator machine. The value recorded the
+first time then persists until the B<-size> argument is provided
+on a future issuance of the command.
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator
+handling the tape for this operation.
+
+=item B<-pname> I<permanent tape name>
+
+Specifies the permanent name to record on the label. It can be
+up to 32 characters in length, and include any alphanumeric
+characters. Avoid metacharacters that have a special meaning to
+the shell, to avoid having to mark them as literal in commands
+issued at the shell prompt.
+
+Include this argument or the B<-name> argument, but not both. If
+this argument is provided, the AFS tape name is set to C<E<lt>NULLE<gt>>.
+If this argument is omitted, any existing permanent name is
+retained.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command records the AFS tape name B<user.monthly.1> on the
+label of the tape in the device with port offset 3:
+
+    backup labeltape -name user.monthly.1 -portoffset 3
+
+The following three commands are equivalent in effect: they all record
+a capacity of 2 GB on the label of the tape in the device with port
+offset 4. They set the AFS tape name to C<E<lt>NULLE<gt>> and leave the permanent
+name unchanged.
+
+    backup labeltape -size 2g -portoffset 4
+
+    backup labeltape -size 2048M -portoffset 4
+
+    backup labeltape -size 2097152 -portoffset 4
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CFG_device_name(1)>,
+L<backup(1)>,
+L<backup_readlabel(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_listdumps.pod b/doc/man-pages/pod/backup_listdumps.pod
new file mode 100644 (file)
index 0000000..07727dc
--- /dev/null
@@ -0,0 +1,135 @@
+=head1 NAME
+
+backup listdumps - Displays the dump hierarchy from the Backup Database
+
+=head1 SYNOPSIS
+
+backup listdumps  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup listd  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup listdumps> command displays the dump hierarchy from the
+Backup Database.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays the complete dump hierarchy and indicates the
+relationship between full and incremental dump levels. Full dump
+levels appear at the left margin. The hierarchy can include more than
+one full dump level; each one defines a subhierarchy of dump levels
+that can be used for dumping different volume sets.
+
+Incremental dump levels appear below and indented to the right of
+their parent dump levels, which can be either full or incremental.
+Since multiple incremental dump levels can share the same parent, an
+incremental dump level is not always directly below its parent; the
+amount of indentation indicates the parent/child relationship.
+
+If a dump level has an associated expiration date, it appears along
+with the level name. Absolute expiration dates appear in the format
+
+I<dump_level> expires at I<day> I<month> I<date> I<time> I<year>
+
+and relative expiration dates in the format
+
+I<dump_level> expires in {I<years>y | I<months>m | I<days>d}
+
+to indicate the number of years, months, days, or combination of the
+three after creation a dump expires when created at this level.
+
+=head1 EXAMPLES
+
+The following example depicts six dump hierarchies. The expiration
+date for all incremental dump levels is 13 days so that the
+corresponding tapes can be recycled two weeks after their creation.
+The expiration dates for all full dump levels is 27 days so that the
+corresponding tapes can be recycled four weeks after their creation.
+
+    backup listdumps
+   /week1  expires in  27d
+         /tuesday  expires in  13d
+                 /thursday  expires in  13d
+         /sunday  expires in  13d
+                /tuesday expires in  13d
+                        /thursday expires in  13d
+   /week3  expires in  27d
+         /tuesday  expires in  13d
+                 /thursday  expires in  13d
+         /sunday  expires in  13d
+                /tuesday  expires in  13d
+                        /thursday  expires in  13d
+   /sunday1  expires in  27d
+           /monday1  expires in  13d
+           /tuesday1  expires in  13d
+           /wednesday1  expires in  13d
+           /thursday1  expires in  13d
+           /friday1  expires in  13d
+   /sunday2  expires in  27d
+           /monday2  expires in  13d
+           /tuesday2  expires in  13d
+           /wednesday2  expires in  13d
+           /thursday2  expires in  13d
+           /friday2  expires in  13d
+   /sunday3  expires in  27d
+           /monday1  expires in  13d
+           /tuesday1  expires in  13d
+           /wednesday1  expires in  13d
+           /thursday1  expires in  13d
+           /friday1  expires in  13d
+   /sunday4  expires in  27d
+           /monday2  expires in  13d
+           /tuesday2  expires in  13d
+           /wednesday2  expires in  13d
+           /thursday2  expires in  13d
+           /friday2  expires in  13d
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_adddump(1)>,
+L<backup_deldump(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_listhosts.pod b/doc/man-pages/pod/backup_listhosts.pod
new file mode 100644 (file)
index 0000000..db1af32
--- /dev/null
@@ -0,0 +1,104 @@
+=head1 NAME
+
+backup listhosts - Lists Tape Coordinator machines registered in the Backup Database
+
+=head1 SYNOPSIS
+
+backup listhosts [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup listh [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup listhosts> command displays the Backup Database record of
+the port offset numbers defined for Tape Coordinator machines. A Tape
+Coordinator must have an entry in the list to be available for backup
+operations.
+
+The existence of an entry does not necessarily indicate that the Tape
+Coordinator process (B<butc>) is currently running at that port offset.
+To check, issue the C<backup status> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+After a C<Tape hosts:> header, the output reports two things about each
+Tape Coordinator currently defined in the Backup Database:
+
+=over
+
+=item *
+
+The hostname of the machine housing the Tape Coordinator. The
+format of this name depends on the hostname format used when the
+C<backup addhost> command was issued.
+
+=item *
+
+The Tape Coordinator's port offset number.
+
+=back
+
+The Tape Coordinators appear in the order in which they were added to
+the Backup Database.
+
+=head1 EXAMPLES
+
+The following example shows the result of the command in the ABC
+Corporation cell:
+
+    backup listhosts
+   Tape hosts:
+       Host backup1.abc.com, port offset 0
+       Host backup1.abc.com, port offset 1
+       Host backup3.abc.com, port offset 4
+       Host backup2.abc.com, port offset 3
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addhost(1)>,
+L<backup_delhost(1)>,
+L<backup_status(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_listvolsets.pod b/doc/man-pages/pod/backup_listvolsets.pod
new file mode 100644 (file)
index 0000000..b1b5d22
--- /dev/null
@@ -0,0 +1,111 @@
+=head1 NAME
+
+backup listvolsets - Lists volume set entries from the Backup Database
+
+=head1 SYNOPSIS
+
+backup listvolsets [B<-name> I<volume set name>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup listv [B<-n> I<volume set name>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup listvolsets> command displays the Backup Database records
+for either
+
+=over
+
+=item *
+
+All volume sets and their volume entries, if the B<-name> argument is
+omitted
+
+=item *
+
+The volume set specified by the B<-name> argument, along with its
+volume entries
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<volume set name>
+
+Names the volume set to display. If this argument is omitted,
+the output lists all volume sets defined in the Backup
+Database.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The entry for each volume set begins with the Volume set header and
+the volume set's name. A temporary volume set's name is followed by
+the string C<(temporary)>. Each volume entry follows on a separate line,
+indicating the entry's index number and the server, partition, and
+volume names it matches. The output uses the metacharacter notation
+described on the L<backup_addvolentry(1)> reference page. Use the index
+number to identify volume entries when deleting them with the C<backup
+delvolentry> command.
+
+=head1 EXAMPLES
+
+The following example shows the volume entries in the three volume
+sets currently defined in the Backup Database:
+
+    backup listvolsets
+   Volume set user:
+       Entry   1: server .*, partition .*, volumes: user.*\.backup
+   Volume set sun
+       Entry   1: server .*, partition .*, volumes: sun4x_55\..*
+       Entry   2: server .*, partition .*, volumes: sun4x_56\..*
+   Volume set rs
+       Entry   1: server .*, partition .*, volumes: rs_aix42\..*
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_delvolentry(1)>,
+L<backup_delvolset(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_quit.pod b/doc/man-pages/pod/backup_quit.pod
new file mode 100644 (file)
index 0000000..9f7b701
--- /dev/null
@@ -0,0 +1,77 @@
+=head1 NAME
+
+backup quit - Leaves interactive mode
+
+=head1 SYNOPSIS
+
+quit [B<-help>]
+
+q [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<(backup) quit> command exits interactive mode, returning the issuer
+to the regular shell prompt at which the C<backup> or C<backup interactive>
+command was issued to enter interactive mode. The command has no
+effect when issued outside interactive mode. Issuing the <B<Ctrl-d>>
+command also exits interactive mode.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command exits interactive mode:
+
+   backup> quit
+
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 CAVEATS
+
+To exit interactive mode, all jobs must be completed. Use the C<(backup)
+jobs> command to list any jobs currently pending or executing, and the
+C<(backup) kill> command to terminate them as necessary.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_interactive(1)>,
+L<backup_jobs(1)>,
+L<backup_kill(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_readlabel.pod b/doc/man-pages/pod/backup_readlabel.pod
new file mode 100644 (file)
index 0000000..afb2a47
--- /dev/null
@@ -0,0 +1,242 @@
+=head1 NAME
+
+backup readlabel - Reads and displays a tape's label
+
+=head1 SYNOPSIS
+
+backup readlabel [B<-portoffset> I<TC port offset>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup rea [B<-p> I<TC port offset>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup readlabel> command displays information from the magnetic
+tape label of a tape. The information includes the tape's name (either
+a I<permanent name>, or an I<AFS tape name> that reflects the tape's
+contents in a prescribed format) and its capacity.
+
+If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
+port offset, then the C<backup readlabel> command reads the label
+information from the first 16 KB block in the backup data file listed
+for that port offset in the Tape Coordinator's
+B</usr/afs/backup/tapeconfig> file, rather than from the beginning of a
+tape.
+
+The Tape Coordinator's default response to this command is to access
+the tape by invoking the B<MOUNT> instruction in the local
+B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
+operator to insert the tape if there is no B<MOUNT> instruction. However,
+if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
+or if the issuer of the B<butc> command included the B<-noautoquery> flag,
+the Tape Coordinator instead expects the tape to be in the device
+already. If it is not, the Tape Coordinator invokes the B<MOUNT>
+instruction or prompts the operator.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator
+handling the tapes for this operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+Output from this command appears in both the shell window where the
+command is issued, and in the Tape Coordinator window.
+
+If the tape is unlabeled or if the specified tape device is empty, the
+output reads
+
+   Failed to read tape label.
+
+Otherwise, the output in the shell window has the following format:
+
+   Tape read was labelled: tape name (dump id)
+        size: size Kbytes
+
+where I<tape name> is the permanent name if the tape has one, or the AFS
+tape name otherwise. The I<dump ID> is the dump ID of the initial dump on the
+tape, and I<size> is the recorded capacity of the tape in kilobytes.
+
+The output in the Tape Coordinator windows is bounded by an underlined
+C<Tape label> header at the top, and the following string at the bottom:
+
+   -- End of tape label --
+
+In between are lines reporting the following information:
+
+=over
+
+=item B<tape name>
+
+The permanent name assigned by using the B<-pname> argument of the
+C<backup labeltape> command. This name remains on the tape until
+that argument is used again, no matter how many times the tape
+is recycled or otherwise relabeled. If the tape does not have a
+permanent name, the value C<E<lt>NULLE<gt>> appears in this field.
+
+=item B<AFS tape name>
+
+A tape name in one of the following prescribed formats. The
+Backup System automatically writes the appropriate AFS tape
+name to the label as part of a C<backup dump> or C<backup savedb>
+operation, or the operator can assign it with the B<-name>
+argument to the C<backup labeltape> command.
+
+=over
+
+=item *
+
+I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape
+contains volume data. The I<volume_set_name> is the name of the
+volume set that was dumped to create the initial dump in the
+dump set of to which this tape belongs; I<dump_level_name> is
+the last pathname element of the dump level at which the
+initial dump was backed up; and I<tape_index> is the numerical
+position of the tape in the dump set.
+
+=item *
+
+C<Ubik.db.dump.>I<tape_index> if the tape contains a dump of the
+Backup Database, created with the C<backup savedb> command. The
+I<tape_index> is the ordinal of the tape in the dump set.
+
+=item *
+
+C<E<lt>NULLE<gt>> if the tape has no AFS tape name. This is normally the
+case if the B<-name> argument was not included the last time the
+C<backup labeltape> command was used on this tape, and no data
+has been written to it since.
+
+=back
+
+=item B<creationTime>
+
+The date and time at which the Backup System started performing
+the dump operation that created the initial dump.
+
+=item B<cell>
+
+The cell in which the dump set was created. This is the cell
+whose Backup Database contains a record of the dump set.
+
+=item B<size>
+
+The tape's capacity (in kilobytes) as recorded on the label,
+rather than the amount of data on the tape. The value is
+assigned by the B<-size> argument to the C<backup labeltape> command
+or derived from the B</usr/afs/backup/tapeconfig> file on the Tape
+Coordinator machine, not from a measurement of the tape.
+
+=item B<dump path>
+
+The dump level of the initial dump in the dump set
+
+=item B<dump id>
+
+The dump ID number of the initial dump in the dump set, as
+recorded in the Backup Database
+
+=item B<useCount>
+
+The number of times a dump has been written to the tape, or it
+has been relabeled
+
+=back
+
+The message C<ReadLabel: Finished> indicates the completion of the
+output.
+
+=head1 EXAMPLES
+
+The following example shows the output for the tape with permanent
+name B<oct.guest.dump> and capacity 2 MB, expressed in kilobyte units
+(2097152 equals 2 times 1024^2).
+
+    backup readlabel -portoffset 6
+   Tape read was labelled: oct.guest.dump (907215000)
+        size: 2097152 Kbytes
+
+The output in the Tape Coordinator window reads:
+
+   Tape label
+   ----------
+   tape name = oct.guest.dump
+   AFS tape name = guests.monthly.3
+   creationTime = Thu Oct 1 00:10:00 1998
+   cell = abc.com
+   size = 2097152 Kbytes
+   dump path = B</monthly>
+   dump id = 907215000
+   useCount = 5
+   ---- End of tape label ----
+
+The following example is for a tape that does not have a permanent
+tape.
+
+    backup readlabel -portoffset 6
+   Tape read was labelled: guests.monthly.2 (909899900)
+        size: 2097152 Kbytes
+
+The output in the Tape Coordinator window reads:
+
+   Tape label
+   ----------
+   tape name = <NULL>
+   AFS tape name = guests.monthly.2
+   creationTime = Sun Nov 1 00:58:20 1998
+   cell = abc.com
+   size = 2097152 Kbytes
+   dump path = B</monthly>
+   dump id = 909899900
+   useCount = 1
+   ---- End of tape label ----
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_labeltape(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_restoredb.pod b/doc/man-pages/pod/backup_restoredb.pod
new file mode 100644 (file)
index 0000000..47ec5b5
--- /dev/null
@@ -0,0 +1,122 @@
+=head1 NAME
+
+backup restoredb - Restores a saved copy of the Backup Database
+
+=head1 SYNOPSIS
+
+backup restoredb [B<-portoffset> I<TC port offset>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup res [B<-p> I<TC port offset>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup restoredb> command restores to the Backup Server machine's
+local disk a version of the Backup Database previously written to tape
+by using the C<backup savedb> command.
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
+port offset, then the C<backup restoredb> command restores data from the
+backup data file listed for that port offset in the Tape Coordinator's
+B</usr/afs/backup/tapeconfig> file, instead of from tape. For the sake of
+clarity, the following text refers to tapes only, but the Backup
+System handles backup data files in much the same way.)
+
+The most common reason to run this command is to replace a corrupted
+or otherwise damaged Backup Database; use the C<backup dbverify> command
+to determine the database's status. The command can also be used to
+restore records that were removed from the database when the B<-archive>
+argument was included on a previous C<backup savedb> command.
+
+The command completely overwrites the existing Backup Database records
+for volume sets, Tape Coordinators, and the dump hierarchy with the
+corresponding information from the saved version. It does not
+overwrite existing dump records, but instead interleaves the records
+from the copy being restored. If both the existing database (on the
+Backup Server machine's disk) and the copy being restored include a
+record about the same dump, the Backup System retains the one in the
+existing database.
+
+The Tape Coordinator's default response to this command is to access
+the first tape it needs by invoking the B<MOUNT> instruction in the local
+B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
+operator to insert the tape if there is no B<MOUNT> instruction. However,
+if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
+or if the issuer of the B<butc> command included the B<-noautoquery> flag,
+the Tape Coordinator instead expects the tape to be in the device
+already. If it is not, or is the wrong tape, the Tape Coordinator
+invokes the B<MOUNT> instruction or prompts the operator. It also invokes
+the B<MOUNT> instruction or prompts for any additional tapes needed to
+complete the restore operation; the backup operator must arrange to
+provide them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator
+handling the tapes for this operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the Backup Database being restored from
+the Tape Coordinator with port offset 0:
+
+    backup restoredb
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+If the database is corrupted, do not attempt to restore a saved
+database on top of it. Instead, use the instructions for repairing a
+corrupted database in the IBM AFS Administration Guide chapter about
+performing backup operations.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dbverify(1)>,
+L<backup_savedb(1)>,
+L<butc(1)>,
+I<IBM AFS Administration Guide>
+
+=cut
diff --git a/doc/man-pages/pod/backup_savedb.pod b/doc/man-pages/pod/backup_savedb.pod
new file mode 100644 (file)
index 0000000..ebe1463
--- /dev/null
@@ -0,0 +1,174 @@
+=head1 NAME
+
+backup savedb - Creates a saved copy of the Backup Database
+
+=head1 SYNOPSIS
+
+backup savedb [B<-portoffset> I<TC port offset>]  [B<-archive> I<date time> ...]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup sa  [B<-p> I<TC port offset>]  [B<-a> I<date time> ...]
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup savedb> command creates a backup copy of the entire Backup
+Database and writes it to the tape in the device controlled by the
+Tape Coordinator indicated with the B<-portoffset> argument. If the
+database is damaged (as reported by the C<backup dbverify> command), this
+command repairs as much of the corruption as possible as it creates
+the saved copy. The Backup Server creates a dump record for the saved
+database in the Backup Database (but in the disk version of the
+database only, not in the version written to tape).
+
+If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
+port offset, then the C<backup savedb> command dumps the database copy to
+the backup data file listed for that port offset in the Tape
+Coordinator's B</usr/afs/backup/tapeconfig> file, instead of to tape. For
+the sake of clarity, the following text refers to tapes only, but the
+Backup System handles backup data files in much the same way.
+
+If the B<-archive> flag is provided, after writing the saved copy of the
+database the Backup System truncates the copy of the database on disk
+by deleting volume dump records with timestamps prior to the specified
+date and time (it does not delete the dump records created by previous
+C<backup savedb> commands, however).
+
+If the tape to which the database copy is written has an AFS tape
+name, it must be B<Ubik_db_dump.1> or C<E<lt>NULLE<gt>>. Any permanent name is
+acceptable.
+
+The Tape Coordinator's default response to this command is to access
+the first tape by invoking the B<MOUNT> instruction in the local
+B</usr/afs/backup/CFG_device_name> file, or by prompting the backup
+operator to insert the tape if there is no B<MOUNT> instruction. However,
+if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
+or if the issuer of the B<butc> command included the B<-noautoquery> flag,
+the Tape Coordinator instead expects the tape to be in the device
+already. If it is not, the Tape Coordinator invokes the B<MOUNT>
+instruction or prompts the operator. It also invokes the B<MOUNT>
+instruction or prompts for any additional tapes needed to complete the
+operation; the backup operator must arrange to provide them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator
+handling the tapes for this operation.
+
+=item B<-archive> I<date time> ...
+
+Specifies a date and time; volume dump records with earlier
+timestamps are deleted from the disk copy of the Backup
+Database after the Backup System dumps the database (a dump's
+timestamp appears in the created field of the output from the
+C<backup dumpinfo> command). However, if a dump set contains any
+dump created after the specified date, none of the dump records
+associated with the dump set are deleted. Dump records for
+previous dumps of the database (created with the C<backup savedb>
+command) are never deleted; use the C<backup deletedump> command
+to remove them.
+
+Provide one of two values:
+
+=over
+
+=item *
+
+The string C<NOW> to indicate the current date and time, in
+which case the Backup System deletes all dump records except
+those for dumps of the Backup Database itself.
+
+=item *
+
+A date value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>]. The month
+(I<mm>), day (I<dd>), and year (I<yyyy>) are required, and valid
+values for the year range from B<1970> to B<2037>; higher values
+are not valid because the latest possible date in the
+standard UNIX representation is in February 2038. The Backup
+System automatically reduces any later date to the maximum
+value.
+
+The hour and minutes (I<hh>:I<MM>) are optional, but if provided
+must be in 24-hour format (for example, the value B<14:36>
+represents 2:36 p.m.). If omitted, the time defaults to 59
+seconds after midnight (00:00:59 hours). Similarly, the
+C<backup> command interpreter automatically adds 59 seconds to
+any time value provided. In both cases, adding 59 seconds
+compensates for how the Backup Database and C<backup dumpinfo>
+command represent dump creation times in hours and minutes
+only. That is, the Database records a creation timestamp of
+C<20:55> for any dump created between 20:55:00 and 20:55:59.
+Automatically adding 59 seconds to a time thus includes the
+records for all dumps created during that minute.
+
+=back
+
+=over
+
+=item B<Note:>
+
+A ... follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition.
+
+=back
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example writes a copy of the Backup Database to the tape
+device controlled by the Tape Coordinator with port offset 1:
+
+    backup savedb -portoffset 1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dbverify(1)>,
+L<backup_restoredb(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_scantape.pod b/doc/man-pages/pod/backup_scantape.pod
new file mode 100644 (file)
index 0000000..7d42072
--- /dev/null
@@ -0,0 +1,359 @@
+=head1 NAME
+
+backup scantape - Extracts dump information from a tape
+
+=head1 SYNOPSIS
+
+backup scantape [B<-dbadd>]  [B<-portoffset> I<TC port offset>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup sc [B<-d>]  [B<-p> I<TC port offset>]  [B<-l>]  [B<-c> I<cell name>]  [B<-help>]
+
+=head1 DESCRIPTION
+
+The C<backup scantape> command extracts information from the dump labels
+and volume headers on the tape in the device controlled by the Tape
+Coordinator indicated by the B<-portoffset> argument. The Tape
+Coordinator displays the information for each volume in its window as
+soon as it extracts it (rather than waiting until it has scanned the
+entire tape).
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
+port offset, then the C<backup scantape> command extracts dump
+information from the backup data file named in that port offset's
+entry in the B</usr/afs/backup/tapeconfig> file on the Tape Coordinator
+machine, rather than from a tape. For the sake of clarity, the
+following text refers to tapes only, but the Backup System handles
+backup data files in much the same way.)
+
+If the B<-dbadd> flag is provided, the C<backup scantape> command creates
+new dump and volume records in the Backup Database for the scanned
+information. However, if it finds that a record already exists in the
+database for the same dump, it terminates the scanning operation.
+
+The scanning operation works only on tapes containing volume data. The
+command fails with an error message if the tape contains a copy of the
+Backup Database (was created with the C<backup savedb> command, or has
+the AFS tape name B<Ubik_db_dump.1>).
+
+The Tape Coordinator's default response to this command is to access
+the tape by invoking the B<MOUNT> instruction in the B<CFG_>I<device_name>
+file, or by prompting the backup operator to insert the tape if there
+is no B<MOUNT> instruction. However, if the B<AUTOQUERY NO> instruction
+appears in the B<CFG_>I<device_name> file, or if the issuer of the B<butc>
+command included the B<-noautoquery> flag, the Tape Coordinator instead
+expects the tape to be in the device already. If it is not, the Tape
+Coordinator invokes the B<MOUNT> instruction or prompts the operator.
+
+To terminate a tape scanning operation in interactive mode, issue the
+C<(backup) kill> command. In noninteractive mode, the only choice is to
+use a termination signal such as <B<Ctrl-c>> to halt the Tape Coordinator
+completely.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dbadd>
+
+Adds the information extracted from the tape to the Backup
+Database (but only if the database does not already contain an
+entry with the same dump ID number).
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator
+handling the tapes for this operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+For every dump on a tape, the C<backup scantape> command displays in the
+Tape Coordinator window the dump label and the volume header of each
+volume in the dump. If a dump spans more than one tape, the dump label
+does not repeat at the beginning of subsequent tapes.
+
+A dump label contains the following fields, which are the same as in
+the output from the C<backup readlabel> command:
+
+=over
+
+=item B<tape name>
+
+The permanent name assigned by using the B<-pname> argument of the
+C<backup labeltape> command. This name remains on the tape until
+that argument is used again, no matter how many times the tape
+is recycled or otherwise relabeled. If the tape does not have a
+permanent name, the value C<E<lt>NULLE<gt>> appears in this field.
+
+=item B<AFS tape name>
+
+A tape name in one of the following prescribed formats. The
+Backup System automatically writes the appropriate AFS tape
+name to the label as part of a C<backup dump> operation, or the
+operator can assign it with the B<-name> argument to the C<backup
+labeltape> command.
+
+=over
+
+=item *
+
+I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape
+contains volume data. The I<volume_set_name> is the name of the
+volume set that was dumped to create the initial dump in the
+dump set of which this tape is a part; I<dump_level_name> is the
+last pathname element of the dump level at which the initial
+dump was backed up; and I<tape_index> is the numerical position
+of the tape in the dump set.
+
+=item *
+
+C<E<lt>NULLE<gt>> if the tape has no AFS tape name. This is normally the
+case if the B<-name> argument was not included the last time the
+C<backup labeltape> command was used on this tape, and no data
+has been written to it since.
+
+=back
+
+=item B<creationTime>
+
+The date and time at which the Backup System started performing
+the dump operation that created the initial dump.
+
+=item B<cell>
+
+The cell in which the dump set was created. This is the cell
+whose Backup Database contains a record of the dump set.
+
+=item B<size>
+
+The tape's capacity (in kilobytes) as recorded on the label,
+rather than the amount of data on the tape. The value is
+assigned by the B<-size> argument to the C<backup labeltape> command
+or derived from the B</usr/afs/backup/tapeconfig> file on the Tape
+Coordinator machine, not from a measurement of the tape.
+
+=item B<dump path>
+
+The dump level of the initial dump in the dump set.
+
+=item B<dump id>
+
+The dump ID number of the initial dump in the dump set, as
+recorded in the Backup Database.
+
+=item B<useCount>
+
+The number of times a dump has been written to the tape, or it
+has been relabeled.
+
+=back
+
+The volume header contains the following fields:
+
+=over
+
+=item B<volume name>
+
+The volume name, complete with a C<.backup> or C<.readonly>
+extension, if appropriate.
+
+=item B<volume ID>
+
+The volume's volume ID.
+
+=item B<dumpSetName>
+
+The dump to which the volume belongs. The dump name is of the
+form I<volume_set_name>.I<dump_level_name> and matches the name
+displayed in the dump label.
+
+=item B<dumpID>
+
+The dump ID of the dump named in the C<dumpSetName> field.
+
+=item B<level>
+
+The depth in the dump hierarchy of the dump level used in
+creating the dump. A value of 0 indicates a full dump. A value
+of 1 or greater indicates an incremental dump made at the
+indicated depth in the hierarchy. The value reported is for the
+entire dump, not necessarily for the volume itself; for
+example, it is possible for a dump performed at an incremental
+level to include a full dump of an individual volume if the
+volume was omitted from previous dumps.
+
+=item B<parentID>
+
+The dump ID number of C<dumpSetName>'s parent dump. It is 0 if the
+value in the C<level> field is 0.
+
+=item B<endTime>
+
+Is always 0; it is reserved for internal use.
+
+=item B<cloneDate>
+
+The date and time at which the volume was created. For a backup
+or read-only volume, this represents the time at which it was
+cloned from its read/write source. For a read/write volume, it
+indicates the time at which the Backup System locked the volume
+for purposes of including it in the dump named in the
+C<dumpSetName> field.
+
+=back
+
+The message C<Scantape: Finished> indicates the completion of the output.
+
+In normal circumstances, the Backup System writes a marker to indicate
+that a volume is the last one on a tape, or that the volume continues
+on the next tape. However, if a backup operation terminated abnormally
+(for example, because the operator terminated the Tape Coordinator by
+issuing the <B<Ctrl-c>> command during the operation), then there is no
+such marker. Some very early versions of the Backup System also did
+not write these markers. If a tape does not conclude with one of the
+expected markers, the Tape Coordinator cannot determine if there is a
+subsequent tape in the dump set and so generates the following message
+in its window:
+
+   Are there more tapes? (y/n)
+
+=head1 EXAMPLES
+
+The following example shows the output for the first two volumes on a
+tape in the device with port offset 0:
+
+    backup scantape
+   Dump label
+   ----------
+   tape name = monthly_guest
+   AFS tape name = guests.monthly.3
+   creationTime =  Mon Feb  1 04:06:40 1999
+   cell = abc.com
+   size = 2150000 Kbytes
+   dump path = B</monthly>
+   dump id = 917860000
+   useCount = 44
+   -- End of dump label --
+   -- volume --
+   volume name: user.guest10.backup
+   volume ID 1937573829
+   dumpSetName: guests.monthly
+   dumpID 917860000
+   level 0
+   parentID 0
+   endTime 0
+   clonedate Mon Feb  1 03:03:23 1999
+   -- volume --
+   volume name: user.guest11.backup
+   volume ID 1938519386
+   dumpSetName: guests.monthly
+   dumpID 917860000
+   level 0
+   parentID 0
+   endTime 0
+   clonedate Mon Feb  1 03:05:15 1999
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+A scanning operation does not have to begin with the first tape in a
+dump set, but the Backup System can process tapes only in sequential
+order after the initial tape provided. The Tape Coordinator
+automatically requests any subsequent tapes by invoking the B<MOUNT>
+instruction in the local B</usr/afs/backup/CFG_>I<device_name> file, or by
+prompting the operator if there is no B<MOUNT> instruction.
+
+The Tape Coordinator's success in scanning a tape that is corrupted or
+damaged depends on the extent of the damage and what type of data is
+corrupted. It can almost always scan the tape successfully up to the
+point of damage. If the damage is minor, the Tape Coordinator can
+usually skip over it and scan the rest of the tape, but more major
+damage can prevent further scanning. Because a scanning operation can
+start on any tape in a dump set, damage on one tape does not prevent
+scanning of the others in the dump set. However, it is possible to
+scan either the tapes that precede the damaged one or the ones that
+follow it, but not both.
+
+If a tape is relabeled with the C<backup labeltape> command, it is not
+possible to recover data from it for the purposes of rebuilding the
+Backup Database.
+
+If the B<-dbadd> flag is included on the command, it is best not to
+terminate the tape scanning operation before it completes (for
+example, by issuing the C<(backup) kill> command in interactive mode).
+The Backup System writes a new record in the Backup Database for each
+dump as soon as it scans the relevant information on the tape, and so
+it possibly has already written new records. If the operator wants to
+rerun the scanning operation, he or she must locate and remove the
+records created during the terminated operation: the second operation
+exits automatically if it finds that a record that it needs to create
+already exists.
+
+If the B<-dbadd> flag is included and the first tape provided is not the
+first tape in the dump set, the following restrictions apply:
+
+=over
+
+=item *
+
+If the first data on the tape is a continuation of a volume that
+begins on the previous (unscanned) tape in the dump set, the
+Backup System does not add a record for that volume to the Backup
+Database.
+
+=item *
+
+The Backup System must read the marker that indicates the start of
+an appended dump to add database records for the volumes in it. If
+the first volume on the tape belongs to an appended dump, but is
+not immediately preceded by the appended-dump marker, the Backup
+System does not create a Backup Database record for it or any
+subsequent volumes that belong to that appended dump.
+
+=back
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dump(1)>,
+L<backup_dumpinfo(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_setexp.pod b/doc/man-pages/pod/backup_setexp.pod
new file mode 100644 (file)
index 0000000..4070345
--- /dev/null
@@ -0,0 +1,175 @@
+=head1 NAME
+
+backup setexp - Sets the expiration date for existing dump levels.
+
+=head1 SYNOPSIS
+
+backup setexp B<-dump> I<dump level name> [I<dump level name> ...]  [B<-expires> I<expiration date> ...]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup se B<-d> I<dump level name> [I<dump level name> ...]  [B<-e> I<expiration date> ...]
+[B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup setexp> command sets or changes the expiration date
+associated with each specified dump level, which must already exist in
+the dump hierarchy.
+
+Use the B<-expires> argument to associate an expiration date with each
+dump level. When the Backup System subsequently creates a dump at the
+dump level, it uses the specified value to derive the dump's
+expiration date, which it records on the label of the tape (or backup
+data file). The Backup System refuses to overwrite a tape until after
+the latest expiration date of any dump that the tape contains, unless
+the C<backup labeltape> command is used to relabel the tape. If a dump
+level does not have an expiration date, the Backup System treats dumps
+created at the level as expired as soon as it creates them.
+
+(Note that the Backup System does not automatically remove a dump's
+record from the Backup Database when the dump reaches its expiration
+date, but only if the tape that contains the dump is recycled or
+relabeled. To remove expired and other obsolete dump records, use the
+C<backup deletedump> command.)
+
+Define either an absolute or relative expiration date:
+
+=over
+
+=item *
+
+An absolute expiration date defines the month/day/year (and,
+optionally, hour and minutes) at which a dump expires. If the
+expiration date predates the dump creation time, the Backup System
+immediately treats the dump as expired.
+
+=item *
+
+A relative date defines the number of years, months, or days (or a
+combination of the three) after the dump's creation that it
+expires. When the Backup System creates a dump at the dump level,
+it calculates an actual expiration date by adding the relative
+date to the start time of the dump operation.
+
+=back
+
+If the command is used to change an existing expiration date
+associated with a dump level, the new date applies only to dumps
+created after the change. Existing dumps retain the expiration date
+assigned at the time they were created.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dump> I<dump level name> [I<dump level name> ...]
+
+Specifies the full pathname of each dump level to assign the
+expiration date specified by the B<-expires> argument.
+
+=item B<-expires> I<expiration date> ...
+
+Defines the absolute or relative expiration date to associate
+with each dump level named by the B<-dump> argument. Absolute
+expiration dates have the following format:
+
+[B<at>] {B<NEVER> | I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>] }
+
+where the optional word C<at> is followed either by the string
+C<NEVER>, which indicates that dumps created at the dump level
+never expire, or by a date value with a required portion (I<mm>
+for month, I<dd> for day, and I<yyyy> for year) and an optional
+portion (I<hh> for hours and I<MM> for minutes).
+
+Omit the I<hh>:I<MM> portion to use the default of midnight (00:00
+hours), or provide a value in 24-hour format (for example,
+B<20:30> is 8:30 p.m.). Valid values for the year range from B<1970>
+to B<2037>; higher values are not valid because the latest
+possible date in the standard UNIX representation is in
+February 2038. The command interpreter automatically reduces
+later dates to the maximum value.
+
+Relative expiration dates have the following format:
+
+[B<in>] [I<years>B<y>] [I<months>B<m>] [I<days>B<d>]
+
+where the optional word C<in> is followed by at least one of a
+number of years (maximum B<9999>) followed by the letter C<y>, a
+number of months (maximum B<12>) followed by the letter C<m>, or a
+number of days (maximum B<31>) followed by the letter C<d>. If
+providing more than one of the three, list them in the
+indicated order. If the date that results from adding the
+relative expiration value to a dump's creation time is later
+than the latest possible date in the UNIX time representation,
+the Backup System automatically reduces it to that date.
+
+=over
+
+=item B<Note:>
+
+A ... follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition to be associated with each dump level specified by the
+B<-dump> argument.
+
+=back
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example associates an absolute expiration date of 10:00
+p.m. on 31 December 1999 with the dump level B</1998/december>:
+
+    backup setexp -dump B</1998/december> -expires at 12/31/1999 22:00
+
+The following example associates a relative expiration date of 7 days
+with the two dump levels B</monthly/week1> and B</monthly/week2>:
+
+    backup setexp -dump B</monthly/week1> B</monthly/week> -expires 7d
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_adddump(1)>,
+L<backup_deldump(1)>,
+L<backup_listdumps(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_status.pod b/doc/man-pages/pod/backup_status.pod
new file mode 100644 (file)
index 0000000..3ce8418
--- /dev/null
@@ -0,0 +1,198 @@
+=head1 NAME
+
+backup status - Reports a Tape Coordinator's status
+
+=head1 SYNOPSIS
+
+backup status [B<-portoffset> I<TC port offset>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup st [B<-p> I<TC port offset>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup status> command displays which operation, if any, the
+indicated Tape Coordinator is currently executing.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-portoffset> I<TC port offset>
+
+Specifies the port offset number of the Tape Coordinator for
+which to report the status.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message indicates that the Tape Coordinator is not
+currently performing an operation:
+
+Tape coordinator is idle
+
+Otherwise, the output includes a message of the following format for
+each running or pending operation:
+
+Task I<task_ID>:  I<operation>:   I<status>
+
+where
+
+=over
+
+=item B<I<task_ID>>
+
+Is a task identification number assigned by the Tape
+Coordinator. It begins with the Tape Coordinator's port offset
+number.
+
+=item B<I<operation>>
+
+Identifies the operation the Tape Coordinator is performing,
+which is initiated by the indicated command:
+
+=over
+
+=item *
+
+Dump (the C<backup dump> command)
+
+=item *
+
+Restore (the backup diskrestore, backup volrestore, or C<backup
+volsetrestore> commands)
+
+=item *
+
+Labeltape (the C<backup labeltape> command)
+
+=item *
+
+Scantape (the C<backup scantape> command)
+
+=item *
+
+SaveDb (the C<backup savedb> command)
+
+=item *
+
+RestoreDb (the C<backup restoredb> command)
+
+=back
+
+=item B<I<status>>
+
+Indicates the job's current status in one of the following
+messages.
+
+=over
+
+=item B<I<number> Kbytes transferred, volume I<volume_name>>
+
+For a running dump operation, indicates the number of
+kilobytes copied to tape or a backup data file so far,
+and the volume currently being dumped.
+
+=item B<I<number> Kbytes, restore.volume>
+
+For a running restore operation, indicates the number of
+kilobytes copied into AFS from a tape or a backup data
+file so far.
+
+=item B<[abort requested]>
+
+The C<(backup) kill> command was issued, but the termination
+signal has yet to reach the Tape Coordinator.
+
+=item B<[abort sent]>
+
+The operation is canceled by the C<(backup) kill> command.
+Once the Backup System removes an operation from the
+queue or stops it from running, it no longer appears at
+all in the output from the command.
+
+=item B<[butc contact lost]>
+
+The C<backup> command interpreter cannot reach the Tape
+Coordinator. The message can mean either that the Tape
+Coordinator handling the operation was terminated or
+failed while the operation was running, or that the
+connection to the Tape Coordinator timed out.
+
+=item B<[done]>
+
+The Tape Coordinator has finished the operation.
+
+=item B<[drive wait]>
+
+The operation is waiting for the specified tape drive to
+become free.
+
+=item B<[operator wait]>
+
+The Tape Coordinator is waiting for the backup operator
+to insert a tape in the drive.
+
+=back
+
+=back
+
+If the Tape Coordinator is communicating with an XBSA server (a
+third-party backup utility that implements the Open Group's Backup
+Service API [XBSA]), the following message appears last in the output:
+
+I<XBSA_program> Tape coordinator
+
+where I<XBSA_program> is the name of the XBSA-compliant program.
+
+=head1 EXAMPLES
+
+The following example shows that the Tape Coordinator with port offset
+4 has so far dumped about 1.5 MB of data for the current dump
+operation, and is currently dumping the volume named B<user.pat.backup>:
+
+    backup status -portoffset 4
+   Task 4001:  Dump:   1520 Kbytes transferred,  volume user.pat.backup
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_volinfo.pod b/doc/man-pages/pod/backup_volinfo.pod
new file mode 100644 (file)
index 0000000..21b0c2e
--- /dev/null
@@ -0,0 +1,134 @@
+=head1 NAME
+
+backup volinfo - Displays a volume's dump history from the Backup Database
+
+=head1 SYNOPSIS
+
+backup volinfo B<-volume> I<volume name>
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup voli B<-v> I<volume name>  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup volinfo> command displays a dump history of the specified
+volume, reporting information such as the date on which the volume was
+dumped and the tapes that contain it. Include the C<.backup> extension on
+the volume name if the backup version of the volume was dumped.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-volume> I<volume name>
+
+Names the volume for which to display the dump history. Include
+the C<.backup> or C<.readonly> extension if the backup or read-only
+version of the volume was dumped.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes a line for each Backup Database dump record that
+mentions the specified volume, order from most to least recent. The
+output for each record appears in a table with six columns:
+
+=over
+
+=item B<dumpID>
+
+The dump ID of the dump that includes the volume.
+
+=item B<lvl>
+
+The depth in the dump hierarchy of the dump level at which the
+volume was dumped. A value of 0 indicates a full dump. A value
+of 1 or greater indicates an incremental dump made at the
+specified depth in the dump hierarchy.
+
+=item B<parentid>
+
+The dump ID of the dump's parent dump. A value of 0 indicates a
+full dump, which has no parent; in this case, the value in the
+C<lvl> column is also 0.
+
+=item B<creation date>
+
+The date and time at which the Backup System started the dump
+operation that created the dump.
+
+=item B<clone date>
+
+For a backup or read-only volume, the time at which it was
+cloned from its read/write source. For a read/write volume, the
+same as the value in the creation date field.
+
+=item B<tape name>
+
+The name of the tape containing the dump: either the permanent
+tape name, or an AFS tape name in the format
+I<volume_set_name>.I<dump_level_name>.I<tape_index> where
+I<volume_set_name> is the name of the volume set associated with
+the initial dump in the dump set of which this tape is a part;
+I<dump_level_name> is the name of the dump level at which the
+initial dump was backed up; I<tape_index> is the ordinal of the
+tape in the dump set. Either type of name can be followed by a
+dump ID in parentheses; if it appears, it is the dump ID of the
+initial dump in the dump set to which this appended dump
+belongs.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows part of the dump history of the Backup
+volume user.smith.backup:
+
+    backup volinfo -volume user.smith.backup
+   DumpID    lvl parentID  creation date    clone date       tape name
+   924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
+   924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2
+   924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6
+       .     .       .         .        .       .        .        .
+       .     .       .         .        .       .        .        .
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dumpinfo(1)>,
+L<backup_volrestore(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_volrestore.pod b/doc/man-pages/pod/backup_volrestore.pod
new file mode 100644 (file)
index 0000000..6c2aa84
--- /dev/null
@@ -0,0 +1,336 @@
+=head1 NAME
+
+backup volrestore - Restores one or more volumes
+
+=head1 SYNOPSIS
+
+backup volrestore B<-server> I<destination machine>
+B<-partition> I<destination partition>
+B<-volume> I<volume(s) to restore> [I<volume(s) to restore> ...]
+[B<-extension> I<new volume name extension>]
+[B<-date> I<date from which to restore> ...]
+[B<-portoffset> I<TC port offsets> [I<TC port offsets> ...]]  [B<-n>]
+[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup volr B<-s> I<destination machine>  B<-pa> I<destination partition>
+B<-v> I<volume(s) to restore> [I<volume(s) to restore> ...]  [B<-e> I<new volume name extension>]
+[B<-d> I<date from which to restore> ...]  [B<-po> I<TC port offsets> [I<TC port offsets> ...]]
+[B<-n>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup volrestore> command restores the contents of one or more
+volumes to the site indicated by the B<-server> and B<-partition> arguments.
+Use the command either to overwrite the contents of existing volumes
+with the restored data or to create new volumes while retaining the
+existing ones. The specified site does not have to be the current site
+for the volumes.
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
+port offset, then the C<backup volrestore> command restores data from the
+backup data file listed for that port offset in the Tape Coordinator's
+B</usr/afs/backup/tapeconfig> file, rather than from tape. For the sake
+of clarity, the following text refers to tapes only, but the Backup
+System handles backup data files in much the same way.)
+
+The command's arguments can be combined as indicated:
+
+=over
+
+=item *
+
+To preserve a volume's current contents and also create a new
+volume to house the restored version, use the B<-extension> argument.
+The Backup System creates the new volume on the server and
+partition named by the B<-server> and B<-partition> arguments, assigns
+it the same name as the current volume with the addition of the
+specified extension, and creates a new Volume Location Database
+(VLDB) entry for it. Creating a new volume enables the
+administrator to compare the two versions.
+
+=item *
+
+To overwrite a volume's existing contents with the restored
+version, omit the B<-extension> argument, and specify the site as
+indicated:
+
+=over
+
+=item *
+
+To retain the current site, specify it with the B<-server> and
+B<-partition> arguments.
+
+=item *
+
+To move the volume to a different site while overwriting it,
+specify the new site with the B<-server> argument, B<-partition>
+argument, or both. The Backup System creates a new volume at
+that site, removes the existing volume, and updates the site
+information in the volume's VLDB entry. The backup version of
+the volume is not removed automatically from the original
+site, if it exists. Use the C<vos remove> command to remove it
+and the C<vos backup> command to create a backup version at the
+new site.
+
+=back
+
+=item *
+
+To restore a volume that no longer exists in the file system,
+specify its name with the B<-volume> argument and use the B<-server> and
+B<-partition> arguments to place it at the desired site. The Backup
+System creates a new volume and new VLDB entry.
+
+=back
+
+In each case, the command sets each volume's creation date to the date
+and time at which it restores it. The creation date appears in the
+Creation field in the output from the C<vos examine> and C<vos listvol>
+commands.
+
+If restoring all of the volumes that resided on a single partition, it
+is usually more efficient to use the C<backup diskrestore> command. If
+restoring multiple volumes to many different sites, it can be more
+efficient to use the C<backup volsetrestore> command.
+
+By default, the C<backup volrestore> command restores the most recent
+full dump and all subsequent incremental dumps for each volume,
+bringing the restored volumes to the most current possible state. To
+restore the volumes to their state at some time in the past, use the
+B<-date> argument. The Backup System restores the most recent full dump
+and each subsequent incremental dump for which the I<clone date> of the
+volume included in the dump is before the indicated date and time (the
+clone date timestamp appears in the C<clone date> field of the output
+from the C<backup volinfo> command). For backup and read-only volumes,
+the clone date represents the time at which the volume was copied from
+its read/write source; for read/write volumes, it represents the time
+at which the volume was locked for inclusion in the dump. The
+resemblance of a restored volume to its actual state at the indicated
+time depends on the amount of time that elapsed between the volume's
+clone date in the last eligible dump and the specified time.
+
+If the B<-volume> argument specifies the base (read/write) form of the
+volume name, the Backup System searches the Backup Database for the
+newest dump set that includes a dump of either the read/write or the
+backup version of the volume. It restores the dumps of that version of
+the volume, starting with the most recent full dump. If, in contrast,
+the volume name explicitly includes the C<.backup> or C<.readonly>
+extension, the Backup System restores dumps of the corresponding
+volume version only.
+
+To generate a list of the tapes the Backup System needs to perform the
+restore operation, without actually performing it, combine the B<-n> flag
+with the options to be used on the actual command.
+
+If all of the full and incremental dumps of all relevant volumes were
+not written to a type of tape that a single Tape Coordinator can read,
+use the B<-portoffset> argument to list multiple port offset numbers in
+the order in which the tapes are needed (first list the port offset
+for the full dump, second the port offset for the level 1 incremental
+dump, and so on). If restoring multiple volumes, the same ordered list
+of port offsets must apply to all of them. If not, either issue this
+command separately for each volume, or use the C<vos volsetrestore>
+command after defining groups of volumes that were dumped to
+compatible tape types. For further discussion, see the IBM AFS
+Administration Guide.
+
+The Tape Coordinator's default response to this command is to access
+the first tape it needs by invoking the B<MOUNT> instruction in the local
+B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
+operator to insert the tape if there is no B<MOUNT> instruction. However,
+if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
+or if the issuer of the B<butc> command included the B<-noautoquery> flag,
+the Tape Coordinator instead expects the tape to be in the device
+already. If it is not, or is the wrong tape, the Tape Coordinator
+invokes the B<MOUNT> instruction or prompts the operator. It also invokes
+the B<MOUNT> instruction or prompts for any additional tapes needed to
+complete the restore operation; the backup operator must arrange to
+provide them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<destination machine>
+
+Names the file server machine on which to restore each volume.
+If this argument and the B<-partition> argument indicate a site
+other than the current site for each volume, and the B<-extension>
+argument is not also provided, the Backup System removes the
+existing volumes from their current sites, places the restored
+contents at the specified site, and changes the site
+information in the volume's VLDB entry.
+
+=item B<-partition> I<destination partition>
+
+Names the partition to which to restore each volume. If this
+argument and the B<-server> argument indicate a site other than
+the current site for each volume, and the B<-extension> argument
+is not also provided, the Backup System removes the existing
+volumes from their current sites, places the restored contents
+at the specified site, and changes the site information in the
+volume's VLDB entry.
+
+=item B<-volume> I<volume(s) to restore> [I<volume(s) to restore> ...]
+
+Names one or more volumes to restore, using the volume name as
+listed in the Backup Database. Provide the base (read/write)
+name of each volume to have the Backup System search the Backup
+Database for the newest dump set that includes a dump of either
+the read/write or the backup version of the volume; it restores
+the dumps of that version of the volume, starting with the most
+recent full dump. If, in contrast, a volume name explicitly
+includes the C<.backup> or C<.readonly> extension, the Backup System
+restores dumps of the corresponding volume version only.
+
+=item B<-extension> I<new volume name extension>
+
+Creates a new volume to house the restored data, with a name
+derived by appending the specified string to each volume named
+by the B<-volume> argument. The Backup System creates a new VLDB
+entry for the volume. Any string other than C<.readonly> or
+C<.backup> is acceptable, but the combination of the existing
+volume name and extension cannot exceed 22 characters in
+length. To use a period to separate the extension from the
+name, specify it as the first character of the string (as in
+C<.rst>, for example).
+
+=item B<-date> I<date from which to restore> ...
+
+Specifies a date and optionally time; the restored volume
+includes data from dumps performed before the date only.
+Provide a value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>], where the
+required I<mm>/I<dd>/I<yyyy> portion indicates the month (I<mm>), day (I<dd>),
+and year (I<yyyy>), and the optional I<hh>:I<MM> portion indicates the
+hour and minutes in 24-hour format (for example, the value
+B<14:36> represents 2:36 p.m.). If omitted, the time defaults to
+59 seconds after midnight (00:00:59 hours).
+
+Valid values for the year range from B<1970> to B<2037>; higher
+values are not valid because the latest possible date in the
+standard UNIX representation is in February 2038. The command
+interpreter automatically reduces any later date to the maximum
+value.
+
+If this argument is omitted, the Backup System restores all
+possible dumps including the most recently created.
+
+=over
+
+=item B<Note:>
+
+A plus sign follows this argument in the command's syntax
+statement because it accepts a multiword value which does not need to
+be enclosed in double quotes or other delimiters, not because it
+accepts multiple dates. Provide only one date (and optionally, time)
+definition.
+
+=back
+
+=item B<-portoffset> I<TC port offsets> [I<TC port offsets> ...]
+
+Specifies one or more port offset numbers (up to a maximum of
+128), each corresponding to a Tape Coordinator to use in the
+operation. If there is more than one value, the Backup System
+uses the first one when restoring the full dump of each volume,
+the second one when restoring the level 1 incremental dump of
+each volume, and so on. It uses the final value in the list
+when restoring dumps at the corresponding depth in the dump
+hierarchy and all dumps at lower levels.
+
+Provide this argument unless the default value of 0 (zero) is
+appropriate for all dumps. If B<0> is just one of the values in
+the list, provide it explicitly in the appropriate order.
+
+=item B<-n>
+
+Displays the list of tapes that contain the dumps required by
+the restore operation, without actually performing the
+operation.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the issuer includes the B<-n> flag with the command, the following
+string appears at the head of the list of the tapes necessary to
+complete the restore operation.
+
+Tapes needed:
+
+=head1 EXAMPLES
+
+The following command restores the volume B<user.pat> to partition
+B</vicepa> on machine B<fs5.abc.com>:
+
+    backup volrestore -server fs5.abc.com -partition a -volume user.pat
+
+The following command restores the volumes B<user.smith> and B<user.terry>
+to partition B</vicepb> on machine B<fs4.abc.com>, adding a B<.rst> extension
+to each volume name and preserving the existing B<user.smith> and
+B<user.terry> volumes. Only dumps created before 5:00 p.m. on 31 January
+1998 are restored. (The command is shown here on multiple lines only
+for legibility reasons.)
+
+    backup volrestore -server fs4.abc.com -partition b  \
+                      -volume user.smith user.terry  \
+                      -extension .rst -date 1/31/1998 17:00
+
+The following command restores the volume B<user.pat> to partition
+B</vicepb> on machine B<fs4.abc.com>. The Tape Coordinator with port offset
+1 handles the tape containing the full dump; the Tape Coordinator with
+port offset 0 handles all tapes containing incremental dumps. (The
+command is shown here on two lines only for legibility reasons.)
+
+    backup volrestore -server fs5.abc.com -partition a  \
+                      -volume user.pat -portoffset 1 0
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is
+running, and on every file server machine that houses an affected
+volume. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser B<root>.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_dump(1)>,
+L<backup_diskrestore(1)>,
+L<backup_volsetrestore(1)>,
+L<butc(1)>,
+L<vos_backup(1)>,
+L<vos_remove(1)>
+
+=cut
diff --git a/doc/man-pages/pod/backup_volsetrestore.pod b/doc/man-pages/pod/backup_volsetrestore.pod
new file mode 100644 (file)
index 0000000..1cdb9bb
--- /dev/null
@@ -0,0 +1,424 @@
+=head1 NAME
+
+backup volsetrestore - Restores all volumes in a volume set
+
+=head1 SYNOPSIS
+
+backup volsetrestore [B<-name> I<volume set name>]  [B<-file> I<file name>]
+[B<-portoffset> I<TC port offset> [I<TC port offset> ...]]
+[B<-extension> I<new volume name extension>]
+[B<-n>]  [B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]
+
+backup vols [B<-na> I<volume set name>]  [B<-f> I<file name>]
+[B<-p> I<TC port offset> [I<TC port offset> ...]]  [B<-e> I<new volume name extension>]
+[B<-n>]  [B<-l>]  [B<-c> I<cell name>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup volsetrestore> command restores the complete contents of a
+group of read/write volumes to the file system, by restoring data from
+the last full dump and all subsequent incremental dumps of each
+volume. It is most useful for recovering from loss of data on multiple
+partitions, since it can restore each of a defined set of volumes to a
+different site.
+
+(If the B<FILE YES> instruction appears in the
+B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
+port offset, then the C<backup volsetrestore> command restores data from
+the backup data file listed for that port offset in the Tape
+Coordinator's B</usr/afs/backup/tapeconfig> file, instead of from tape.
+For the sake of clarity, the following text refers to tapes only, but
+the Backup System handles backup data files in much the same way.)
+
+If restoring one or more volumes to a single site only, it is usually
+more efficient to use the C<backup volrestore> command. If restoring all
+volumes that resided on a single partition, it is usually more
+efficient to use the C<backup diskrestore> command.
+
+Indicate the volumes to restore by providing either the B<-name> argument
+or the B<-file> argument:
+
+=over
+
+=item *
+
+The B<-name> argument names a volume set. The Backup System restores
+all volumes listed in the Volume Location Database (VLDB) that
+match the server, partition, and volume name criteria defined in
+the volume set's volume entries, and for which dumps are
+available. It restores the volumes to their current site (machine
+and partition), and by default overwrites the existing volume
+contents.
+
+It is not required that the volume set was previously used to back
+up volumes (was used as the B<-volumeset> option to the C<backup dump>
+command). It can be defined especially to match the volumes that
+need to be restored with this command, and that is usually the
+better choice. Indeed, a temporary volume set, created by
+including the B<-temporary> flag to the C<backup addvolset> command, can
+be especially useful in this context. A temporary volume set is
+not added to the Backup Database and exists only during the
+current interactive backup session, which is suitable if the
+volume set is needed only to complete the single restore operation
+initialized by this command.
+
+The reason that a specially defined volume set is probably better
+is that volume sets previously defined for use in dump operations
+usually match the backup version of volumes, whereas for a restore
+operation it is best to define volume entries that match the base
+(read/write) name. In that case, the Backup System searches the
+Backup Database for the newest dump set that includes either the
+read/write or the backup version of the volume. If, in contrast, a
+volume entry explicitly matches the volume's backup or read-only
+version, the Backup System restores dumps of that volume version
+only.
+
+=item *
+
+The B<-file> argument names a file that lists specific volumes and
+the site to which to restore each. The volume name must match the
+name used in Backup Database dump records rather than in the VLDB,
+if they differ, because the Backup System does not look up volumes
+in the VLDB. The specified site can be different than the volume's
+current one; in that case, the Backup System removes the current
+version of the volume and updates the volume's location
+information in the VLDB.
+
+=back
+
+If all of the full and incremental dumps of all relevant volumes were
+not written to a type of tape that a single Tape Coordinator can read,
+use the B<-portoffset> argument to list multiple port offset numbers in
+the order in which the tapes are needed (first list the port offset
+for the full dump, second the port offset for the level 1 incremental
+dump, and so on). This implies that the full dumps of all relevant
+volumes must have been written to a type of tape that the first Tape
+Coordinator can read, the level 1 incremental dumps to a type of tape
+the second Tape Coordinator can read, and so on. If dumps are on
+multiple incompatible tape types, use the C<backup volrestore> command to
+restore individual volumes, or use this command after defining new
+volume sets that group together volumes that were dumped to compatible
+tape types. For further discussion, see the IBM AFS Administration
+Guide.
+
+By default, the Backup System overwrites the contents of an existing
+volume with the restored data. To create a new volume to house the
+restored version instead, use the B<-extension> argument. The Backup
+System derives the new volume's name by adding the specified extension
+to the read/write base name, and creates a new VLDB entry. The command
+does not affect the existing volume in any way. However, if a volume
+with the specified extension also already exists, the command
+overwrites it.
+
+The B<-n> flag produces a list of the volumes to be restored if the B<-n>
+flag were not included, without actually restoring any volumes. See
+the L</"OUTPUT"> section of this reference page for a detailed description
+of the output, and suggestions on how to combine it most effectively
+with the B<-file> and B<-name> arguments.
+
+The execution time for a C<backup volsetrestore> command depends on the
+number of volumes to be restored and the amount of data in them, but
+it can take hours to restore a large number of volumes. One way to
+reduce the time is to run multiple instances of the command
+simultaneously, either using the B<-name> argument to specify disjoint
+volume sets for each command, or the B<-file> argument to name files that
+list different volumes. This is possible if there are multiple
+available Tape Coordinators that can read the required tapes.
+Depending on how the volumes to be restored were dumped to tape,
+specifying disjoint volume sets can also reduce the number of tape
+changes required.
+
+The Tape Coordinator's default response to this command is to access
+the first tape it needs by invoking the B<MOUNT> instruction in the local
+B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
+operator to insert the tape if there is no B<MOUNT> instruction. However,
+if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
+or if the issuer of the B<butc> command included the B<-noautoquery> flag,
+the Tape Coordinator instead expects the tape to be in the device
+already. If it is not, or is the wrong tape, the Tape Coordinator
+invokes the B<MOUNT> instruction or prompts the operator. It also invokes
+the B<MOUNT> instruction or prompts for any additional tapes needed to
+complete the restore operation; the backup operator must arrange to
+provide them.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<volume set name>
+
+Names a volume set to restore. The Backup System restores all
+of the volumes listed in the VLDB that match the volume set's
+volume entries. Provide this argument or the B<-file> argument,
+but not both.
+
+=item B<-file> I<file name>
+
+Specifies the full pathname of a file that lists one or more
+volumes and the site (file server machine and partition) to
+which to restore each. Use either this argument or the B<-name>
+argument, but not both.
+
+Each volume's entry must appear on its own (unbroken) line in
+the file, and have the following format:
+
+    machine  partition
+ volume [comments...]
+
+where
+
+=over
+
+=item B<machine>
+
+Names the file server machine to which to restore the
+volume.
+
+=item B<partition>
+
+Names the partition to which to restore the volume.
+
+=item B<volume>
+
+Names the volume to restore. It is generally best to
+specify the base (read/write) name of each volume. In
+this case, the Backup System searches the Backup Database
+for the newest dump set that includes a dump of either
+the read/write or the backup version of the volume. It
+restores the dumps of that version of the volume,
+starting with the most recent full dump. If, in contrast,
+the name explicitly includes the B<.backup> or B<.readonly>
+extension, the Backup System restores dumps of that
+volume version only.
+
+=item B<comments...>
+
+Is any other text. The Backup System ignores any text on
+each line that appears after the volume name, so this
+field can be used for notes helpful to the backup
+operator or other administrator.
+
+=back
+
+Do not use wildcards (for example, B<.*>) in the I<machine>,
+I<partition>, or I<volume> fields. It is acceptable for multiple
+lines in the file to name the same volume, but the Backup
+System processes only the first of them.
+
+=item B<-extension> I<new volume name extension>
+
+Creates a new volume for each volume specified by the B<-name> or
+B<-file> argument, to house the restored data from that volume.
+The Backup System derives the new volume's name by appending
+the specified string to the read/write base name, and creates a
+new VLDB volume entry. It preserves the contents of each
+existing volume. Any string other than B<.readonly> or B<.backup> is
+acceptable, but the combination of the base name and extension
+cannot exceed 22 characters in length. To use a period to
+separate the extension from the name, specify it as the first
+character of the string (as in B<.rst>, for example).
+
+=item B<-portoffset> I<TC port offset> [I<TC port offset> ...]
+
+Specifies one or more port offset numbers (up to a maximum of
+128), each corresponding to a Tape Coordinator to use in the
+operation. If there is more than one value, the Backup System
+uses the first one when restoring the full dump of each volume,
+the second one when restoring the level 1 incremental dump of
+each volume, and so on. It uses the final value in the list
+when restoring dumps at the corresponding depth in the dump
+hierarchy and all dumps at lower levels.
+
+Provide this argument unless the default value of 0 (zero) is
+appropriate for all dumps. If B<0> is just one of the values in
+the list, provide it explicitly in the appropriate order.
+
+=item B<-n>
+
+Displays a list of the volumes to be restored if the flag were
+not included, without actually restoring them. The L</"OUTPUT">
+section of this reference page details the format of the
+output. When combined with the B<-name> argument, its output is
+easily edited for use as input to the B<-file> argument on a
+subsequent C<backup volsetrestore> command.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the B<-n> flag is not provided, the command displays a unique task ID
+number for the operation, in two places:
+
+=over
+
+=item *
+
+In the shell window, directly following the command line
+
+=item *
+
+In the Tape Coordinator window, if the B<butc> process was started at
+debug level 1
+
+=back
+
+The task ID number is not the same as the job ID number displayed by
+the C<(backup) jobs> command when the C<(backup) volsetrestore> command is
+issued in interactive mode. The Backup System does not assign either
+type of ID number until the restoration process actually begins.
+
+When the B<-n> flag is included, no task ID or job ID numbers are
+reported because none are assigned. Instead, the output begins with a
+count of the number of volumes to be restored, followed by a line for
+each dump of a volume. For each volume, the line representing the most
+recent full dump appears first, and lines for any subsequent
+incremental dumps follow, ordered by dump level. The lines for a given
+volume do not necessarily appear all together, however.
+
+The format of each line is as follows (the output is shown here on two
+lines only for legibility reasons):
+
+   machine partition volume_dumped  # as volume_restored; tape_name (tape_ID);  \
+              pos position_number; date
+
+where
+
+=over
+
+=item B<machine>
+
+Names the file server machine that currently houses the volume,
+as listed in the VLDB.
+
+=item B<partition>
+
+Names the partition that currently houses the volume, as listed
+in the VLDB.
+
+=item B<volume_dumped>
+
+Specifies the version (read/write or backup) of the volume that
+was dumped, as listed in the Backup Database.
+
+=item B<volume_restored>
+
+Specifies the name under which to restore the volume. The
+Backup System only restores data to read/write volumes. If the
+B<-extension> argument is included, then the specified extension
+appears on the name in this field (for example, C<user.pat.rst>).
+
+=item B<tape_name>
+
+Names the tape containing the dump of the volume, from the
+Backup Database. If the tape has a permanent name, it appears
+here; otherwise, it is the AFS tape name.
+
+=item B<tape_ID>
+
+The tape ID of the tape containing the dump of the volume, from
+the Backup Database.
+
+=item B<position_number>
+
+Specifies the dump's position on the tape (for example, C<31>
+indicates that 30 volume dumps precede the current one on the
+tape). If the dump was written to a backup data file, this
+number is the ordinal of the 16 KB-offset at which the volume's
+data begins.
+
+=item B<date>
+
+The date and time when the volume was dumped.
+
+=back
+
+One way to generate a file for use as input to the B<-file> argument is
+to combine the B<-name> and B<-n> options, directing the output to a file.
+The IBM AFS Administration Guide section on using the Backup System to
+restore data explains how to edit the file as necessary before using
+it as input to the B<-file> argument.
+
+The output of this command includes only volumes for which the Backup
+Database includes at least one dump record. The command interpreter
+generates a message on the standard error stream about volumes that do
+not have dump records but either are listed in the file named by the
+B<-file> argument, or appear in the VLDB as a match to a volume entry in
+the volume set named by the B<-name> argument.
+
+=head1 EXAMPLES
+
+The following command restores all volumes included in entries in the
+volume set named B<data.restore>, which was created expressly to restore
+data to a pair of file server machines on which all data was corrupted
+due to a software error. All volumes are restored to the sites
+recorded in their entries in the VLDB.
+
+    backup volsetrestore -name data.restore
+   Starting restore
+   backup: task ID of restore operation: 112
+   backup: Finished doing restore
+
+The following command restores all volumes that have entries in the
+file named B</tmp/restore>:
+
+    backup volsetrestore -file B</tmp/restore>
+   Starting restore
+   backup: task ID of restore operation: 113
+   backup: Finished doing restore
+
+The B</tmp/restore> file has the following contents:
+
+   fs1.abc.com b user.pat
+   fs1.abc.com b user.terry
+   fs1.abc.com b user.smith
+   fs2.abc.com c user.jones
+        .      .     .
+        .      .     .
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is
+running, and on every file server machine that houses an affected
+volume. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser B<root>.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_diskrestore(1)>,
+L<backup_dump(1)>,
+L<backup_volrestore(1)>,
+L<butc(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos.pod b/doc/man-pages/pod/bos.pod
new file mode 100644 (file)
index 0000000..c34c8a3
--- /dev/null
@@ -0,0 +1,299 @@
+=head1 NAME
+
+bos - Introduction to the C<bos> command suite
+
+=head1 DESCRIPTION
+
+The commands in the C<bos> command suite are the administrative interface
+to the Basic OverSeer (BOS) Server, which runs on every file server
+machine to monitor the other server processes on it. If a process
+fails, the BOS Server can restart it automatically, taking into
+account interdependencies between it and other processes. The BOS
+Server frees system administrators from constantly monitoring the
+status of server machines and processes.
+
+There are several categories of commands in the C<bos> command suite:
+
+=over
+
+=item *
+
+Commands to administer server process binary files: C<bos getdate>,
+C<bos install>, C<bos prune>, and C<bos uninstall>
+
+=item *
+
+Commands to maintain system configuration files: C<bos addhost>, C<bos
+addkey>, C<bos adduser>, C<bos listhosts>, C<bos listkeys>, C<bos listusers>,
+C<bos removehost>, C<bos removekey>, C<bos removeuser>, and C<bos setcellname>
+
+=item *
+
+Commands to start and stop processes: C<bos create>, C<bos delete>, C<bos
+restart>, C<bos shutdown>, C<bos start>, C<bos startup>, and C<bos stop>
+
+=item *
+
+Commands to set and verify server process and server machine
+status: C<bos getlog>, C<bos getrestart>, C<bos setauth>, C<bos setrestart>,
+and C<bos status>
+
+=item *
+
+A command to restore file system consistency: C<bos salvage>
+
+=item *
+
+Commands to obtain help: C<bos apropos> and C<bos help>
+
+=back
+
+The BOS Server and the C<bos> commands use and maintain the following
+configuration and log files:
+
+=over
+
+=item *
+
+The B</usr/afs/etc/CellServDB> file lists the local cell's database
+server machines. These machines run the Authentication, Backup,
+Protection and Volume Location (VL) Server processes, which
+maintain databases of administrative information. The database
+server processes consult the file to learn about their peers,
+whereas the other server processes consult it to learn where to
+access database information as needed. To administer the
+B<CellServDB> file, use the following commands: C<bos addhost>, C<bos
+listhosts>, C<bos removehost>, and C<bos setcellname>.
+
+=item *
+
+The B</usr/afs/etc/KeyFile> file lists the server encryption keys
+that the server processes use to decrypt tickets presented by
+client processes and one another. To administer the KeyFile file,
+use the following commands: C<bos addkey>, C<bos listkeys>, and C<bos
+removekey>.
+
+=item *
+
+The B</usr/afs/etc/ThisCell> file defines the cell to which the
+server machine belongs for the purposes of server-to-server
+communication. Administer it with the C<bos setcellname> command.
+There is also a B</usr/vice/etc/ThisCell> file that defines the
+machine's cell membership with respect to the AFS command suites
+and Cache Manager access to AFS data.
+
+=item *
+
+The B</usr/afs/etc/UserList> file lists the user name of each
+administrator authorized to issue privileged C<bos> and C<vos> commands.
+To administer the UserList file, use the following commands: C<bos
+adduser>, C<bos listusers>, and C<bos removeuser>.
+
+=item *
+
+The B</usr/afs/local/BosConfig> file defines which AFS server
+processes run on the server machine, and whether the BOS Server
+restarts them automatically if they fail. It also defines when all
+processes restart automatically (by default once per week), and
+when the BOS Server restarts processes that have new binary files
+(by default once per day). To administer the BosConfig file, use
+the following commands: C<bos create>, C<bos delete>, C<bos getrestart>,
+C<bos setrestart>, C<bos start>, and C<bos stop>.
+
+=item *
+
+The B</usr/afs/log/BosLog> file records important operations the BOS
+Server performs and error conditions it encounters.
+
+=back
+
+For more details, see the reference page for each file.
+
+=head1 OPTIONS
+
+The following arguments and flags are available on many commands in
+the C<bos> suite. The reference page for each command also lists them,
+but they are described here in greater detail.
+
+=over 4
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. It is acceptable to
+abbreviate the cell name to the shortest form that
+distinguishes it from the other entries in the
+B</usr/vice/etc/CellServDB> file on the local machine. If the
+B<-cell> argument is omitted, the command interpreter determines
+the name of the local cell by reading the following in order:
+
+=over
+
+=item 1.
+
+The value of the AFSCELL environment variable
+
+=item 2.
+
+The local B</usr/vice/etc/ThisCell> file
+
+=back
+
+Do not combine the B<-cell> and B<-localauth> options. A command on
+which the B<-localauth> flag is included always runs in the local
+cell (as defined in the server machine's local
+B</usr/afs/etc/ThisCell> file), whereas a command on which the
+B<-cell> argument is included runs in the specified foreign cell.
+
+=item B<-help>
+
+Prints a command's online help message on the standard output
+stream. Do not combine this flag with any of the command's
+other options; when it is provided, the command interpreter
+ignores all other options, and only prints the help message.
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with
+the highest key version number in the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket, which never expires, to the BOS Server during
+mutual authentication.
+
+Use this flag only when issuing a command on a server machine;
+client machines do not usually have a B</usr/afs/etc/KeyFile>
+file. The issuer of a command that includes this flag must be
+logged on to the server machine as the local superuser B<root>.
+The flag is useful for commands invoked by an unattended
+application program, such as a process controlled by the UNIX
+B<cron> utility or by a cron entry in the machine's
+B</usr/afs/local/BosConfig> file. It is also useful if an
+administrator is unable to authenticate to AFS but is logged in
+as the local superuser B<root>.
+
+Do not combine the B<-cell> and B<-localauth> options. A command on
+which the B<-localauth> flag is included always runs in the local
+cell (as defined in the server machine's local
+B</usr/afs/etc/ThisCell> file), whereas a command on which the
+B<-cell> argument is included runs in the specified foreign cell.
+Also, do not combine the B<-localauth> and B<-noauth> flags.
+
+=item B<-noauth>
+
+Establishes an unauthenticated connection to the BOS Server, in
+which the BOS Server treats the issuer as the unprivileged user
+B<anonymous>. It is useful only when authorization checking is
+disabled on the server machine (during the installation of a
+file server machine or when the C<bos setauth> command has been
+used during other unusual circumstances). In normal
+circumstances, the BOS Server allows only privileged users to
+issue commands that change the status of a server or
+configuration file, and refuses to perform such an action even
+if the B<-noauth> flag is provided. Do not combine the B<-noauth> and
+B<-localauth> flags.
+
+=item B<-server> I<machine name> 
+
+Indicates the AFS server machine on which to run the command.
+Identify the machine by its IP address in dotted decimal
+format, its fully-qualified host name (for example,
+B<fs1.abc.com>), or by an abbreviated form of its host name that
+distinguishes it from other machines. Successful use of an
+abbreviated form depends on the availability of a name service
+(such as the Domain Name Service or a local host table) at the
+time the command is issued.
+
+For the commands that alter the administrative files shared by
+all server machines in the cell (the C<bos addhost>, C<bos addkey>,
+C<bos adduser>, C<bos removehost>, C<bos removekey>, and C<bos removeuser>
+commands), the appropriate machine depends on whether the cell
+uses the United States or international version of AFS:
+
+=over
+
+=item *
+
+If the cell runs the United States edition of AFS and (as
+recommended) uses the Update Server to distribute the
+contents of the B</usr/afs/etc> directory, provide the name of
+the system control machine. After issuing the command, allow
+up to five minutes for the Update Server to distribute the
+changed file to the other AFS server machines in the cell. If
+the specified machine is not the system control machine but
+is running an B<upclientetc> process that refers to the system
+control machine, then the change will be overwritten when the
+process next brings over the relevant file from the system
+control machine.
+
+=item *
+
+If the cell runs the international edition of AFS, do not use
+the Update Server to distribute the contents of the
+B</usr/afs/etc> directory. Instead, repeatedly issue the
+command, naming each of the cell's server machines in turn.
+To avoid possible inconsistency problems, finish issuing the
+commands within a fairly short time.
+
+=back
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue any C<bos> command that changes a configuration file or alters
+process status, the issuer must be listed in the B</usr/afs/etc/UserList>
+file on the server machine named by the B<-server> argument.
+Alternatively, if the B<-localauth> flag is included the issuer must be
+logged on as the local superuser B<root>.
+
+To issue a C<bos> command that only displays information (other than the
+C<bos listkeys> command), no privilege is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<CellServDB_client_version(1)>,
+L<CellServDB_server_version(1)>,
+L<KeyFile(1)>,
+L<ThisCell_client_version(1)>,
+L<ThisCell_server_version(1)>,
+L<UserList(1)>,
+L<bos_addhost(1)>,
+L<bos_addkey(1)>,
+L<bos_adduser(1)>,
+L<bos_apropos(1)>,
+L<bos_create(1)>,
+L<bos_delete(1)>,
+L<bos_exec(1)>,
+L<bos_getdate(1)>,
+L<bos_getlog(1)>,
+L<bos_getrestart(1)>,
+L<bos_help(1)>,
+L<bos_install(1)>,
+L<bos_listhosts(1)>,
+L<bos_listkeys(1)>,
+L<bos_listusers(1)>,
+L<bos_prune(1)>,
+L<bos_removehost(1)>,
+L<bos_removekey(1)>,
+L<bos_removeuser(1)>,
+L<bos_restart(1)>,
+L<bos_salvage(1)>,
+L<bos_setauth(1)>,
+L<bos_setcellname(1)>,
+L<bos_setrestart(1)>,
+L<bos_shutdown(1)>,
+L<bos_start(1)>,
+L<bos_startup(1)>,
+L<bos_status(1)>,
+L<bos_stop(1)>,
+L<bos_uninstall(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_addhost.pod b/doc/man-pages/pod/bos_addhost.pod
new file mode 100644 (file)
index 0000000..0118873
--- /dev/null
@@ -0,0 +1,124 @@
+=head1 NAME
+
+bos addhost - Adds a database server machine to the B</usr/afs/etc/CellServDB> file
+
+=head1 SYNOPSIS
+
+bos addhost B<-server> I<machine name>  B<-host> I<host name> [I<host name> ...]
+[B<-cell> I<cell name>]  [B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos addh B<-s> I<machine name>  B<-ho> I<host name> [I<host name> ...]
+[B<-c> I<cell name>]  [B<-n>]  [B<-l>]  [B<-he>]
+
+=head1 DESCRIPTION
+
+The C<bos addhost> command adds an entry for each database server machine
+specified with the B<-host> argument to the B</usr/afs/etc/CellServDB> file
+on the machine named by the B<-server> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Identifies the server machine on which to change the
+B</usr/afs/etc/CellServDB> file. Identify the machine by IP
+address or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-host> I<host name> [I<host name> ...]
+
+Specifies the fully-qualified host name (such as B<db1.abc.com>)
+of each database server machine to register in the B<CellServDB>
+file.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command adds the database server machines B<db2.abc.com>
+and B<db3.abc.com> to the B</usr/afs/etc/CellServDB> file on the machine
+B<fs1.abc.com> (the system control machine).
+
+    bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+After executing this command (and waiting for the Update Server to
+propagate the changes, if it is used), restart the database server
+processes on all database server machines to force election of a
+quorum that includes the new set of machines listed in the
+B</usr/afs/etc/CellServDB> file. The IBM AFS Quick Beginnings explains in
+more detail how to add and remove database server machines.
+
+It is best to maintain a one-to-one mapping between hostnames and IP
+addresses on a multihomed database server machine (this is actually
+the conventional configuration for any AFS machine). The BOS Server
+uses the B<gethostbyname( )> routine to obtain the IP address associated
+with the hostname specified by the -host argument. If there is more
+than one address, the BOS Server records in the B<CellServDB> entry the
+one that appears first in the list of addresses returned by the
+routine. The routine possibly returns addresses in a different order
+on different machines, which can create inconsistency.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_server_version(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_listhosts(1)>,
+L<bos_removehost(1)>,
+IBM AFS Quick Beginnings
+
+=cut
diff --git a/doc/man-pages/pod/bos_addkey.pod b/doc/man-pages/pod/bos_addkey.pod
new file mode 100644 (file)
index 0000000..2787f09
--- /dev/null
@@ -0,0 +1,141 @@
+=head1 NAME
+
+bos addkey - Adds a new server encryption key to the B</usr/afs/etc/KeyFile> file
+
+=head1 SYNOPSIS
+
+bos addkey B<-server> I<machine name>  [B<-key> I<key>]
+B<-kvno> I<key version number>  [B<-cell> I<cell name>]
+[B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos addk B<-s> I<machine name>  [B<-ke> I<key>]  B<-kv> I<key version number>
+[B<-ce> I<cell name>]  [B<-n>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos addkey> command constructs a server encryption key from the
+text string provided, assigns it the key version number specified with
+the B<-kvno> argument, and adds it to the B</usr/afs/etc/KeyFile> file on
+the machine specified with the B<-server> argument. Be sure to use the
+C<kas setpassword> or C<kas setkey> command to add the same key to the B<afs>
+entry in the Authentication Database.
+
+Do not use the B<-key> argument, which echoes the password string visibly
+on the screen. If the argument is omitted, the BOS Server prompts for
+the string and does not echo it visibly:
+
+   Input key:
+   Retype input key:
+
+The BOS Server prohibits reuse of any key version number already
+listed in the B</usr/afs/etc/KeyFile> file. This ensures that users who
+still have tickets sealed with the current key are not prevented from
+communicating with a server process because the current key is
+overwritten with a new key. Use the C<bos listkeys> command to display
+the key version numbers in the B</usr/afs/etc/KeyFile> file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/KeyFile> file. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-key> I<key>
+
+Specifies a character string just like a password; the BOS
+Server calls a DES conversion function to encode it into a form
+appropriate for use as an encryption key. Omit this argument to
+have the BOS Server prompt for the string instead.
+
+=item B<-kvno> I<key version number>
+
+Defines the new key's key version number. It must be an integer
+in the range from B<0> (zero) through B<255>. For the sake of
+simplicity, use the number one higher than the current highest
+key version number; use the C<bos listkeys> command to display key
+version numbers.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the strings typed at the C<Input key> and C<Retype input key> prompts do
+not match, the following message appears, and the command exits
+without adding a new key:
+
+   Input key mismatch
+
+=head1 EXAMPLES
+
+The following command adds a new server encryption key with key
+version number 14 to the B<KeyFile> file kept on the machine B<fs1.abc.com>
+(the system control machine). The issuer omits the B<-key> argument, as
+recommended, and provides the password at the prompts.
+
+    bos addkey -server fs1.abc.com -kvno 14
+   Input key:
+   Retype input key:
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_listkeys(1)>,
+L<bos_removekey(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_adduser.pod b/doc/man-pages/pod/bos_adduser.pod
new file mode 100644 (file)
index 0000000..69acd1e
--- /dev/null
@@ -0,0 +1,104 @@
+=head1 NAME
+
+bos adduser - Adds a privileged user to the B</usr/afs/etc/UserList> file
+
+=head1 SYNOPSIS
+
+bos adduser B<-server> I<machine name>  B<-user> I<user names> [I<user names> ...]
+[B<-cell> I<cell name>]  [B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos addu B<-s> I<machine name>  B<-u> I<user names> [I<user names> ...]
+[B<-c> I<cell name>]  [B<-n>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos adduser> command adds each user name specified with the B<-user>
+argument to the B</usr/afs/etc/UserList> file on the machine named by the
+B<-server> argument. It is the issuer's responsibility to verify that an
+entry for the user exists in the Authentication and Protection
+Databases.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/UserList> file. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-user> I<user names> [I<user names> ...]
+
+Specifies each user name to insert into the
+B</usr/afs/etc/UserList> file.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command adds the user names pat and smith to the
+B</usr/afs/etc/UserList> file on the machine B<fs1.abc.com> (the system
+control machine).
+
+    bos adduser -server fs1.abc.com -user pat smith
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_listusers(1)>,
+L<bos_removeuser(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_apropos.pod b/doc/man-pages/pod/bos_apropos.pod
new file mode 100644 (file)
index 0000000..df4f3c2
--- /dev/null
@@ -0,0 +1,70 @@
+=head1 NAME
+
+bos apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+bos apropos B<-topic> I<help string>  [B<-help>]
+
+bos ap B<-t> I<help string>  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos apropos> command displays the first line of the online help
+entry for any C<bos> command that has in its name or short description
+the string specified by the B<-topic> argument.
+
+To display the syntax for a command, use the C<bos help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> I<help string>
+
+Specifies the keyword string to match, in lowercase letters
+only. If the string is more than a single word, surround it
+with double quotes ("") or other delimiters.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of a command's online help entry names it and briefly
+describes its function. This command displays the first line for any
+C<bos> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all C<bos> commands that include the word
+B<restart> in their names or short descriptions:
+
+    bos apropos restart
+   getrestart: get restart times
+   restart: restart all processes
+   setrestart: set restart times
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos(1)>,
+L<bos_help(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_create.pod b/doc/man-pages/pod/bos_create.pod
new file mode 100644 (file)
index 0000000..3107fea
--- /dev/null
@@ -0,0 +1,410 @@
+=head1 NAME
+
+bos create - Defines a new process in the B</usr/afs/local/BosConfig> file and starts
+it running
+
+=head1 SYNOPSIS
+
+bos create B<-server> I<machine name>  B<-instance> I<server process name>
+B<-type> I<server type>  B<-cmd> I<command lines> [I<command lines> ...]
+[B<-notifier> I<Notifier program>]  [B<-cell> I<cell name>]
+[B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos c B<-s> I<machine name>  B<-i> I<server process name>  B<-t> I<server type>
+B<-cm> I<command lines> [I<command lines> ...]  [B<-not> I<Notifier program>]  [B<-ce> I<cell name>]
+[B<-noa>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos create> command creates a server process entry in the
+B</usr/afs/local/BosConfig> file on the server machine named by the
+B<-server> argument, sets the process's status to B<Run> in the B<BosConfig>
+file and in memory, and starts the process.
+
+A server process's entry in the B<BosConfig> file defines its name, its
+type, the command that initializes it, and optionally, the name of a
+notifier program that runs when the process terminates.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to define and start the
+new process. Identify the machine by IP address or its host
+name (either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-instance> I<server process name>
+
+Names the process to define and start. Any name is acceptable,
+but for the sake of simplicity it is best to use the last
+element of the process's binary file pathname, and to use the
+same name on every server machine. The conventional names, as
+used in all AFS documentation, are:
+
+=over
+
+=item B<buserver>
+
+The Backup Server process
+
+=item B<fs>
+
+The process that combines the File Server, Volume Server,
+and Salvager processes (B<fileserver>, B<volserver>, and
+B<salvager>)
+
+=item B<kaserver>
+
+The Authentication Server process
+
+=item B<ptserver>
+
+The Protection Server process
+
+=item B<runntp>
+
+The controller process for the Network Time Protocol
+Daemon
+
+=item B<upclientbin>
+
+The client portion of the Update Server process that
+retrieves binary files from the B</usr/afs/bin> directory of
+the binary distribution machine for this machine's
+CPU/operating system type. (The name of the binary is
+B<upclient>, but the B<bin> suffix distinguishes this process
+from B<upclientetc>.)
+
+=item B<upclientetc>
+
+The client portion of the Update Server process that
+retrieves configuration files from the B</usr/afs/etc>
+directory of the system control machine. Do not run this
+process in cells that use the international edition of
+AFS. (The name of the binary is B<upclient>, but the B<etc>
+suffix distinguishes this process from B<upclientbin>.)
+
+=item B<upserver>
+
+The server portion of the Update Server process
+
+=item B<vlserver>
+
+The Volume Location (VL) Server process
+
+=back
+
+=item B<-type> I<server type>
+
+Specifies the process's type. The acceptable values are:
+
+=over
+
+=item B<cron>
+
+Use this value for cron-type processes that the BOS
+Server starts only at a defined daily or weekly time,
+rather than whenever it detects that the process has
+terminated. AFS does not define any such processes by
+default, but makes this value available for administrator
+use. Define the time for command execution as part of the
+B<-cmd> argument to the C<bos create> command.
+
+=item B<fs>
+
+Use this value only for the B<fs> process, which combines
+the File Server, Volume Server and Salvager processes. If
+one of the component processes terminates, the BOS Server
+shuts down and restarts the processes in the appropriate
+order.
+
+=item B<simple>
+
+Use this value for all processes listed as acceptable
+values to the B<-instance> argument, except for the B<fs>
+process. There are no interdependencies between simple
+processes, so the BOS Server can stop and start them
+independently as necessary.
+
+=back
+
+=item B<-cmd> I<command lines> [I<command lines> ...]
+
+Specifies each command the BOS Server runs to start the
+process. Specify no more than six commands (which can include
+the command's options, in which case the entire string is
+surrounded by double quotes); any additional commands are
+ignored.
+
+For a simple process, provide the complete pathname of the
+process's binary file on the local disk (for example,
+B</usr/afs/bin/ptserver> for the Protection Server). If including
+any of the initialization command's options, surround the
+entire command in double quotes (" "). The B<upclient> process has
+a required argument, and the commands for all other processes
+take optional arguments.
+
+For the B<fs> process, provide the complete pathname of the local
+disk binary file for each of the component processes:
+B<fileserver>, B<volserver>, and B<salvager>, in that order. The
+standard binary directory is B</usr/afs/bin>. If including any of
+an initialization command's options, surround the entire
+command in double quotes (B<" ">).
+
+For a B<cron> process, provide two parameters:
+
+=over
+
+=item *
+
+The complete local disk pathname of either an executable file
+or a command from one of the AFS suites (complete with all of
+the necessary arguments). Surround this parameter with double
+quotes (B<" ">) if it contains spaces.
+
+=item *
+
+A specification of when the BOS Server executes the file or
+command indicated by the first parameter. There are three
+acceptable values:
+
+=over
+
+=item *
+
+The string C<now>, which directs the BOS Server to execute
+the file or command immediately and only once. It is
+usually simpler to issue the command directly or issue
+the C<bos exec> command.
+
+=item *
+
+A time of day. The BOS Server executes the file or
+command daily at the indicated time. Separate the hours
+and minutes with a colon (I<hh>:I<MM>), and use either 24-hour
+format, or a value in the range from B<1:00> through B<12:59>
+with the addition of B<am> or B<pm>. For example, both B<14:30>
+and B<"2:30 pm"> indicate 2:30 in the afternoon. Surround
+this parameter with double quotes (B<" ">) if it contains a
+space.
+
+=item *
+
+A day of the week and time of day, separated by a space
+and surrounded with double quotes (B<" ">). The BOS Server
+executes the file or command weekly at the indicated day
+and time. For the day, provide either the whole name or
+the first three letters, all in lowercase letters
+(B<sunday> or B<sun>, B<thursday> or B<thu>, and so on). For the
+time, use the same format as when specifying the time
+alone.
+
+=back
+
+=back
+
+=item B<-notifier> I<Notifier program>
+
+Specifies the complete pathname on the local disk of a program
+that the BOS Server invokes when the process terminates. The
+AFS distribution does not include any notifier programs, but
+this argument is available for administrator use. See the
+L</"Related Information"> section.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command defines and starts the simple process kaserver
+on the machine B<fs3.abc.com>:
+
+ bos create -server fs3.abc.com -instance kaserver -type simple  \
+            -cmd /usr/afs/bin/kaserver
+
+The following command defines and starts the simple process
+B<upclientbin> on the machine B<fs4.abc.com>. It references B<fs1.abc.com> as
+the source for updates to binary files, checking for changes to the
+B</usr/afs/bin> directory every 120 seconds.
+
+ bos create -server fs4.abc.com -instance upclientbin -type simple  \
+            -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120  \
+            /usr/afs/bin"
+
+The following command creates the fs process B<fs> on the machine
+B<fs4.abc.com>. Type the command on a single line.
+
+ bos create -server fs4.abc.com -instance fs -type fs  \
+            -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver  \
+            /usr/afs/bin/salvager
+
+The following command creates a B<cron> process called B<userbackup> on the
+machine B<fs5.abc.com>, so that the BOS Server issues the indicated C<vos
+backupsys> command each day at 3:00 a.m. (the command creates a backup
+version of every volume in the file system whose name begins with
+B<user>). Note that the issuer provides the complete pathname to the C<vos>
+command, includes the B<-localauth> flag on it, and types the entire C<bos
+create> command on one line.
+
+ bos create -server fs5.abc.com -instance userbackup -type cron  \
+            -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 Related Information
+
+If the B<-notifier> argument is included when this command is used to
+define and start a process, the BOS Server invokes the indicated
+I<notifier program> when the process exits. The intended use of a
+notifier program is to inform administrators when a process exits
+unexpectedly, but it can be used to perform any appropriate actions.
+The following paragraphs describe the B<bnode> and B<bnode_proc> structures
+in which the BOS Server records information about the exiting process.
+The list of AFS commands related to this one follows.
+
+The BOS Server constructs and sends on the standard output stream one
+B<bnode> and one B<bnode_proc> structure for each exiting process associated
+with the notifier program. It brackets each structure with appropriate
+C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN bnode_proc>
+and C<END bnode_proc>), which immediately follow the preceding newline
+character with no intervening spaces or other characters. If the
+notifier program does not need information from a structure, it can
+scan ahead in the input stream for the C<END> statement.
+
+In general, each field in a structure is a string of ASCII text
+terminated by the newline character. The format of the information
+within a structure possibly varies slightly depending on the type of
+process associated with the notifier program.
+
+The C code for the B<bnode> and B<bnode_proc> structures follows. Note that
+the structures sent by the BOS Server do not necessarily include all
+of the fields described here, because some are used only for internal
+record keeping. The notifier process must robustly handle the absence
+of expected fields, as well as the presence of unexpected fields, on
+the standard input stream.
+
+For proper performance, the notifier program must continue processing
+the input stream until it detects the end-of-file (EOF). The BOS
+Server closes the standard input file descriptor to the notifier
+process when it has completed delivery of the data, and it is the
+responsibility of the notifier process to terminate properly.
+
+=head2 struct bnode contents
+
+ struct bnode {
+   struct bnode *next;      /* next pointer in top-level's list */
+   char *name;              /* instance name */
+   long nextTimeout;        /* next time this guy should be awakened */
+   long period;             /* period between calls */
+   long rsTime;             /* time we started counting restarts */
+   long rsCount;            /* count of restarts since rsTime */
+   struct bnode_type *type; /* type object */
+   struct bnode_ops *ops;   /* functions implementing bnode class */
+   long procStartTime;      /* last time a process was started */
+   long procStarts;         /* number of process starts */
+   long lastAnyExit;        /* last time a process exited for any reason */
+   long lastErrorExit;      /* last time a process exited unexpectedly */
+   long errorCode;          /* last exit return code */
+   long errorSignal;        /* last proc terminating signal */
+   char *lastErrorName;     /* name of proc that failed last */
+   short refCount;          /* reference count */
+   short flags;             /* random flags */
+   char goal;               /* 1=running or 0=not running */
+   char fileGoal;           /* same, but to be stored in file */
+ };
+
+=head2 format of struct bnode explosion
+
+  printf("name: %s\n",tp->name);
+  printf("rsTime: %ld\n", tp->rsTime);
+  printf("rsCount: %ld\n", tp->rsCount);
+  printf("procStartTime: %ld\n", tp->procStartTime);
+  printf("procStarts: %ld\n", tp->procStarts);
+  printf("lastAnyExit: %ld\n", tp->lastAnyExit);
+  printf("lastErrorExit: %ld\n", tp->lastErrorExit);
+  printf("errorCode: %ld\n", tp->errorCode);
+  printf("errorSignal: %ld\n", tp->errorSignal);
+  printf("lastErrorName: %s\n", tp->lastErrorName);
+  printf("goal: %d\n", tp->goal);
+
+=head2 struct bnode_proc contents
+
+ struct bnode_proc {
+   struct bnode_proc *next; /* next guy in top-level's list */
+   struct bnode *bnode;     /* bnode creating this process */
+   char *comLine;           /* command line used to start this process */
+   char *coreName;          /* optional core file component name */
+   long pid;                /* pid if created */
+   long lastExit;           /* last termination code */
+   long lastSignal;         /* last signal that killed this guy */
+   long flags;              /* flags giving process state */
+ };
+
+=head2 format of struct bnode_proc explosion
+
+  printf("comLine: %s\n", tp->comLine);
+  printf("coreName: %s\n", tp->coreName);
+  printf("pid: %ld\n", tp->pid);
+  printf("lastExit: %ld\n", tp->lastExit);
+  printf("lastSignal: %ld\n", tp->lastSignal);
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<buserver(1)>,
+L<fileserver(1)>,
+L<kaserver(1)>,
+L<ptserver(1)>,
+L<runntp(1)>,
+L<salvager(1)>,
+L<upclient(1)>,
+L<upserver(1)>,
+L<vlserver(1)>,
+L<volserver(1)>,
+L<vos_backupsys(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_delete.pod b/doc/man-pages/pod/bos_delete.pod
new file mode 100644 (file)
index 0000000..684287e
--- /dev/null
@@ -0,0 +1,101 @@
+=head1 NAME
+
+bos delete - Deletes a server process from the B</usr/afs/local/BosConfig> file
+
+=head1 SYNOPSIS
+
+bos delete B<-server> I<machine name>  B<-instance> I<server process name> [I<server process name> ...]
+[B<-cell> I<cell name>]  [B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos d B<-s> I<machine name>  B<-i> I<server process name> [I<server process name> ...]  [B<-c> I<cell name>]
+[B<-n>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos delete> command removes the B</usr/afs/local/BosConfig> entry for
+each process indicated by the B<-instance> argument, on the server
+machine named by the B<-server> argument.
+
+Before issuing this command, issue the C<bos stop> command to stop the
+process and set its status flag in the B<BosConfig> file to C<NotRun>. The
+C<bos delete> command fails with an error message if a process's status
+flag is C<Run>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to delete the server
+process entry from the B</usr/afs/local/BosConfig> file. Identify
+the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<server process name> [I<server process name> ...]
+
+Names each process to delete. Use the name assigned with the
+B<-instance> argument to the C<bos create> command; process names
+appear in the output of the C<bos status> command.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the B<buserver>, B<kaserver>, B<ptserver>, and
+B<vlserver> entries from the B<BosConfig> file on B<db3.abc.com>, a database
+server machine being decommissioned.
+
+  bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_status(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_exec.pod b/doc/man-pages/pod/bos_exec.pod
new file mode 100644 (file)
index 0000000..1f1210d
--- /dev/null
@@ -0,0 +1,90 @@
+=head1 NAME
+
+bos exec - Executes a command on a remote server machine
+
+=head1 SYNOPSIS
+
+bos exec B<-server> I<machine name>  B<-cmd> I<command to execute>
+[B<-cell> I<cell name>]  [B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos e B<-s> I<machine name>  B<-cm> I<command to execute>  [B<-ce> I<cell name>]
+[B<-n>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos exec> command executes the indicated command on the file server
+machine named by the B<-server> argument. Its intended use is to reboot
+the machine, using the B</etc/reboot> command or equivalent.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to execute the command.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-cmd> I<command to execute>
+
+Specifies the complete local disk pathname of the command to
+execute (for example, B</etc/reboot>). Surround this argument with
+double quotes ("") if the command contains one or more spaces.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command reboots the machine B<fs2.abc.com>. The issuer has
+previously issued the C<bos shutdown> command to shutdown all processes
+cleanly.
+
+   bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_getdate.pod b/doc/man-pages/pod/bos_getdate.pod
new file mode 100644 (file)
index 0000000..ed67b62
--- /dev/null
@@ -0,0 +1,119 @@
+=head1 NAME
+
+bos getdate - Displays the time stamps on an AFS binary file
+
+=head1 SYNOPSIS
+
+bos getdate B<-server> I<machine name>  B<-file> I<files to check> [I<files to check> ...]
+[B<-dir> I<destination dir>]  [B<-cell> I<cell name>]
+[B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos getd B<-s> I<machine name>  B<-f> I<files to check> [I<files to check> ...]  [B<-d> I<destination dir>]
+[B<-c> I<cell name>]  [B<-n>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos getdate> command displays the time stamps on the current
+version, C<.BAK> version (if any) and C<.OLD> version (if any) of each
+binary file named by the B<-file> argument. (The BOS Server automatically
+creates C<.BAK> and C<.OLD> versions when new binaries are installed with
+the C<bos install> command.) The files must reside in the B</usr/afs/bin>
+directory on the server machine named by the B<-server> argument unless
+the B<-dir> argument indicates an alternate directory.
+
+To revert to the C<.BAK> version of a binary, use the C<bos uninstall>
+command. To remove obsolete binary files from the B</usr/afs/bin>
+directory, use the C<bos prune> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to list binary files.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+All server machines of the same AFS system type show the same
+timestamps if the binaries were installed properly on the
+binary distribution machine for this machine's system type, and
+if all other machines of that type are running the appropriate
+B<upclientbin> process.
+
+=item B<-file> I<files to check> [I<files to check> ...]
+
+Names each binary file to list.
+
+=item B<-dir> I<destination dir>
+
+Specifies the complete pathname of the local disk directory
+containing each file named by the B<-file> argument. It is
+necessary only if the files are not in the B</usr/afs/bin>
+directory.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+For each file specified with the B<-file> argument, the output displays
+the time stamp on the current (unmarked), C<.BAK>, and C<.OLD> version. The
+output explicitly reports that a version does not exist, rather than
+simply omitting it.
+
+=head1 EXAMPLES
+
+The following command examines the time stamps on the files with
+basename B<kaserver> on the machine B<fs2.abc.com>:
+
+    bos getdate -server fs2.abc.com -file kaserver
+   File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999.
+   .BAK file dated Wed Dec 9 18:55:04 1998, no .OLD file.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<bos(1)>,
+L<bos_install(1)>,
+L<bos_prune(1)>,
+L<bos_uninstall(1)>
+
+=cut
diff --git a/doc/man-pages/pod/bos_getlog.pod b/doc/man-pages/pod/bos_getlog.pod
new file mode 100644 (file)
index 0000000..6d3a97b
--- /dev/null
@@ -0,0 +1,154 @@
+=head1 NAME
+
+bos getlog - Prints a server process's log file
+
+=head1 SYNOPSIS
+
+bos getlog B<-server> I<machine name>  B<-file> I<log file to examine>
+[B<-cell> I<cell name>]  [B<-noauth>]  [B<-localauth>]  [B<-help>]
+
+bos getl B<-s> I<machine name>  B<-f> I<log file to examine>  [B<-c> I<cell name>]
+[B<-n>]  [B<-l>]  [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos getlog> command displays on the standard output stream the
+specified log file from the machine named by the B<-server> argument. The
+BOS Server fetches the log file from the B</usr/afs/logs> directory
+unless an alternate pathname is provided as part of the B<-file>
+argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to retrieve the log
+file. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-file> I<log file to examine>
+
+Names the log file to display. If a filename only is provided,
+the BOS Server fetches the log file from the B</usr/afs/logs>
+directory; the standard values are:
+
+=over
+
+=item B<AuthLog>
+
+The Authentication Server (B<kaserver>) log file
+
+=item B<BackupLog>
+
+The Backup Server (B<buserver>) log file
+
+=item B<BosLog>
+