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
+all:
-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
+maintclean:
+ rm -f *.1 *.5 *.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 \
+dest:
+ mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8
+ set -e; for M in *.1 ; do \
$(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \
done
- -set -e; for M in $(MAN8) ; do \
+ set -e; for M in *.5 ; do \
+ $(INSTALL) -c -m 0644 $$M $(DEST)/man/man5/$$M ; \
+ done
+ set -e; for M in *.8 ; 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 \
+ mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man5 \
+ $(DESTDIR)$(mandir)/man8
+ set -e; for M in *.1 ; do \
$(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \
done
- -set -e; for M in $(MAN8) ; do \
+ set -e; for M in *.5 ; do \
+ $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man5/$$M ; \
+ done
+ set -e; for M in *.8 ; do \
$(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \
done
--- /dev/null
+#!/usr/bin/perl
+#
+# From an AFS Administrative Reference HTML page, try to figure out what
+# command or file it corresponds to and output the appropriate generate-pod
+# command. Intended to be run as follows:
+#
+# generate-file-map *.htm > generate-pods.sh
+#
+# Each line of the output will be a generate-pod invocation, saving its output
+# to the appropriate POD file.
+
+my %except = map { $_ => 1 }
+ ('Table of Contents', 'Audience and Purpose', 'Organization',
+ 'How to Use This Document', 'Related Documents',
+ 'Typographical Conventions');
+
+for my $file (@ARGV) {
+ my $command;
+ open (IN, '<', $file) or die "$0: cannot open $file: $!\n";
+ while (<IN>) {
+ s/<I>//g;
+ s%</I>%%g;
+ if (/<H2><A [^>]+>([^<]+)/) {
+ $command = $1;
+ last;
+ }
+ }
+ if ($command) {
+ next if $except{$command};
+ next if $command =~ /\(AFS version\)/;
+ $command =~ s/,.*//;
+ $command =~ s/ and.*//;
+ $command =~ s/\s/_/g;
+ $command =~ s/([\(\)])/\\$1/g;
+ print "../../man-pages/generate-pod $file >"
+ ." ../../man-pages/pod/$command.pod\n";
+ }
+}
#!/usr/bin/perl -w
#
-# Parser for files obtained via
-# lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt
+# Convert the HTML pages of the Administrator's Reference into POD man pages.
+# This script was written by Chas Williams and Russ Allbery, based on work by
+# Alf Wachsmann and Elizabeth Cassell. It just does a first pass; it's
+# expected that the results will require further hand-editing.
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;
+use HTML::Parser ();
+
+my @ignore_tags = qw(meta head comment html body);
+my @ignore_elements = qw(script style);
+
+my %INLINES = ('b' => 'B<',
+ '/b' => '>',
+ 'i' => 'I<',
+ '/i' => '>',
+ 'var' => 'I<',
+ '/var' => '>',
+ 'tt' => 'C<',
+ '/tt' => '>',
+ 'a' => 'L<',
+ '/a' => '(1)>',
+ 'sup' => '',
+ '/sup' => '');
+
+my %CDATA = ('dd' => 1,
+ 'dt' => 1,
+ 'h2' => 1,
+ 'a' => 1,
+ 'li' => 1,
+ 'p' => 1,
+ 'pre' => 1,
+ 'strong' => 1);
+
+# Global state of the conversion.
+my $command = "";
+my $output = 0;
+my $emit = 0;
+my $pre = 0;
+my $buffer = "";
+my $inpara = 0;
+my $lasttag = "";
+my $open = "";
+my $cdata = "";
+my $result = "";
+
+# Output some data. Accumulate this into $results so that we can do some
+# post-filtering at the end.
+sub output {
+ my ($format, @args) = @_;
+ $result .= sprintf($format, @args);
}
-$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} = "";
+# Handle a single element.
+sub element {
+ if ($output) {
+ $buffer =~ s/^\s+\n/\n/m;
+ $buffer =~ s/\n+$/\n/g;
+
+ if ($lasttag eq "h2") {
+ $command = $buffer;
+ $command =~ s/^L<//;
+ $command =~ s/\(1\)>$//;
+ } elsif ($lasttag eq "strong") {
+ if ($buffer eq 'Cautions') {
+ $buffer = 'CAVEATS';
+ } elsif ($buffer eq 'Related Information') {
+ $buffer = 'SEE ALSO';
+ } else {
+ $buffer = uc $buffer;
+ }
+ if ($buffer eq 'PURPOSE') {
+ output "=head1 NAME\n\n%s - ", $command;
+ } else {
+ output "=head1 %s\n\n", $buffer;
+ }
+ } elsif ($lasttag eq "h5") {
+ output "=head2 %s\n\n", $buffer;
+ } elsif ($lasttag eq "h6") {
+ output "=head3 %s\n\n", $buffer;
+ } elsif ($lasttag eq "p") {
+ $buffer =~ s/\n+$//g;
+ output "%s\n\n", $buffer if $buffer ne "";
+ } elsif ($lasttag eq "pre") {
+ $buffer =~ s/\n+$//;
+ output "%s\n\n", $buffer if $buffer ne "";
+ } elsif ($lasttag eq "ul" || $lasttag eq "dl") {
+ output "=over 4\n\n";
+ } elsif ($lasttag eq "li") {
+ output "=item *\n\n%s\n\n", $buffer;
+ } elsif ($lasttag eq "dt") {
+ output "=item %s\n\n", $buffer;
+ } elsif ($lasttag eq "dd") {
+ output "%s\n", $buffer;
+ } elsif ($lasttag eq "/ul" || $lasttag eq "/dl") {
+ output "=back\n\n";
+ } else {
+ if ($buffer ne "") {
+ printf ">>>%s:%s<<<", $lasttag, $buffer;
+ }
+ }
}
- }
-
- $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;
- }
-
-
-};
-
+ $buffer = "";
+}
-######################################################################
-## Output Section:
-######################################################################
+# Handle a single tag.
+sub tag {
+ my $self = shift;
+ local $_ = shift;
+ my $tag = shift;
+ my $attr = shift;
+
+ $output = 1 if ($tag eq "h2");
+ $output = 0 if ($tag eq "hr");
+
+ if (defined $INLINES{$tag}) {
+ if (defined $open && $open eq $tag) {
+ printf STDERR "duplicate tag <%s>\n", $tag;
+ return;
+ }
+ if ($tag =~ /^\//) {
+ undef $open;
+ } else {
+ $open = $tag;
+ }
+
+ &text(sprintf "%s", $INLINES{$tag});
+ return;
+ }
-my $file;
-($file = $hash{Command} . ".pod") =~ s/\s/_/g;
+ $cdata = 0;
+ $cdata = 1 if defined $CDATA{$tag};
-my $FH;
-if ($DEBUG) {
- $FH = *STDOUT
-} else {
- open(FILE, "> $file") || die("Could not open $file\n");
- $FH = *FILE;
+ &element;
+ $lasttag = $tag;
}
-print $FH "=head1 NAME\n\n";
-print $FH "$hash{Command} - $hash{Purpose}\n\n";
+# Do text conversion, mostly undoing SGML escapes.
+sub text {
+ local $_ = shift;
-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 ($cdata) {
+ s/&/&/g;
+ s/ / /g;
+ s/>/>/g;
+ s/</</g;
-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";
+ s/\n$//g if defined $open; # in inline seq, remove \n
+ s/L<(\S+) (\S+\(1\))>/L<${1}_${2}>/g;
+ $buffer = $buffer . $_;
+ }
}
-if (exists $hash{Output}) {
- print $FH "=head1 OUTPUT\n\n";
- print $FH "$hash{Output}\n\n";
-}
+my $file = shift @ARGV;
-if (exists $hash{Examples}) {
- print $FH "=head1 EXAMPLES\n\n";
- print $FH "$hash{Examples}\n\n";
-}
+my $p = HTML::Parser->new(api_version => 3,
+ start_h => [\&tag, "self, text, tag, attr"],
+ end_h => [\&tag, "self, text, tag, attr"],
+ process_h => ["", ""],
+ comment_h => ["", ""],
+ declaration_h => ["", ""],
+ default_h => [\&text, "text"],
-if (exists $hash{'Privilege Required'}) {
- print $FH "=head1 PRIVILEGE REQUIRED\n\n";
- print $FH "$hash{'Privilege Required'}\n\n";
-}
+ ignore_tags => \@ignore_tags,
+ ignore_elements => \@ignore_elements,
+ unbroken_text => 1);
-if (exists $hash{Cautions}) {
- print $FH "=head1 CAVEATS\n\n";
- print $FH "$hash{Cautions}\n\n";
-}
+$p->parse_file($file) || die "Can't open file: $!\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";
+# Fix up a few last things.
+$result =~ s/L<(\S+) (\S+\(1\))>/L<${1}_${2}>/g;
+$result =~ s/^(L<\S+>)\n\n(?=L<)/$1,\n/mg;
+$result =~ s/^(\S+[^\n]+)\n +/$1\n/mg;
+$result =~ s/^(\s+.*)B<([^>]+)>/$1$2/mg;
-if (exists $hash{'Related Information'}) {
- print $FH "=head1 SEE ALSO\n\n";
- print $FH "$hash{'Related Information'}\n\n";
- print $FH "=cut\n";
-}
+# Append a stock copyright statement.
+$result .= <<'EOC';
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
-close(FILE) unless $DEBUG;
+This documentation is covered by the IBM Public License Version 1.0. It was
+converted from HTML to POD by software written by Chas Williams and Russ
+Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
+EOC
+# Output the results.
+print $result;
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
+++ /dev/null
-=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
<
git://git.openafs.org / openafs.git / commitdiff