echo Skipping login for ${SYS_NAME} ; \
fi
+man-pages:
+ if test -d "doc/man-pages" ; then \
+ cd doc/man-pages ${COMPILE_PART2} ; \
+ fi
+
#
# _depinstall targets - only build and install headers/sources that are needed by libafs/libuafs
#
finale: project cmd comerr afsd butc tbutc @ENABLE_KERNEL_MODULE@ libuafs audit kauth log package \
ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \
venus update xstat afsmonitor dauth rxdebug libafsrpc \
- libafsauthent shlibafsrpc shlibafsauthent libadmin login
+ libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages
${COMPILE_PART1} finale ${COMPILE_PART2}
finale_nolibafs: project cmd comerr afsd butc tbutc libuafs audit kauth log package \
ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \
venus update xstat afsmonitor dauth rxdebug libafsrpc \
- libafsauthent shlibafsrpc shlibafsauthent libadmin login
+ libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages
${COMPILE_PART1} finale ${COMPILE_PART2}
# Use washtool to ensure MakefileProto is current and obj/libafs exists.
src/wsadmin.src/Makefile \
src/xstat/Makefile \
src/helper-splint.sh
+ if test -d doc/man-pages ; then rm -f doc/man-pages/Makefile ; fi
pristine: distclean
/bin/rm -f src/config/afsconfig.h.in configure configure-libafs aclocal.m4
AC_PROG_CC
OPENAFS_CONFIGURE_COMMON
+if test -d 'doc/man-pages' ; then
+ MAN_MAKEFILE=doc/man-pages/Makefile
+else
+ MAN_MAKEFILE=
+fi
+
AC_OUTPUT( \
Makefile \
+${MAN_MAKEFILE} \
src/afs/Makefile \
src/afsd/Makefile \
src/afsmonitor/Makefile \
--- /dev/null
+# Makefile for AFS man pages
+
+srcdir=@srcdir@
+include @TOP_OBJDIR@/src/config/Makefile.config
+
+MAN1 = \
+ afs_intro.1 \
+ fs.1 \
+ fs_apropos.1 \
+ fs_checkservers.1 \
+ fs_checkvolumes.1 \
+ fs_cleanacl.1 \
+ fs_copyacl.1 \
+ fs_diskfree.1 \
+ fs_examine.1 \
+ fs_exportafs.1 \
+ fs_flush.1 \
+ fs_flushmount.1 \
+ fs_flushvolume.1 \
+ fs_getcacheparms.1 \
+ fs_getcellstatus.1 \
+ fs_getclientaddrs.1 \
+ fs_getserverprefs.1 \
+ fs_help.1 \
+ fs_listacl.1 \
+ fs_listcells.1 \
+ fs_listquota.1 \
+ fs_lsmount.1 \
+ fs_messages.1 \
+ fs_mkmount.1 \
+ fs_newcell.1 \
+ fs_quota.1 \
+ fs_rmmount.1 \
+ fs_setacl.1 \
+ fs_setcachesize.1 \
+ fs_setcell.1 \
+ fs_setclientaddrs.1 \
+ fs_setquota.1 \
+ fs_setserverprefs.1 \
+ fs_setvol.1 \
+ fs_storebehind.1 \
+ fs_sysname.1 \
+ fs_whereis.1 \
+ fs_whichcell.1 \
+ fs_wscell.1 \
+ klog.1 \
+ kpasswd.1 \
+ kpwvalid.1 \
+ pts.1 \
+ pts_adduser.1 \
+ pts_apropos.1 \
+ pts_chown.1 \
+ pts_creategroup.1 \
+ pts_createuser.1 \
+ pts_delete.1 \
+ pts_examine.1 \
+ pts_help.1 \
+ pts_listentries.1 \
+ pts_listmax.1 \
+ pts_listowned.1 \
+ pts_membership.1 \
+ pts_removeuser.1 \
+ pts_rename.1 \
+ pts_setfields.1 \
+ pts_setmax.1
+
+MAN8 = \
+ afsd.8 \
+ afsmonitor.8 \
+ backup.8 \
+ backup_adddump.8 \
+ backup_addhost.8 \
+ backup_addvolentry.8 \
+ backup_addvolset.8 \
+ backup_apropos.8 \
+ backup_dbverify.8 \
+ backup_deldump.8 \
+ backup_deletedump.8 \
+ backup_delhost.8 \
+ backup_delvolentry.8 \
+ backup_delvolset.8 \
+ backup_diskrestore.8 \
+ backup_dump.8 \
+ backup_dumpinfo.8 \
+ backup_help.8 \
+ backup_interactive.8 \
+ backup_jobs.8 \
+ backup_kill.8 \
+ backup_labeltape.8 \
+ backup_listdumps.8 \
+ backup_listhosts.8 \
+ backup_listvolsets.8 \
+ backup_quit.8 \
+ backup_readlabel.8 \
+ backup_restoredb.8 \
+ backup_savedb.8 \
+ backup_scantape.8 \
+ backup_setexp.8 \
+ backup_status.8 \
+ backup_volinfo.8 \
+ backup_volrestore.8 \
+ backup_volsetrestore.8 \
+ bos.8 \
+ bos_addhost.8 \
+ bos_addkey.8 \
+ bos_adduser.8 \
+ bos_apropos.8 \
+ bos_create.8 \
+ bos_delete.8 \
+ bos_exec.8 \
+ bos_getdate.8 \
+ bos_getlog.8 \
+ bos_getrestart.8 \
+ bos_help.8 \
+ bos_install.8 \
+ bos_listhosts.8 \
+ bos_listkeys.8 \
+ bos_listusers.8 \
+ bos_prune.8 \
+ bos_removehost.8 \
+ bos_removekey.8 \
+ bos_removeuser.8 \
+ bos_restart.8 \
+ bos_salvage.8 \
+ bos_setauth.8 \
+ bos_setcellname.8 \
+ bos_setrestart.8 \
+ bos_shutdown.8 \
+ bos_start.8 \
+ bos_startup.8 \
+ bos_status.8 \
+ bos_stop.8 \
+ bos_uninstall.8 \
+ bosserver.8 \
+ buserver.8 \
+ butc.8 \
+ dlog.8 \
+ dpass.8 \
+ fileserver.8 \
+ fms.8 \
+ fstrace.8 \
+ fstrace_apropos.8 \
+ fstrace_clear.8 \
+ fstrace_dump.8 \
+ fstrace_help.8 \
+ fstrace_lslog.8 \
+ fstrace_lsset.8 \
+ fstrace_setlog.8 \
+ fstrace_setset.8 \
+ kadb_check.8 \
+ kas.8 \
+ kas_apropos.8 \
+ kas_create.8 \
+ kas_delete.8 \
+ kas_examine.8 \
+ kas_forgetticket.8 \
+ kas_help.8 \
+ kas_interactive.8 \
+ kas_list.8 \
+ kas_listtickets.8 \
+ kas_noauthentication.8 \
+ kas_quit.8 \
+ kas_setfields.8 \
+ kas_setpassword.8 \
+ kas_statistics.8 \
+ kas_stringtokey.8 \
+ kas_unlock.8 \
+ kaserver.8 \
+ kdb.8 \
+ knfs.8
+
+all: $(MAN1) $(MAN8)
+
+%.1: $(srcdir)/pod/%.pod
+ pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 $< $@
+
+%.8: $(srcdir)/pod/%.pod
+ pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 $< $@
+
+clean:
+ rm -f *.1 *.8
+
+dest: $(MAN1) $(MAN8)
+ mkdir -p $(DEST)/man/man1 $(DEST)/man/man8
+ set -e; for M in $(MAN1) ; do \
+ $(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \
+ done
+ set -e; for M in $(MAN8) ; do \
+ $(INSTALL) -c -m 0644 $$M $(DEST)/man/man8/$$M ; \
+ done
+
+install: $(MAN1) $(MAN8)
+ mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man8
+ set -e; for M in $(MAN1) ; do \
+ $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \
+ done
+ set -e; for M in $(MAN8) ; do \
+ $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \
+ done
--- /dev/null
+#!/usr/bin/perl -w
+#
+# Parser for files obtained via
+# lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt
+
+use strict;
+my $DEBUG = 0;
+my $RAW = 0;
+
+my %hash;
+my %options;
+
+######################################################################
+## Input Section:
+######################################################################
+
+my $del = $/;
+undef $/;
+my $text = <STDIN>;
+$/ = $del;
+
+my $sections = 'Purpose|Synopsis|Description|Cautions|Options|Output|Examples|Privilege\ Required|Related\ Information|References';
+
+$text =~ s/^.*\[7\]\s*(.+?)\n//xs;
+
+$hash{Command} = $1;
+my $Cmd_fam = "backup|bos|fs|kas|pts|uss|vos";
+$Cmd_fam .= '|' . (split(" ", $hash{Command}))[0];
+
+while ($text !~ /^\s+$/xs) {
+ $text =~ s/($sections)(.*?)(\n\s*(?:$sections)\n\s*|$)/$3/xs;
+ $hash{$1} = $2;
+}
+
+$hash{'Related Information'} =~ s/\s*(.+?)\s*___________.*$/$1/xs;
+
+
+
+if (! $RAW) {
+ ######################################################################
+ ## Clean-up Section:
+ ######################################################################
+
+ # make C<pts adduser> out of pts adduser:
+ $hash{Description} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Description});
+ $hash{Options} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Options});
+
+ # strip leading and trailing whitespace:
+ my $pattern = '^\s*(.*?)\s*$';
+ foreach (keys(%hash)) {
+ $hash{$_} =~ s/$pattern/$1/sxg;
+ $hash{$_} =~ s/\n\ +/\n/sxg;
+ $hash{$_} =~ s/((?:$Cmd_fam)\s?\w*)(\s)reference(\s)page/L<$1(1)>$2reference$3page/g;
+ $hash{$_} =~ s/the(\s)(\w+(?:\s\w+)?)(\s)reference(\s)page/the$1L<$2(1)>$3reference$4page/g;
+ $hash{$_} =~ s/(\(?\b(?:$Cmd_fam)\)?\s?\w*)(\s)command/C<$1>$2command/g;
+ $hash{$_} =~ s/the(\s)(\w+)(\s)command/the$1C<$2>$3command/g;
+ $hash{$_} =~ s/\n\*\ /\n\n=item \*\n\n/g;
+ $hash{$_} =~ s/\n\+\ /\n\n=item \*\n\n/g;
+ $hash{$_} =~ s"(\s)((?:/\w+)+)"$1B<$2>"g if($_ ne "Synopsis");
+ $hash{$_} =~ s/(superuser\s)root/$1B<root>/g;
+ $hash{$_} =~ s/(unprivileged\s(?:identity|user)\s)anonymous/$1B<anonymous>/g;
+ $hash{$_} =~ s/system\:administrators/B<system:administrators>/g;
+ $hash{$_} =~ s/(\s)(\w)(\s)\((\w+)\)(\s)/$1B<$2>$3(B<$4>)$5/g;
+ }
+
+ ######################################################################
+ ## POD-ify Section:
+ ######################################################################
+
+ # Make B<-group> out of -group:
+ $hash{Synopsis} =~ s/(\s|^|\[)(-\w+)\b/$1B<$2>/g if ($hash{Synopsis});
+ $hash{Description} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Description});
+ $hash{Options} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Options});
+ $hash{Output} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Output});
+ $hash{Cautions} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Cautions});
+ $hash{'Privilege Required'} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{'Privilege Required'});
+
+ $hash{Description} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Description});
+ $hash{Options} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Options});
+ $hash{Output} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Output});
+ $hash{'Privilege Required'} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{'Privilege Required'});
+ $hash{Cautions} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Cautions});
+
+ $hash{Synopsis} =~ s/<([^>]*?)>\^\+/I<$1> [I<$1> ...]/g if ($hash{Synopsis});
+ $hash{Synopsis} =~ s/( |\n)<(.*?)>/$1I<$2>/g if ($hash{Synopsis});
+ $text = $hash{Synopsis};
+ while ($text && $text =~ /B<-\w+> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?/s) {
+ $text =~ s/B<(-\w+)> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?//s;
+ if ($2) {
+ $options{$1} = ' '.$2;
+ } else {
+ $options{$1} = "";
+ }
+ }
+
+ $hash{Options} =~ s/(?:\n|^)B<([^>]*?)>\ \n/\n=item B<$1>$options{$1}\n\n/sxg if ($hash{Options});
+
+ $hash{Examples} =~ s/\n\s*%(.*?)(?:\n|$)/\n\nB<\ \ \ $1>\n/sxg if ($hash{Examples});
+
+ $hash{'Related Information'} =~ s/\[\d+\](.*?)\s*\n/L<$1(1)>,\n/msxg if ($hash{'Related Information'});
+ $hash{'Related Information'} =~ s/\[\d+\](.*)\s*/L<$1(1)>/msxg if ($hash{'Related Information'});
+ $hash{'Related Information'} =~ s/(\w+)\s+(\w+)/$1_$2/msxg if ($hash{'Related Information'});
+
+ foreach (keys(%hash)) {
+ $hash{$_} =~ s/((?:\n\n=item\ \*\n(?:\n.+$)+)+)/\n\n=over$1\n\n=back/mxg;
+ }
+
+
+};
+
+
+######################################################################
+## Output Section:
+######################################################################
+
+my $file;
+($file = $hash{Command} . ".pod") =~ s/\s/_/g;
+
+my $FH;
+if ($DEBUG) {
+ $FH = *STDOUT
+} else {
+ open(FILE, "> $file") || die("Could not open $file\n");
+ $FH = *FILE;
+}
+
+print $FH "=head1 NAME\n\n";
+print $FH "$hash{Command} - $hash{Purpose}\n\n";
+
+if (exists $hash{Synopsis}) {
+ print $FH "=head1 SYNOPSIS\n\n";
+ print $FH "$hash{Synopsis}\n\n";
+}
+
+print $FH "=head1 DESCRIPTION\n\n";
+print $FH "$hash{Description}\n\n";
+
+if (exists $hash{Options}) {
+ print $FH "=head1 OPTIONS\n\n";
+ print $FH "=over 4\n";
+ print $FH "$hash{Options}\n\n";
+ print $FH "=back\n\n";
+}
+
+if (exists $hash{Output}) {
+ print $FH "=head1 OUTPUT\n\n";
+ print $FH "$hash{Output}\n\n";
+}
+
+if (exists $hash{Examples}) {
+ print $FH "=head1 EXAMPLES\n\n";
+ print $FH "$hash{Examples}\n\n";
+}
+
+if (exists $hash{'Privilege Required'}) {
+ print $FH "=head1 PRIVILEGE REQUIRED\n\n";
+ print $FH "$hash{'Privilege Required'}\n\n";
+}
+
+if (exists $hash{Cautions}) {
+ print $FH "=head1 CAVEATS\n\n";
+ print $FH "$hash{Cautions}\n\n";
+}
+
+print $FH "=head1 COPYRIGHT\n\n";
+print $FH "IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.\n\n";
+print $FH "Converted from html to pod by Alf Wachsmann <alfw\@slac.stanford.edu>, 2003,\n";
+print $FH "and Elizabeth Cassell <e_a_c\@mailsnare.net>, 2004,\n";
+print $FH "Stanford Linear Accelerator Center, a department of Stanford University.\n\n";
+
+if (exists $hash{'Related Information'}) {
+ print $FH "=head1 SEE ALSO\n\n";
+ print $FH "$hash{'Related Information'}\n\n";
+ print $FH "=cut\n";
+}
+
+close(FILE) unless $DEBUG;
+
--- /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 listdumps - Displays the dump hierarchy from the Backup Database
+
+=head1 SYNOPSIS
+
+backup listdumps [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
+
+backup listd [B<-l>] [B<-c> I<cell name>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<backup listdumps> command displays the dump hierarchy from the
+Backup Database.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
+presents it to the Backup Server, Volume Server and VL Server
+during mutual authentication. Do not combine this flag with the
+B<-cell> argument. For more details, see the introductory L<backup(1)>
+reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<backup(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays the complete dump hierarchy and indicates the
+relationship between full and incremental dump levels. Full dump
+levels appear at the left margin. The hierarchy can include more than
+one full dump level; each one defines a subhierarchy of dump levels
+that can be used for dumping different volume sets.
+
+Incremental dump levels appear below and indented to the right of
+their parent dump levels, which can be either full or incremental.
+Since multiple incremental dump levels can share the same parent, an
+incremental dump level is not always directly below its parent; the
+amount of indentation indicates the parent/child relationship.
+
+If a dump level has an associated expiration date, it appears along
+with the level name. Absolute expiration dates appear in the format
+
+I<dump_level> expires at I<day> I<month> I<date> I<time> I<year>
+
+and relative expiration dates in the format
+
+I<dump_level> expires in {I<years>y | I<months>m | I<days>d}
+
+to indicate the number of years, months, days, or combination of the
+three after creation a dump expires when created at this level.
+
+=head1 EXAMPLES
+
+The following example depicts six dump hierarchies. The expiration
+date for all incremental dump levels is 13 days so that the
+corresponding tapes can be recycled two weeks after their creation.
+The expiration dates for all full dump levels is 27 days so that the
+corresponding tapes can be recycled four weeks after their creation.
+
+ backup listdumps
+ /week1 expires in 27d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday expires in 13d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /week3 expires in 27d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday expires in 13d
+ /tuesday expires in 13d
+ /thursday expires in 13d
+ /sunday1 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ /sunday2 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+ /sunday3 expires in 27d
+ /monday1 expires in 13d
+ /tuesday1 expires in 13d
+ /wednesday1 expires in 13d
+ /thursday1 expires in 13d
+ /friday1 expires in 13d
+ /sunday4 expires in 27d
+ /monday2 expires in 13d
+ /tuesday2 expires in 13d
+ /wednesday2 expires in 13d
+ /thursday2 expires in 13d
+ /friday2 expires in 13d
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server is running, or must be logged onto a
+server machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_adddump(1)>,
+L<backup_deldump(1)>
+
+=cut
--- /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
+here; otherwise, it is the AFS tape name.
+
+=item B<tape_ID>
+
+The tape ID of the tape containing the dump of the volume, from
+the Backup Database.
+
+=item B<position_number>
+
+Specifies the dump's position on the tape (for example, C<31>
+indicates that 30 volume dumps precede the current one on the
+tape). If the dump was written to a backup data file, this
+number is the ordinal of the 16 KB-offset at which the volume's
+data begins.
+
+=item B<date>
+
+The date and time when the volume was dumped.
+
+=back
+
+One way to generate a file for use as input to the B<-file> argument is
+to combine the B<-name> and B<-n> options, directing the output to a file.
+The IBM AFS Administration Guide section on using the Backup System to
+restore data explains how to edit the file as necessary before using
+it as input to the B<-file> argument.
+
+The output of this command includes only volumes for which the Backup
+Database includes at least one dump record. The command interpreter
+generates a message on the standard error stream about volumes that do
+not have dump records but either are listed in the file named by the
+B<-file> argument, or appear in the VLDB as a match to a volume entry in
+the volume set named by the B<-name> argument.
+
+=head1 EXAMPLES
+
+The following command restores all volumes included in entries in the
+volume set named B<data.restore>, which was created expressly to restore
+data to a pair of file server machines on which all data was corrupted
+due to a software error. All volumes are restored to the sites
+recorded in their entries in the VLDB.
+
+ backup volsetrestore -name data.restore
+ Starting restore
+ backup: task ID of restore operation: 112
+ backup: Finished doing restore
+
+The following command restores all volumes that have entries in the
+file named B</tmp/restore>:
+
+ backup volsetrestore -file B</tmp/restore>
+ Starting restore
+ backup: task ID of restore operation: 113
+ backup: Finished doing restore
+
+The B</tmp/restore> file has the following contents:
+
+ fs1.abc.com b user.pat
+ fs1.abc.com b user.terry
+ fs1.abc.com b user.smith
+ fs2.abc.com c user.jones
+ . . .
+ . . .
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on every
+machine where the Backup Server or Volume Location (VL) Server is
+running, and on every file server machine that houses an affected
+volume. If the B<-localauth> flag is included, the issuer must instead be
+logged on to a server machine as the local superuser B<root>.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<backup(1)>,
+L<backup_addvolentry(1)>,
+L<backup_addvolset(1)>,
+L<backup_diskrestore(1)>,
+L<backup_dump(1)>,
+L<backup_volrestore(1)>,
+L<butc(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos - Introduction to the C<bos> command suite
+
+=head1 DESCRIPTION
+
+The commands in the C<bos> command suite are the administrative interface
+to the Basic OverSeer (BOS) Server, which runs on every file server
+machine to monitor the other server processes on it. If a process
+fails, the BOS Server can restart it automatically, taking into
+account interdependencies between it and other processes. The BOS
+Server frees system administrators from constantly monitoring the
+status of server machines and processes.
+
+There are several categories of commands in the C<bos> command suite:
+
+=over
+
+=item *
+
+Commands to administer server process binary files: C<bos getdate>,
+C<bos install>, C<bos prune>, and C<bos uninstall>
+
+=item *
+
+Commands to maintain system configuration files: C<bos addhost>, C<bos
+addkey>, C<bos adduser>, C<bos listhosts>, C<bos listkeys>, C<bos listusers>,
+C<bos removehost>, C<bos removekey>, C<bos removeuser>, and C<bos setcellname>
+
+=item *
+
+Commands to start and stop processes: C<bos create>, C<bos delete>, C<bos
+restart>, C<bos shutdown>, C<bos start>, C<bos startup>, and C<bos stop>
+
+=item *
+
+Commands to set and verify server process and server machine
+status: C<bos getlog>, C<bos getrestart>, C<bos setauth>, C<bos setrestart>,
+and C<bos status>
+
+=item *
+
+A command to restore file system consistency: C<bos salvage>
+
+=item *
+
+Commands to obtain help: C<bos apropos> and C<bos help>
+
+=back
+
+The BOS Server and the C<bos> commands use and maintain the following
+configuration and log files:
+
+=over
+
+=item *
+
+The B</usr/afs/etc/CellServDB> file lists the local cell's database
+server machines. These machines run the Authentication, Backup,
+Protection and Volume Location (VL) Server processes, which
+maintain databases of administrative information. The database
+server processes consult the file to learn about their peers,
+whereas the other server processes consult it to learn where to
+access database information as needed. To administer the
+B<CellServDB> file, use the following commands: C<bos addhost>, C<bos
+listhosts>, C<bos removehost>, and C<bos setcellname>.
+
+=item *
+
+The B</usr/afs/etc/KeyFile> file lists the server encryption keys
+that the server processes use to decrypt tickets presented by
+client processes and one another. To administer the KeyFile file,
+use the following commands: C<bos addkey>, C<bos listkeys>, and C<bos
+removekey>.
+
+=item *
+
+The B</usr/afs/etc/ThisCell> file defines the cell to which the
+server machine belongs for the purposes of server-to-server
+communication. Administer it with the C<bos setcellname> command.
+There is also a B</usr/vice/etc/ThisCell> file that defines the
+machine's cell membership with respect to the AFS command suites
+and Cache Manager access to AFS data.
+
+=item *
+
+The B</usr/afs/etc/UserList> file lists the user name of each
+administrator authorized to issue privileged C<bos> and C<vos> commands.
+To administer the UserList file, use the following commands: C<bos
+adduser>, C<bos listusers>, and C<bos removeuser>.
+
+=item *
+
+The B</usr/afs/local/BosConfig> file defines which AFS server
+processes run on the server machine, and whether the BOS Server
+restarts them automatically if they fail. It also defines when all
+processes restart automatically (by default once per week), and
+when the BOS Server restarts processes that have new binary files
+(by default once per day). To administer the BosConfig file, use
+the following commands: C<bos create>, C<bos delete>, C<bos getrestart>,
+C<bos setrestart>, C<bos start>, and C<bos stop>.
+
+=item *
+
+The B</usr/afs/log/BosLog> file records important operations the BOS
+Server performs and error conditions it encounters.
+
+=back
+
+For more details, see the reference page for each file.
+
+=head1 OPTIONS
+
+The following arguments and flags are available on many commands in
+the C<bos> suite. The reference page for each command also lists them,
+but they are described here in greater detail.
+
+=over 4
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. It is acceptable to
+abbreviate the cell name to the shortest form that
+distinguishes it from the other entries in the
+B</usr/vice/etc/CellServDB> file on the local machine. If the
+B<-cell> argument is omitted, the command interpreter determines
+the name of the local cell by reading the following in order:
+
+=over
+
+=item 1.
+
+The value of the AFSCELL environment variable
+
+=item 2.
+
+The local B</usr/vice/etc/ThisCell> file
+
+=back
+
+Do not combine the B<-cell> and B<-localauth> options. A command on
+which the B<-localauth> flag is included always runs in the local
+cell (as defined in the server machine's local
+B</usr/afs/etc/ThisCell> file), whereas a command on which the
+B<-cell> argument is included runs in the specified foreign cell.
+
+=item B<-help>
+
+Prints a command's online help message on the standard output
+stream. Do not combine this flag with any of the command's
+other options; when it is provided, the command interpreter
+ignores all other options, and only prints the help message.
+
+=item B<-localauth>
+
+Constructs a server ticket using the server encryption key with
+the highest key version number in the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket, which never expires, to the BOS Server during
+mutual authentication.
+
+Use this flag only when issuing a command on a server machine;
+client machines do not usually have a B</usr/afs/etc/KeyFile>
+file. The issuer of a command that includes this flag must be
+logged on to the server machine as the local superuser B<root>.
+The flag is useful for commands invoked by an unattended
+application program, such as a process controlled by the UNIX
+B<cron> utility or by a cron entry in the machine's
+B</usr/afs/local/BosConfig> file. It is also useful if an
+administrator is unable to authenticate to AFS but is logged in
+as the local superuser B<root>.
+
+Do not combine the B<-cell> and B<-localauth> options. A command on
+which the B<-localauth> flag is included always runs in the local
+cell (as defined in the server machine's local
+B</usr/afs/etc/ThisCell> file), whereas a command on which the
+B<-cell> argument is included runs in the specified foreign cell.
+Also, do not combine the B<-localauth> and B<-noauth> flags.
+
+=item B<-noauth>
+
+Establishes an unauthenticated connection to the BOS Server, in
+which the BOS Server treats the issuer as the unprivileged user
+B<anonymous>. It is useful only when authorization checking is
+disabled on the server machine (during the installation of a
+file server machine or when the C<bos setauth> command has been
+used during other unusual circumstances). In normal
+circumstances, the BOS Server allows only privileged users to
+issue commands that change the status of a server or
+configuration file, and refuses to perform such an action even
+if the B<-noauth> flag is provided. Do not combine the B<-noauth> and
+B<-localauth> flags.
+
+=item B<-server> I<machine name>
+
+Indicates the AFS server machine on which to run the command.
+Identify the machine by its IP address in dotted decimal
+format, its fully-qualified host name (for example,
+B<fs1.abc.com>), or by an abbreviated form of its host name that
+distinguishes it from other machines. Successful use of an
+abbreviated form depends on the availability of a name service
+(such as the Domain Name Service or a local host table) at the
+time the command is issued.
+
+For the commands that alter the administrative files shared by
+all server machines in the cell (the C<bos addhost>, C<bos addkey>,
+C<bos adduser>, C<bos removehost>, C<bos removekey>, and C<bos removeuser>
+commands), the appropriate machine depends on whether the cell
+uses the United States or international version of AFS:
+
+=over
+
+=item *
+
+If the cell runs the United States edition of AFS and (as
+recommended) uses the Update Server to distribute the
+contents of the B</usr/afs/etc> directory, provide the name of
+the system control machine. After issuing the command, allow
+up to five minutes for the Update Server to distribute the
+changed file to the other AFS server machines in the cell. If
+the specified machine is not the system control machine but
+is running an B<upclientetc> process that refers to the system
+control machine, then the change will be overwritten when the
+process next brings over the relevant file from the system
+control machine.
+
+=item *
+
+If the cell runs the international edition of AFS, do not use
+the Update Server to distribute the contents of the
+B</usr/afs/etc> directory. Instead, repeatedly issue the
+command, naming each of the cell's server machines in turn.
+To avoid possible inconsistency problems, finish issuing the
+commands within a fairly short time.
+
+=back
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue any C<bos> command that changes a configuration file or alters
+process status, the issuer must be listed in the B</usr/afs/etc/UserList>
+file on the server machine named by the B<-server> argument.
+Alternatively, if the B<-localauth> flag is included the issuer must be
+logged on as the local superuser B<root>.
+
+To issue a C<bos> command that only displays information (other than the
+C<bos listkeys> command), no privilege is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<CellServDB_client_version(1)>,
+L<CellServDB_server_version(1)>,
+L<KeyFile(1)>,
+L<ThisCell_client_version(1)>,
+L<ThisCell_server_version(1)>,
+L<UserList(1)>,
+L<bos_addhost(1)>,
+L<bos_addkey(1)>,
+L<bos_adduser(1)>,
+L<bos_apropos(1)>,
+L<bos_create(1)>,
+L<bos_delete(1)>,
+L<bos_exec(1)>,
+L<bos_getdate(1)>,
+L<bos_getlog(1)>,
+L<bos_getrestart(1)>,
+L<bos_help(1)>,
+L<bos_install(1)>,
+L<bos_listhosts(1)>,
+L<bos_listkeys(1)>,
+L<bos_listusers(1)>,
+L<bos_prune(1)>,
+L<bos_removehost(1)>,
+L<bos_removekey(1)>,
+L<bos_removeuser(1)>,
+L<bos_restart(1)>,
+L<bos_salvage(1)>,
+L<bos_setauth(1)>,
+L<bos_setcellname(1)>,
+L<bos_setrestart(1)>,
+L<bos_shutdown(1)>,
+L<bos_start(1)>,
+L<bos_startup(1)>,
+L<bos_status(1)>,
+L<bos_stop(1)>,
+L<bos_uninstall(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos addhost - Adds a database server machine to the B</usr/afs/etc/CellServDB> file
+
+=head1 SYNOPSIS
+
+bos addhost B<-server> I<machine name> B<-host> I<host name> [I<host name> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos addh B<-s> I<machine name> B<-ho> I<host name> [I<host name> ...]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-he>]
+
+=head1 DESCRIPTION
+
+The C<bos addhost> command adds an entry for each database server machine
+specified with the B<-host> argument to the B</usr/afs/etc/CellServDB> file
+on the machine named by the B<-server> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Identifies the server machine on which to change the
+B</usr/afs/etc/CellServDB> file. Identify the machine by IP
+address or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-host> I<host name> [I<host name> ...]
+
+Specifies the fully-qualified host name (such as B<db1.abc.com>)
+of each database server machine to register in the B<CellServDB>
+file.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command adds the database server machines B<db2.abc.com>
+and B<db3.abc.com> to the B</usr/afs/etc/CellServDB> file on the machine
+B<fs1.abc.com> (the system control machine).
+
+ bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+After executing this command (and waiting for the Update Server to
+propagate the changes, if it is used), restart the database server
+processes on all database server machines to force election of a
+quorum that includes the new set of machines listed in the
+B</usr/afs/etc/CellServDB> file. The IBM AFS Quick Beginnings explains in
+more detail how to add and remove database server machines.
+
+It is best to maintain a one-to-one mapping between hostnames and IP
+addresses on a multihomed database server machine (this is actually
+the conventional configuration for any AFS machine). The BOS Server
+uses the B<gethostbyname( )> routine to obtain the IP address associated
+with the hostname specified by the -host argument. If there is more
+than one address, the BOS Server records in the B<CellServDB> entry the
+one that appears first in the list of addresses returned by the
+routine. The routine possibly returns addresses in a different order
+on different machines, which can create inconsistency.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_server_version(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_listhosts(1)>,
+L<bos_removehost(1)>,
+IBM AFS Quick Beginnings
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos addkey - Adds a new server encryption key to the B</usr/afs/etc/KeyFile> file
+
+=head1 SYNOPSIS
+
+bos addkey B<-server> I<machine name> [B<-key> I<key>]
+B<-kvno> I<key version number> [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos addk B<-s> I<machine name> [B<-ke> I<key>] B<-kv> I<key version number>
+[B<-ce> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos addkey> command constructs a server encryption key from the
+text string provided, assigns it the key version number specified with
+the B<-kvno> argument, and adds it to the B</usr/afs/etc/KeyFile> file on
+the machine specified with the B<-server> argument. Be sure to use the
+C<kas setpassword> or C<kas setkey> command to add the same key to the B<afs>
+entry in the Authentication Database.
+
+Do not use the B<-key> argument, which echoes the password string visibly
+on the screen. If the argument is omitted, the BOS Server prompts for
+the string and does not echo it visibly:
+
+ Input key:
+ Retype input key:
+
+The BOS Server prohibits reuse of any key version number already
+listed in the B</usr/afs/etc/KeyFile> file. This ensures that users who
+still have tickets sealed with the current key are not prevented from
+communicating with a server process because the current key is
+overwritten with a new key. Use the C<bos listkeys> command to display
+the key version numbers in the B</usr/afs/etc/KeyFile> file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/KeyFile> file. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-key> I<key>
+
+Specifies a character string just like a password; the BOS
+Server calls a DES conversion function to encode it into a form
+appropriate for use as an encryption key. Omit this argument to
+have the BOS Server prompt for the string instead.
+
+=item B<-kvno> I<key version number>
+
+Defines the new key's key version number. It must be an integer
+in the range from B<0> (zero) through B<255>. For the sake of
+simplicity, use the number one higher than the current highest
+key version number; use the C<bos listkeys> command to display key
+version numbers.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the strings typed at the C<Input key> and C<Retype input key> prompts do
+not match, the following message appears, and the command exits
+without adding a new key:
+
+ Input key mismatch
+
+=head1 EXAMPLES
+
+The following command adds a new server encryption key with key
+version number 14 to the B<KeyFile> file kept on the machine B<fs1.abc.com>
+(the system control machine). The issuer omits the B<-key> argument, as
+recommended, and provides the password at the prompts.
+
+ bos addkey -server fs1.abc.com -kvno 14
+ Input key:
+ Retype input key:
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_listkeys(1)>,
+L<bos_removekey(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos adduser - Adds a privileged user to the B</usr/afs/etc/UserList> file
+
+=head1 SYNOPSIS
+
+bos adduser B<-server> I<machine name> B<-user> I<user names> [I<user names> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos addu B<-s> I<machine name> B<-u> I<user names> [I<user names> ...]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos adduser> command adds each user name specified with the B<-user>
+argument to the B</usr/afs/etc/UserList> file on the machine named by the
+B<-server> argument. It is the issuer's responsibility to verify that an
+entry for the user exists in the Authentication and Protection
+Databases.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/UserList> file. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-user> I<user names> [I<user names> ...]
+
+Specifies each user name to insert into the
+B</usr/afs/etc/UserList> file.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command adds the user names pat and smith to the
+B</usr/afs/etc/UserList> file on the machine B<fs1.abc.com> (the system
+control machine).
+
+ bos adduser -server fs1.abc.com -user pat smith
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_listusers(1)>,
+L<bos_removeuser(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+bos apropos B<-topic> I<help string> [B<-help>]
+
+bos ap B<-t> I<help string> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos apropos> command displays the first line of the online help
+entry for any C<bos> command that has in its name or short description
+the string specified by the B<-topic> argument.
+
+To display the syntax for a command, use the C<bos help> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic> I<help string>
+
+Specifies the keyword string to match, in lowercase letters
+only. If the string is more than a single word, surround it
+with double quotes ("") or other delimiters.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of a command's online help entry names it and briefly
+describes its function. This command displays the first line for any
+C<bos> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all C<bos> commands that include the word
+B<restart> in their names or short descriptions:
+
+ bos apropos restart
+ getrestart: get restart times
+ restart: restart all processes
+ setrestart: set restart times
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos(1)>,
+L<bos_help(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos create - Defines a new process in the B</usr/afs/local/BosConfig> file and starts
+it running
+
+=head1 SYNOPSIS
+
+bos create B<-server> I<machine name> B<-instance> I<server process name>
+B<-type> I<server type> B<-cmd> I<command lines> [I<command lines> ...]
+[B<-notifier> I<Notifier program>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos c B<-s> I<machine name> B<-i> I<server process name> B<-t> I<server type>
+B<-cm> I<command lines> [I<command lines> ...] [B<-not> I<Notifier program>] [B<-ce> I<cell name>]
+[B<-noa>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos create> command creates a server process entry in the
+B</usr/afs/local/BosConfig> file on the server machine named by the
+B<-server> argument, sets the process's status to B<Run> in the B<BosConfig>
+file and in memory, and starts the process.
+
+A server process's entry in the B<BosConfig> file defines its name, its
+type, the command that initializes it, and optionally, the name of a
+notifier program that runs when the process terminates.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to define and start the
+new process. Identify the machine by IP address or its host
+name (either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-instance> I<server process name>
+
+Names the process to define and start. Any name is acceptable,
+but for the sake of simplicity it is best to use the last
+element of the process's binary file pathname, and to use the
+same name on every server machine. The conventional names, as
+used in all AFS documentation, are:
+
+=over
+
+=item B<buserver>
+
+The Backup Server process
+
+=item B<fs>
+
+The process that combines the File Server, Volume Server,
+and Salvager processes (B<fileserver>, B<volserver>, and
+B<salvager>)
+
+=item B<kaserver>
+
+The Authentication Server process
+
+=item B<ptserver>
+
+The Protection Server process
+
+=item B<runntp>
+
+The controller process for the Network Time Protocol
+Daemon
+
+=item B<upclientbin>
+
+The client portion of the Update Server process that
+retrieves binary files from the B</usr/afs/bin> directory of
+the binary distribution machine for this machine's
+CPU/operating system type. (The name of the binary is
+B<upclient>, but the B<bin> suffix distinguishes this process
+from B<upclientetc>.)
+
+=item B<upclientetc>
+
+The client portion of the Update Server process that
+retrieves configuration files from the B</usr/afs/etc>
+directory of the system control machine. Do not run this
+process in cells that use the international edition of
+AFS. (The name of the binary is B<upclient>, but the B<etc>
+suffix distinguishes this process from B<upclientbin>.)
+
+=item B<upserver>
+
+The server portion of the Update Server process
+
+=item B<vlserver>
+
+The Volume Location (VL) Server process
+
+=back
+
+=item B<-type> I<server type>
+
+Specifies the process's type. The acceptable values are:
+
+=over
+
+=item B<cron>
+
+Use this value for cron-type processes that the BOS
+Server starts only at a defined daily or weekly time,
+rather than whenever it detects that the process has
+terminated. AFS does not define any such processes by
+default, but makes this value available for administrator
+use. Define the time for command execution as part of the
+B<-cmd> argument to the C<bos create> command.
+
+=item B<fs>
+
+Use this value only for the B<fs> process, which combines
+the File Server, Volume Server and Salvager processes. If
+one of the component processes terminates, the BOS Server
+shuts down and restarts the processes in the appropriate
+order.
+
+=item B<simple>
+
+Use this value for all processes listed as acceptable
+values to the B<-instance> argument, except for the B<fs>
+process. There are no interdependencies between simple
+processes, so the BOS Server can stop and start them
+independently as necessary.
+
+=back
+
+=item B<-cmd> I<command lines> [I<command lines> ...]
+
+Specifies each command the BOS Server runs to start the
+process. Specify no more than six commands (which can include
+the command's options, in which case the entire string is
+surrounded by double quotes); any additional commands are
+ignored.
+
+For a simple process, provide the complete pathname of the
+process's binary file on the local disk (for example,
+B</usr/afs/bin/ptserver> for the Protection Server). If including
+any of the initialization command's options, surround the
+entire command in double quotes (" "). The B<upclient> process has
+a required argument, and the commands for all other processes
+take optional arguments.
+
+For the B<fs> process, provide the complete pathname of the local
+disk binary file for each of the component processes:
+B<fileserver>, B<volserver>, and B<salvager>, in that order. The
+standard binary directory is B</usr/afs/bin>. If including any of
+an initialization command's options, surround the entire
+command in double quotes (B<" ">).
+
+For a B<cron> process, provide two parameters:
+
+=over
+
+=item *
+
+The complete local disk pathname of either an executable file
+or a command from one of the AFS suites (complete with all of
+the necessary arguments). Surround this parameter with double
+quotes (B<" ">) if it contains spaces.
+
+=item *
+
+A specification of when the BOS Server executes the file or
+command indicated by the first parameter. There are three
+acceptable values:
+
+=over
+
+=item *
+
+The string C<now>, which directs the BOS Server to execute
+the file or command immediately and only once. It is
+usually simpler to issue the command directly or issue
+the C<bos exec> command.
+
+=item *
+
+A time of day. The BOS Server executes the file or
+command daily at the indicated time. Separate the hours
+and minutes with a colon (I<hh>:I<MM>), and use either 24-hour
+format, or a value in the range from B<1:00> through B<12:59>
+with the addition of B<am> or B<pm>. For example, both B<14:30>
+and B<"2:30 pm"> indicate 2:30 in the afternoon. Surround
+this parameter with double quotes (B<" ">) if it contains a
+space.
+
+=item *
+
+A day of the week and time of day, separated by a space
+and surrounded with double quotes (B<" ">). The BOS Server
+executes the file or command weekly at the indicated day
+and time. For the day, provide either the whole name or
+the first three letters, all in lowercase letters
+(B<sunday> or B<sun>, B<thursday> or B<thu>, and so on). For the
+time, use the same format as when specifying the time
+alone.
+
+=back
+
+=back
+
+=item B<-notifier> I<Notifier program>
+
+Specifies the complete pathname on the local disk of a program
+that the BOS Server invokes when the process terminates. The
+AFS distribution does not include any notifier programs, but
+this argument is available for administrator use. See the
+L</"Related Information"> section.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command defines and starts the simple process kaserver
+on the machine B<fs3.abc.com>:
+
+ bos create -server fs3.abc.com -instance kaserver -type simple \
+ -cmd /usr/afs/bin/kaserver
+
+The following command defines and starts the simple process
+B<upclientbin> on the machine B<fs4.abc.com>. It references B<fs1.abc.com> as
+the source for updates to binary files, checking for changes to the
+B</usr/afs/bin> directory every 120 seconds.
+
+ bos create -server fs4.abc.com -instance upclientbin -type simple \
+ -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
+ /usr/afs/bin"
+
+The following command creates the fs process B<fs> on the machine
+B<fs4.abc.com>. Type the command on a single line.
+
+ bos create -server fs4.abc.com -instance fs -type fs \
+ -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
+ /usr/afs/bin/salvager
+
+The following command creates a B<cron> process called B<userbackup> on the
+machine B<fs5.abc.com>, so that the BOS Server issues the indicated C<vos
+backupsys> command each day at 3:00 a.m. (the command creates a backup
+version of every volume in the file system whose name begins with
+B<user>). Note that the issuer provides the complete pathname to the C<vos>
+command, includes the B<-localauth> flag on it, and types the entire C<bos
+create> command on one line.
+
+ bos create -server fs5.abc.com -instance userbackup -type cron \
+ -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 Related Information
+
+If the B<-notifier> argument is included when this command is used to
+define and start a process, the BOS Server invokes the indicated
+I<notifier program> when the process exits. The intended use of a
+notifier program is to inform administrators when a process exits
+unexpectedly, but it can be used to perform any appropriate actions.
+The following paragraphs describe the B<bnode> and B<bnode_proc> structures
+in which the BOS Server records information about the exiting process.
+The list of AFS commands related to this one follows.
+
+The BOS Server constructs and sends on the standard output stream one
+B<bnode> and one B<bnode_proc> structure for each exiting process associated
+with the notifier program. It brackets each structure with appropriate
+C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN bnode_proc>
+and C<END bnode_proc>), which immediately follow the preceding newline
+character with no intervening spaces or other characters. If the
+notifier program does not need information from a structure, it can
+scan ahead in the input stream for the C<END> statement.
+
+In general, each field in a structure is a string of ASCII text
+terminated by the newline character. The format of the information
+within a structure possibly varies slightly depending on the type of
+process associated with the notifier program.
+
+The C code for the B<bnode> and B<bnode_proc> structures follows. Note that
+the structures sent by the BOS Server do not necessarily include all
+of the fields described here, because some are used only for internal
+record keeping. The notifier process must robustly handle the absence
+of expected fields, as well as the presence of unexpected fields, on
+the standard input stream.
+
+For proper performance, the notifier program must continue processing
+the input stream until it detects the end-of-file (EOF). The BOS
+Server closes the standard input file descriptor to the notifier
+process when it has completed delivery of the data, and it is the
+responsibility of the notifier process to terminate properly.
+
+=head2 struct bnode contents
+
+ struct bnode {
+ struct bnode *next; /* next pointer in top-level's list */
+ char *name; /* instance name */
+ long nextTimeout; /* next time this guy should be awakened */
+ long period; /* period between calls */
+ long rsTime; /* time we started counting restarts */
+ long rsCount; /* count of restarts since rsTime */
+ struct bnode_type *type; /* type object */
+ struct bnode_ops *ops; /* functions implementing bnode class */
+ long procStartTime; /* last time a process was started */
+ long procStarts; /* number of process starts */
+ long lastAnyExit; /* last time a process exited for any reason */
+ long lastErrorExit; /* last time a process exited unexpectedly */
+ long errorCode; /* last exit return code */
+ long errorSignal; /* last proc terminating signal */
+ char *lastErrorName; /* name of proc that failed last */
+ short refCount; /* reference count */
+ short flags; /* random flags */
+ char goal; /* 1=running or 0=not running */
+ char fileGoal; /* same, but to be stored in file */
+ };
+
+=head2 format of struct bnode explosion
+
+ printf("name: %s\n",tp->name);
+ printf("rsTime: %ld\n", tp->rsTime);
+ printf("rsCount: %ld\n", tp->rsCount);
+ printf("procStartTime: %ld\n", tp->procStartTime);
+ printf("procStarts: %ld\n", tp->procStarts);
+ printf("lastAnyExit: %ld\n", tp->lastAnyExit);
+ printf("lastErrorExit: %ld\n", tp->lastErrorExit);
+ printf("errorCode: %ld\n", tp->errorCode);
+ printf("errorSignal: %ld\n", tp->errorSignal);
+ printf("lastErrorName: %s\n", tp->lastErrorName);
+ printf("goal: %d\n", tp->goal);
+
+=head2 struct bnode_proc contents
+
+ struct bnode_proc {
+ struct bnode_proc *next; /* next guy in top-level's list */
+ struct bnode *bnode; /* bnode creating this process */
+ char *comLine; /* command line used to start this process */
+ char *coreName; /* optional core file component name */
+ long pid; /* pid if created */
+ long lastExit; /* last termination code */
+ long lastSignal; /* last signal that killed this guy */
+ long flags; /* flags giving process state */
+ };
+
+=head2 format of struct bnode_proc explosion
+
+ printf("comLine: %s\n", tp->comLine);
+ printf("coreName: %s\n", tp->coreName);
+ printf("pid: %ld\n", tp->pid);
+ printf("lastExit: %ld\n", tp->lastExit);
+ printf("lastSignal: %ld\n", tp->lastSignal);
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<buserver(1)>,
+L<fileserver(1)>,
+L<kaserver(1)>,
+L<ptserver(1)>,
+L<runntp(1)>,
+L<salvager(1)>,
+L<upclient(1)>,
+L<upserver(1)>,
+L<vlserver(1)>,
+L<volserver(1)>,
+L<vos_backupsys(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos delete - Deletes a server process from the B</usr/afs/local/BosConfig> file
+
+=head1 SYNOPSIS
+
+bos delete B<-server> I<machine name> B<-instance> I<server process name> [I<server process name> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos d B<-s> I<machine name> B<-i> I<server process name> [I<server process name> ...] [B<-c> I<cell name>]
+[B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos delete> command removes the B</usr/afs/local/BosConfig> entry for
+each process indicated by the B<-instance> argument, on the server
+machine named by the B<-server> argument.
+
+Before issuing this command, issue the C<bos stop> command to stop the
+process and set its status flag in the B<BosConfig> file to C<NotRun>. The
+C<bos delete> command fails with an error message if a process's status
+flag is C<Run>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to delete the server
+process entry from the B</usr/afs/local/BosConfig> file. Identify
+the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<server process name> [I<server process name> ...]
+
+Names each process to delete. Use the name assigned with the
+B<-instance> argument to the C<bos create> command; process names
+appear in the output of the C<bos status> command.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the B<buserver>, B<kaserver>, B<ptserver>, and
+B<vlserver> entries from the B<BosConfig> file on B<db3.abc.com>, a database
+server machine being decommissioned.
+
+ bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos exec - Executes a command on a remote server machine
+
+=head1 SYNOPSIS
+
+bos exec B<-server> I<machine name> B<-cmd> I<command to execute>
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos e B<-s> I<machine name> B<-cm> I<command to execute> [B<-ce> I<cell name>]
+[B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos exec> command executes the indicated command on the file server
+machine named by the B<-server> argument. Its intended use is to reboot
+the machine, using the B</etc/reboot> command or equivalent.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to execute the command.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-cmd> I<command to execute>
+
+Specifies the complete local disk pathname of the command to
+execute (for example, B</etc/reboot>). Surround this argument with
+double quotes ("") if the command contains one or more spaces.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command reboots the machine B<fs2.abc.com>. The issuer has
+previously issued the C<bos shutdown> command to shutdown all processes
+cleanly.
+
+ bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos getdate - Displays the time stamps on an AFS binary file
+
+=head1 SYNOPSIS
+
+bos getdate B<-server> I<machine name> B<-file> I<files to check> [I<files to check> ...]
+[B<-dir> I<destination dir>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos getd B<-s> I<machine name> B<-f> I<files to check> [I<files to check> ...] [B<-d> I<destination dir>]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos getdate> command displays the time stamps on the current
+version, C<.BAK> version (if any) and C<.OLD> version (if any) of each
+binary file named by the B<-file> argument. (The BOS Server automatically
+creates C<.BAK> and C<.OLD> versions when new binaries are installed with
+the C<bos install> command.) The files must reside in the B</usr/afs/bin>
+directory on the server machine named by the B<-server> argument unless
+the B<-dir> argument indicates an alternate directory.
+
+To revert to the C<.BAK> version of a binary, use the C<bos uninstall>
+command. To remove obsolete binary files from the B</usr/afs/bin>
+directory, use the C<bos prune> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to list binary files.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+All server machines of the same AFS system type show the same
+timestamps if the binaries were installed properly on the
+binary distribution machine for this machine's system type, and
+if all other machines of that type are running the appropriate
+B<upclientbin> process.
+
+=item B<-file> I<files to check> [I<files to check> ...]
+
+Names each binary file to list.
+
+=item B<-dir> I<destination dir>
+
+Specifies the complete pathname of the local disk directory
+containing each file named by the B<-file> argument. It is
+necessary only if the files are not in the B</usr/afs/bin>
+directory.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+For each file specified with the B<-file> argument, the output displays
+the time stamp on the current (unmarked), C<.BAK>, and C<.OLD> version. The
+output explicitly reports that a version does not exist, rather than
+simply omitting it.
+
+=head1 EXAMPLES
+
+The following command examines the time stamps on the files with
+basename B<kaserver> on the machine B<fs2.abc.com>:
+
+ bos getdate -server fs2.abc.com -file kaserver
+ File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999.
+ .BAK file dated Wed Dec 9 18:55:04 1998, no .OLD file.
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<bos(1)>,
+L<bos_install(1)>,
+L<bos_prune(1)>,
+L<bos_uninstall(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos getlog - Prints a server process's log file
+
+=head1 SYNOPSIS
+
+bos getlog B<-server> I<machine name> B<-file> I<log file to examine>
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos getl B<-s> I<machine name> B<-f> I<log file to examine> [B<-c> I<cell name>]
+[B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos getlog> command displays on the standard output stream the
+specified log file from the machine named by the B<-server> argument. The
+BOS Server fetches the log file from the B</usr/afs/logs> directory
+unless an alternate pathname is provided as part of the B<-file>
+argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to retrieve the log
+file. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-file> I<log file to examine>
+
+Names the log file to display. If a filename only is provided,
+the BOS Server fetches the log file from the B</usr/afs/logs>
+directory; the standard values are:
+
+=over
+
+=item B<AuthLog>
+
+The Authentication Server (B<kaserver>) log file
+
+=item B<BackupLog>
+
+The Backup Server (B<buserver>) log file
+
+=item B<BosLog>
+
+The BOS Server (B<bosserver>) log file
+
+=item B<FileLog>
+
+The File Server (B<fileserver>) log file
+
+=item B<SalvageLog>
+
+The Salvager (B<salvager>) log file
+
+=item B<VLLog>
+
+The Volume Location (VL) Server (B<vlserver>) log file
+
+=item B<VolserLog>
+
+The Volume Server (B<volserver>) log file
+
+=back
+
+If a pathname and filename are provided, the log file is
+retrieved from the indicated directory. Partial pathnames are
+interpreted relative to the B</usr/afs/logs> directory.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output is preceded by the line
+
+Fetching log file 'I<filename>'...
+
+The remainder of the output depends on the particular log file.
+
+=head1 EXAMPLES
+
+The following example displays the B<FileLog> file from the machine
+B<fs3.abc.com>:
+
+ bos getlog -server fs3.abc.com -file FileLog
+ Fetching log file 'FileLog'...
+ Sun Nov 8 04:00:34 1998 File server starting
+ Sun Nov 8 04:00:39 1998 Partition /vicepa: attached 21 volumes;
+ 0 volumes not attached
+ Sun Nov 8 04:00:40 1998 File Server started Sun Nov 8 04:00:40
+ 1998
+ Mon Nov 9 21:45:06 1998 CB: RCallBack (zero fid probe in host.c)
+ failed for host 28cf37c0.22811
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Log files can grow quite large, especially for the database server
+processes. To keep them to a manageable size, periodically either use
+the UNIX B<rm> command to truncate each log file, or use the C<bos restart>
+command to restart each process.
+
+It can take up to five minutes after the file is removed or process
+restarted for the space occupied by a log file to become available.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos getrestart - Displays the automatic restart times for server processes
+
+=head1 SYNOPSIS
+
+bos getrestart B<-server> I<machine name> [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos getr B<-s> I<machine name> [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos getrestart> command displays two restart times from the
+B</usr/afs/local/BosConfig> file on the server machine named by the
+B<-server> argument:
+
+=over
+
+=item *
+
+The I<general restart time> at which the BOS Server process
+automatically restarts itself and all processes marked with status
+Run in the B<BosConfig> file. The default is Sunday at 4:00 a.m.
+
+=item *
+
+The binary restart time at which the BOS Server automatically
+restarts any process for which the time stamp on the binary file
+in the B</usr/afs/bin> directory is later than the last restart time
+for the process. The default is 5:00 a.m. Use the C<bos getdate>
+command to list a binary file's timestamp, and the B<-long> flag to
+the C<bos status> command to display a process's most recent restart
+time.
+
+=back
+
+Use the C<bos setrestart> command to set the restart times.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine for which to display the restart
+times. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output consists of two lines:
+
+Server I<machine_name> restarts at I<time>
+
+Server I<machine_name> restarts for new binaries at I<time>
+
+Possible values for I<time> include:
+
+=over
+
+=item *
+
+C<never>, indicating that the BOS Server never performs that type of
+restart
+
+=item *
+
+C<now>, indicating that the BOS Server performs that type of restart
+only each time it restarts
+
+=item *
+
+A specified day and time, indicating that the BOS Server performs
+that type of restart once per week. Example: C<sun 4:00 am>.
+
+=item *
+
+A specified time, indicating that the BOS Server performs that
+type of restart once per day. Examples: C<11:00 pm>, C<3:00 am>.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the restart times for the machine
+B<db2.abc.com>:
+
+ bos getrestart db2.abc.com
+ Server db2.abc.com restarts at sun 4:00 am
+ Server db2.abc.com restarts for new binaries at 2:15 am
+
+In the following example, the issuer abbreviates the machine name
+B<fs1.abc.com> to B<fs1>, relying on the cell's name server to resolve the
+name. The output echoes the abbreviated form.
+
+ bos getrestart fs1
+ Server fs1 restarts at sat 5:00 am
+ Server fs1 restarts for new binaries at 11:30 pm
+
+=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<BosConfig(1)>,
+L<KeyFile(1)>,
+L<bos(1)>,
+L<bos_getdate(1)>,
+L<bos_setrestart(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos help - Displays the syntax of specified C<bos> commands or lists functional
+descriptions of all C<bos> commands
+
+=head1 SYNOPSIS
+
+bos help [B<-topic> I<help string> [I<help string> ...]] [B<-help>]
+
+bos h [B<-t> I<help string> [I<help string> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<bos> command.
+
+To list every C<bos> command whose name or short description includes a
+specified keyword, use the C<bos 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<bos> part of the command name, providing
+only the operation code (for example, specify C<status>, not C<bos
+status>). If this argument is omitted, the output briefly
+describes every C<bos> 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<bos> 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 command displays the online help entry for the C<bos
+status> command:
+
+ bos help status
+ bos status: show server instance status
+ Usage: bos status -server <machine name> [-instance <server
+ process name>+] [-long] [-cell <cell name>] [-noauth]
+ [-localauth] [-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<bos(1)>,
+L<bos_apropos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos install - Installs a new version of a binary file
+
+=head1 SYNOPSIS
+
+bos install B<-server> I<machine name> B<-file> I<files to install> [I<files to install> ...]
+[B<-dir> I<destination dir>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos i B<-s> I<machine name> B<-f> I<files to install> [I<files to install> ...]
+[B<-d> I<destination dir>] [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos install> command copies each binary file specified with the
+B<-file> argument to the local disk of the server machine named by the
+B<-server> argument, which is normally the binary distribution machine
+for its CPU/operating system type. The destination directory is
+B</usr/afs/bin> unless the B<-dir> argument indicates an alternate
+directory. The source file's UNIX mode bits are preserved in the
+transfer.
+
+If there is already a file of the same name in the destination
+directory, the BOS Server automatically saves it by adding a C<.BAK>
+extension. If there is a current C<.BAK> version at least seven days old,
+it replaces the current C<.OLD> version. If there is no current C<.OLD>
+version, the current C<.BAK> version becomes the C<.OLD> version
+automatically. The C<bos getdate> command displays the timestamps on the
+current versions of the file.
+
+To start using the new binary immediately, issue the C<bos restart>
+command. Otherwise, the BOS Server automatically restarts the process
+at the time defined in the B</usr/afs/local/BosConfig> file; use the C<bos
+getrestart> command to display the time and the C<bos setrestart> time to
+set it.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the binary distribution machine on which to install
+the new binaries. Identify the machine by IP address or its
+host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+If the machine is not a binary distribution machine and is
+running an B<upclientbin> process, then the files are overwritten
+the next time the B<upclientbin> process fetches the corresponding
+file from the distribution machine (by default within five
+minutes).
+
+=item B<-file> I<files to install> [I<files to install> ...]
+
+Specifies the complete pathname of each binary file to copy
+into the destination directory. Each source directory can be on
+the local disk or in AFS, in which case the issuer of the C<bos
+install> command must have the necessary AFS access rights and
+the local machine must run the Cache Manager. For the BOS
+Server to create C<.BAK> and C<.OLD> versions, the last element in
+the pathname (the filename) must match the name of a file in
+the destination directory. The reference page for the C<bos
+create> command lists the standard binary file names.
+
+=item B<-dir> I<destination dir>
+
+Provides the complete pathname of the local disk directory in
+which to install binary files. It is necessary only if the
+destination directory is not B</usr/afs/bin>.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command copies the file
+B</afs/abc.com/rs_aix42/usr/afs/bin/vlserver> to the file
+B</usr/afs/bin/vlserver> on the machine B<fs3.abc.com>, which is the binary
+distribution machine for server machines running AIX 4.2 in the
+B<abc.com> cell. The current version of the B</usr/afs/bin/vlserver> file is
+moved to B</usr/afs/bin/vlserver.BAK>.
+
+ bos install -server fs3.abc.com \
+ -file /afs/abc.com/rs_aix42/usr/afs/bin/vlserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_getdate(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(1)>,
+L<bos_setrestart(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos listhosts - Displays the contents of the B</usr/afs/etc/CellServDB> file
+
+=head1 SYNOPSIS
+
+bos listhosts B<-server> I<machine name> [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos listh B<-s> I<machine name> [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+bos getcell B<-server> I<machine name> [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos getc B<-s> I<machine name> [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos listhosts> command formats and displays the list of a cell's
+database server machines from the B</usr/afs/etc/CellServDB> file on the
+server machine named by the B<-server> argument.
+
+To alter the list of machines, use the C<bos addhost> and C<bos removehost>
+commands.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to display the
+B</usr/afs/etc/CellServDB> file. Identify the machine by IP
+address or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+For consistent performance in the cell, the output must be the
+same on every server machine. The L<bos_addhost(1)> reference page
+explains how to keep the machines synchronized.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of the output names the cell to which the server
+machine belongs. Each of the following lines names a database server
+machine for that cell.
+
+The Host number assigned to each database server machine is for
+server-internal use only and is not the same as, nor necessarily
+related to, the machine's IP address. The BOS Server assigned it as
+part of performing the C<bos addhost> command.
+
+=head1 EXAMPLES
+
+The following command displays the database server machines listed in
+the B</usr/afs/etc/CellServDB> file on the machine B<fs7.abc.com>.
+
+ bos listhosts fs7.abc.com
+ Cell name is abc.com
+ Host 1 is db1.abc.com
+ Host 2 is db2.abc.com
+ Host 3 is db3.abc.com
+
+=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<CellServDB_server_version(1)>,
+L<KeyFile(1)>,
+L<bos(1)>,
+L<bos_addhost(1)>,
+L<bos_removehost(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos listkeys - Displays the server encryption keys from the B</usr/afs/etc/KeyFile> file
+
+=head1 SYNOPSIS
+
+bos listkeys B<-server> I<machine name> [B<-showkey>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos listk B<-se> I<machine name> [B<-sh>] [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos listkeys> command formats and displays the list of server
+encryption keys from the B</usr/afs/etc/KeyFile> file on the server
+machine named by the B<-server> argument.
+
+To edit the list of keys, use the C<bos addkey> and C<bos removekey>
+commands.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to display the B<KeyFile>
+file. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+For consistent performance in the cell, the output must be the
+same on every server machine. The L<bos_addkey(1)> reference page
+explains how to keep the machines synchronized.
+
+=item B<-showkey>
+
+Displays the octal digits that constitute each key.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output includes one line for each server encryption key listed in
+the B<KeyFile> file, identified by its key version number.
+
+If the B<-showkey> flag is included, the output displays the actual
+string of eight octal numbers that constitute the key. Each octal
+number is a backslash and three decimal digits.
+
+If the B<-showkey> flag is not included, the output represents each key
+as a checksum, which is a decimal number derived by encrypting a
+constant with the key.
+
+Following the list of keys or checksums, the string C<Keys last changed>
+indicates when a key was last added to the B<KeyFile> file. The words C<All
+done> indicate the end of the output.
+
+For mutual authentication to work properly, the output from the
+command B<kas examine afs> must match the key or checksum with the same
+key version number in the output from this command.
+
+=head1 EXAMPLES
+
+The following example shows the checksums for the keys stored in the
+B<KeyFile> file on the machine B<fs3.abc.com>.
+
+ bos listkeys fs3.abc.com
+ key 1 has cksum 972037177
+ key 3 has cksum 2825175022
+ key 4 has cksum 260617746
+ key 6 has cksum 4178774593
+ Keys last changed on Mon Apr 12 11:24:46 1999.
+ All done.
+
+The following example shows the actual keys from the B<KeyFile> file on
+the machine B<fs6.abc.com>.
+
+ bos listkeys fs6.abc.com -showkey
+ key 0 is '\040\205\211\241\345\002\023\211'
+ key 1 is '\343\315\307\227\255\320\135\244'
+ key 2 is '\310\310\255\253\326\236\261\211'
+ Keys last changed on Wed Mar 31 11:24:46 1999.
+ All done.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Displaying actual keys on the standard output stream (by including the
+B<-showkey> flag) is a security exposure. Displaying a checksum is
+sufficient for most purposes.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos_addkey(1)>,
+L<bos_removekey(1)>,
+L<bos_setauth(1)>,
+L<kas_examine(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos listusers - Lists the privileged users from the B</usr/afs/etc/UserList> file
+
+=head1 SYNOPSIS
+
+bos listusers B<-server> I<machine name> [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos listu B<-s> I<machine name> [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos listusers> command lists the user names from the
+B</usr/afs/etc/UserList> file on the file server machine named by the
+B<-server> argument. The users are authorized to issue privileged C<bos> and
+C<vos> commands.
+
+To edit the list of users, use the C<bos adduser> and C<bos removeuser>
+commands.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to display the B<UserList>
+file. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+For consistent performance in the cell, the output must be the
+same on every server machine. The L<bos_adduser(1)> reference page
+explains how to keep the machines synchronized.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output lists the user name of each user entitled to issue
+privileged C<bos> and C<vos> commands.
+
+=head1 EXAMPLES
+
+The following example lists the users from B<UserList> file on the
+machine B<fs4.abc.com>.
+
+ bos listusers fs4.abc.com
+ SUsers are: pat smith jones terry
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_adduser(1)>,
+L<bos_removeuser(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos prune - Removes obsolete versions of files from the B</usr/afs/bin> and
+B</usr/afs/logs> directories
+
+=head1 SYNOPSIS
+
+bos prune B<-server> I<machine name> [B<-bak>] [B<-old>] [B<-core>] [B<-all>]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos p B<-s> I<machine name> [B<-b>] [B<-o>] [B<-co>] [B<-a>]
+[B<-ce> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos prune> command removes files from the local disk of the server
+machine named by the B<-server> argument, as specified by one or more of
+the following flags provided on the command line:
+
+=over
+
+=item *
+
+The B<-bak> flag removes all files from the B</usr/afs/bin> directory
+that have a C<.BAK> extension.
+
+=item *
+
+The B<-old> flag removes all files from the B</usr/afs/bin> directory
+that have a C<.OLD> extension.
+
+=item *
+
+The B<-core> flag removes all files from the B</usr/afs/logs> directory
+that have a C<core.> prefix.
+
+=item *
+
+The B<-all> flag removes all three types of files at once.
+
+=back
+
+(If none of these flags are included, the command appears to succeed,
+but removes no files at all.)
+
+To display the timestamp on the current, C<.BAK>, and C<.OLD> versions of
+one or more files, use the C<bos getdate> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine from which to remove files.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-bak>
+
+Removes all files from the B</usr/afs/bin> directory that have a
+C<.BAK> extension. Do not combine this flag and the B<-all> flag.
+
+=item B<-old>
+
+Removes all files from the B</usr/afs/bin> directory that have a
+C<.OLD> extension. Do not combine this flag and the B<-all> flag.
+
+=item B<-core>
+
+Removes all files from the B</usr/afs/logs> directory that have a
+C<core.> prefix. Do not combine this flag and the B<-all> flag.
+
+=item B<-all>
+
+Combines the effect of the B<-bak>, B<-old>, and B<-core> flags. Do not
+combine this flag with any of those three.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example removes all files from the B</usr/afs/bin>
+directory on the machine B<fs3.abc.com> that have a C<.BAK> or C<.OLD>
+extension.
+
+ bos prune -server fs3.abc.com -bak -old
+
+The following example removes all files from the B</usr/afs/bin>
+directory on the machine B<db2.abc.com> that have a C<.BAK> or C<.OLD>
+extension, and all files from the B</usr/afs/logs> directory that have a
+C<core.> prefix.
+
+ bos prune -server db2.abc.com -all
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_getdate(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos removehost - Removes a database server machine from the B</usr/afs/etc/CellServDB>
+file
+
+=head1 SYNOPSIS
+
+bos removehost B<-server> I<machine name> B<-host> I<host name> [I<host name> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos removeh B<-s> I<machine name> B<-ho> I<host name> [I<host name> ...] [B<-c> I<cell name>]
+[B<-n>] [B<-l>] [B<-he>]
+
+=head1 DESCRIPTION
+
+The C<bos removehost> command removes the entry for each database server
+machine specified with the B<-host> argument from the
+B</usr/afs/etc/CellServDB> file on the server machine named by the
+B<-server> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/CellServDB> file. Identify the machine by IP
+address or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-host> I<host name> [I<host name> ...]
+
+Specifies the fully-qualified host name (such as B<fs2.abc.com>)
+of each database server machine to remove from the B<CellServDB>
+file.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the former database server machine
+B<db2.abc.com> from the B<CellServDB> file on the system control machine
+B<fs1.abc.com>.
+
+ bos removehost -server fs1.abc.com -host db2.abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+After executing this command (and waiting for the Update Server to
+propagate the changes, if it is used), restart the database server
+processes on all database server machines to force election of a
+quorum that includes the new set of machines listed in the
+B</usr/afs/etc/CellServDB> file. The IBM AFS Quick Beginnings explains in
+more detail how to add and remove database server machines.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_addhost(1)>,
+L<bos_listhosts(1)>,
+IBM_AFS Quick_Beginnings
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos removekey - Removes a server encryption key from the B</usr/afs/etc/KeyFile> file
+
+=head1 SYNOPSIS
+
+bos removekey B<-server> I<machine name> B<-kvno> I<key version number> [I<key version number> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos removek B<-s> I<machine name> B<-k> I<key version number> [I<key version number> ...]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos removekey> command removes each specified encryption key from
+the B</usr/afs/etc/KeyFile> file on the machine named by the B<-server>
+argument. Use the B<-kvno> argument to identify each key by its key
+version number; use the C<bos listkeys> command to display the key
+version numbers.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/KeyFile> file. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-kvno> I<key version number> [I<key version number> ...]
+
+Specifies the key version number of each key to remove.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the keys with key version numbers 5 and
+6 from the B<KeyFile> file on the system control machine B<fs1.abc.com>.
+
+ bos removekey -server fs1.abc.com -kvno 5 6
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Before removing a obsolete key, verify that the cell's maximum ticket
+lifetime has passed since the current key was defined using the C<kas
+setpassword> and C<bos addkey> commands. This ensures that no clients
+still possess tickets encrypted with the obsolete key.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_addkey(1)>,
+L<bos_listkeys(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos removeuser - Removes a privileged user from the B</usr/afs/etc/UserList> file
+
+=head1 SYNOPSIS
+
+bos removeuser B<-server> I<machine name> B<-user> I<user names> [I<user names> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos removeu B<-s> I<machine name> B<-u> I<user names> [I<user names> ...] [B<-c> I<cell name>]
+[B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos removeuser> command removes each user name specified with the
+B<-user> argument from the B</usr/afs/etc/UserList> file on the machine
+named by the B<-server> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to change the
+B</usr/afs/etc/UserList> file. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+In cells that run the United States edition of AFS and use the
+Update Server to distribute the contents of the B</usr/afs/etc>
+directory, it is conventional to specify only the system
+control machine as a value for the B<-server> argument. In cells
+that run the international version of AFS, repeat the command
+for each file server machine. For further discussion, see the
+introductory reference page for the C<bos> command suite.
+
+=item B<-user> I<user names> [I<user names> ...]
+
+Specifies each user name to remove.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example removes the users B<pat> and B<jones> from the
+B<UserList> file on the system control machine B<fs1.abc.com>.
+
+ bos removeuser -server fs1.abc.com -user pat jones
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_addkey(1)>,
+L<bos_listkeys(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos restart - Restarts a server process
+
+=head1 SYNOPSIS
+
+bos restart B<-server> I<machine name> [B<-instance> I<instances> [I<instances> ...]] [B<-bosserver>]
+[B<-all>] [B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos res B<-s> I<machine name> [B<-i> I<instances> [I<instances> ...]] [B<-b>] [B<-a>]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos restart> command stops and immediately restarts server
+processes on the server machine named by the B<-server> argument.
+Indicate which process or processes to restart by providing one of the
+following arguments:
+
+=over
+
+=item *
+
+The B<-instance> argument names each AFS server process to stop and
+restart immediately, regardless of its status flag in the
+B</usr/afs/local/BosConfig> file. Do not include B<bosserver> in the
+list of processes; use the B<-bosserver> flag instead.
+
+=item *
+
+The B<-bosserver> flag stops all AFS server processes running on the
+machine, including the BOS Server. A new BOS Server starts
+immediately, and it starts a new instance of each process that is
+marked with the Run status flag in the B<BosConfig> file.
+
+=item *
+
+The B<-all> flag stops all AFS server processes running on the
+machine, except the BOS Server, and immediately restarts the
+processes that are marked with the Run status flag in the
+B<BosConfig> file.
+
+=back
+
+This command does not change a process's status flag in the B<BosConfig>
+file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to restart each process.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<instances> [I<instances> ...]
+
+Names each process to stop and then restart immediately
+regardless of its status flag setting. Use the process name
+assigned with the B<-instance> argument to the C<bos create> command.
+The output from the C<bos status> command lists the names. Provide
+this flag or one of the B<-bosserver> or B<-all> options, but do not
+combine them.
+
+=item B<-bosserver>
+
+Stops all AFS server processes running on the machine,
+including the BOS Server. A new BOS Server instance immediately
+starts, and starts all processes marked with the Run status
+flag in the B<BosConfig> file. Provide this flag or one of the
+B<-instance> or B<-all> options, but do not combine them.
+
+=item B<-all>
+
+Stops all AFS server processes running on the machine other
+than the BOS Server, and immediately restarts the processes
+marked with the B<Run> status flag in the B<BosConfig> file. Provide
+this flag or one of the B<-instance> or B<-bosserver> options, but do
+not combine them.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command stops and restarts all processes running on the
+machine B<fs3.abc.com>, including the BOS Server.
+
+ bos restart -server fs3.abc.com -bosserver
+
+The following command stops and restarts all processes running on the
+machine B<fs5.abc.com>, excluding the BOS Server.
+
+ bos restart -server fs5.abc.com -all
+
+The following command stops and restarts the Protection Server and
+Volume Location (VL) Server processes on the machine B<db3.abc.com>:
+
+ bos restart -server db3.abc.com -instance ptserver vlserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos salvage - Restores internal consistency to a file system or volume
+
+=head1 SYNOPSIS
+
+bos salvage B<-server> I<machine name> [B<-partition> I<salvage partition>]
+[B<-volume> I<salvage volume number or volume name>]
+[B<-file> I<salvage log output file>] [B<-all>] [B<-showlog>]
+[B<-parallel> I<# of max parallel partition salvaging>]
+[B<-tmpdir> I<directory to place tmp files>]
+[B<-orphans> I<ignore | remove | attach>]
+[B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos sa B<-se> I<machine name> [B<-part> I<salvage partition>]
+[B<-v> I<salvage volume number or volume name>]
+[B<-f> I<salvage log output file>] [B<-a>] [B<-sh>]
+[B<-para> I<# of max parallel partition salvaging>]
+[B<-t> I<directory to place tmp files>]
+[B<-o> I<ignore | remove | attach>]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos salvage> command salvages (restores internal consistency to)
+one or more volumes on the file server machine named by the B<-server>
+argument. When processing one or more partitions, the command restores
+consistency to corrupted read/write volumes where possible. For
+read-only or backup volumes, it inspects only the volume header:
+
+=over
+
+=item *
+
+If the volume header is corrupted, the Salvager removes the volume
+completely and records the removal in its log file,
+B</usr/afs/logs/SalvageLog>. Issue the C<vos release> or C<vos backup>
+command to create the read-only or backup volume again.
+
+=item *
+
+If the volume header is intact, the Salvager skips the volume
+(does not check for corruption in the contents). However, if the
+File Server notices corruption as it initializes, it sometimes
+refuses to attach the volume or bring it online. In this case, it
+is simplest to remove the volume by issuing the C<vos remove> or C<vos
+zap> command. Then issue the C<vos release> or C<vos backup> command to
+create it again.
+
+=back
+
+Use the indicated arguments to salvage a specific number of volumes:
+
+=over
+
+=item *
+
+To process all volumes on a file server machine, provide the
+B<-server> argument and the B<-all> flag. No volumes on the machine are
+accessible to Cache Managers during the salvage operation, because
+the BOS Server stops the File Server and Volume Server processes
+while the Salvager runs. The BOS Server automatically restarts
+them when the operation completes.
+
+=item *
+
+To process all volumes on one partition, provide the B<-server> and
+B<-partition> arguments. As for a salvage of the entire machine, no
+volumes on the machine are accessible to Cache Managers during the
+salvage operation. The BOS Server automatically restarts the File
+Server and Volume Server when the operation completes.
+
+=item *
+
+To salvage only one read/write volume, combine the B<-server>,
+B<-partition>, and B<-volume> arguments. Only that volume is
+inaccessible to Cache Managers, because the BOS Server does not
+shutdown the File Server and Volume Server processes during the
+salvage of a single volume. Do not name a read-only or backup
+volume with the B<-volume> argument. Instead, remove the volume,
+using the C<vos remove> or C<vos zap> command. Then create a new copy of
+the volume with the C<vos release> or C<vos backup> command.
+
+=back
+
+During the salvage of an entire machine or partition, the C<bos status>
+command reports the fs process's auxiliary status as C<Salvaging file
+system>.
+
+The Salvager always writes a trace to the B</usr/afs/logs/SalvageLog>
+file on the file server machine where it runs. To record the trace in
+another file as well (either in AFS or on the local disk of the
+machine where the C<bos salvage> command is issued), name the file with
+the B<-file> argument. To display the trace on the standard output stream
+as it is written to the B</usr/afs/logs/SalvageLog> file, include the
+B<-showlog> flag.
+
+By default, multiple Salvager subprocesses run in parallel: one for
+each partition up to four, and four subprocesses for four or more
+partitions. To increase or decrease the number of subprocesses running
+in parallel, provide a positive integer value for the B<-parallel>
+argument.
+
+If there is more than one server partition on a physical disk, the
+Salvager by default salvages them serially to avoid the inefficiency
+of constantly moving the disk head from one partition to another.
+However, this strategy is often not ideal if the partitions are
+configured as logical volumes that span multiple disks. To force the
+Salvager to salvage logical volumes in parallel, provide the string
+all as the value for the B<-parallel> argument. Provide a positive
+integer to specify the number of subprocesses to run in parallel (for
+example, B<-parallel 5all> for five subprocesses), or omit the integer to
+run up to four subprocesses, depending on the number of logical
+volumes being salvaged.
+
+The Salvager creates temporary files as it runs, by default writing
+them to the partition it is salvaging. The number of files can be
+quite large, and if the partition is too full to accommodate them, the
+Salvager terminates without completing the salvage operation (it
+always removes the temporary files before exiting). Other Salvager
+subprocesses running at the same time continue until they finish
+salvaging all other partitions where there is enough disk space for
+temporary files. To complete the interrupted salvage, reissue the
+command against the appropriate partitions, adding the B<-tmpdir>
+argument to redirect the temporary files to a local disk directory
+that has enough space.
+
+The B<-orphans> argument controls how the Salvager handles orphaned files
+and directories that it finds on server partitions it is salvaging. An
+I<orphaned> element is completely inaccessible because it is not
+referenced by the vnode of any directory that can act as its parent
+(is higher in the filespace). Orphaned objects occupy space on the
+server partition, but do not count against the volume's quota.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the file server machine on which to salvage volumes.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-partition> I<salvage partition>
+
+Specifies a single partition on which to salvage all volumes.
+Provide the complete partition name (for example B</vicepa>) or
+one of the following abbreviated 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
+
+=item B<-volume> I<salvage volume number or volume name>
+
+Specifies the name or volume ID number of a read/write volume
+to salvage. The B<-partition> argument must be provided along with
+this one.
+
+=item B<-file> I<salvage log output file>
+
+Specifies the complete pathname of a file into which to write a
+trace of the salvage operation, in addition to the
+B</usr/afs/logs/SalvageLog> file on the server machine. If the
+file pathname is local, the trace is written to the specified
+file on the local disk of the machine where the C<bos salvage>
+command is issued. If the B<-volume> argument is included, the
+file can be in AFS, though not in the volume being salvaged. Do
+not combine this argument with the B<-showlog> flag.
+
+=item B<-all>
+
+Salvages all volumes on all of the partitions on the machine
+named by the B<-server> argument.
+
+=item B<-showlog>
+
+Displays the trace of the salvage operation on the standard
+output stream, as well as writing it to the
+B</usr/afs/logs/SalvageLog> file. Do not combine this flag with
+the B<-file> argument.
+
+=item B<-parallel> I<# of max parallel partition salvaging>
+
+Specifies the maximum number of Salvager subprocesses to run in
+parallel. Provide one of three values:
+
+=over
+
+=item *
+
+An integer from the range B<1> to B<32>. A value of B<1> means that a
+single Salvager process salvages the partitions sequentially.
+
+=item *
+
+The string C<all> to run up to four Salvager subprocesses in
+parallel on partitions formatted as logical volumes that span
+multiple physical disks. Use this value only with such
+logical volumes.
+
+=item *
+
+The string C<all> followed immediately (with no intervening
+space) by an integer from the range B<1> to B<32>, to run the
+specified number of Salvager subprocesses in parallel on
+partitions formatted as logical volumes. Use this value only
+with such logical volumes.
+
+=back
+
+The BOS Server never starts more Salvager subprocesses than
+there are partitions, and always starts only one process to
+salvage a single volume. If this argument is omitted, up to
+four Salvager subprocesses run in parallel.
+
+=item B<-tmpdir> I<directory to place tmp files>
+
+Specifies the full pathname of a local disk directory to which
+the Salvager process writes temporary files as it runs. If this
+argument is omitted, or specifies an ineligible or nonexistent
+directory, the Salvager process writes the files to the
+partition it is currently salvaging.
+
+=item B<-orphans> I<ignore | remove | attach>
+
+Controls how the Salvager handles orphaned files and
+directories. Choose one of the following three values:
+
+=over
+
+=item B<ignore>
+
+Leaves the orphaned objects on the disk, but prints a
+message to the B</usr/afs/logs/SalvageLog> file reporting
+how many orphans were found and the approximate number of
+kilobytes they are consuming. This is the default if the
+B<-orphans> argument is omitted.
+
+=item B<remove>
+
+Removes the orphaned objects, and prints a message to the
+B</usr/afs/logs/SalvageLog> file reporting how many orphans
+were removed and the approximate number of kilobytes they
+were consuming.
+
+=item B<attach>
+
+Attaches the orphaned objects by creating a reference to
+them in the vnode of the volume's root directory. Since
+each object's actual name is now lost, the Salvager
+assigns each one a name of the following form:
+
+B<_ _ORPHANFILE_ _.>I<index> for files
+
+B<_ _ORPHANDIR_ _.>I<index> for directories
+
+where I<index> is a two-digit number that uniquely
+identifies each object. The orphans are charged against
+the volume's quota and appear in the output of the C<ls>
+command issued against the volume's root directory.
+
+=back
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command salvages all volumes on the B</vicepd> partition of
+the machine B<db3.abc.com>:
+
+ bos salvage -server db3.abc.com -partition /vicepd
+
+The following command salvages the volume with volume ID number
+536870988 on partition B</vicepb> of the machine B<fs2.abc.com>:
+
+ bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988
+
+The following command salvages all volumes on the machine B<fs4.abc.com>.
+Six Salvager processes run in parallel rather than the default four.
+
+ bos salvage -server fs4.abc.com -all -parallel 6
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Running this command can result in data loss if the Salvager process
+can repair corruption only by removing the offending data. Consult the
+IBM AFS Administration Guide for more information.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<SalvageLog(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<salvager(1)>,
+L<vos_backup(1)>,
+L<vos_release(1)>,
+L<vos_remove(1)>,
+L<vos_zap(1)>,
+IBM AFS Administration Guide
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos setauth - Sets authorization checking requirements for all server processes
+
+=head1 SYNOPSIS
+
+bos setauth B<-server> I<machine name>
+B<-authrequired> I<on or off: authentication required for admin requests>
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos seta B<-s> I<machine name>
+B<-a> I<on or off: authentication required for admin requests>
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos setauth> command enables or disables authorization checking on
+the server machine named by the B<-server> argument. When authorization
+checking is enabled (the normal case), the AFS server processes
+running on the machine verify that the issuer of a command meets its
+privilege requirements. When authorization checking is disabled,
+server processes perform any action for anyone, including the
+unprivileged user B<anonymous>; this security exposure precludes
+disabling of authorization checking except during installation or
+emergencies.
+
+To indicate to the server processes that authorization checking is
+disabled, the BOS Server creates the zero-length file
+B</usr/afs/local/NoAuth> on its local disk. All AFS server processes
+constantly monitor for the B<NoAuth> file's presence and do not check for
+authorization when it is present. The BOS Server removes the file when
+this command is used to reenable authorization checking.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to enable or disable
+authorization checking. Identify the machine by IP address or
+its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+=item B<-authrequired> I<on or off: authentication required for admin requests>
+
+Enables authorization checking if the value is C<on>, or disables
+it if the value is C<off>.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example disables authorization checking on the machine
+B<fs7.abc.com>:
+
+ bos setauth -server fs7.abc.com -authrequired off
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Do not create the B<NoAuth> file directly, except when directed by
+instructions for dealing with emergencies (doing so requires being
+logged in as the local superuser B<root>). Use this command instead.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<KeyFile(1)>,
+L<NoAuth(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_restart(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos setcellname - Sets the cell's name in the B</usr/afs/etc/ThisCell> and
+B</usr/afs/etc/CellServDB> files
+
+=head1 SYNOPSIS
+
+bos setcellname B<-server> I<machine name> B<-name> I<cell name>
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos setc B<-s> I<machine name> B<-n> I<cell name> [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos setcellname> command establishes the cell's name and makes the
+server machine named by the B<-server> argument a member of it, by
+recording the value of the B<-name> argument in two files which it
+creates on the local disk:
+
+=over
+
+=item *
+
+B</usr/afs/etc/ThisCell>
+
+=item *
+
+B</usr/afs/etc/CellServDB>. The cell name appears on the first line
+in the file, preceded by the required > symbol. The machine name
+specified with the B<-server> argument appears on the second line
+along with its IP address as obtained from the cell's naming
+service. The machine is thus designated as the cell's first
+database server machine.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to set the cell name in
+the B<ThisCell> and B<CellServDB> file. It is always the first
+machine installed in a cell. Identify the machine by IP address
+or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+=item B<-name> I<cell name>
+
+Defines the cell name, using standard Internet domain name
+format (the actual domain name is usually appropriate).
+Examples are B<abc.com> for the ABC Corporation and B<stateu.edu> for
+the State University. It must match the value of the B<-cell>
+argument, if that is provided.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command defines the cell name B<abc.com> in the B<ThisCell>
+and B<CellServDB> files on the machine B<fs1.abc.com> as it is installed as
+the cell's first server machine.
+
+ bos setcellname -server fs1.abc.com -name abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+Authorization checking is normally turned off during installation,
+which is the only recommended time to use this command; in this case
+no privilege is required. If authorization checking is turned on, the
+issuer must be listed in the B</usr/afs/etc/UserList> file on the machine
+named by the B<-server> argument, or must be logged in as the local
+superuser B<root> if the B<-localauth> flag is included.
+
+=head1 CAVEATS
+
+Issue this command only when the installing the cell's first AFS
+server machine. The IBM AFS Quick Beginnings explains how to copy over
+the B<ThisCell> and B<CellServDB> files from this or another appropriate
+machine during installation of additional server machines.
+
+Be sure to choose a satisfactory cell name when issuing this command,
+because changing a cell's name is very complicated; for one thing, it
+requires changing every password in the Authentication Database.
+Consult the IBM AFS Administration Guide for advice on choosing a cell
+name. If changing the cell's name is absolutely necessary, contact AFS
+Product Support for complete instructions.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_server_version(1)>,
+L<KeyFile(1)>,
+L<ThisCell_server_version(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+IBM AFS Quick Beginnings,
+IBM AFS Administration Guide
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos setrestart - Sets the date and time at which the BOS Server restarts processes
+
+=head1 SYNOPSIS
+
+bos setrestart B<-server> I<machine name> B<-time> I<time to restart server>
+[B<-general>] [B<-newbinary>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos setr B<-s> I<machine name> B<-t> I<time to restart server> [B<-g>] [B<-ne>]
+[B<-c> I<cell name>] [B<-no>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos setrestart> command records in the B</usr/afs/local/BosConfig>
+file the times at which the BOS Server running on the server machine
+named by the B<-server> argument performs two types of restarts:
+
+=over
+
+=item *
+
+A I<general restart>. By default, once per week the BOS Server
+restarts itself and then any AFS process marked with the C<Run>
+status flag in the B<BosConfig> file (equivalent in effect to issuing
+the C<bos restart> command with the B<-bosserver> flag). The default
+setting is 4:00 a.m. each Sunday morning.
+
+=item *
+
+A I<binary restart>. By default, once per day the BOS Server restarts
+any currently running process for which the timestamp on the
+binary file in the B</usr/afs/bin> directory is later than the time
+the process last started or restarted. The default is 5:00 B<a.m>.
+each day.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to set a new restart
+time. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-time> I<time to restart server>
+
+Specifies the restart time. By convention the general restart
+is defined as weekly (specifies both a day and a time), and the
+binary restart is defined as daily (specifies only a time).
+However, it is acceptable to define a daily general restart or
+weekly binary restart.
+
+There are four acceptable values for either type of restart
+setting:
+
+=over
+
+=item *
+
+The string C<never>, which directs the BOS Server never to
+perform the indicated type of restart.
+
+=item *
+
+The string C<now>, which directs the BOS Server to perform the
+restart immediately and never again.
+
+=item *
+
+A time of day (the conventional type of value for the binary
+restart time). Separate the hours and minutes with a colon
+(I<hh>:I<MM>), and use either 24-hour format, or a value in the
+range from B<1:00> through B<12:59> with the addition of B<am> or B<pm>.
+For example, both B<14:30> and B<"2:30 pm"> indicate 2:30 in the
+afternoon. Surround this parameter with double quotes (B<" ">)
+if it contains a space.
+
+=item *
+
+A day of the week and time of day, separated by a space and
+surrounded with double quotes (B<" ">). This is the conventional
+type of value for the general restart. For the day, provide
+either the whole name or the first three letters, all in
+lowercase letters (C<sunday> or C<sun>, C<thursday> or C<thu>, and so
+on). For the time, use the same format as when specifying the
+time alone.
+
+=back
+
+If desired, precede a time or day and time definition with the
+string C<every> or C<at>. These words do not change the meaning, but
+possibly make the output of the C<bos getrestart> command easier
+to understand.
+
+=item B<-general>
+
+Sets the general restart time.
+
+=item B<-newbinary>
+
+Sets the binary restart time.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the general restart time on the machine
+B<fs4.abc.com> to Saturday at 3:30 am.
+
+ bos setrestart -server fs4.abc.com -time "sat 3:30" -general
+
+The following command sets the binary restart time on the machine
+B<fs6.abc.com> to 11:45 pm.
+
+ bos setrestart -server fs6.abc.com -time 23:45 -newbinary
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 CAVEATS
+
+Restarting a process makes it unavailable for a period of time. The B<fs>
+process has potentially the longest outage, depending on how many
+volumes the file server machine houses (the File Server and Volume
+Server reattach each volume when they restart). The default settings
+are designed to coincide with periods of low usage, so that the
+restarts disturb the smallest possible number of users.
+
+If the setting specified with the B<-time> argument is within one hour of
+the current time, the BOS Server does not restart any processes until
+the next applicable opportunity (the next day for binary restarts, or
+the next week for general restarts).
+
+The command changes only one type of restart setting at a time; issue
+the command twice to change both settings.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos shutdown - Stops a process without changing its status flag in the
+B</usr/afs/local/BosConfig> file
+
+=head1 SYNOPSIS
+
+bos shutdown B<-server> I<machine name> [B<-instance> I<instances> [I<instances> ...]] [B<-wait>]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos sh B<-s> I<machine name> [B<-i> I<instances> [I<instances> ...]] [B<-w>]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos shutdown> command stops, on the server machine named by the
+B<-server> argument, either
+
+=over
+
+=item *
+
+All of the currently running AFS server processes, except the BOS
+Server
+
+=item *
+
+Only the processes specified by the B<-instance> argument
+
+=back
+
+This command does not change a process's status flag in the
+B</usr/afs/local/BosConfig> file, but only in the BOS Server's memory. To
+stop a process and change its B<BosConfig> status flag, use the C<bos stop>
+command instead.
+
+Once stopped with this command, a process does not run again until an
+administrator starts it by using the C<bos start>, C<bos startup>, or C<bos
+restart> command, or until the BOS Server restarts (assuming that the
+process's B<BosConfig> status flag is C<Run>).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to stop processes.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<instances> [I<instances> ...]
+
+Names each process to stop. Use the process name assigned with
+the B<-instance> argument to the C<bos create> command. The output
+from the C<bos status> command lists the names. Omit this argument
+to stop all processes other than the BOS Server.
+
+=item B<-wait>
+
+Delays the return of the command shell prompt until all
+processes actually stop. If this argument is omitted, the
+prompt returns almost immediately even if all processes are not
+stopped.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command stops all processes other than the BOS Server on
+the machine B<fs3.abc.com>.
+
+ bos shutdown fs3.abc.com
+
+The following command stops the B<upserver> process (server portion of
+the Update Server) on the machine B<fs5.abc.com>.
+
+ bos shutdown -server fs5.abc.com -instance upserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_restart(1)>,
+L<bos_start(1)>,
+L<bos_startup(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos start - Starts a process after setting its status flag in the
+B</usr/afs/local/BosConfig> file
+
+=head1 SYNOPSIS
+
+bos start B<-server> I<machine name> B<-instance> I<server process name> [I<server process name> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos start B<-s> I<machine name> B<-i> I<server process name> [I<server process name> ...]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos start> command sets the status flag for each process specified
+by the B<-instance> argument to Run in the B</usr/afs/local/BosConfig> file
+and in the BOS Server's memory on the server machine named by the
+B<-server> argument, then starts it. If the process is already running,
+the command's only effect is to guarantee that the status flag is Run;
+it does not restart the process.
+
+To start a process without changing its status flag in the B<BosConfig>
+file, use the C<bos startup> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to start processes.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<server process name> [I<server process name> ...]
+
+Names each process to start. Use the process name assigned with
+the B<-instance> argument to the C<bos create> command. The output
+from the C<bos status> command lists the names.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command changes the status flag for the B<upclientbin> and
+B<upclientetc> processes to C<Run> in the B<BosConfig> file on the machine
+B<fs6.abc.com> and starts them running.
+
+ bos start -server fs6.abc.com -instance upclientbin upclientetc
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_startup(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos startup - Starts a process without changing its status flag in the
+B</usr/afs/local/BosConfig> file
+
+=head1 SYNOPSIS
+
+bos startup B<-server> I<machine name> [B<-instance> I<instances> [I<instances> ...]]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos startu B<-s> I<machine name> [B<-i> I<instances> [I<instances> ...]]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos startup> command starts, on the server machine named by the
+B<-server> argument, either
+
+=over
+
+=item *
+
+All AFS server processes not currently running but marked with the
+C<Run> status flag in the B</usr/afs/local/BosConfig> file
+
+=item *
+
+Each process specified by B<-instance> argument, even if its status
+flag in the B<BosConfig> file is C<NotRun>.
+
+=back
+
+To start a process and set its B<BosConfig> status flag to C<Run>, use the
+C<bos start> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to start processes.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<instances> [I<instances> ...]
+
+Names each process to start. Use the process name assigned with
+the B<-instance> argument to the C<bos create> command. The output
+from the C<bos status> command lists the names.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command starts all processes marked with status flag C<Run>
+in the B<BosConfig> file on the machine B<fs3.abc.com> that are not
+currently running.
+
+ bos startup fs3.abc.com
+
+The following command starts the B<buserver>, B<kaserver>, B<ptserver>, and
+B<vlserver> processes running on the machine B<db2.abc.com>, even if their
+status flags in the B<BosConfig> file are C<NotRun>.
+
+ bos startup -server db2.abc.com -instance buserver kaserver ptserver vlserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_start(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos status - Displays the status of server processes
+
+=head1 SYNOPSIS
+
+bos status B<-server> I<machine name> [B<-instance> I<server process name> [I<server process name> ...]]
+[B<-long>] [B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos stat B<-s> I<machine name> [B<-i> I<server process name> [I<server process name> ...]]
+[B<-lon>] [B<-c> I<cell name>] [B<-n>] [B<-loc>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos status> command reports the status of processes on the server
+machine named by the B<-server> argument, either
+
+=over
+
+=item *
+
+All of the AFS server processes listed in the
+B</usr/afs/local/BosConfig> file
+
+=item *
+
+Only these processes named by the B<-instance> argument
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine for which to report server process
+status. Identify the machine by IP address or its host name
+(either fully-qualified or abbreviated unambiguously). For
+details, see the introductory reference page for the C<bos>
+command suite.
+
+=item B<-instance> I<server process name> [I<server process name> ...]
+
+Names each process for which to report status. Use the process
+name assigned with the B<-instance> argument to the C<bos> command.
+The output from the C<bos status> command lists the names.
+
+=item B<-long>
+
+Produces more detailed status information.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output for a process includes at least one line, which reports one
+of the following as the process's current status:
+
+=over
+
+=item *
+
+C<currently running normally>. The process's status flag in the
+B<BosConfig> file is C<Run>. For B<cron> entries, this message indicates
+only that the command is scheduled to run, not necessarily that it
+was executing when the C<bos status> command was issued.
+
+=item *
+
+C<disabled>. The process is not running, and its B<BosConfig> status
+flag is C<NotRun>.
+
+=item *
+
+C<temporarily disabled>. The process is not running although its
+status flag in the B<BosConfig> file is C<Run>. Either an administrator
+used the C<bos shutdown> command to stop it, or the
+BOS Server stopped trying to restart it after numerous failed
+attempts. In the second case, the auxiliary message is C<stopped for
+too many errors>.
+
+=item *
+
+C<temporarily enabled>. The process is running although its status
+flag in the B<BosConfig> file is C<NotRun>. An administrator has used
+the C<bos startup> command to start it.
+
+=back
+
+If one of the following special circumstances applies to the process,
+the indicated message appears in its entry:
+
+=over
+
+=item *
+
+C<has core file>. The process failed and created a core file in the
+B</usr/afs/logs> directory. If the BOS Server was able to restart the
+process after the failure, the primary status is C<currently running
+normally>.
+
+=item *
+
+C<stopped for too many errors>. The reason for the primary status
+C<temporarily disabled> is that the BOS Server's attempts to restart
+the process all failed.
+
+=back
+
+The entry for the B<fs> process always includes a second line to report
+the process's C<Auxiliary status>, which is one of the following:
+
+=over
+
+=item *
+
+C<file server running>. The File Server and Volume Server components
+of the File Server process are running normally.
+
+=item *
+
+C<salvaging file system>. The Salvager is running, so the File Server
+and Volume Server are temporarily disabled. The BOS Server
+restarts them as soon as the Salvager is finished.
+
+=back
+
+The entry for a B<cron> process includes an C<Auxiliary status> that reports
+when the command will next execute.
+
+If the B<-long> flag is used, each entry includes the following
+additional information:
+
+=over
+
+=item *
+
+The process's type (C<simple>, C<fs>, or C<cron>).
+
+=item *
+
+The day and time the process last started or restarted.
+
+=item *
+
+The number of C<proc starts>, which is how many times the BOS Server
+has started or restarted the process since it started itself.
+
+=item *
+
+The C<Last exit> time when the process (or one of the component
+processes in the B<fs> process) last terminated. This line does not
+appear if the process has not terminated since the BOS Server
+started.
+
+=item *
+
+The C<Last error exit> time when the process (or one of the component
+processes in the B<fs> process) last failed due to an error. A
+further explanation such as C<due to shutdown request> sometimes
+appears. This line does not appear if the process has not failed
+since the BOS Server started.
+
+=item *
+
+Each command that the BOS Server invokes to start the process, as
+specified by the B<-cmd> argument to the C<bos create> command.
+
+=item *
+
+The pathname of the notifier program that the BOS Server invokes
+when the process terminates (if any), as specified by the
+B<-notifier> argument to the C<bos create> command.
+
+=back
+
+If the B<-long> flag is provided and the BOS Server discovers that the
+mode bits on files and subdirectories in the local B</usr/afs> directory
+differ from the expected values, it prints the following warning
+message:
+
+ Bosserver reports inappropriate access on server directories
+
+The following chart summarizes the expected mode bit settings. A
+question mark indicates that the BOS Server does not check that bit.
+
+ /usr/afs drwxr?xr-x
+ /usr/afs/backup drwx???---
+ /usr/afs/bin drwxr?xr-x
+ /usr/afs/db drwx???---
+ /usr/afs/etc drwxr?xr-x
+ /usr/afs/etc/KeyFile -rw????---
+ /usr/afs/etc/UserList -rw?????--
+ /usr/afs/local drwx???---
+ /usr/afs/logs drwxr?xr-x
+
+=head1 EXAMPLES
+
+The following example command displays the status of processes on the
+machine fs3.abc.com:
+
+ bos status fs3.abc.com
+ Instance buserver, currently running normally.
+ Instance kaserver, currently running normally.
+ Instance ptserver, currently running normally.
+ Instance vlserver, currently running normally.
+ Instance fs, has core file, currently running normally.
+ Auxiliary status is: file server running.
+ Instance upserver, currently running normally.
+ Instance runntp, currently running normally.
+
+The following example command displays a detailed status report for
+the fs and ptserver processes on the machine fs1.abc.com.
+
+ bos status -server fs1.abc.com -instance fs ptserver -long
+ Instance fs, (type is fs), currently running normally.
+ Auxiliary status is: file server running.
+ Process last started at Wed Jan 7 5:34:49 1998 (3 proc starts)
+ Last exit at Wed Jan 7 5:34:49 1998
+ Last error exit at Wed Jan 7 5:34:49 1998, due to shutdown
+ request
+ Command 1 is '/usr/afs/bin/fileserver'
+ Command 2 is '/usr/afs/bin/volserver'
+ Command 3 is '/usr/afs/bin/salvager'
+ Instance ptserver, (type is simple) currently running normally.
+ Process last started at Tue Jan 6 8:29:19 1998 (1 proc starts)
+ Command 1 is '/usr/afs/bin/ptserver'
+
+=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<BosConfig(1)>,
+L<KeyFile(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_shutdown(1)>,
+L<bos_startup(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos stop - Stops a process after changing its status flag in the
+B</usr/afs/local/BosConfig> file
+
+=head1 SYNOPSIS
+
+bos stop B<-server> I<machine name> B<-instance> I<server process name> [I<server process name> ...]
+[B<-wait>] [B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos sto B<-s> I<machine name> B<-i> I<server process name> [I<server process name> ...]
+[B<-w>] [B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos stop> command sets the status flag for each process specified
+with the B<-instance> argument to C<NotRun> in the B</usr/afs/local/BosConfig>
+file on the server machine named by the B<-server> argument, then stops
+it.
+
+To stop a process without changing its B<BosConfig> status flag, use the
+C<bos shutdown> command instead.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the server machine on which to stop processes.
+Identify the machine by IP address or its host name (either
+fully-qualified or abbreviated unambiguously). For details, see
+the introductory reference page for the C<bos> command suite.
+
+=item B<-instance> I<server process name> [I<server process name> ...]
+
+Names each process to stop. Use the process name assigned with
+the B<-instance> argument to the C<bos create> command. The output
+from the C<bos status> command lists the names.
+
+=item B<-wait>
+
+Delays the return of the command shell prompt until all
+processes actually stop. If this argument is omitted, the
+prompt returns almost immediately even if all processes are not
+stopped.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command stops the B<upserver> and B<runntp> on the
+machine B<fs7.abc.com>.
+
+ bos stop -server fs7.abc.com -instance upserver runntp
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_shutdown(1)>,
+L<bos_status(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bos uninstall - Reverts to the former version of a process's binary file
+
+=head1 SYNOPSIS
+
+bos uninstall B<-server> I<machine name> B<-file> I<files to uninstall> [I<files to uninstall> ...]
+[B<-dir> I<destination dir>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-localauth>] [B<-help>]
+
+bos u B<-s> I<machine name> B<-f> I<files to uninstall> [I<files to uninstall> ...] [B<-d> I<destination dir>]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<bos uninstall> command replaces each binary file specified by the
+B<-file> argument with its C<.BAKversion> on the server machine named by the
+B<-server> argument, which is normally the binary distribution machine
+for its CPU/operating system type. It also changes the extension on
+the current C<.OLD> version (if any) to C<.BAK>. Each binary file must
+reside in the local B</usr/afs/bin> directory unless the B<-dir> argument
+names an alternate directory.
+
+To start using the reverted binary immediately, issue the C<bos restart>
+command. Otherwise, the BOS Server automatically restarts the process
+at the time defined in the B</usr/afs/local/BosConfig> file; use the C<bos
+getrestart> command to display the time and the C<bos setrestart> time to
+set it.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-server> I<machine name>
+
+Indicates the binary distribution machine on which to revert to
+the C<.BAK> version of binaries. Identify the machine by IP
+address or its host name (either fully-qualified or abbreviated
+unambiguously). For details, see the introductory reference
+page for the C<bos> command suite.
+
+If the machine is not a binary distribution machine and is
+running an B<upclientbin> process, then the files are overwritten
+the next time the B<upclientbin> process fetches the corresponding
+file from the distribution machine (by default within five
+minutes).
+
+=item B<-file> I<files to uninstall> [I<files to uninstall> ...]
+
+Names each binary file to replace with its C<.BAK> version.
+
+=item B<-dir> I<destination dir>
+
+Provides the complete pathname of the local disk directory
+containing each file named by the B<-file> argument. It is
+necessary only if the binaries are not in the B</usr/afs/bin>
+directory.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. Do not combine this
+argument with the B<-localauth> flag. For more details, see the
+introductory L<bos(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. Do
+not combine this flag with the B<-localauth> flag. For more
+details, see the introductory L<bos(1)> reference page.
+
+=item B<-localauth>
+
+Constructs a server ticket using a key from the local
+B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
+the ticket to the BOS Server during mutual authentication. Do
+not combine this flag with the B<-cell> or B<-noauth> options. For
+more details, see the introductory L<bos(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command overwrites the B</usr/afs/bin/kaserver>
+file on the machine B<fs4.abc.com> with its C<.BAKversion>, and the current
+C<.BAK> version by the C<.OLDversion>.
+
+ bos uninstall -server fs4.abc.com -file kaserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be listed in the B</usr/afs/etc/UserList> file on the
+machine named by the B<-server> argument, or must be logged onto a server
+machine as the local superuser B<root> if the B<-localauth> flag is
+included.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<KeyFile(1)>,
+L<UserList(1)>,
+L<bos(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(1)>,
+L<bos_setrestart(1)>,
+L<upclient(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+bosserver - Initializes the BOS Server
+
+=head1 SYNOPSIS
+
+bosserver [B<-noauth>] [B<-log>] [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<bosserver> command initializes the Basic OverSeer (BOS) Server
+(B<bosserver> process). In the conventional configuration, the binary
+file is located in the B</usr/afs/bin> directory on a file server
+machine.
+
+The BOS Server must run on every file server machine and helps to
+automate file server administration by performing the following tasks:
+
+=over
+
+=item *
+
+Monitors the other AFS server processes on the local machine, to
+make sure they are running correctly.
+
+=item *
+
+Automatically restarts failed processes, without contacting a
+human operator. When restarting multiple server processes
+simultaneously, the BOS Server takes interdependencies into
+account and initiates restarts in the correct order.
+
+=item *
+
+Processes commands from the B<bos> suite that administrators issue to
+verify the status of server processes, install and start new
+processes, stop processes either temporarily or permanently, and
+restart halted processes.
+
+=item *
+
+Manages system configuration information: the files that list the
+cell's server encryption keys, database server machines, and users
+privileged to issue commands from the B<bos> and B<vos> suites.
+
+=back
+
+The BOS Server logs a default set of important events in the file
+B</usr/afs/logs/BosLog>. To record the name of any user who performs a
+privileged B<bos> command (one that requires being listed in the
+B</usr/afs/etc/UserList> file), add the B<-log> flag. To display the
+contents of the B<BosLog> file, use the C<bos getlog> command.
+
+The first time that the BOS Server initializes on a server machine, it
+creates several files and subdirectories in the local B</usr/afs>
+directory, and sets their mode bits to protect them from unauthorized
+access. Each time it restarts, it checks that the mode bits still
+comply with the settings listed in the following chart. A question
+mark indicates that the BOS Server initially turns off the bit (sets
+it to the hyphen), but does not check it at restart.
+
+ /usr/afs drwxr?xr-x
+ /usr/afs/backup drwx???---
+ /usr/afs/bin drwxr?xr-x
+ /usr/afs/db drwx???---
+ /usr/afs/etc drwxr?xr-x
+ /usr/afs/etc/KeyFile -rw????---
+ /usr/afs/etc/UserList -rw?????--
+ /usr/afs/local drwx???---
+ /usr/afs/logs drwxr?xr-x
+
+If the mode bits do not comply, the BOS Server writes the following
+warning to the B<BosLog> file:
+
+ Bosserver reports inappropriate access on server directories
+
+However, the BOS Server does not reset the mode bits, so the
+administrator can set them to alternate values if desired (with the
+understanding that the warning message then appears at startup).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer,
+which is useful only when authorization checking is disabled on
+the server machine (for instance, during the installation of a
+file server machine.)
+
+=item B<-log>
+
+Records in the B</usr/afs/logs/BosLog> file the names of all users
+who successfully issue a privileged B<bos> command (one that
+requires being listed in the B</usr/afs/etc/UserList> file).
+
+=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 following command initializes the BOS Server and logs the names of
+users who issue privileged B<bos> commands.
+
+ bosserver -log &
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer most be logged onto a file 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<BosConfig(1)>,
+L<BosLog(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_exec(1)>,
+L<bos_getlog(1)>,
+L<bos_getrestart(1)>,
+L<bos_restart(1)>,
+L<bos_shutdown(1)>,
+L<bos_start(1)>,
+L<bos_startup(1)>,
+L<bos_status(1)>,
+L<bos_stop(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+buserver - Initializes the Backup Server
+
+=head1 SYNOPSIS
+
+buserver [B<-database> I<database directory>]
+[B<-cellservdb> I<cell configuration directory>]
+[B<-resetdb>] [B<-noauth>] [B<-smallht>]
+[B<-servers> I<ubik database servers> [I<ubik database servers> ...]]
+[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<buserver> command initializes the Backup Server, which runs on
+database server machines and maintains the Backup Database. In the
+conventional configuration, the binary file is located in the
+B</usr/afs/bin> directory on a file server machine.
+
+The C<buserver> command is not normally issued at the command shell
+prompt, but rather placed into a database server machine's
+B</usr/afs/local/BosConfig> file with the bos create command. If it is
+ever issued at the command shell prompt, the issuer must be logged
+onto a file server machine as the local superuser B<root>.
+
+As it initializes, the Backup Server process creates the two files
+that constitute the Backup Database, B<bdb.DB0> and B<bdb.DBSYS1>, in the
+B</usr/afs/db> directory if they do not already exist. The Backup
+Database houses information about volume sets and entries, the dump
+hierarchy, Tape Coordinators, and previously performed dump sets. Use
+the commands in the B<backup> suite to administer the database.
+
+The Backup Server records a trace of its activity in the
+B</usr/afs/logs/BackupLog> file. Use the C<bos getlog> command to display
+the contents of the file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-database> I<database directory>
+
+Specifies the pathname of an alternate directory for the Backup
+Database files, ending in a final slash (/). If this argument
+is not provided, the default is the B</usr/afs/db> directory.
+
+=item B<-cellservdb> I<cell configuration directory>
+
+Specifies the pathname of the directory from which the Backup
+Server reads in an alternate version of the B<CellServDB> file.
+This argument is mandatory for correct functioning when the
+Backup Server is running on a subset of the cell's database
+server machines that is not a majority of the machines listed
+in the standard B</usr/afs/etc/CellServDB> file (which the Backup
+Server consults if this argument is not provided). It is not
+appropriate in any other circumstances.
+
+=item B<-resetdb>
+
+Removes all of the information in the Backup Database files in
+the B</usr/afs/db> directory, leaving zero-length versions of
+them. The backup operator must recreate the configuration
+entries in the database (for volume sets, the dump hierarchy
+and so on) before performing backup operations.
+
+=item B<-noauth>
+
+Establishes an unauthenticated connection between the issuer
+and the Backup Server, in which the Backup Server treats the
+issuer as the unprivileged user B<anonymous>. It is useful only
+when authorization checking is disabled on the database server
+machine. In normal circumstances, the Backup Server allows only
+authorized (privileged) users to issue commands that affect or
+contact the Backup Database, and refuses to perform such an
+action even if the B<-noauth> flag is used.
+
+=item B<-smallht>
+
+Directs the Backup Server to use smaller internal hash tables
+for the Backup Database, which reduces memory requirements but
+can make data access take longer.
+
+=item B<-servers> I<ubik database servers> [I<ubik database servers> ...]
+
+Specifies the database server machines on which to start the
+Backup Server. Use this argument if running the Backup Server
+on a subset of the database server machines that is not a
+majority of the machines listed in the B</usr/afs/etc/CellServDB>
+file.
+
+=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 following example C<bos create> command creates a B<buserver> process on
+the file server machine B<fs3.abc.com>. It appears here on two lines only
+for legibility.
+
+ bos create -server fs3.abc.com -instance buserver \
+ -type simple -cmd /usr/afs/bin/buserver
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the superuser B<root> on a file server
+machine to issue the command at a command shell prompt. It is
+conventional instead to create and start the process by issuing the
+C<bos create> command.
+
+=head1 CAVEATS
+
+The B<buserver> process reserves port B<7021> for its use. Unexpected
+behavior can occur if another process tries to reserve this port while
+the B<buserver> process is running.
+
+=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<BackupLog(1)>,
+L<BosConfig(1)>,
+L<CellServDB_server_version(1)>,
+L<bdb.DB0> and L<bdb.DBSYS1>,
+L<backup(1)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+butc - Initializes the Tape Coordinator process
+
+=head1 SYNOPSIS
+
+butc [B<-port> I<port offset>] [B<-debuglevel> I<0> | I<1> | I<2>]
+[B<-cell> I<cell name>] [B<-noautoquery>]
+[B<-localauth>] [B<-help>]
+
+butc [B<-p> I<port offset>] [B<-d> I<0> | I<1> | I<2>]
+[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<butc> command initializes a Tape Coordinator process on a Tape
+Coordinator machine, enabling an operator to direct Backup System
+requests to the associated tape device or backup data file. (The Tape
+Coordinator controls a backup data file if the B<FILE YES> instruction
+appears in the B</usr/afs/backup/CFG_>I<device_name> file that corresponds
+to the Tape Coordinator's entry in the B</usr/afs/backup/tapeconfig>
+file. For the sake of simplicity, the following discusses tape devices
+only.)
+
+It is conventional to start and run the Tape Coordinator in the
+foreground. In this case, it runs on its own connection, which is
+unavailable for any other use and must remain open the entire time the
+Tape Coordinator is to accept backup requests and while it is
+executing them. (When using a window manager, the connection
+corresponds to a separate command shell window.) The Tape Coordinator
+can run in the background if the B<CFG_>I<device_name> file is configured to
+eliminate any need for the Tape Coordinator to prompt the operator. In
+both the foreground and background, the Tape Coordinator writes
+operation traces and other output to the standard output stream on the
+connection over which it was started. Use the B<-debuglevel> argument to
+control the amount of information that appears. The Tape Coordinator
+also writes traces and error messages to two files in the local
+B</usr/afs/backup> directory:
+
+=over
+
+=item *
+
+The B<TE_>I<device_name> file records problems that the Tape Coordinator
+encounters as it executes backup operations.
+
+=item *
+
+The B<TL_>I<device_name> file records a trace of operations as well as
+the same errors written to the B<TE_>I<device_name> file.
+
+=back
+
+The Tape Coordinator creates the files automatically as it
+initializes. If there are existing files, the Tape Coordinator renames
+them with a B<.old> extension, overwriting the existing B<.old> files if
+they exist. It derives the I<device_name> part of the file names by
+stripping off the device name's B</dev/> prefix and replacing any other
+slashes with underscores. For example, the files are called B<TE_rmt_4m>
+and B<TL_rmt_4m> for a device called B</dev/rmt/4m>.
+
+By default, at the beginning of each operation the Tape Coordinator
+prompts for the operator to insert the first tape into the drive and
+press B<E<lt>ReturnE<gt>>. To suppress this prompt, include the B<-noautoquery> flag
+on the command line or the instruction B<AUTOQUERY NO> in the
+B</usr/afs/backup/CFG_>I<device_name> file. When the prompt is suppressed,
+the first required tape must be in the drive before a C<backup> command
+is issued. For subsequent tapes, the Tape Coordinator uses its normal
+tape acquisition routine: if the B</usr/afs/backup/CFG_>I<device_name> file
+includes a B<MOUNT> instruction, the Tape Coordinator invokes the
+indicated command; otherwise, it prompts the operator for the next
+tape.
+
+To stop the Tape Coordinator process, enter an interrupt signal such
+as B<E<lt>Ctrl-cE<gt>> over the dedicated connection (in the command shell
+window).
+
+To cancel a C<backup> operation that involves a tape before it begins
+(assuming the initial tape prompt has not been suppressed), enter the
+letter C<a> (for B<abort>) and press B<E<lt>ReturnE<gt>> at the Tape Coordinator's
+prompt for the first tape.
+
+Tape Coordinator operation depends on the correct configuration of
+certain files, as described in the following list:
+
+=over
+
+=item *
+
+The local B</usr/afs/backup/tapeconfig> file must include an entry
+for the Tape Coordinator that specifies its device name and port
+offset number, among other information; for details, see the
+L<tapeconfig(1)> reference page.
+
+=item *
+
+The port offset number recorded in the Tape Coordinator's entry in
+the Backup Database must match the one in the B<tapeconfig> file.
+Create the Backup Database entry by using the C<backup addhost>
+command.
+
+=item *
+
+The optional B</usr/afs/backup/CFG_>I<device_name> file can contain
+instructions for mounting and unmounting tapes automatically (when
+using a tape stacker or jukebox, for instance) or automating other
+aspects of the backup process. The I<device_name> part of the name is
+derived as described previously for the B<TE_>I<device_name> and
+B<TL_>I<device_name> files.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-port> I<port offset>
+
+Specifies the port offset number of the Tape Coordinator to
+initialize.
+
+=item B<-debuglevel> I<0> | I<1> | I<2>
+
+Controls the amount and type of messages the Tape Coordinator
+displays on the standard output stream. Provide one of three
+acceptable values:
+
+=over
+
+=item *
+
+B<0> to display the minimum level of detail required to describe
+Tape Coordinator operations, including prompts for tapes,
+messages that indicate the beginning and end of operations,
+and error messages. This is the default value.
+
+=item *
+
+B<1> to display the names of the volumes being dumped or
+restored as well as the information displayed at level 0.
+
+=item *
+
+B<2> to display all messages also being written to the
+B<TL_>I<device_name> log file.
+
+=back
+
+=item B<-cell> I<cell name>
+
+Names the cell in which the Tape Coordinator operates (the cell
+to which the file server machines that house affected volumes
+belong). If this argument is omitted, the Tape Coordinator runs
+in the local cell as defined in the local
+B</usr/vice/etc/ThisCell> file. Do not combine this flag with the
+B<-localauth> argument.
+
+=item B<-noautoquery>
+
+Suppresses the Tape Coordinator's prompt for insertion of the
+first tape needed for an operation. The operator must insert
+the tape into the drive before issuing the C<backup> command that
+initializes the operation.
+
+=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>. The C<butc> command interpreter presents the
+ticket, which never expires, to the Volume Server and Volume
+Location Server to use in mutual authentication.
+
+Do not combine this argument with the B<-cell> flag, and use it
+only when logged on to a server machine as the local superuser
+B<root>; client machines do not have B</usr/afs/etc/KeyFile> file.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command starts the Tape Coordinator with port offset B<7>
+at debug level B<1>, meaning the Tape Coordinator reports the names of
+volumes it is dumping or restoring.
+
+ butc -port 7 -debuglevel 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 a volume to be
+backed up. If the B<-localauth> flag is included, the issuer must instead
+be logged on to the Tape Coordinator machine as the local superuser
+B<root>. In addition, the issuer must be able to read and write to the
+log and configuration files in the local B</usr/afs/backup> directory.
+
+=head1 CAVEATS
+
+If the Tape Coordinator machine is an AIX machine, use the B<SMIT>
+utility to set the device's block size to 0 (zero), indicating
+variable block size. Otherwise, tape devices attached to machines
+running other operating systems sometimes cannot read tapes written on
+AIX machines. For instructions, see the IBM AFS Administration Guide
+chapter about configuring the Backup System.
+
+=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<KeyFile(1)>,
+L<TE_device_name(1)>,
+L<ThisCell_client_version(1)>,
+L<TL_device_name(1)>,
+L<UserList(1)>,
+L<tapeconfig(1)>,
+L<backup_addhost(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+dlog - Authenticates to the DCE Security Service
+
+=head1 SYNOPSIS
+
+dlog [B<-principal> I<user name>] [B<-cell> I<cell name>]
+[B<-password> I<user's password>] [B<-servers> I<servers> [I<servers> ...]]
+[B<-lifetime> I<ticket lifetime in hh:mm[:ss]>]
+[B<-setpag>] [B<-pipe>] [B<-help>]
+
+dlog [B<-pr> I<user name>] [B<-c> I<cell name>] [B<-pw> I<user's password>]
+[B<-ser> I<servers> [I<servers> ...]]
+[B<-l> I<ticket lifetime in hh:mm[:ss]>] [B<-set>] [B<-pi>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<dlog> command obtains DCE credentials for the issuer from the DCE
+Security Service in the cell named by the B<-cell> argument, and stores
+them on the AFS client machine on which the user issues the command.
+The AFS/DFS Migration Toolkit Protocol Translator processes running on
+machines in the DCE cell accept the credentials, which enables the
+user to access the DCE cell's filespace from the AFS client. The
+user's identity in the local file system is unchanged.
+
+If the issuer does not provide the B<-principal> argument, the C<dlog>
+command interpreter uses the user name under which the issuer is
+logged into the local file system. Provide the DCE password for the
+appropriate user name. As with the C<klog> command, the password does not
+cross the network in clear text (unless the issuer is logged into the
+AFS client from a remote machine).
+
+The credentials are valid for a lifetime equivalent to the smallest of
+the following, all but the last of which is defined by the DCE cell's
+Security Server:
+
+=over
+
+=item *
+
+The maximum certificate lifetime for the issuer's DCE account
+
+=item *
+
+The maximum certificate lifetime for the B<afs> principal's DCE
+account
+
+=item *
+
+The registry-wide maximum certificate lifetime
+
+=item *
+
+The registry-wide default certificate lifetime
+
+=item *
+
+The lifetime requested using the B<-lifetime> argument
+
+=back
+
+If the previous maximum certificate lifetime values are set to
+B<default-policy>, the maximum possible ticket lifetime is defined by the
+default certificate lifetime. Refer to the DCE vendor's administration
+guide for more information before setting any of these values.
+
+The AFS Cache Manager stores the ticket in a credential structure
+associated with the name of the issuer (or the user named by the
+B<-principal> argument. If the user already has a ticket for the DCE
+cell, the ticket resulting from this command replaces it in the
+credential structure.
+
+The AFS C<tokens> command displays the ticket obtained by the C<dlog>
+command for the server principal B<afs>, regardless of the principal to
+which it is actually granted. Note that the tokens command does not
+distinguish tickets for a DFS(TM) File Server from tickets for an AFS
+File Server.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-principal> I<user name>
+
+Specifies the DCE user name for which to obtain DCE
+credentials. If this option is omitted, the C<dlog> command
+interpreter uses the name under which the issuer is logged into
+the local file system.
+
+=item B<-cell> I<cell name>
+
+Specifies the DCE cell in which to authenticate. During a
+single login session on a given machine, a user can
+authenticate in multiple cells simultaneously, but can have
+only one ticket at a time for each cell (that is, it is
+possible to authenticate under only one identity per cell per
+machine). It is legal to abbreviate the cell name to the
+shortest form that distinguishes it from the other cells listed
+in the B</usr/vice/etc/CellServDB> file on the local client
+machine.
+
+If the issuer does not provide the B<-cell> argument, the C<dlog>
+command attempts to authenticate with the DCE Security Server
+for the cell defined by
+
+=over
+
+=item 1.
+
+The value of the environment variable AFSCELL on the local
+AFS client machine, if defined. The issuer can set the
+AFSCELL environment variable to name the desired DCE cell.
+
+=item 2.
+
+The cell name in the B</usr/vice/etc/ThisCell> file on the local
+AFS client machine. The machine's administrator can place the
+desired DCE cell's name in the file.
+
+=back
+
+=item B<-password> I<user's password>
+
+Specifies the password for the issuer (or for the user named by
+the B<-principal> argument). Using this argument is not
+recommended, because it makes the password visible on the
+command line. If this argument is omitted, the command prompts
+for the password and does not echo it visibly.
+
+=item B<-servers> I<explicit list of servers> ...
+
+Specifies a list of DFS database server machines running the
+Translator Server through which the AFS client machine can
+attempt to authenticate. Specify each server by hostname,
+shortened machine name, or IP address. If this argument is
+omitted, the C<dlog> command interpreter randomly selects a
+machine from the list of DFS Fileset Location (FL) Servers in
+the B</usr/vice/etc/CellServDB> file for the DCE cell specified by
+the B<-cell> argument. This argument is useful for testing when
+authentication seems to be failing on certain server machines.
+
+=item B<-lifetime> I<ticket lifetime in hh:mm[:ss]>
+
+Requests a ticket lifetime using the format I<hh>:I<mm>[:I<ss>] (hours,
+minutes, and optionally a number seconds between 00 and 59).
+For example, the value B<168:30> requests a ticket lifetime of 7
+days and 30 minutes, and B<96:00> requests a lifetime of 4 days.
+Acceptable values range from B<00:05> (5 minutes) to B<720:00> (30
+days). If this argument is not provided and no other
+determinants of ticket lifetime have been changed from their
+defaults, ticket lifetime is 10 hours.
+
+The requested lifetime must be smaller than any of the DCE
+cell's determinants for ticket lifetime; see the discussion in
+the preceding L</"DESCRIPTION"> section.
+
+=item B<-setpag>
+
+Creates a process authentication group (PAG) in which the newly
+created ticket is placed. If this flag is omitted, the ticket
+is instead associated with the issuers' local user ID (UID).
+
+=item B<-pipe>
+
+Suppresses any prompts that the command interpreter otherwise
+produces, including the prompt for the issuer's password.
+Instead, the command interpreter accepts the password via the
+standard input stream.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the C<dlog> command interpreter cannot contact a Translator Server, it
+produces a message similar to the following:
+
+ dlog: server or network not responding -- failed to contact
+ authentication service
+
+=head1 EXAMPLES
+
+The following command authenticates the issuer as B<cell_admin> in the
+B<dce.abc.com> cell.
+
+ dlog -principal cell_admin -cell dce.abc.com
+ Password: cell_admin's password
+
+In the following example, the issuer authenticates as B<cell_admin> to
+the B<dce.abc.com> cell and request a ticket lifetime of 100 hours. The
+C<tokens> command confirms that the user obtained DCE credentials as the
+user B<cell_admin>: the AFS ID is equivalent to the UNIX ID of B<1> assigned
+to B<cell_admin> in B<dce.abc.com> cell's DCE registry.
+
+ dlog -principal cell_admin -cell dce.abc.com -lifetime 100
+ Password: cell_admin's password
+
+
+ tokens
+ Tokens held by the Cache Manager:
+
+ User's (AFS ID 1) tokens for afs@dce.abc.com [Expires Jul 6 14:12]
+ User's (AFS ID 4758) tokens for afs@abc.com [Expires Jul 2 13:14]
+
+ --End of list--
+
+=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<dpass(1)>,
+L<klog(1)>,
+L<tokens(1)>,
+L<unlog(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+dpass - Returns the DCE password for a new DCE account
+
+=head1 SYNOPSIS
+
+dpass [B<-cell> I<original AFS cell name>] [B<-help>]
+
+dpass [B<-c> I<original AFS cell name>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<dpass> command returns the DCE password that an administrator
+assigned to the issuer when using the C<dm pass> command to migrate AFS
+user accounts into a DCE cell.
+
+The C<dpass> command, issued on an AFS client, requests the issuer's new
+DCE password from the AFS cell specified with the B<-cell> argument.
+
+The issuer must be authenticated as the AFS user whose AFS account was
+moved into DCE, and be able to provide the user's AFS password when
+prompted by the C<dpass> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> I<original AFS cell name>
+
+Specifies the name of the AFS cell from which the AFS account
+was moved into DCE and from which to fetch the new DCE
+password.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+By default, the C<dpass> command writes a message similar to the
+following to the standard output stream.
+
+ Please read the following message before entering your password.
+
+ This program will display your new, temporary DCE password on your
+ terminal, and you should change the assigned password as soon as
+ possible (from a DCE client). The program assumes that the AFS cell
+ uses the AFS Authentication Server and that an administrator used the
+ utilities in the AFS/DFS Migration Toolkit to migrate the account from
+ AFS to DCE. The password you enter should be the AFS password that was
+ in effect when your DCE account was created; this is not necessarily
+ the same password you have at the moment. The cell name (which you
+ may override with a command line option), must be the name of the AFS
+ cell from which the authentication information was taken.
+
+To suppress this message, set the DPASS_NO_MESSAGE environment
+variable. It is then possible to substitute a customized message if
+desired by using a script similar to the following example:
+
+ #! B</bin/csh>
+ echo "Start of customized message"
+ echo "Continuation of customized message"
+ .
+ .
+ .
+ echo "Conclusion of customized message"
+ setenv DPASS_NO_MESSAGE
+ dpass $*
+
+After the standard or customized message, if any, the C<dpass> command
+generates the following prompt for the original AFS password:
+
+ Original password for AFS cell cell:
+ Re-enter password to verify:
+
+If the AFS passwords match and are correct, the command reports the
+temporary DCE password in the following message.
+
+ The new DCE password is: Issuer's_temporary_DCE_password
+
+=head1 EXAMPLES
+
+The following example returns the DCE password of the issuer, whose
+AFS account is in the B<abc.com> cell. The DPASS_NO_MESSAGE variable has
+been set to suppress the standard message.
+
+ dpass
+ Original password for AFS cell abc.com: Issuer's_AFS_password
+ Re-enter password to verify: Issuer's_AFS_password
+ The new DCE password is: 8655--eg8e-dcdc-8157
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be authenticated as the AFS user for whom to display
+the corresponding DCE password.
+
+=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<dlog(1)>,
+C<dm pass> reference page in IBM AFS/DFS Migration Toolkit Administration Guide and Reference
+
+=cut
--- /dev/null
+=head1 NAME
+
+fileserver - Initializes the File Server component of the fs process
+
+=head1 SYNOPSIS
+
+fileserver [B<-d> I<debug level>] [B<-p> I<number of processes>]
+[B<-spare> I<number of spare blocks>]
+[B<-pctspare> I<percentage spare>] [B<-b> I<buffers>]
+[B<-l> I<large vnodes>] [B<-s> I<small nodes>]
+[B<-vc> I<volume cachesize>] [B<-w> I<call back wait interval>]
+[B<-cb> I<number of call backs>]
+[B<-banner> (print banner every 10 minutes)]
+[B<-novbc> (whole volume cbs disabled)]
+[B<-implicit> I<admin mode bits: rlidwka>]
+[B<-hr> I<number of hours between refreshing the host cps>]
+[B<-busyat> I<redirect clients when queue > n>]
+[B<-rxpck> I<number of rx extra packets>]
+[B<-rxdbg> (enable rx debugging)]
+[B<-rxdbge> (enable rxevent debugging)]
+[B<-m> I<min percentage spare in partition>]
+[B<-lock> (keep fileserver from swapping)]
+[B<-L> (large server conf)] [B<-S> (small server conf)]
+[B<-k> I<stack size>] [B<-realm> I<Kerberos realm name>]
+[B<-udpsize> I<size of socket buffer in bytes>]
+[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<fileserver> command initializes the File Server component of the B<fs>
+process. In the conventional configuration, its binary file is located
+in the B</usr/afs/bin> directory on a file server machine.
+
+The C<fileserver> command is not normally issued at the command shell
+prompt, but rather placed into a database server machine's
+B</usr/afs/local/BosConfig> file with the C<bos create> command. If it is
+ever issued at the command shell prompt, the issuer must be logged
+onto a file server machine as the local superuser B<root>.
+
+The File Server creates the B</usr/afs/logs/FileLog> log file as it
+initializes, if the file does not already exist. It does not write a
+detailed trace by default, but use the B<-d> option to increase the
+amount of detail. Use the C<bos getlog> command to display the contents
+of the log file.
+
+The command's arguments enable the administrator to control many
+aspects of the File Server's performance, as detailed in the L</"OPTIONS">
+section. By default the C<fileserver> command sets values for many
+arguments that are suitable for a medium-sized file server machine. To
+set values suitable for a small or large file server machine, use the
+B<-S> or B<-L> flag respectively. The following list describes the
+parameters and corresponding argument for which the C<fileserver> command
+sets default values, and L</"Table 1"> summarizes the setting for each of
+the three machine sizes.
+
+=over
+
+=item *
+
+The maximum number of lightweight processes (LWPs) the File Server
+uses to handle requests for data; corresponds to the B<-p> argument.
+The File Server always uses a minimum of 32 KB for these
+processes.
+
+=item *
+
+The maximum number of directory blocks the File Server caches in
+memory; corresponds to the B<-b> argument. Each cached directory
+block (buffer) consumes 2,092 bytes of memory.
+
+=item *
+
+The maximum number of large vnodes the File Server caches in
+memory for tracking directory elements; corresponds to the B<-l>
+argument. Each large vnode consumes 292 bytes of memory.
+
+=item *
+
+The maximum number of small vnodes the File Server caches in
+memory for tracking file elements; corresponds to the B<-s> argument.
+Each small vnode consumes 100 bytes of memory.
+
+=item *
+
+The maximum volume cache size, which determines how many volumes
+the File Server can cache in memory before having to retrieve data
+from disk; corresponds to the B<-vc> argument.
+
+=item *
+
+The maximum number of callback structures the File Server caches
+in memory; corresponds to the B<-cb> argument. Each callback
+structure consumes 16 bytes of memory.
+
+=item *
+
+The maximum number of B<Rx> packets the File Server uses; corresponds
+to the B<-rxpck> argument. Each packet consumes 1544 bytes of memory.
+
+=back
+
+=head2 Table 1
+
+B<File Server configuration parameters>
+
+ -------------------------------------------------
+ Parameter | Configuration:
+ (Argument) | Small | Medium | Large
+ | (-S) | (default) | (-L)
+ -------------------------------------------------
+ Number of | 6 | 9 | 12
+ LWPs (-p) | | |
+ -------------------------------------------------
+ Number of cached | 70 | 90 | 120
+ directory blocks | | |
+ (-b) | | |
+ -------------------------------------------------
+ Number of cached | 200 | 400 | 600
+ large vnodes (-l) | | |
+ -------------------------------------------------
+ Number of cached | 200 | 400 | 600
+ small vnodes (-s) | | |
+ -------------------------------------------------
+ Maximum volume | 200 | 400 | 600
+ cache size (-vc) | | |
+ -------------------------------------------------
+ Number of | 20,000 | 60,000 | 64,000
+ callbacks (-cb) | | |
+ -------------------------------------------------
+ Number of Rx | 100 | 150 | 200
+ packets (-rxpck) | | |
+ -------------------------------------------------
+
+To override any of the values, provide the indicated argument (which
+can be combined with the B<-S> or B<-L> flag).
+
+The amount of memory required for the File Server varies. The
+approximate default memory usage is 751 KB when the B<-S> flag is used
+(small configuration), 1.1 MB when all defaults are used (medium
+configuration), and 1.4 MB when the B<-L> flag is used (large
+configuration). If additional memory is available, increasing the
+value of the B<-cb> and B<-vc> arguments can improve File Server performance
+most directly.
+
+By default, the File Server allows a volume to exceed its quota by 1
+MB when an application is writing data to an existing file in a volume
+that is full. The File Server still does not allow users to create new
+files in a full volume. To change the default, use one of the
+following arguments:
+
+=over
+
+=item *
+
+Set the B<-spare> argument to the number of extra kilobytes that the
+File Server allows as overage. A value of B<0> allows no overage.
+
+=item *
+
+Set the B<-pctspare> argument to the percentage of the volume's quota
+the File Server allows as overage.
+
+=back
+
+By default, the File Server implicitly grants the B<a> (B<administer>) and B<l>
+(B<lookup>) permissions to the B<system:administrators> on the access
+control list (ACL) of every directory in the volumes stored on its
+file server machine. In other words, the group's members can exercise
+those two permissions even when an entry for the group does not appear
+on an ACL. To change the set of default permissions, use the B<-implicit>
+argument.
+
+The File Server maintains a I<host current protection subgroup> (I<host
+CPS>) for each client machine from which it has received a data access
+request. Like the CPS for a user, a host CPS lists all of the
+Protection Database groups to which the machine belongs, and the File
+Server compares the host CPS to a directory's ACL to determine in what
+manner users on the machine are authorized to access the directory's
+contents. When the C<pts adduser> or C<pts removeuser> command is used to
+change the groups to which a machine belongs, the File Server must
+recompute the machine's host CPS in order to notice the change. By
+default, the File Server contacts the Protection Server every two
+hours to recompute host CPSs, implying that it can take that long for
+changed group memberships to become effective. To change this
+frequency, use the B<-hr> argument.
+
+=over
+
+=item B<Note:>
+
+The AIX operating system does not automatically reserve a part
+of each partition to avoid the negative consequences that can result
+when the space on a partition is completely exhausted. Therefore, the
+AIX version of the File Server creates an 8% disk reserve
+automatically. To change the percentage, use the B<-m> argument.
+
+=back
+
+The File Server generates the following message when a partition is
+nearly full:
+
+ No space left on device
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-d> I<debug level>
+
+Sets the detail level for the debugging trace written to the
+B</usr/afs/logs/FileLog> file. Provide one of the following
+values, each of which produces an increasingly detailed trace:
+B<0>, B<1>, B<5>, B<25>, and B<125>. The default value of B<0> produces only a
+few messages.
+
+=item B<-p> I<number of processes>
+
+Sets the number of threads to run. Provide a positive integer.
+The File Server creates and uses five threads for special
+purposes, in addition to the number specified (but if this
+argument specifies the maximum possible number, the File Server
+automatically uses five of the threads for its own purposes).
+
+The maximum number of threads can differ in each release of
+AFS. Consult the IBM AFS Release Notes for the current release.
+
+=item B<-spare> I<number of spare blocks>
+
+Specifies the number of additional kilobytes an application can
+store in a volume after the quota is exceeded. Provide a
+positive integer; a value of B<0> prevents the volume from ever
+exceeding its quota. Do not combine this argument with the
+B<-pctspare> argument.
+
+=item B<-pctspare> I<percentage spare>
+
+Specifies the amount by which the File Server allows a volume
+to exceed its quota, as a percentage of the quota. Provide an
+integer between B<0> and B<99>. A value of B<0> prevents the volume from
+ever exceeding its quota. Do not combine this argument with the
+B<-spare> argument.
+
+=item B<-b> I<buffers>
+
+Sets the number of directory buffers. Provide a positive
+integer.
+
+=item B<-l> I<large vnodes>
+
+Sets the number of large vnodes available in memory for caching
+directory elements. Provide a positive integer.
+
+=item B<-s> I<small nodes>
+
+Sets the number of small vnodes available in memory for caching
+file elements. Provide a positive integer.
+
+=item B<-vc> I<volume cachesize>
+
+Sets the number of volumes the File Server can cache in memory.
+Provide a positive integer.
+
+=item B<-w> I<call back wait interval>
+
+Sets the interval at which the daemon spawned by the File
+Server performs its maintenance tasks. Do not use this
+argument; changing the default value can cause unpredictable
+behavior.
+
+=item B<-cb> I<number of call backs>
+
+Sets the number of callbacks the File Server can track. Provide
+a positive integer.
+
+=item B<-banner>
+
+Prints the following banner to B</dev/console> about every 10
+minutes.
+
+File Server is running at I<time>.
+
+=item B<-novbc>
+
+Prevents the File Server from breaking the callbacks that Cache
+Managers hold on a volume that the File Server is reattaching
+after the volume was offline (as a result of the C<vos restore>
+command, for example). Use of this flag is strongly
+discouraged.
+
+=item B<-implicit> I<admin mode bits: rlidwka>
+
+Defines the set of permissions granted by default to the
+B<system:administrators> group on the ACL of every directory in a
+volume stored on the file server machine. Provide one or more
+of the standard permission letters (B<rlidwka>) and auxiliary
+permission letters (B<ABCDEFGH>), or one of the shorthand
+notations for groups of permissions (B<all>, B<none>, B<read>, and
+B<write>). To review the meaning of the permissions, see the L<fs_setacl(1)>
+reference page.
+
+=over
+
+=item B<Note:>
+
+The File Server always implicitly grants the B<a> permission to the
+B<system:administrators> group, even if you use the B<none> value.
+
+=back
+
+=item B<-hr> I<number of hours between refreshing the host cps>
+
+Specifies how often the File Server refreshes its knowledge of
+the machines that belong to protection groups (refreshes the
+host CPSs for machines). The File Server must update this
+information to enable users from machines recently added to
+protection groups to access data for which those machines now
+have the necessary ACL permissions.
+
+=item B<-busyat> I<redirect clients when queue >
+
+Defines the number of incoming RPCs that can be waiting for a
+response from the File Server before the File Server returns
+the error code B<VBUSY> to the Cache Manager that sent the latest
+RPC. In response, the Cache Manager retransmits the RPC after a
+delay. This argument prevents the accumulation of so many
+waiting RPCs that the File Server can never process them all.
+Provide a positive integer. The default value is 600.
+
+=item B<-rxpck> I<number of rx extra packets>
+
+Controls the number of Rx packets the File Server uses to store
+data for incoming RPCs that it is currently handling, that are
+waiting for a response, and for replies that are not yet
+complete. Provide a positive integer.
+
+=item B<-rxdbg>
+
+Writes a trace of the File Server's operations on Rx packets to
+the file B</usr/afs/logs/rx_dbg>.
+
+=item B<-rxdbge>
+
+Writes a trace of the File Server's operations on Rx events
+(such as retransmissions) to the file B</usr/afs/logs/rx_dbg>.
+
+=item B<-m> I<min percentage spare in partition>
+
+Specifies the percentage of each AFS server partition that the
+AIX version of the File Server creates as a reserve. Specify an
+integer value between B<0> and B<30>; the default is 8%. A value of B<0>
+means that the partition can become completely full, which can
+have serious negative consequences.
+
+=over
+
+=item B<Note:>
+
+This argument is available only on machines running the AIX
+operating system, and so does not appear in the syntax statement when
+the B<-help> flag is used on other system types.
+
+=back
+
+=item B<-lock>
+
+Prevents any portion of the B<fileserver> binary from being paged
+(swapped) out of memory on a file server machine running the
+IRIX operating system.
+
+=over
+
+=item B<Note:>
+
+This argument is available only on machines running the IRIX
+operating system, and so does not appear in the syntax statement when
+the B<-help> flag is used on other system types.
+
+=back
+
+=item B<-L>
+
+Sets values for many arguments in a manner suitable for a large
+file server machine. Combine this flag with any option except
+the B<-S> flag; omit both flags to set values suitable for a
+medium-sized file server machine.
+
+=item B<-S>
+
+Sets values for many arguments in a manner suitable for a small
+file server machine. Combine this flag with any option except
+the B<-L> flag; omit both flags to set values suitable for a
+medium-sized file server machine.
+
+=item B<-k> I<stack size>
+
+Sets the LWP stack size in units of 1 kilobyte. Do not use this
+argument, and in particular do not specify a value less than
+the default of 24.
+
+=item B<-realm> I<Kerberos realm name>
+
+Defines the Kerberos realm name for the File Server to use. If
+this argument is not provided, it uses the realm name
+corresponding to the cell listed in the local
+B</usr/afs/etc/ThisCell> file.
+
+=item B<-udpsize> I<size of socket buffer in bytes>
+
+Sets the size of the UDP buffer, which is 64 KB by default.
+Provide a positive integer, preferably larger than the default.
+
+=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 following C<bos create> command creates an B<fs> process on the file
+server machine B<fs2.abc.com> that uses the large configuration size, and
+allows volumes to exceed their quota by 10%. Type the command on a
+single line:
+
+ bos create -server fs2.abc.com -instance fs -type fs \
+ -cmd "/usr/afs/bin/fileserver -pctspare 10 \
+ -L" /usr/afs/bin/volserver /usr/afs/bin/salvager
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the superuser B<root> on a file server
+machine to issue the command at a command shell prompt. It is
+conventional instead to create and start the process by issuing the
+C<bos create> command.
+
+=head1 CAVEATS
+
+Do not use the B<-k> and B<-w> arguments, which are intended for use by the
+AFS Development group only. Changing them from their default values
+can result in unpredictable File Server behavior. In any case, on many
+operating systems the File Server uses native threads rather than the
+LWP threads, so using the B<-k> argument to set the number of LWP threads
+has no effect.
+
+Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so
+causes the File Server to exit, leaving an error message in the
+B</usr/afs/logs/FileLog> file.
+
+Options that are available only on some system types, such as the B<-m>
+and B<-lock> options, appear in the output generated by the B<-help> option
+only on the relevant system type.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<BosConfig(1)>,
+L<FileLog(1)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>,
+L<fs_setacl(1)>,
+L<salvager(1)>,
+L<volserver(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fms - Determine a tape's capacity and a tape device's filemark size
+
+=head1 SYNOPSIS
+
+fms B<-tape> I<tape special file> [B<-help>]
+
+fms B<-t> I<tape special file> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fms> command determines the capacity of the tape currently in the
+tape device identified by the B<-tape> argument, along with the size of
+the filemark for the device. The filemark is also referred to as the
+device's end-of-file (EOF) marker, and can differ for each combination
+of tape and tape device.
+
+As the Tape Coordinator writes a dump, it writes a filemark between
+the data included from each volume and also tracks the amount of space
+left before the end of the tape (EOT). For some tape devices, the
+filemark is large enough (multiple megabytes) that failure to consider
+it leads the Tape Coordinator significantly to overestimate the
+available space.
+
+The intended use of this command is to determine tape capacity and
+filemark size values that can be specified in a tape device's entry in
+the B</usr/afs/backup/tapeconfig> file. For certain types of tape drives,
+the Tape Coordinator operates more efficiently when the B<tapeconfig>
+file lists accurate values. For further discussion, see the IBM AFS
+Administration Guide chapter on configuring the Backup System.
+
+Insert a tape in the drive before issuing this command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-tape> I<tape special file>
+
+Specifies the UNIX device name of the tape device for which to
+determine filemark size and the capacity of the tape it
+currently contains. The format varies on different system
+types, but usually begins with B</dev>; an example is B</dev/sd0a>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command generates output both on the standard output stream and in
+the B<fms.log> file that it creates in the current working directory. The
+output reports the capacity of the tape in the device and the device's
+filemark size.
+
+The first few lines of output include status information about the
+execution of the command, including such information as the number of
+blocks and the number of file marks written to the tape by the
+command. The last two lines of both screen and file output provide the
+following information:
+
+=over
+
+=item *
+
+C<Tape capacity is> I<number> C<bytes>: specifies the size, in bytes, of
+the tape in the device.
+
+=item *
+
+C<File marks are> I<number> C<bytes>: specifies the device's filemark size
+in bytes.
+
+=back
+
+The following message indicates that the C<fms> command interpreter
+cannot access the tape device. The command halts.
+
+Can't open tape drive I<device>
+
+The following message indicates that the command interpreter cannot
+create the B<fms.log> log file. Again, the command halts.
+
+Can't open log file
+
+=head1 EXAMPLES
+
+The following command illustrates the output for the device called
+B</dev/rmt1h>:
+
+ fms /dev/rmt1h
+ wrote block: 130408
+ Finished data capacity test - rewinding
+ wrote 1109 blocks, 1109 file marks
+ Finished file mark test
+ Tape capacity is 2136604672 bytes
+ File marks are 1910205 bytes
+
+The following appears in the B<fms.log> file:
+
+ fms test started
+ wrote 9230 blocks
+ Finished file mark test
+ Tape capacity is 151224320 bytes
+ File marks are 2375680 bytes
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be able to insert and write to files in the currently
+working directory, if the B<fms.log> file does not already exist. If it
+already exists, the issuer need only be able to write to it.
+
+=head1 CAVEATS
+
+Do not use this command on compressing tape devices in compression
+mode or with tape devices that handle tapes of multigigabyte (or
+multiterabyte) capacity. It does not produce accurate results in those
+cases. For alternate suggestions on the values to record in the
+B<tapeconfig> file for compressing drives, see the IBM AFS Administration
+Guide chapter on configuring the Backup System.
+
+Running the command completely overwrites the tape, so use a blank one
+or one that can be recycled.
+
+Because it writes filemarks to the complete length of the tape, the
+command can take from several hours to more than a day to complete.
+
+=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<fms.log(1)>,
+L<tapeconfig(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs - Introduction to the C<fs> command suite
+
+=head1 DESCRIPTION
+
+The commands in the C<fs> command suite constitute the main
+administrative interface to the Cache Manager on an AFS client
+machine, which is responsible for fetching AFS data from file server
+machines on behalf of applications running on the client machine.
+
+There are several categories of commands in the C<fs> command suite:
+
+=over
+
+=item *
+
+Commands to set and report how the Cache Manager interacts with
+server machines: C<fs checkservers>, C<fs getcellstatus>, C<fs
+getserverprefs>, C<fs listcells>, C<fs newcell>, C<fs setcell>,
+C<fs setserverprefs>, C<fs sysname>, and C<fs wscell>
+
+=item *
+
+Commands to administer access control lists (ACLs): C<fs cleanacl>,
+C<fs copyacl>, C<fs listacl>, and C<fs setacl>
+
+=item *
+
+Commands to administer server machines, volumes or partitions that
+house a given file or directory: C<fs diskfree>, C<fs examine>, C<fs
+listquota>, C<fs quota>, C<fs setquota>, C<fs setvol>,
+C<fs whereis>, and C<fs whichcell>
+
+=item *
+
+Commands to administer the local client cache and related
+information: C<fs checkvolumes>, C<fs flush>, C<fs flushvolume>, C<fs
+getcacheparms>, and C<fs setcachesize>
+
+=item *
+
+Commands to administer volume mount points: C<fs lsmount>, C<fs
+mkmount>, and C<fs rmmount>
+
+=item *
+
+Commands to control monitoring and tracing: C<fs debug>, and C<fs
+messages>
+
+=item *
+
+A command to administer the Cache Manager's interaction with other
+file systems: C<fs exportafs>
+
+=item *
+
+Commands to obtain help: C<fs apropos> and C<fs help>
+
+=back
+
+The Cache Manager and the C<fs> commands use and maintain the following
+configuration files:
+
+=over
+
+=item *
+
+The B</usr/vice/etc/CellServDB> file lists the database server
+machines in the local cell and any foreign cell to which the
+administrator wishes to enable AFS access for users working on the
+machine. The database server machines run the Authentication,
+Backup, Protection and Volume Location (VL) Server processes,
+which maintain databases of administrative information. For users
+to access a cell, its B<root.cell> volume must also be mounted in the
+local cell's AFS file tree.
+
+=item *
+
+The B</usr/vice/etc/ThisCell> file defines the machine's cell
+membership with respect to the AFS command suites and Cache
+Manager access to AFS data.
+
+=item *
+
+The B</usr/vice/etc/cacheinfo> file defines configuration parameters
+for the cache, including its size and whether it is in memory or
+on disk.
+
+=back
+
+In addition, the Cache Manager automatically creates files on the
+cache partition (by default, B</usr/vice/cache> for caching and tracking
+files fetched from file server machines.
+
+For more details, see the reference page for each file.
+
+=head1 OPTIONS
+
+The following flag is available on every command in the C<fs> suite. The
+reference page for each command also lists it, but it is described
+here in greater detail.
+
+=over 4
+
+=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.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+The privileges required for C<fs> commands vary more than for other
+command suites. Pay special attention to the C<PRIVILEGE REQUIRED>
+section of each command description.
+
+The various types of necessary privilege include:
+
+=over
+
+=item *
+
+Having permissions on a directory's ACL. For example, creating and
+removing mount points requires B<a> (B<administer>), B<i> (B<insert>), and B<d>
+(B<delete>) permissions on the ACL of the directory in which the
+mount point resides.
+
+=item *
+
+Being logged onto the machine as the local superuser B<root>. This is
+necessary when issuing commands that affect Cache Manager
+configuration.
+
+=item *
+
+Belonging to the B<system:administrators> group in the Protection
+Database.
+
+=item *
+
+No privilege. Many C<fs> commands simply list information.
+
+=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<CacheItems(1)>,
+L<CellServDB_client_version(1)>,
+L<ThisCell_client_version(1)>,
+L<Vn(1)>,
+L<VolumeItems(1)>,
+L<cacheinfo(1)>,
+L<fs_apropos(1)>,
+L<fs_checkservers(1)>,
+L<fs_checkvolumes(1)>,
+L<fs_cleanacl(1)>,
+L<fs_copyacl(1)>,
+L<fs_diskfree(1)>,
+L<fs_examine(1)>,
+L<fs_exportafs(1)>,
+L<fs_flush(1)>,
+L<fs_flushmount(1)>,
+L<fs_flushvolume(1)>,
+L<fs_getcacheparms(1)>,
+L<fs_getcellstatus(1)>,
+L<fs_getclientaddrs(1)>,
+L<fs_getserverprefs(1)>,
+L<fs_help(1)>,
+L<fs_listacl(1)>,
+L<fs_listcells(1)>,
+L<fs_listquota(1)>,
+L<fs_lsmount(1)>,
+L<fs_messages(1)>,
+L<fs_mkmount(1)>,
+L<fs_newcell(1)>,
+L<fs_quota(1)>,
+L<fs_rmmount(1)>,
+L<fs_setacl(1)>,
+L<fs_setcachesize(1)>,
+L<fs_setcell(1)>,
+L<fs_setclientaddrs(1)>,
+L<fs_setquota(1)>,
+L<fs_setserverprefs(1)>,
+L<fs_setvol(1)>,
+L<fs_storebehind(1)>,
+L<fs_sysname(1)>,
+L<fs_whereis(1)>,
+L<fs_whichcell(1)>,
+L<fs_wscell(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+fs apropos B<-topic> I<help string> [B<-help>]
+
+fs ap B<-t> I<help string> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs apropos> command displays the first line of the online help
+entry for any C<fs> 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<fs 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<fs> command where the string specified with the B<-topic> argument is part
+of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all C<fs> commands that include the word
+B<cache> in their names or short online descriptions:
+
+ fs apropos cache
+ setcachesize: set cache size
+ flush: flush file from cache
+ getcacheparms: get cache usage info
+ monitor: set cache monitor host address
+
+=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<fs(1)>,
+L<fs_help(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs checkservers - Displays the status of server machines
+
+=head1 SYNOPSIS
+
+fs checkservers [B<-cell> I<cell to check>] [B<-all>] [B<-fast>]
+[B<-interval> I<seconds between probes>] [B<-help>]
+
+fs checks [B<-c> I<cell to check>] [B<-a>] [B<-f>]
+[B<-i> I<seconds between probes>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs checkservers> command reports whether certain AFS server
+machines are accessible from the local client machine. The machines
+belong to one of two classes, and the Cache Manager maintains a list
+of them in kernel memory:
+
+=over
+
+=item *
+
+The database server machines in every cell listed in the local
+B</usr/vice/etc/CellServDB> file, plus any machines added to the
+memory list by the C<fs newcell> command since the last reboot.
+
+=item *
+
+All file server machines the Cache Manager has recently contacted,
+and which it probably needs to contact again soon. In most cases,
+the Cache Manager holds a callback on a file or volume fetched
+from the machine.
+
+=back
+
+If the Cache Manager is unable to contact the B<vlserver> process on a
+database server machine or the B<fileserver> process on a file server
+machine, it marks the machine as inaccessible. (Actually, if a file
+server machine is multihomed, the Cache Manager attempts to contact
+all of the machine's interfaces, and only marks the machine as down if
+the B<fileserver> fails to reply via any of them.) The Cache Manager then
+periodically (by default, every three minutes) sends a probe to each
+marked machine, to see if it is still inaccessible. If a previously
+inaccessible machine responds, the Cache Manager marks it as
+accessible and no longer sends the periodic probes to it.
+
+The C<fs checkservers> command updates the list of inaccessible machines
+by having the Cache Manager probe a specified set of them:
+
+=over
+
+=item *
+
+By default, only machines that are marked inaccessible and belong
+to the local cell (the cell listed in the local
+B</usr/vice/etc/ThisCell> file)
+
+=item *
+
+If the B<-cell> argument is included, only machines that are marked
+inaccessible and belong to the specified cell
+
+=item *
+
+If the B<-all> flag is included, all machines marked inaccessible
+
+=back
+
+If the B<-fast> flag is included, the Cache Manager does not probe any
+machines, but instead reports the results of the most recent previous
+probe.
+
+To set the interval between probes rather than produce a list of
+inaccessible machines, use the B<-interval> argument. The non-default
+setting persists until the machine reboots; to preserve it across
+reboots, put the appropriate C<fs checkservers> command in the machine's
+AFS initialization files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> I<cell to check>
+
+Names each cell in which to probe server machines marked as
+inaccessible. Provide the fully qualified domain name, or a
+shortened form that disambiguates it from the other cells
+listed in the local B</usr/vice/etc/CellServDB> file. Combine this
+argument with the B<-fast> flag if desired, but not with the B<-all>
+flag. Omit both this argument and the B<-all> flag to probe
+machines in the local cell only.
+
+=item B<-all>
+
+Probes all machines in the Cache Manager's memory list that are
+marked inaccessible. Combine this argument with the B<-fast> flag
+if desired, but not with the B<-cell> argument. Omit both this
+flag and the B<-cell> argument to probe machines in the local cell
+only.
+
+=item B<-fast>
+
+Displays the Cache Manager's current list of machines that are
+inaccessible, rather than sending new probes. The output can as
+old as the current setting of the probe interval (by default
+three minutes, and maximum ten minutes).
+
+=item B<-interval> I<seconds between probes>
+
+Sets or reports the number of seconds between the Cache
+Manager's probes to machines in the memory list that are marked
+inaccessible:
+
+=over
+
+=item *
+
+To set the interval, specify a value from the range between B<1>
+and B<600> (10 minutes); the default is B<180> (three minutes). The
+issuer must be logged in as the local superuser B<root>. The
+altered setting persists until again changed with this
+command, or until the machine reboots, at which time the
+setting returns to the default.
+
+=item *
+
+Provide a value of B<0> (zero) to display the current interval
+setting. No privilege is required. Do not combine this
+argument with any other.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If there are no machines marked as inaccessible, or if all of them now
+respond to the Cache Manager's probe, the output is:
+
+C<All servers are running.>
+
+Note that this message does not mean that all server machines in each
+relevant cell are running. The output indicates the status of only
+those machines that the Cache Manager probes.
+
+If a machine fails to respond to the probe within the timeout period,
+the output begins with the string:
+
+C<These servers unavailable due to network or server problems:>
+
+and lists the hostname of each machine on its own line. The Cache
+Manager stores machine records by Internet address, so the format of
+each hostname (uppercase or lowercase letters, or an Internet address
+in dotted decimal format) depends on how the local cell's name service
+translates it at the time the command is issued. If a server machine
+is multihomed, the output lists only one of its interfaces (usually,
+the currently most preferred one).
+
+If the B<-interval> argument is provided with a value between B<1> and B<600>,
+there is no output. If the value is 0, the output reports the probe
+interval as follows:
+
+C<The current down server probe interval is I<interval> secs>
+
+=head1 EXAMPLES
+
+The following command displays the Cache Manager's current list of
+unresponsive machines in the local cell, rather than probing them
+again. The output indicates that if there were any machines marked
+inaccessible, they all responded to the previous probe.
+
+ fs checkservers -fast
+ All servers are running.
+
+The following example probes machines in the Cache Manager's memory
+list that belong to the B<stateu.edu> cell:
+
+ fs checkservers -cell stateu.edu
+ All servers are running.
+
+The following example probes all server machines in the Cache
+Manager's memory list. It reports that two machines did not respond to
+the probe.
+
+ fs checkservers -all
+ These servers unavailable due to network or server problems:
+ fs1.abc.com SV3.STATE.EDU.
+
+=head1 PRIVILEGE REQUIRED
+
+To set the probe interval, the issuer must be logged in as the local
+superuser B<root>. Otherwise, no privilege is required.
+
+=head1 CAVEATS
+
+The command can take quite a while to complete, if a number of
+machines do not respond to the Cache Manager's probe. The Cache
+Manager probes machines sequentially and waits a standard timeout
+period before marking the machine as unresponsive, to allow for slow
+network communication. To make the command shell prompt return
+quickly, put the command in the background. It is harmless to
+interrupt the command by typing B<Ctrl-c> or another interrupt signal.
+
+Note that the Cache Manager probes only server machines marked
+inaccessible in its memory list. A server machine's absence from the
+output does not necessarily mean that it is functioning, because it
+possibly is not included in the memory list at all (if, for example,
+the Cache Manager has not contacted it recently). For the same reason,
+the output is likely to vary on different client machines.
+
+Unlike most C<fs> commands, the C<fs checkservers> command does not refer to
+the AFSCELL environment variable.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_client_version(1)>,
+L<ThisCell_client_version(1)>,
+L<fs_newcell(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs checkvolumes - Forces the Cache Manager to update volume-related information
+
+=head1 SYNOPSIS
+
+fs checkvolumes [B<-help>]
+
+fs checkv [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs checkvolumes> command discards the table of mappings between
+volume names and volume ID numbers that the Cache Manager stores in
+memory and uses when fetching data from volumes. The next time an
+application requests AFS data, the Cache Manager must contact the
+Volume Location (VL) Server for volume location information, and then
+an appropriate file server machine for the actual data.
+
+The Cache Manager updates the table of mappings periodically (by
+default, hourly), but this command is useful if the issuer knows that
+a volume's name has changed, or that new read-only replicas of a
+volume have been released, because issuing it forces the Cache Manager
+to reference the changed volume.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following message confirms that the command ran successfully.
+
+ All volumeID/name mappings checked.
+
+=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.
+
--- /dev/null
+=head1 NAME
+
+fs cleanacl - Remove obsolete entries from an ACL
+
+=head1 SYNOPSIS
+
+fs cleanacl [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs cl [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs cleanacl> command removes from the access control list (ACL) of
+each specified directory or file any entry that refers to a user or
+group that no longer has a Protection Database entry. Such an entry
+appears on the ACL as an AFS user ID number (UID) rather than a name,
+because without a Protection Database entry, the File Server cannot
+translate the UID into a name.
+
+Cleaning access control lists in this way not only keeps them from
+becoming crowded with irrelevant information, but also prevents the
+new possessor of a recycled AFS UID from obtaining access intended for
+the former possessor of the AFS UID. (Note that recycling UIDs is not
+recommended in any case.)
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each directory for which to clean the ACL (specifying a
+filename cleans its directory's ACL). If this argument is
+omitted, the current working directory's ACL is cleaned.
+
+Specify the read/write path to each directory, to avoid the
+failure that results from attempting to change a read-only
+volume. By convention, the read/write path is indicated by
+placing a period before the cell name at the pathname's second
+level (for example, B</afs/.abc.com>). For further discussion of
+the concept of read/write and read-only paths through the
+filespace, see the L<fs_mkmount(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If there are no obsolete entries on the ACL, the following message
+appears:
+
+Access list for I<dir/file path> is fine.
+
+Otherwise, the output reports the resulting state of the ACL,
+following the header
+
+Access list for I<dir/file path> is now
+
+At the same time, the following error message appears for each file in
+the cleaned directories:
+
+fs: 'I<filename>': Not a directory
+
+=head1 EXAMPLES
+
+The following example illustrates the cleaning of the ACLs on the
+current working directory and two of its subdirectories. Only the
+second subdirectory had obsolete entries on it.
+
+ fs cleanacl -path . ./reports ./sources
+ Access list for . is fine.
+ Access list for ./reports is fine.
+ Access list for ./sources is now
+ Normal rights:
+ system:authuser rl
+ pat rlidwka
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<a> (B<administer>) permission on each directory's
+ACL (or the ACL of each file's parent directory); the directory's
+owner and the members of the B<system:administrators> group have the
+right implicitly, even if it does not appear on the ACL.
+
+=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<fs_listacl(1)>,
+L<fs_mkmount(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs copyacl - Copies an ACL from one directory to one or more other directories
+
+=head1 SYNOPSIS
+
+fs copyacl B<-fromdir> I<source directory (or DFS file)>
+B<-todir> I<destination directory (or DFS file)> [I<destination directory (or DFS file)> ...]
+[B<-clear>] [B<-id>] [B<-if>] [B<-help>]
+
+fs co B<-f> I<source directory (or DFS file)>
+B<-t> I<destination directory (or DFS file)> [I<destination directory (or DFS file)> ...]
+[B<-c>] [B<-id>] [B<-if>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs copyacl> command copies the access control list (ACL) from a
+source directory to each specified destination directory. The source
+directory's ACL is unchanged, and changes to the destination
+directory's ACL obey the following rules:
+
+=over
+
+=item *
+
+If an entry on the source ACL does not already exist on the
+destination ACL, it is added.
+
+=item *
+
+If an entry exists on both the source and destination ACLs, the
+permissions from the source ACL entry replace the current
+permissions on the destination ACL entry.
+
+=item *
+
+If an entry on the destination ACL has no corresponding entry on
+the source ACL, it is removed if the B<-clear> flag is included and
+is unchanged otherwise. In other words, if the B<-clear> flag is
+provided, the source ACL completely replaces the destination ACL.
+
+=back
+
+When using this command to copy ACLs between objects in DFS filespace
+accessed via the AFS/DFS Migration Toolkit Protocol Translator, it is
+possible to specify files, as well as directories, with the B<-fromdir>
+and B<-todir> arguments. For more information on copying ACLs between DFS
+directories and files, refer to the IBM AFS/DFS Migration Toolkit
+Administration Guide and Reference.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-fromdir> I<source directory (or DFS file)>
+
+Specifies the source directory from which to copy the ACL.
+(Specifying an AFS file copies its directory's ACL, but
+specifying a DFS file copies its own ACL). A partial pathname
+is interpreted relative to the current working directory.
+
+=item B<-todir> I<destination directory (or DFS file)> [I<destination directory (or DFS file)> ...]
+
+Specifies each directory for which to alter the ACL to match
+the source ACL. (Specifying an AFS file halts the command with
+an error, but specifying a DFS file alters the file's ACL). A
+partial pathname is interpreted relative to the current working
+directory.
+
+Specify the read/write path to each directory (or DFS file), to
+avoid the failure that results from attempting to change a
+read-only volume. By convention, the read/write path is
+indicated by placing a period before the cell name at the
+pathname's second level (for example, B</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only
+paths through the filespace, see the L<fs_mkmount(1)> reference page.
+
+=item B<-clear>
+
+Replaces the ACL of each destination directory with the source
+ACL.
+
+=item B<-id>
+
+Modifies the Initial Container ACL of each DFS directory named
+by the B<-todir> argument, rather than the regular Object ACL.
+This argument is supported only when both the source and each
+destination directory reside in DFS and are accessed via the
+AFS/DFS Migration Toolkit Protocol Translator.
+
+=item B<-if>
+
+Modifies the Initial Object ACL of each DFS directory named by
+the B<-todir> argument, rather than the regular Object ACL. This
+argument is supported only when both the source and each
+destination directory reside in DFS and are accessed via the
+AFS/DFS Migration Toolkit Protocol Translator.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command copies the current working directory's
+ACL to its subdirectory called B<reports>. Note that the source
+directory's ACL is unaffected. Entries on the B<reports> directory's that
+are not on the source ACL of the current directory remain unaffected
+as well, because the -clear flag is not used.
+
+ fs listacl . reports
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ smith rlidwk
+ Access list for reports is
+ Normal rights:
+ pat rl
+ pat:friends rl
+ Negative rights
+ jones rlidwka
+
+
+ fs copyacl -fromdir . -todir reports
+
+
+ fs listacl . reports
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ smith rlidwk
+ Access list for reports is
+ Normal rights:
+ pat rlidwka
+ pat:friends rl
+ smith rlidwk
+ Negative rights
+ jones rlidwka
+
+=head1 PRIVILEGE REQUIRED
+
+To copy an ACL between AFS objects, the issuer must have the B<l>
+(B<lookup>) permission on the source directory's ACL and the B<a>
+(B<administer>) permission on each destination directory's ACL. If the
+B<-fromdir> argument names a file rather than a directory, the issuer
+must have both the B<l> and B<r> (B<read>) permissions on the ACL of the file's
+directory.
+
+To copy an ACL between DFS objects, the issuer must have the B<r>
+permission on the source directory or file's ACL and the B<c> (B<control>)
+permission on each destination directory or file's ACL.
+
+=head1 CAVEATS
+
+Do not copy ACLs between AFS and DFS files or directories. The ACL
+formats are incompatible.
+
+=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<fs_listacl(1)>,
+L<fs_mkmount(1)>,
+L<fs_setacl(1)>,
+IBM AFS/DFS Migration Toolkit Administration Guide and Reference
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs diskfree - Displays information about the partition housing a directory or file
+
+=head1 SYNOPSIS
+
+fs diskfree [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs df [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+fs di [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs diskfree> command formats and displays information about the
+partition that houses the volume containing the specified directory or
+file, including its size and how much space is currently used.
+
+To display information about the volume itself, use the C<fs examine>
+command. The C<fs examine> and C<fs quota> commands also display information
+about a volume.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names a file or directory that resides on the partition about
+which to produce output. Partial pathnames are interpreted
+relative to the current working directory, which is also the
+default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports the following information about the volume and
+partition that houses each file or directory:
+
+=over
+
+=item B<Volume Name>
+
+The name of the volume
+
+=item B<kbytes>
+
+The partition's total size in kilobytes
+
+=item B<used>
+
+The number of kilobytes used on the partition
+
+=item B<avail>
+
+The number of kilobytes available on the partition
+
+=item B<%used>
+
+The percentage of the partition's total space that is used (the
+used statistic divided by the kbytes statistic, times 100)
+
+=back
+
+If the C<%used> statistic is greater than 90%, it is marked with the
+string C<E<lt>E<lt>WARNING> at the right margin.
+
+If the volume is a read-only volume, the output includes information
+about only one of the partitions that houses it, generally the one on
+the file server machine with the lowest preference rank. To verify
+which machine the output is referring to, use the C<vos listvldb> command
+to list the volume's locations, and the C<vos partinfo> command to
+display the size of each one.
+
+=head1 EXAMPLES
+
+The following example shows the output for the partitions housing the
+volumes B<user.smith> and B<sun4x_56.bin>:
+
+ fs diskfree -path /afs/abc.com/usr/smith /afs/abc.com/sun4x_56/bin
+ Volume Name kbytes used avail %used
+ user.smith 4177920 3841258 336662 92% <<WARNING
+ sun4x_56.bin 4423680 3174500 1249180 72%
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 CAVEATS
+
+The partition-related statistics in this command's output do not
+always agree with the corresponding values in the output of the
+standard UNIX C<df> command. The statistics reported by this command can
+be up to five minutes old, because the Cache Manager polls the File
+Server for partition information at that frequency. Also, on some
+operating systems, the C<df> command's report of partition size includes
+reserved space not included in this command's calculation, and so is
+likely to be about 10% larger.
+
+=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<fs_examine(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs examine - Displays information about the volume containing a directory or file
+
+=head1 SYNOPSIS
+
+fs examine [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs exa [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+fs listvol [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+fs listv [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+fs lv [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs examine> command displays information about the volume
+containing each specified directory or file, including its volume ID
+number, quota and the percentage of its quota that is used.
+
+This command provides the most information about a volume, but the C<fs
+listquota> command displays similar information in tabular format, and
+the C<fs quota> command reports only the percentage of quota used.
+
+To set volume quota, use the C<fs setquota> or C<fs setvol> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names a file or directory that resides in the volume about
+which to produce output. Partial pathnames are interpreted
+relative to the current working directory, which is also the
+default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays information about the volume that houses each
+specified directory or file, in the following format
+
+ Volume status for vid = volume ID named volume name
+ Current offline message is message
+ Current disk quota is quota in kilobytes
+ Current blocks used are volume size in kilobytes
+ The partition has available partition blocks available out of
+ partition size
+
+where the first line specifies the volume's ID number and name. The
+C<Current offline message> line appears only if an administrator has
+included the B<-offlinemsg> argument to the C<fs setvol> command. The
+remaining lines report, respectively,
+
+=over
+
+=item *
+
+the volume's quota in kilobytes, or the string C<unlimited> to
+indicate an unlimited quota
+
+=item *
+
+the volume's current size in kilobytes
+
+=item *
+
+the number of blocks available and total size of the host
+partition, both in kilobytes.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the output for the volume B<user.smith> and
+the partition housing it:
+
+ fs examine -path /afs/abc.com/usr/smith
+ Volume status for vid = 50489902 named user.smith
+ Current maximum quota is 15000
+ Current blocks used are 5073
+ The partition has 336662 blocks available out of 4177920
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=head1 CAVEATS
+
+The partition-related statistics in this command's output do not
+always agree with the corresponding values in the output of the
+standard UNIX C<df> command. The statistics reported by this command can
+be up to five minutes old, because the Cache Manager polls the File
+Server for partition information at that frequency. Also, on some
+operating systems, the C<df> command's report of partition size includes
+reserved space not included in this command's calculation, and so is
+likely to be about 10% larger.
+
+=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<fs_listquota(1)>,
+L<fs_quota(1)>,
+L<fs_setquota(1)>,
+L<fs_setvol(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs exportafs - Reports or sets whether the machine can export AFS to clients of other
+file systems
+
+=head1 SYNOPSIS
+
+fs exportafs B<-type> I<exporter name>
+[B<-start> I<start/stop translator (on | off)>]
+[B<-convert> I<convert from afs to unix mode (on | off)>]
+[B<-uidcheck> I<run on strict 'uid check' mode (on | off)>]
+[B<-submounts> I<allow nfs mounts to subdirs of /afs/.. (on | off)>]
+[B<-help>]
+
+fs exp B<-t> I<exporter name>
+[B<-st> I<start/stop translator (on | off)>]
+[B<-c> I<convert from afs to unix mode (on | off)>]
+[B<-u> I<run on strict 'uid check' mode (on | off)>]
+[B<-su> I<allow nfs mounts to subdirs of /afs/.. (on | off)>]
+[B<-help>]
+
+=head1 DESCRIPTION
+
+The C<fs exportafs> command sets (if the B<-start> argument is provided) or
+reports (if it is omitted) whether the machine can reexport the AFS
+filespace to clients of a non-AFS file system. To control certain
+features of the translation protocol, use the following arguments:
+
+=over
+
+=item *
+
+To control whether the UNIX B<group> and B<other> mode bits on an AFS
+file or directory are set to match the B<owner> mode bits when it is
+exported to the non-AFS file system, use the B<-convert> argument.
+
+=item *
+
+To control whether tokens can be placed in a credential structure
+identified by a UID that differs from the local UID of the entity
+that is placing the tokens in the structure, use the B<-uidcheck>
+argument. The most common use is to control whether issuers of the
+C<knfs> command can specify a value for its B<-id> argument that does
+not match their local UID on the NFS/AFS translator machine.
+
+=item *
+
+To control whether users can create mounts in the non-AFS
+filespace to an AFS directory other than B</afs>, use the B<-submounts>
+argument.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-type> I<exporter name>
+
+Names the alternate file system to which to reexport the AFS
+filespace. The only acceptable value is B<nfs>, in lowercase
+letters only.
+
+=item B<-start> I<start/stop translator (on | off)>
+
+Enables the local machine to reexport the AFS filespace if the
+value is B<on>, or disables it if the value is B<off>. Omit this
+argument to report the current setting for all of the
+configurable parameters.
+
+=item B<-convert> I<convert from afs to unix mode (on | off)>
+
+Controls the setting of the UNIX B<group> and B<other> mode bits on
+AFS files and directories exported to the non-AFS file system.
+If the value is B<on>, they are set to match the owner mode bits.
+If the value is B<off>, the bits are not changed. If this argument
+is omitted, the default value is B<on>.
+
+=item B<-uidcheck> I<run on strict 'uid check' mode (on | off)>
+
+Controls whether tokens can be placed in a credential structure
+identified by a UID that differs from the local UID of the
+entity that is placing the tokens in the structure.
+
+=over
+
+=item *
+
+If the value is B<on>, the UID that identifies the credential
+structure must match the local UID.
+
+With respect to the C<knfs> command, this value means that the
+value of B<-id> argument must match the issuer's local UID on
+the translator machine. In practice, this setting makes it
+pointless to include the B<-id> argument to the C<knfs> command,
+because the only acceptable value (the issuer's local UID) is
+already used when the B<-id> argument is omitted.
+
+Enabling UID checking also makes it impossible to issue the
+C<klog> and C<pagsh> commands on a client machine of the non-AFS
+file system even though it is a system type supported by AFS.
+For an explanation, see the reference page for the C<klog>
+command.
+
+=item *
+
+If the value is B<off> (the default), tokens can be assigned to
+a local UID in the non-AFS file system that does not match
+the local UID of the entity assigning the tokens.
+
+With respect to the C<knfs> command, it means that the issuer
+can use the B<-id> argument to assign tokens to a local UID on
+the NFS client machine that does not match his or her local
+UID on the translator machine. (An example is assigning
+tokens to the MFS client machine's local superuser B<root>.)
+This setting allows more than one issuer of the C<knfs> command
+to make tokens available to the same user on the NFS client
+machine. Each time a different user issues the C<knfs> command
+with the same value for the B<-id> argument, that user's tokens
+overwrite the existing ones. This can result in unpredictable
+access for the user on the NFS client machine.
+
+=back
+
+=item B<-submounts> I<allow nfs mounts to subdirs of /afs/.. (on | off)>
+
+Controls whether a user of the non-AFS filesystem can mount any
+directory in the AFS filespace other than the top-level B</afs>
+directory. If the value is B<on>, such submounts are allowed. If
+the value is off, only mounts of the B</afs> directory are
+allowed. If this argument is omitted, the default value is B<off>.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the machine is not even configured as a server of the non-AFS file
+system, the following message appears:
+
+Sorry, the I<file_system>-exporter type is currently not supported on this AFS client
+
+If the machine is configured as a server of the non-AFS file system
+but is not currently enabled to reexport AFS to it (because the B<-start>
+argument to this command is not set to on), the message is as follows:
+
+'I<file_system>' translator is disabled
+
+If the machine is enabled to reexport AFS, the following message
+precedes messages that report the settings of the other parameters.
+
+'I<file_system>' translator is enabled with the following options:
+
+The following messages indicate that the B<-convert> argument is set to
+B<on> or B<off> respectively:
+
+ Running in convert owner mode bits to world/other mode
+ Running in strict unix mode
+
+The following messages indicate that the B<-uidcheck> argument is set to
+B<on> or B<off> respectively:
+
+ Running in strict 'passwd sync' mode
+ Running in no 'passwd sync' mode
+
+The following messages indicate that the B<-submounts> argument is set to
+B<on> or B<off> respectively:
+
+ Allow mounts of /afs/.. subdirs
+ Only mounts to /afs allowed
+
+=head1 EXAMPLES
+
+The following example shows that the local machine can export AFS to
+NFS client machines.
+
+ fs exportafs nfs
+ 'nfs' translator is enabled with the following options:
+ Running in convert owner mode bits to world/other mode
+ Running in no 'passwd sync' mode
+ Only mounts to /afs allowed
+
+The following example enables the machine as an NFS server and
+converts the UNIX B<group> and B<other> mode bits on exported AFS
+directories and files to match the UNIX B<owner> mode bits.
+
+ fs exportafs -type nfs -start on -convert on
+
+The following example disables the machine from reexporting AFS to NFS
+client machines:
+
+ fs exportafs -type nfs -start off
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<klog(1)>,
+L<knfs(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs flush - Forces the Cache Manager to discard a cached file or directory
+
+=head1 SYNOPSIS
+
+fs flush [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs flush [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs flush> command removes from the cache all data and status
+information associated with each specified file or directory. The next
+time an application requests data from the flushed directory or file,
+the Cache Manager fetches the most current version from a File Server,
+along with a new callback (if necessary) and associated status
+information. This command has no effect on two types of data:
+
+=over
+
+=item 1.
+
+Data in application program buffers
+
+=item 2.
+
+Data that has been changed locally and written to the cache but
+not yet written to the copy on the file server machine
+
+=back
+
+To flush all data in the cache that was fetched from the same volume
+as a specified file or directory, use the C<fs flushvolume> command. To
+flush a corrupted mount point, use the C<fs flushmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each file or directory to flush from the cache. If it is
+a directory, only the directory element itself is flushed, not
+data cached from files or subdirectories that reside in it.
+Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this
+argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command flushes from the cache the file B<projectnotes> in
+the current working directory and all data from the subdirectory
+B<plans>:
+
+ fs flush -path projectnotes ./plans/*
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=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<fs_flushmount(1)>,
+L<fs_flushvolume(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs flushmount - Forces the Cache Manager to discard a mount point
+
+=head1 SYNOPSIS
+
+fs flushmount [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs flushm [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs flushmount> command removes from the cache all information
+associated with each mount point named by the B<-path> argument. The next
+time an application accesses the mount point, the Cache Manager
+fetches the most current version of it from the File Server. Data
+cached from the associated volume is not affected.
+
+The command's intended use is to discard information about mount
+points that has become corrupted in the cache. (The Cache Manager
+periodically refreshes cached mount points, but the only other way to
+discard them immediately is to reinitialize the Cache Manager by
+rebooting the machine.) Symptoms of a corrupted mount point included
+garbled output from the C<fs lsmount> command, and failed attempts to
+change directory to or list the contents of a mount point.
+
+To flush cached data rather than a mount point, use the C<fs flush> or C<fs
+flushvolume> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each mount point to flush from the cache. Partial
+pathnames are interpreted relative to the current working
+directory, which is also the default value if this argument is
+omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command flushes from the cache the mount point for user
+B<pat>'s home directory:
+
+ fs flushm /afs/abc.com/usr/pat
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=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<fs_flush(1)>,
+L<fs_flushvolume(1)>,
+L<fs_lsmount(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs flushvolume - Forces the Cache Manager to discard all cached data from the volume
+containing a file or directory
+
+=head1 SYNOPSIS
+
+fs flushvolume [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs flushv [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs flushvolume> command removes from the cache all data that was
+fetched from the same volume as each specified directory or file. It
+does not discard cached status information. The next time an
+application requests data from a flushed directory or file, the Cache
+Manager fetches the most current version from a File Server, along
+with a new callback (if necessary) and associated status information.
+This command has no effect on two types of data:
+
+=over
+
+=item 1.
+
+Data in application program buffers
+
+=item 2.
+
+Data that has been changed locally and written to the cache but
+not yet written to the copy on the file server machine
+
+=back
+
+To discard the data and status information associated with individual
+files and directories, use the C<fs flush> command. To flush a corrupted
+mount point, use the C<fs flushmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names a file or directory from each volume for which to discard
+all cached data. Partial pathnames are interpreted relative to
+the current working directory, which is also the default value
+if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command flushes from the cache all data fetched from the
+volume that contains the current working directory:
+
+ fs flushvolume
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=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<fs_flush(1)>,
+L<fs_flushmount(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs getcacheparms - Displays the current size of the cache and the amount being used
+
+=head1 SYNOPSIS
+
+fs getcacheparms [B<-help>]
+
+fs getca [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs getcacheparms> command displays the current size of the cache
+(which can be in memory or on disk), and the amount currently in use.
+
+The reported statistics are from kernel memory, so the reported size
+can differ from the setting specified in the B</usr/vice/etc/cacheinfo>
+file on a machine using a disk cache, if the C<fs setcachesize> command
+has been used to alter cache size.
+
+=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 reports
+
+AFS using I<amount used> of the cache's available I<size> 1K byte blocks.
+
+where I<amount used> is the number of kilobyte blocks currently used to
+cache data and status information, and I<size> is the total current cache
+size.
+
+=head1 EXAMPLES
+
+The following example shows the output on a machine with a 25000
+kilobyte cache.
+
+ fs getcacheparms
+ AFS using 22876 of the cache's available 25000 1K byte blocks.
+
+=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<fs_setcachesize(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs getcellstatus - Reports whether the machine can run setuid programs from a specified
+cell
+
+=head1 SYNOPSIS
+
+fs getcellstatus B<-cell> I<cell name> [I<cell name> ...] [B<-help>]
+
+fs getce B<-c> I<cell name> [I<cell name> ...] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs getcellstatus> command reports whether the Cache Manager allows
+programs fetched from each specified cell to run with setuid
+permission. To set a cell's setuid status, use the C<fs setcell> command;
+its reference page fully describes how AFS treats setuid programs.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> I<cell name> [I<cell name> ...]
+
+Names each cell for which to report setuid status. Provide the
+fully qualified domain name, or a shortened form that
+disambiguates it from the other cells listed in the local
+B</usr/vice/etc/CellServDB> file.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports one of the following two values as appropriate:
+
+Cell I<cell> status: setuid allowed
+
+Cell I<cell> status: no setuid allowed
+
+=head1 EXAMPLES
+
+The following example indicates that programs from the cell B<abc.com>
+are not allowed to run with setuid permission.
+
+ fs getcellstatus abc.com
+ Cell abc.com status: no setuid allowed
+
+=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<CellServDB_client_version(1)>,
+L<fs_setcell(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs getclientaddrs - Displays the client interfaces to register with the File Server
+
+=head1 SYNOPSIS
+
+fs getclientaddrs [B<-help>]
+
+fs gc [B<-h>]
+
+fs getcl [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs getclientaddrs> command displays the IP addresses of the
+interfaces that the local Cache Manager registers with a File Server
+when first establishing a connection to it.
+
+The File Server uses the addresses when it initiates a remote
+procedure call (RPC) to the Cache Manager (as opposed to responding to
+an RPC sent by the Cache Manager). There are two common circumstances
+in which the File Server initiates RPCs: when it breaks callbacks and
+when it pings the client machine to verify that the Cache Manager is
+still accessible.
+
+If an RPC to that interface fails, the File Server simultaneously
+sends RPCs to all of the other interfaces in the list, to learn which
+of them are still available. Whichever interface replies first is the
+one to which the File Server then sends pings and RPCs to break
+callbacks.
+
+The L<fs_setclientaddrs(1)> reference page explains how the Cache Manager
+constructs the list automatically in kernel memory as it initializes,
+and how to use that command to alter the kernel list after
+initialization.
+
+=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 displays the IP address of each interface that the Cache
+Manager is currently registering with File Server processes that it
+contacts, with one address per line. The File Server initially uses
+the first address for breaking callbacks and pinging the Cache
+Manager, but the ordering of the other interfaces is not meaningful.
+
+=head1 EXAMPLES
+
+The following example displays the two interfaces that the Cache
+Manager is registering with File Servers.
+
+ fs getclientaddrs
+ 192.12.105.68
+ 192.12.108.84
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 CAVEATS
+
+The File Server uses the list of interfaces displayed by this command
+only when selecting an alternative interface after a failed attempt to
+break a callback or ping the Cache Manager. When responding to the
+Cache Manager's request for file system data, the File Server replies
+to the interface which the Cache Manager used when sending the
+request. If the File Server's reply to a data request fails, the file
+server machine's network routing configuration determines which
+alternate network routes to the client machine are available for
+resending the reply.
+
+The displayed list applies to all File Servers to which the Cache
+Manager connects in the future. It is not practical to register
+different sets of addresses with different File Servers, because it
+requires using the C<fs setclientaddrs> command to change the list and
+then rebooting each relevant File Server immediately.
+
+The displayed list is not necessarily governing the behavior of a
+given File Server, if an administrator has issued the C<fs
+setclientaddrs> command since the Cache Manager first contacted that
+File Server. It determines only which addresses the Cache Manager
+registers when connecting to File Servers in the future.
+
+The list of interfaces does not influence the Cache Manager's choice
+of interface when establishing a connection to a File Server.
+
+=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<fileserver(1)>,
+L<fs_setclientaddrs(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs getserverprefs - Displays the Cache Manager's preference ranks for file server or VL
+Server machines
+
+=head1 SYNOPSIS
+
+fs getserverprefs [B<-file> I<output to named file>]
+[B<-numeric>] [B<-vlservers>] [B<-help>]
+
+fs gets [B<-f> I<output to named file>] [B<-n>] [B<-v>] [B<-h>]
+
+fs gp [B<-f> I<output to named file>] [B<-n>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs getserverprefs> command displays preference ranks for file
+server machine interfaces (file server machines run the B<fs> process)
+or, if the B<-vlserver> flag is provided, for Volume Location (VL) Server
+machines (which run the B<vlserver> process). For file server machines,
+the Cache Manager tracks up to 15 interfaces per machine and assigns a
+separate rank to each interface. The ranks indicate the order in which
+the local Cache Manager attempts to contact the interfaces of machines
+that are housing a volume when it needs to fetch data from the volume.
+For VL Server machines, the ranks indicate the order in which the
+Cache Manager attempts to contact a cell's VL Servers when requesting
+VLDB information. For both types of rank, lower integer values are
+more preferred.
+
+The Cache Manager stores ranks in kernel memory. Once set, a rank
+persists until the machine reboots, or until the C<fs setserverprefs>
+command is used to change it. The reference page for the C<fs
+setserverprefs> command explains how the Cache Manager sets default
+ranks, and how to use that command to change the default values.
+
+Default VL Server ranks range from 10,000 to 10,126, and the Cache
+Manager assigns them to every machine listed in its copy of the
+B</usr/vice/etc/CellServDB> file. When the Cache Manager needs to fetch
+VLDB information from a cell, it compares the ranks for the VL Server
+machines belonging to that cell, and attempts to contact the VL Server
+with the lowest integer rank. If the Cache Manager cannot reach the VL
+Server (because of server process, machine or network outage), it
+tries to contact the VL Server with the next lowest integer rank, and
+so on. If all of a cell's VL Server machines are unavailable, the
+Cache Manager cannot fetch data from the cell.
+
+Default file server ranks range from 5,000 to 40,000, excluding the
+range used for VL Servers (10,000 to 10,126); the maximum possible
+rank is 65,534. When the Cache Manager needs to fetch data from a
+volume, it compares the ranks for the interfaces of machines that
+house the volume, and attempts to contact the interface that has the
+lowest integer rank. If it cannot reach the B<fileserver> process via
+that interface (because of server process, machine or network outage),
+it tries to contact the interface with the next lowest integer rank,
+and so on. If it cannot reach any of the interfaces for machines that
+house the volume, it cannot fetch data from the volume.
+
+For both file server machines and VL Server machines, it is possible
+for a machine or interface in a foreign cell to have the same rank as
+a machine or interface in the local cell. This does not present a
+problem, because the Cache Manager only ever compares ranks for
+machines belonging to one cell at a time.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-file> I<output to named file>
+
+Specifies the full pathname of a file to which to write the
+preference ranks. If the specified file already exists, the
+command overwrites its contents. If the pathname is invalid,
+the command fails. If this argument is not provided, the
+preference ranks appear on the standard output stream.
+
+=item B<-numeric>
+
+Displays the IP addresses of file server machine interfaces or
+VL Server machines, rather than their hostnames. If this
+argument is not provided, the C<fs> command interpreter has the IP
+addresses translated to hostnames such as B<fs1.abc.com>.
+
+=item B<-vlservers>
+
+Displays preference ranks for VL Server machines rather than
+file server machine interfaces.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output consists of a separate line for each file server machine
+interface or VL Server machine, pairing the machine's hostname or IP
+address with its rank. The Cache Manager stores IP addresses in its
+kernel list of ranks, but the command by default identifies interfaces
+by hostname, by calling a translation routine that refers to either
+the cell's name service (such as the Domain Name Server) or the local
+host table. If an IP address appears in the output, it is because the
+translation attempt failed. To bypass the translation step and display
+IP addresses rather than hostnames, include the B<-numeric> flag. This
+can significantly speed the production of output.
+
+By default, the command writes to the standard output stream. Use the
+B<-file> argument to write the output to a file instead.
+
+=head1 EXAMPLES
+
+The following example displays the local Cache Manager's preference
+ranks for file server machines. The local machine belongs to the AFS
+cell named B<abc.com>, and in this example the ranks of file server
+machines in its local cell are lower than the ranks of file server
+machines from the foreign cell, B<def.com>. It is not possible to
+translate the IP addresses of two machines on the 138.255 network.
+
+ fs getserverprefs
+ fs2.abc.com 20007
+ fs3.abc.com 30002
+ fs1.abc.com 20011
+ fs4.abc.com 30010
+ server1.def.com 40002
+ 138.255.33.34 40000
+ server6.def.com 40012
+ 138.255.33.37 40005
+
+The following example shows hows the output displays IP addresses when
+the B<-numeric> flag is included, and illustrates how network proximity
+determines default ranks (as described on the L<fs_setserverprefs(1)>
+reference page). The local machine has IP address 192.12.107.210, and
+the two file server machines on its subnetwork have ranks of 20,007
+and 20,011. The two file server machines on a different subnetwork of
+the local machine's network have higher ranks, 30,002 and 30,010,
+whereas the ranks of the remaining machines range from 40,000 to
+40,012 because they are in a completely different network.
+
+ fs getserverprefs -numeric
+ 192.12.107.214 20007
+ 192.12.105.99 30002
+ 192.12.107.212 20011
+ 192.12.105.100 30010
+ 138.255.33.41 40002
+ 138.255.33.34 40000
+ 138.255.33.36 40012
+ 138.255.33.37 40005
+
+The example shows how the B<-vlservers> flag displays preference ranks
+for VL Server machines:
+
+ fs getserverprefs -vlservers
+ fs2.abc.com 10052
+ fs3.abc.com 10113
+ fs1.abc.com 10005
+
+=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<fs_setserverprefs(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs help - Displays the syntax of specified C<fs> commands or lists functional
+descriptions of all C<fs> commands
+
+=head1 SYNOPSIS
+
+fs help [B<-topic> I<help string> [I<help string> ...]] [B<-help>]
+
+fs h [B<-t> I<help string> [I<help string> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<fs> command.
+
+To display every C<fs> command whose name or short description includes a
+specified keyword, use the C<fs 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<fs> part of the command name, providing
+only the operation code (for example, specify C<setacl>, not C<fs
+setacl>). If this argument is omitted, the output briefly
+describes every C<fs> 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<fs> 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 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 command displays the online help entry for the C<fs setacl>
+command:
+
+ fs help setacl
+ fs setacl: set access control list
+ aliases: sa
+ Usage: fs setacl -dir <directory>+ -acl <access list entries>+
+ [-clear] [-negative] [-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<fs(1)>,
+L<fs_apropos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs listacl - Displays ACLs
+
+=head1 SYNOPSIS
+
+fs listacl [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-id>] [B<-if>] [B<-help>]
+
+fs la [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-id>] [B<-if>] [B<-h>]
+
+fs lista [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-id>] [B<-if>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs listacl> command displays the access control list (ACL)
+associated with each specified file, directory, or symbolic link. The
+specified element can reside in the DFS filespace if the issuer is
+using the AFS/DFS Migration Toolkit Protocol Translator to access DFS
+data (and DFS does implement per-file ACLs). To display the ACL of the
+current working directory, omit the B<-path> argument.
+
+To alter an ACL, use the C<fs setacl> command. To copy an ACL from one
+directory to another, use the C<fs copyacl> command. To remove obsolete
+entries from an ACL, use the C<fs cleanacl> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each directory or file for which to display the ACL. For
+AFS files, the output displays the ACL from the file's parent
+directory; DFS files do have their own ACL. Incomplete
+pathnames are interpreted relative to the current working
+directory, which is also the default value if this argument is
+omitted.
+
+=item B<-id>
+
+Displays the Initial Container ACL of each DFS directory. This
+argument is supported only on DFS directories accessed via the
+AFS/DFS Migration Toolkit Protocol Translator.
+
+=item B<-if>
+
+Displays the Initial Object ACL of each DFS directory. This
+argument is supported only on DFS directories accessed via the
+AFS/DFS Migration Toolkit Protocol Translator.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of the output for each file, directory, or symbolic
+link reads as follows:
+
+Access list for I<directory> is
+
+If the issuer used shorthand notation in the pathname, such as the
+period (.) to represent the current current directory, that notation
+sometimes appears instead of the full pathname of the directory.
+
+Next, the C<Normal rights> header precedes a list of users and groups who
+are granted the indicated permissions, with one pairing of user or
+group and permissions on each line. If negative permissions have been
+assigned to any user or group, those entries follow a C<Negative rights>
+header. The format of negative entries is the same as those on the
+C<Normal rights> section of the ACL, but the user or group is denied
+rather than granted the indicated permissions.
+
+AFS does not implement per-file ACLs, so for a file the command
+displays the ACL on its directory. The output for a symbolic link
+displays the ACL that applies to its target file or directory, rather
+than the ACL on the directory that houses the symbolic link.
+
+The permissions for AFS enable the possessor to perform the indicated
+action:
+
+=over
+
+=item B<a>
+
+(B<administer>): change the entries on the ACL
+
+=item B<d>
+
+(B<delete>): remove files and subdirectories from the directory or
+move them to other directories
+
+=item B<i>
+
+(B<insert>): add files or subdirectories to the directory by
+copying, moving or creating
+
+=item B<k>
+
+(B<lock>): set read locks or write locks on the files in the
+directory
+
+=item B<l>
+
+(B<lookup>): list the files and subdirectories in the directory,
+stat the directory itself, and issue the C<fs listacl> command to
+examine the directory's ACL
+
+=item B<r>
+
+(B<read>): read the contents of files in the directory; issue the
+C<ls -l> command to stat the elements in the directory
+
+=item B<w>
+
+(B<write>): modify the contents of files in the directory, and
+issue the UNIX C<chmod> command to change their mode bits
+
+=item B<A, B, C, D, E, F, G, H:>
+
+Have no default meaning to the AFS server processes, but are
+made available for applications to use in controlling access to
+the directory's contents in additional ways. The letters must
+be uppercase.
+
+=back
+
+For DFS files and directories, the permissions are similar, except
+that the DFS B<x> (B<execute>) permission replaces the AFS B<l> (B<lookup>)
+permission, DFS B<c> (B<control>) replaces AFS B<a> (B<administer>), and there is
+no DFS equivalent to the AFS B<k> (B<lock>) permission. The meanings of the
+various permissions also differ slightly, and DFS does not implement
+negative permissions. For a complete description of DFS permissions,
+see the DFS documentation and the IBM AFS/DFS Migration Toolkit
+Administration Guide and Reference.
+
+=head1 EXAMPLES
+
+The following command displays the ACL on the home directory of the
+user B<pat> (the current working directory), and on its B<private>
+subdirectory.
+
+ fs listacl -path . private
+ Access list for . is
+ Normal rights:
+ system:authuser rl
+ pat rlidwka
+ pat:friends rlid
+ Negative rights:
+ smith rlidwka
+ Access list for private is
+ Normal rights:
+ pat rlidwka
+
+=head1 PRIVILEGE REQUIRED
+
+If the B<-path> argument names an AFS directory, the issuer must have the
+B<l> (B<lookup>) permission on its ACL and the ACL for every directory that
+precedes it in the pathname.
+
+If the B<-path> argument names an AFS file, the issuer must have the B<l>
+(B<lookup>) and B<r> (B<read>) permissions on the ACL of the file's directory,
+and the l permission on the ACL of each directory that precedes it in
+the pathname.
+
+If the B<-path> argument names a DFS directory or file, the issuer must
+have the B<x> (B<execute>) permission on its ACL and on the ACL of each
+directory that precedes it in the pathname.
+
+=head1 CAVEATS
+
+Placing a user or group on the C<Negative rights> section of the ACL does
+not guarantee denial of permissions, if the C<Normal rights> section
+grants the permissions to members of the B<system:anyuser> group. In that
+case, the user needs only to issue the C<unlog> command to obtain the
+permissions granted to the B<system:anyuser> group.
+
+=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<fs_cleanacl(1)>,
+L<fs_copyacl(1)>,
+L<fs_setacl(1)>,
+IBM AFS/DFS Migration Toolkit Administration Guide and Reference
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs listcells - Displays the database server machines in each cell known to the Cache
+Manager
+
+=head1 SYNOPSIS
+
+fs listcells [B<-numeric>] [B<-help>]
+
+fs listc [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs listcells> command formats and displays the list of the database
+server machines that the Cache Manager stores in kernel memory for its
+home cell and foreign cells.
+
+At each reboot of the client machine, the Cache Manager copies the
+contents of B</usr/vice/etc/CellServDB> into kernel memory. To modify the
+list between reboots, use the C<fs newcell> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-numeric>
+
+Displays each database server machine's IP address rather than
+hostname.
+
+=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 cell included in the Cache
+Manager's kernel memory list, in the following format:
+
+Cell I<cell> on hosts I<database server machines>
+
+The Cache Manager stores IP addresses, but by default has them
+translated to hostnames before reporting them, by passing them to the
+cell's name service (such as the Domain Name Service or a local host
+table). The name service sometimes returns hostnames in uppercase
+letters, or an IP address if it cannot resolve a name.
+
+Using the B<-numeric> flag bypasses the translation to hostnames, which
+can result in significantly faster production of output. The output
+includes IP addresses only.
+
+=head1 EXAMPLES
+
+The following example shows output for several cells as illustrations
+of the different formats for machine names:
+
+ fs listcells
+ Cell abc.com on hosts fs1.abc.com fs2.abc.com fs3.abc.com
+ Cell stateu.edu on hosts DB1.FS.STATEU.EDU
+ DB2.FS.STATEU.EDU DB3.FS.STATEU.EDU
+ Cell def.gov on hosts 138.255.0.2 sv3.def.gov
+
+=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<CellServDB_client_version(1)>,
+L<fs_newcell(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs listquota - Displays quota information for the volume containing a file or
+directory.
+
+=head1 SYNOPSIS
+
+fs listquota [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs listq [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+fs lq [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs listquota> command displays information about the volume
+containing each specified directory or file (its name, quota, and
+amount of disk space used), along with an indicator of the percentage
+of space used on the host partition.
+
+To display more information about the host partition, use the C<fs
+examine> command.
+
+To set volume quota, use the fs setquota or C<fs setvol> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names a file or directory that resides in the volume about
+which to produce output. Partial pathnames are interpreted
+relative to the current working directory, which is also the
+default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output displays information about the volume that houses each
+specified directory or file, in a tabular format that uses the
+following headers:
+
+=over
+
+=item B<Volume Name>
+
+The name of the volume.
+
+=item B<Quota>
+
+The volume's quota in kilobytes, or the string no limit to
+indicate an unlimited quota.
+
+=item B<Used>
+
+The number of kilobytes of quota used.
+
+=item B<% Used>
+
+The percentage of the volume's quota that is used (the Used
+statistic divided by the Quota statistic, times 100).
+
+=item B<Partition>
+
+The percentage of space used on the partition that houses the
+volume. Although not directly related to how much of the user's
+quota is used, it is reported because a full partition can
+cause writing of data back to the volume to fail even when the
+volume has not reached its quota.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows the output for the volume B<user.smith>:
+
+ fs listquota -path /afs/abc.com/usr/smith
+ Volume Name Quota Used % Used Partition
+ user.smith 15000 5071 34% 86%
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=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<fs_diskfree(1)>,
+L<fs_examine(1)>,
+L<fs_quota(1)>,
+L<fs_setquota(1)>,
+L<fs_setvol(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs lsmount - Reports the volume for which a directory is the mount point.
+
+=head1 SYNOPSIS
+
+fs lsmount B<-dir> I<directory> [I<directory> ...] [B<-help>]
+
+fs ls B<-d> I<directory> [I<directory> ...] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs lsmount> command reports the volume for which each specified
+directory is a mount point, or indicates with an error message that a
+directory is not a mount point or is not in AFS.
+
+To create a mount point, use the C<fs mkmount> command. To remove one,
+use the C<fs rmmount> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> I<directory> [I<directory> ...]
+
+Names the directory that serves as a mount point for a volume.
+The last element in the pathname provided must be an actual
+name, not a shorthand notation such as one or two periods (. or
+..).
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the specified directory is a mount point, the output is of the
+following form:
+
+'I<directory>' is a mount point for volume 'I<volume name>'
+
+where
+
+=over
+
+=item *
+
+A number sign (#) precedes the I<volume name> string for a regular
+mount point.
+
+=item *
+
+A percent sign (%) precedes the I<volume name> string for a
+read/write mount point.
+
+=item *
+
+A cell name and colon (:) follow the number or percent sign and
+precede the I<volume name> string for a cellular mount point.
+
+=back
+
+The L<fs_mkmount(1)> reference page explains how the Cache Manager
+interprets each of the three types of mount points.
+
+If the directory is a symbolic link to a mount point, the output is of
+the form:
+
+'I<directory>' is a symbolic link, leading to a mount point for volume 'I<volume
+name>'
+
+If the directory is not a mount point or is not in AFS, the output
+reads:
+
+'I<directory>' is not a mount point.
+
+If the output is garbled, it is possible that the mount point has
+become corrupted in the local AFS client cache. Use the C<fs flushmount>
+command to discard it, which forces the Cache Manager to refetch the
+mount point.
+
+=head1 EXAMPLES
+
+The following example shows the mount point for the home directory of
+user B<smith>:
+
+ fs lsmount /afs/abc.com/usr/smith
+ '/afs/abc.com/usr/smith' is a mount point for volume '#user.smith'
+
+The following example shows both the regular and read/write mount
+points for the ABC Corporation cell's C<root.cell> volume.
+
+ fs lsmount /afs/abc.com
+ '/afs/abc.com' is a mount point for volume '#root.cell'
+
+ fs lsmount /afs/.abc.com
+ '/afs/.abc.com' is a mount point for volume '%root.cell'
+
+The following example shows a cellular mount point: the State
+University cell's C<root.cell> volume as mounted in the ABC Corporation
+cell's tree.
+
+ fs lsmount /afs/stateu.edu
+ '/afs/stateu.edu' is a mount point for volume '#stateu.edu:root.cell'
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-dir> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=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<fs_flushmount(1)>,
+L<fs_mkmount(1)>,
+L<fs_rmmount(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs messages - Sets whether the Cache Manager writes log messages
+
+=head1 SYNOPSIS
+
+fs messages [B<-show> I<[user|console|all|none]>] [B<-help>]
+
+fs me [B<-s> I<[user|console|all|none]>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs messages> command controls whether the Cache Manager displays
+status and warning messages on user screens, the client machine
+console, on both, or on neither.
+
+There are two types of Cache Manager messages:
+
+=over
+
+=item *
+
+User messages provide user-level status and warning information,
+and the Cache Manager directs them to user screens.
+
+=item *
+
+Console messages provide system-level status and warning
+information, and the Cache Manager directs them to the client
+machine's designated console.
+
+=back
+
+Disabling messaging completely is not recommended, because the
+messages provide useful status and warning information.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-show> I<[user|console|all|none]>
+
+Specifies the types of messages to display. Choose one of the
+following values:
+
+=over
+
+=item B<user>
+
+Send user messages to user screens
+
+=item B<console>
+
+Send console messages to the console
+
+=item B<all>
+
+Send user messages to user screens and console messages
+to the console (the default if the B<-show> argument is
+omitted)
+
+=item B<none>
+
+Do not send any messages to user screens or the console
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command instructs the Cache Manager to display both
+types of messages:
+
+ fs messages -show all
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<afsd(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs mkmount - Creates a mount point for a volume
+
+=head1 SYNOPSIS
+
+fs mkmount B<-dir> I<directory> B<-vol> I<volume name> [B<-cell> I<cell name>]
+[B<-rw>] [B<-fast>] [B<-help>]
+
+fs mk B<-d> I<directory> B<-v> I<volume name> [B<-c> I<cell name>] [B<-r>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs mkmount> command creates a mount point for the volume named by
+the B<-vol> argument at the location in the AFS file space specified by
+the B<-dir> argument. The mount point looks like a standard directory
+element, and serves as the volume's root directory, but is actually a
+special file system object that refers to an AFS volume. When the
+Cache Manager first encounters a given mount point during pathname
+traversal, it contacts the VL Server to learn which file server
+machines house the indicated volume, then fetches a copy of the
+volume's root directory from the appropriate file server machine.
+
+It is possible, although not recommended, to create more than one
+mount point to a volume. The Cache Manager can become confused if a
+volume is mounted in two places along the same path through the
+filespace.
+
+The Cache Manager observes three basic rules as it traverses the AFS
+filespace and encounters mount points:
+
+=over
+
+=item *
+
+B<Rule 1>: Access Backup and Read-only Volumes When Specified
+
+When the Cache Manager encounters a mount point that specifies a
+volume with either a B<.readonly> or a B<.backup> extension, it accesses
+that type of volume only. If a mount point does not have either a
+B<.backup> or B<.readonly> extension, the Cache Manager uses Rules 2 and
+3.
+
+For example, the Cache Manager never accesses the read/write
+version of a volume if the mount point names the backup version.
+If the specified version is inaccessible, the Cache Manager
+reports an error.
+
+=item *
+
+B<Rule 2>: Follow the Read-only Path When Possible
+
+If a mount point resides in a read-only volume and the volume that
+it references is replicated, the Cache Manager attempts to access
+a read-only copy of the volume; if the referenced volume is not
+replicated, the Cache Manager accesses the read/write copy. The
+Cache Manager is thus said to prefer a I<read-only> path through the
+filespace, accessing read-only volumes when they are available.
+
+The Cache Manager starts on the read-only path in the first place
+because it always accesses a read-only copy of the B<root.afs> volume
+if it exists; the volume is mounted at the root of a cell's AFS
+filespace (named B</afs> by convention). That is, if the B<root.afs>
+volume is replicated, the Cache Manager attempts to access a
+read-only copy of it rather than the read/write copy. This rule
+then keeps the Cache Manager on a read-only path as long as each
+successive volume is replicated. The implication is that both the
+B<root.afs> and B<root.cell> volumes must be replicated for the Cache
+Manager to access replicated volumes mounted below them in the AFS
+filespace. The volumes are conventionally mounted at the B</afs> and
+B</afs/>I<cellname> directories, respectively.
+
+=item *
+
+B<Rule 3>: Once on a Read/write Path, Stay There
+
+If a mount point resides in a read/write volume and the volume
+name does not have a B<.readonly> or a B<.backup> extension, the Cache
+Manager attempts to access only the a read/write version of the
+volume. The access attempt fails with an error if the read/write
+version is inaccessible, even if a read-only version is
+accessible. In this situation the Cache Manager is said to be on a
+I<read/write path> and cannot switch back to the read-only path
+unless mount point explicitly names a volume with a B<.readonly>
+extension. (Cellular mount points are an important exception to
+this rule, as explained in the following discussion.
+
+=back
+
+There are three types of mount points, each appropriate for a
+different purpose because of the manner in which the Cache Manager
+interprets them.
+
+=over
+
+=item *
+
+When the Cache Manager crosses a I<regular> mount point, it obeys all
+three of the mount point traversal rules previously described. To
+create a regular mount point, include only the required B<-dir> and
+B<-vol> arguments to the C<fs mkmount> command.
+
+=over
+
+=item B<Note>:
+
+A regular mount point does not force the Cache Manager always to
+access read-only volumes (it is explicitly not a "read-only mount
+point"). If a volume is not replicated, the third traversal rule means
+that the Cache Manager still accesses the read/write volume when that
+is the only type available. However, if the Cache Manager is to access
+the read-only version of a replicated volume named by a regular mount
+point, all volumes that are mounted above it in the pathname must also
+be replicated.
+
+=back
+
+=item *
+
+When the Cache Manager crosses a I<read/write> mount point, it
+attempts to access only the volume version named in the mount
+point. If the volume name is the base (read/write) form, without a
+B<.readonly> or B<.backup> extension, the Cache Manager accesses the
+read/write version of the volume, even if it is replicated. In
+other words, the Cache Manager disregards the second mount point
+traversal rule when crossing a read/write mount point: it switches
+to the read/write path through the filespace.
+
+To create a read/write mount point, include the B<-rw> flag on the C<fs
+mkmount> command. It is conventional to create only one read/write
+mount point in a cell's filespace, using it to mount the cell's
+B<root.cell> volume just below the AFS filespace root (by convention,
+B</afs/>.I<cellname>). See the IBM AFS Quick Beginnings for instructions
+and the chapter about volume management in the IBM AFS
+Administration Guide for further discussion.
+
+Creating a read/write mount point for a read-only or backup volume
+is acceptable, but unnecessary. The first rule of mount point
+traversal already specifies that the Cache Manager accesses them
+if the volume name in a regular mount point has a B<.readonly> or
+B<.backup> extension.
+
+=item *
+
+When the Cache Manager crosses a I<cellular> mount point, it accesses
+the indicated volume in the specified cell, which is normally a
+foreign cell. (If the mount point does not name a cell along with
+the volume, the Cache Manager accesses the volume in the cell
+where the mount point resides.) The Cache Manager disregards the
+third mount point traversal rule when crossing a regular cellular
+mount point: it accesses a read-only version of the volume if it
+is replicated, even if the volume that houses the mount point is
+read/write. Switching to the read-only path in this way is
+designed to avoid imposing undue load on the file server machines
+in foreign cells.
+
+To create a regular cellular mount point, include the B<-cell>
+argument on the C<fs mkmount> command. It is conventional to create
+cellular mount points only at the second level in a cell's
+filespace, using them to mount foreign cells' B<root.cell> volumes
+just below the AFS filespace root (by convention, at
+B</afs/>I<foreign_cellname>). The mount point enables local users to
+access the foreign cell's filespace, assuming they have the
+necessary permissions on the ACL of the volume's root directory
+and that there is an entry for the foreign cell in each local
+client machine's B</usr/vice/etc/CellServDB> file. In the output of
+the C<fs lsmount> command, the cell name and a colon (:) appear
+between the initial number sign and the volume name in a regular
+cellular mount point name.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> I<directory>
+
+Names the directory to create as a mount point. The directory
+must not already exist. Relative pathnames are interpreted with
+respect to the current working directory.
+
+Specify the read/write path to the directory, to avoid the
+failure that results from attempting to create a new mount
+point in a read-only volume. By convention, the read/write path
+is indicated by placing a period before the cell name at the
+pathname's second level (for example, B</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only
+paths through the filespace, see the L</"DESCRIPTION"> section of
+this reference page.
+
+=item B<-vol> I<volume name>
+
+Specifies the name or volume ID number of the volume to mount.
+If appropriate, add the C<.readonly> or C<.backup> extension to the
+name, or specify the appropriate volume ID number.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which the volume resides (creates a cellular
+mount point). Provide the fully qualified domain name, or a
+shortened form that disambiguates it from the other cells
+listed in the local B</usr/vice/etc/CellServDB> file.
+
+If this argument is omitted, no cell indicator appears in the
+mount point. When the Cache Manager interprets it, it assumes
+that the volume named in the mount point resides in the same
+cell as the volume that houses the mount point.
+
+=item B<-rw>
+
+Creates a read/write mount point. Omit this flag to create a
+regular mount point.
+
+=item B<-fast>
+
+Prevents the Volume Location (VL) Server from checking that the
+volume has a VLDB entry and printing a warning message if it
+does not. Whether or not this flag is included, the File Server
+creates the mount point even when the volume has no VLDB entry.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command creates a regular mount point, mounting the
+volume B<user.smith> at B</afs/abc.com/usr/smith>:
+
+ cd /afs/abc.com/usr
+
+ fs mkmount -dir smith -vol user.smith
+
+The following commands create a read/write mount point and a regular
+mount point for the ABC Corporation cell's C<root.cell> volume in that
+cell's file tree. The second command follows the convention of putting
+a period at the beginning of the read/write mount point's name.
+
+ fs mkmount -dir /afs/abc.com -vol root.cell
+
+ fs mkmount -dir /afs/.abc.com -vol root.cell -rw
+
+The following command mounts the State University cell's C<root.cell>
+volume in the ABC Corporation cell's file tree, creating a regular
+cellular mount point called B</afs/stateu.edu>. When a ABC Corporation
+Cache Manager encounters this mount point, it crosses into the State
+University cell on a read-only path.
+
+ fs mkmount -dir /afs/stateu.edu -vol root.cell -c stateu.edu
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<i> (B<insert>) and B<a> (B<administer>) permissions on
+the ACL of the directory that is to house the mount point.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_client_version(1)>,
+L<fs_lsmount(1)>,
+L<fs_rmmount(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs newcell - Changes the kernel-resident list of a cell's database server machines
+
+=head1 SYNOPSIS
+
+fs newcell B<-name> I<cell name> B<-servers> I<primary servers> [I<primary servers> ...]
+[B<-linkedcell> I<linked cell name>] [B<-help>]
+
+fs n B<-n> I<cell name> B<-s> I<primary servers> [I<primary servers> ...] [B<-l> I<linked cell name>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs newcell> command removes the Cache Manager's kernel-resident
+list of database server machines for the cell specified by the B<-name>
+argument and replaces it with the database server machines named by
+the B<-servers> argument.
+
+Each time the machine reboots, the Cache Manager constructs the kernel
+list of cells and database server machines by reading the local
+B</usr/vice/etc/CellServDB> file. This command does not change the
+B<CellServDB> file, so any changes made with it persist only until the
+next reboot, unless the issuer also edits the file. The output of the
+C<fs listcells> command reflects changes made with this command, because
+that command consults the kernel-resident list rather than the
+B<CellServDB> file.
+
+This command can introduce a completely new cell into the
+kernel-resident list, but cannot make a cell inaccessible (it is not
+possible to remove a cell's entry from the kernel-resident list by
+providing no values for the B<-server> argument). To make a cell
+inaccessible, remove its entry from the B<CellServDB> file and reboot the
+machine.
+
+If the B<-name> argument names a DCE cell, then the B<-servers> argument
+names DFS Fileset Location (FL) Server machines. The B<-linkedcell>
+argument specifies the name of the AFS cell to link to a DCE cell for
+the purpose of DFS fileset location. Refer to the IBM AFS/DFS
+Migration Toolkit Administration Guide and Reference for more
+information on linking AFS clients to DCE cells using this command or
+by editing the B</usr/vice/etc/CellServDB> file.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<cell name>
+
+Specifies the fully-qualified cell name of the AFS or DCE cell.
+
+=item B<-servers> I<primary servers> [I<primary servers> ...]
+
+Specifies the fully-qualified hostnames of all AFS database
+server machines or DFS Fileset Location (FL) Server machines
+for the cell named by the B<-name> argument. If FL Server machines
+are specified, the local machine must be running the AFS/DFS
+Migration Toolkit Protocol Translator.
+
+=item B<-linkedcell> I<linked cell name>
+
+Specifies the name of the AFS cell to link to a DCE cell for
+the purpose of DFS fileset location.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the machine's kernel-resident list of
+database server machines for the ABC Corporation cell to include the
+machines B<db1.abc.com> and B<db2.abc.com>:
+
+ fs newcell -name abc.com -servers db1.abc.com db2.abc.com
+
+The following example links the DCE cell B<dce.abc.com> to the AFS cell
+B<abc.com>. The AFS client contacts the Fileset Location (FL) servers
+B<db1.dce.abc.com> and B<db2.dce.abc.com> for fileset location information
+as it interprets a DFS pathname.
+
+ fs newcell -name dce.abc.com -servers db1.dce.abc.com db2.dce.abc.com \
+ -linkedcell abc.com
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+Some commands, such as the C<klog> command, work correctly only when the
+information is accurate for a cell in both the B<CellServDB> file and the
+kernel-resident list.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_client_version(1)>,
+L<fs_listcells(1)>,
+IBM AFS/DFS Migration Toolkit Administration Guide and Reference,
+IBM AFS/DFS Migration Toolkit Administration Installation and Configuration Guide
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs quota - Displays the percentage of quota used in the volume containing a
+directory or file
+
+=head1 SYNOPSIS
+
+fs quota [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs q [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs quota> command displays the percent of quota consumed in the
+volume that contains each specified directory or file.
+
+To display more detailed information about the volume and the
+partition it resides on, use the C<fs examine> and C<fs listquota> commands.
+
+To set volume quota, use the C<fs setquota> or C<fs setvol> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each file or directory for which to display the quota
+consumed in its parent volume. Partial pathnames are
+interpreted relative to the current working directory, which is
+also the default value if this argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports the percent of volume quota used, in the following
+format:
+
+I<percent>% of quota used.
+
+=head1 EXAMPLES
+
+The following command lists the percent quota used of the volume
+housing the current working directory:
+
+ fs quota
+ 17% of quota used.
+
+The following command lists the percent quota used of both the volume
+housing the current working directory's parent directory and the
+volume housing the directory B</afs/abc.com/usr/smith>:
+
+ fs quota -path .. B</afs/abc>.com/usr/smith
+ 43% of quota used.
+ 92% of quota used.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<l> (B<lookup>) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and on the ACL of each directory that precedes it in
+the pathname.
+
+=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<fs_examine(1)>,
+L<fs_listquota(1)>,
+L<fs_setquota(1)>,
+L<fs_setvol(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs rmmount - Removes a mount point
+
+=head1 SYNOPSIS
+
+fs rmmount B<-dir> I<directory> [I<directory> ...] [B<-help>]
+
+fs rm B<-d> I<directory> [I<directory> ...] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs rmmount> command removes the mount point named by the B<-dir>
+argument from the file system. The corresponding volume remains on its
+host partition or partitions, but is inaccessible if there are no
+other mount points for it.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> I<directory> [I<directory> ...]
+
+Names the mount point to delete from the file system. The last
+element in the pathname must be an actual name, not a shorthand
+notation such as "dot" (.) or "dot dot" (..).
+
+Specify the read/write path to the directory, to avoid the
+failure that results from attempting to delete a mount point
+from a read-only volume. By convention, the read/write path is
+indicated by placing a period before the cell name at the
+pathname's second level (for example, B</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only
+paths through the filespace, see the L<fs_mkmount(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command removes the mount points B<jones> and B<terry> from
+the current working directory (the B</afs/abc.com/usr> directory).
+
+ fs rmmount jones terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<d> (B<delete>) permission on the ACL of the
+directory that houses each mount point.
+
+=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<fs_lsmount(1)>,
+L<fs_mkmount(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setacl - Sets the ACL for a directory
+
+=head1 SYNOPSIS
+
+fs setacl B<-dir> I<directory> [I<directory> ...] B<-acl> I<access list entries> [I<access list entries> ...]
+[B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>]
+
+fs sa B<-d> I<directory> [I<directory> ...] B<-a> I<access list entries> [I<access list entries> ...]
+[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
+
+fs seta B<-d> I<directory> [I<directory> ...] B<-a> I<access list entries> [I<access list entries> ...]
+[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setacl> command adds the access control list (ACL) entries
+specified with the B<-acl> argument to the ACL of each directory named by
+the B<-dir> argument.
+
+If the B<-dir> argument designates a pathname in DFS filespace (accessed
+via the AFS/DFS Migration Toolkit Protocol Translator), it can be a
+file as well as a directory. The ACL must already include an entry for
+B<mask_obj>, however. For more details, refer to the IBM AFS/DFS
+Migration Toolkit Administration Guide and Reference.
+
+Only user and group entries are acceptable values for the B<-acl>
+argument. Do not place machine entries (IP addresses) directly on an
+ACL; instead, make the machine entry a group member and place the
+group on the ACL.
+
+To completely erase the existing ACL before adding the new entries,
+provide the B<-clear> flag. To add the specified entries to the Negative
+rights section of the ACL (deny rights to specified users or groups),
+provide the B<-negative> flag.
+
+To display an ACL, use the C<fs listacl> command. To copy an ACL from one
+directory to another, use the C<fs copyacl> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dir> I<directory> [I<directory> ...]
+
+Names each AFS directory, or DFS directory or file, for which
+the set the ACL. Partial pathnames are interpreted relative to
+the current working directory.
+
+Specify the read/write path to each directory (or DFS file), to
+avoid the failure that results from attempting to change a
+read-only volume. By convention, the read/write path is
+indicated by placing a period before the cell name at the
+pathname's second level (for example, B</afs/.abc.com>). For
+further discussion of the concept of read/write and read-only
+paths through the filespace, see the L<fs_mkmount(1)> reference page.
+
+=item B<-acl> I<access list entries> [I<access list entries> ...]
+
+Defines a list of one or more ACL entries, each a pair that
+names
+
+=over
+
+=item *
+
+A user name or group name as listed in the Protection
+Database
+
+=item *
+
+One or more ACL permissions, indicated either by combining
+the individual letters or by one of the four acceptable
+shorthand words
+
+=back
+
+in that order, separated by a space (thus every instance of
+this argument has two parts). The accepted AFS abbreviations
+and shorthand words, and the meaning of each, are as follows:
+
+=over
+
+=item B<a>
+
+(B<administer>): change the entries on the ACL
+
+=item B<d>
+
+(B<delete>): remove files and subdirectories from the
+directory or move them to other directories
+
+=item B<i>
+
+(B<insert>): add files or subdirectories to the directory by
+copying, moving or creating
+
+=item B<k>
+
+(B<lock>): set read locks or write locks on the files in the
+directory
+
+=item B<l>
+
+(B<lookup>): list the files and subdirectories in the
+directory, stat the directory itself, and issue the C<fs
+listacl> command to examine the directory's ACL
+
+=item B<r>
+
+(B<read>): read the contents of files in the directory;
+issue the C<ls -l> command to stat the elements in the
+directory
+
+=item B<w>
+
+(B<write>): modify the contents of files in the directory,
+and issue the UNIX C<chmod> command to change their mode
+bits
+
+=item B<A, B, C, D, E, F, G, H>
+
+Have no default meaning to the AFS server processes, but
+are made available for applications to use in controlling
+access to the directory's contents in additional ways.
+The letters must be uppercase.
+
+=item B<all>
+
+Equals all seven permissions (B<rlidwka>).
+
+=item B<none>
+
+No permissions. Removes the user/group from the ACL, but
+does not guarantee they have no permissions if they
+belong to groups that remain on the ACL.
+
+=item B<read>
+
+Equals the B<r> (B<read>) and B<l> (B<lookup>) permissions.
+
+=item B<write>
+
+Equals all permissions except B<a> (B<administer>), that is,
+B<rlidwk>.
+
+=back
+
+It is acceptable to mix entries that combine the individual
+letters with entries that use the shorthand words, but not use
+both types of notation within an individual pairing of user or
+group and permissions.
+
+To learn the proper format and acceptable values for DFS ACL
+entries, see the IBM AFS/DFS Migration Toolkit Administration
+Guide and Reference.
+
+=item B<-clear>
+
+Removes all existing entries on each ACL before adding the
+entries specified with the B<-acl> argument.
+
+=item B<-negative>
+
+Places the specified ACL entries in the C<Negative rights> section
+of each ACL, explicitly denying the rights to the user or
+group, even if entries on the accompanying C<Normal rights>
+section of the ACL grant them permissions.
+
+This argument is not supported for DFS files or directories,
+because DFS does not implement negative ACL permissions.
+
+=item B<-id>
+
+Places the ACL entries on the Initial Container ACL of each DFS
+directory, which are the only file system objects for which
+this flag is supported.
+
+=item B<-if>
+
+Places the ACL entries on the Initial Object ACL of each DFS
+directory, which are the only file system objects for which
+this flag is supported.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example adds two entries to the C<Normal rights> section of
+the current working directory's ACL: the first entry grants B<r> (B<read>)
+and B<l> (B<lookup>) permissions to the group B<pat:friends>, while the other
+(using the B<write> shorthand) gives all permissions except B<a>
+(B<administer>) to the user B<smith>.
+
+ fs setacl -dir . -acl pat:friends rl smith write
+
+ fs listacl -path .
+ Access list for . is
+ Normal rights:
+ pat:friends rl
+ smith rlidwk
+
+The following example includes the B<-clear> flag, which removes the
+existing permissions (as displayed with the C<fs listacl> command) from
+the current working directory's B<reports> subdirectory and replaces them
+with a new set.
+
+ fs listacl -dir reports
+ Access list for reports is
+ Normal rights:
+ system:authuser rl
+ pat:friends rlid
+ smith rlidwk
+ pat rlidwka
+ Negative rights:
+ terry rl
+
+ fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl
+
+ fs listacl -dir reports
+ Access list for reports is
+ Normal rights:
+ system:anyuser rl
+ smith rlidwk
+ pat rlidwka
+
+The following example use the B<-dir> and B<-acl> switches because it sets
+the ACL for more than one directory (both the current working
+directory and its public subdirectory).
+
+ fs setacl -dir . public -acl pat:friends rli
+
+ fs listacl -path . public
+ Access list for . is
+ Normal rights:
+ pat rlidwka
+ pat:friends rli
+ Access list for public is
+ Normal rights:
+ pat rlidwka
+ pat:friends rli
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the B<a> (B<administer>) permission on the directory's
+ACL; the directory's owner and the members of the
+B<system:administrators> group have the right implicitly, even if it does
+not appear on the ACL.
+
+=head1 CAVEATS
+
+If the ACL already grants certain permissions to a user or group, the
+permissions specified with the C<fs setacl> command replace the existing
+permissions, rather than being added to them.
+
+Setting negative permissions is generally unnecessary and not
+recommended. Simply omitting a user or group from the Normal rights
+section of the ACL is normally adequate to prevent access. In
+particular, note that it is futile to deny permissions that are
+granted to members of the B<system:anyuser> group on the same ACL; the
+user needs only to issue the C<unlog> command to receive the denied
+permissions.
+
+When including the B<-clear> option, be sure to reinstate an entry for
+each directory's owner that includes at least the B<l> (B<lookup>)
+permission. Without that permission, it is impossible to resolve the
+"dot" ( . ) and "dot dot" ( .. ) shorthand from within the directory.
+(The directory's owner does implicitly have the B<a> [B<administer>]
+permission even on a cleared ACL, but must know to use it to add other
+permissions.)
+
+=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<fs_copyacl(1)>,
+L<fs_listacl(1)>,
+L<fs_mkmount(1)>,
+IBM_AFS/DFS_Migration Toolkit_Administration Guide_and Reference
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setcachesize - Sets the size of the disk cache
+
+=head1 SYNOPSIS
+
+fs setcachesize [B<-blocks> I<size in 1K byte blocks (0 =E<gt> reset)>]
+[B<-reset>] [B<-help>]
+
+fs setca [B<-b> I<size in 1K byte blocks (0 =E<gt> reset)>] [B<-r>] [B<-h>]
+
+fs cachesize [B<-b> I<size in 1K byte blocks (0 =E<gt> reset)>] [B<-r>] [B<-h>]
+
+fs ca [B<-b> I<size in 1K byte blocks (0 =E<gt> reset)>] [B<-r>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setcachesize> command changes the number of kilobyte blocks of
+local disk space available to the Cache Manager for its data cache, on
+machines that use a disk cache. The command is not operative on
+machines that use a memory cache.
+
+To return the cache size to the default value specified in the third
+field of the local B</usr/vice/etc/cacheinfo> file, provide a value of B<0>
+to the B<-blocks> argument.
+
+To return the cache size to the value set when the machine was last
+rebooted, use the B<-reset> flag instead of the B<-blocks> argument. This is
+normally the amount specified in the B<cacheinfo> file, unless the
+B<-blocks> argument was included on the C<afsd> command to override the
+B<cacheinfo> value.
+
+To display the current cache size and amount of cache in use, for both
+disk and memory caches, use the C<fs getcacheparms> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-blocks> I<size in 1K byte blocks (0 =E<gt> reset)>
+
+Specifies the number of one-kilobyte blocks of disk space
+available for the Cache Manager to devote to the cache. Provide
+a value of B<0> to set cache size to the default specified in the
+B<cacheinfo> file.
+
+=item B<-reset>
+
+Returns the cache size to the value set when the machine was
+last booted. This agrees with the value in the B<cacheinfo> file
+unless the B<-blocks> argument was used on the C<afsd> command.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the disk cache size to 25000 kilobyte
+blocks.
+
+ fs setcachesize -blocks 25000
+
+Both of the following commands reset the disk cache size to the value
+in the B<cacheinfo> file, assuming that the B<-blocks> argument to the C<afsd>
+command was not used.
+
+ fs setcachesize -blocks 0
+
+ fs setcachesize -reset
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+This command is not operative on machines using a memory cache, and
+results in an error message. To change memory cache size, edit the
+B<cacheinfo> file and reboot, or reboot and provide the B<-blocks> argument
+to the C<afsd> command.
+
+On machines using a disk cache, do not set the cache size to exceed
+85% to 90% of the actual disk space available for the cache directory.
+The cache implementation itself requires a small amount of space 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,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<cacheinfo(1)>,
+L<afsd(1)>,
+L<fs_getcacheparms(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setcell - Allows or disallows running of setuid programs from specified cells
+
+=head1 SYNOPSIS
+
+fs setcell B<-cell> I<cell name> [I<cell name> ...] [B<-suid>] [B<-nosuid>] [B<-help>]
+
+fs setce B<-c> I<cell name> [I<cell name> ...] [B<-s>] [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setcell> command sets whether the Cache Manager allows programs
+(and other executable files) from each cell named by the B<-cell>
+argument to run with setuid permission. By default, the Cache Manager
+allows programs from its home cell to run with setuid permission, but
+not programs from any foreign cells. A program belongs to the same
+cell as the file server machine that houses the volume in which the
+program's binary file resides, as specified in the file server
+machine's B</usr/afs/etc/ThisCell> file. The Cache Manager determines its
+own home cell by reading the B</usr/vice/etc/ThisCell> file at
+initialization.
+
+To enable programs from each specified cell to run with setuid
+permission, include the B<-suid> flag. To prohibit programs from running
+with setuid permission, include the B<-nosuid> flag, or omit both flags.
+
+The C<fs setcell> command directly alters a cell's setuid status as
+recorded in kernel memory, so rebooting the machine is unnecessary.
+However, non-default settings do not persist across reboots of the
+machine unless the appropriate C<fs setcell> command appears in the
+machine's AFS initialization file.
+
+To display a cell's setuid status, issue the C<fs getcellstatus> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> I<cell name> [I<cell name> ...]
+
+Names each cell for which to set setuid status. Provide the
+fully qualified domain name, or a shortened form that
+disambiguates it from the other cells listed in the local
+B</usr/vice/etc/CellServDB> file.
+
+=item B<-suid>
+
+Allows programs from each specified cell to run with setuid
+privilege. Provide it or the B<-nosuid> flag, or omit both flags
+to disallow programs from running with setuid privilege.
+
+=item B<-nosuid>
+
+Prevents programs from each specified cell from running with
+setuid privilege. Provide it or the B<-suid> flag, or omit both
+flags to disallow programs form running with setuid privilege.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command enables executable files from the State
+University cell to run with setuid privilege on the local machine:
+
+ fs setcell -cell stateu.edu -suid
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+AFS does not recognize effective UID: if a setuid program accesses AFS
+files and directories, it does so using the current AFS identity of
+the AFS user who initialized the program, not of the program's owner.
+Only the local file system recognizes effective UID.
+
+Only members of the B<system:administrators> group can turn on the setuid
+mode bit on an AFS file or directory.
+
+When the setuid mode bit is turned on, the UNIX C<ls -l> command displays
+the third user mode bit as an s instead of an x. However, the s does
+not appear on an AFS file or directory unless setuid permission is
+enabled for the cell in which the file resides.
+
+=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<fs_getcellstatus(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setclientaddrs - Sets the client interfaces to register with the File Server
+
+=head1 SYNOPSIS
+
+fs setclientaddrs [B<-address> I<client network interfaces> [I<client network interfaces> ...]] [B<-help>]
+
+fs setcl [B<-a> I<client network interfaces> [I<client network interfaces> ...]] [B<-h>]
+
+fs sc [B<-a> I<client network interfaces> [I<client network interfaces> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setclientaddrs> command defines the IP addresses of the
+interfaces that the local Cache Manager registers with a File Server
+when first establishing a connection to it.
+
+The File Server uses the addresses when it initiates a remote
+procedure call (RPC) to the Cache Manager (as opposed to responding to
+an RPC sent by the Cache Manager). There are two common circumstances
+in which the File Server initiates RPCs: when it breaks callbacks and
+when it pings the client machine to verify that the Cache Manager is
+still accessible.
+
+The list of interfaces specified with this command replaces the list
+that the Cache Manager constructs and records in kernel memory as it
+initializes. At that time, if the file B</usr/vice/etc/NetInfo> exists on
+the client machine's local disk, the Cache Manager uses its contents
+as the basis for the list of interfaces addresses. If the file does
+not exist, the Cache Manager instead uses the network interfaces
+configured with the operating system. It then removes from the list
+any address included in the local B</usr/vice/etc/NetRestrict> file. It
+records the final list in kernel memory. (An administrator must create
+the B<NetInfo> and B<NetRestrict> files; there are no default versions of
+them.)
+
+If an RPC to that interface fails, the File Server simultaneously
+sends RPCs to all of the other interfaces in the list, to learn which
+of them are still available. Whichever interface replies first is the
+one to which the File Server then sends pings and RPCs to break
+callbacks.
+
+To list the interfaces that the Cache Manager is currently registering
+with File Servers, use the C<fs getclientaddrs> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-address> I<client network interfaces> [I<client network interfaces> ...]
+
+Specifies each IP address to place in the list of interfaces,
+in dotted decimal format. Hostnames are not acceptable.
+Separate each address with one or more spaces.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The message:
+
+Adding I<interface>
+
+confirms that each new interface was added to the Cache Manager's
+list. The address appears in hexadecimal format to match the notation
+used in the File Server log, B</usr/afs/logs/FileLog>.
+
+=head1 EXAMPLES
+
+The following example sets the two interfaces that the Cache Manager
+registers with File Servers.
+
+ fs setclientaddrs 191.255.105.68 191.255.108.84
+ Adding 0xbfff6944
+ Adding 0xbfff6c54
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+The list specified with this command persists in kernel memory only
+until the client machine reboots. To preserve it across reboots,
+either list the interfaces in the local B</usr/vice/etc/NetInfo> file, or
+place the appropriate C<fs setclientaddrs> command in the machine's AFS
+initialization script.
+
+Changes made with this command do not propagate automatically to File
+Servers to which the Cache Manager has already established a
+connection. To force such File Servers to use the revised list, either
+reboot each file server machine, or change the B<NetInfo> file and reboot
+the client machine.
+
+The C<fs> command interpreter verifies that each of the addresses
+specified as a value for the B<-address> argument is actually configured
+with the operating system on the client machine. If it is not, the
+command fails with an error message that marks the address as a
+Nonexistent interface.
+
+=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<NetInfo_client_version(1)>,
+L<NetRestrict_client_version(1)>,
+L<fileserver(1)>,
+L<fs_getclientaddrs(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setquota - Sets the maximum quota for the volume containing a file or directory
+
+=head1 SYNOPSIS
+
+fs setquota [B<-path> I<dir/file path>] B<-max> I<max quota in kbytes> [B<-help>]
+
+fs setq [B<-p> I<dir/file path>] B<-m> I<max quota in kbytes> [B<-h>]
+
+fs sq [B<-p> I<dir/file path>] B<-m> I<max quota in kbytes> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setquota> command sets the quota (maximum possible size) of the
+read/write volume that contains the directory or file named by the
+B<-path> argument.
+
+To set the quota on multiple volumes at the same time, use the C<fs
+setvol> command.
+
+To display a volume's quota, use the C<fs examine>, C<fs listquota> or C<fs
+quota> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path>
+
+Names the directory or file for which to set the host volume's
+quota. Partial pathnames are interpreted relative to the
+current working directory, which is also the default value if
+this argument is omitted.
+
+Specify the read/write path to the file or directory, to avoid
+the failure that results from attempting to change a read-only
+volume. By convention, the read/write path is indicated by
+placing a period before the cell name at the pathname's second
+level (for example, B</afs/.abc.com>). For further discussion of
+the concept of read/write and read-only paths through the
+filespace, see the L<fs_mkmount(1)> reference page.
+
+=item B<-max> I<max quota in kbytes>
+
+Sets the maximum amount of file server disk space the volume
+can occupy. Specify the number of one-kilobyte blocks as a
+positive integer (B<1024> is one megabyte). A value of B<0> sets an
+unlimited quota, but the size of the disk partition that houses
+the volume places an absolute limit on the volume's size.
+
+If the B<-path> argument is omitted (to set the quota of the
+volume housing the current working directory), the B<-max> switch
+must be included with this argument.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command imposes a maximum quota of 3000 kilobytes on the
+volume that houses the B</afs/abc.com/usr/smith> directory:
+
+ fs setquota -path /afs/abc.com/usr/smith -max 3000
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the B<system:administrators> group.
+
+=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<fs_examine(1)>,
+L<fs_listquota(1)>,
+L<fs_quota(1)>,
+L<fs_mkmount(1)>,
+L<fs_setvol(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setserverprefs - Sets the Cache Manager's preference ranks for file server or VL Server
+machines
+
+=head1 SYNOPSIS
+
+fs setserverprefs [B<-servers> I<fileserver names and ranks> [I<fileserver names and ranks> ...]]
+[B<-vlservers> I<VL server names and ranks> [I<VL server names and ranks> ...]]
+[B<-file> I<input from named file>] [B<-stdin>] [B<-help>]
+
+fs sets [B<-se> I<fileserver names and ranks> [I<fileserver names and ranks> ...]] [B<-vl> I<VL server names and ranks>^
++]
+[B<-f> I<input from named file>] [B<-st>] [B<-h>]
+
+fs sp [B<-se> I<fileserver names and ranks> [I<fileserver names and ranks> ...]] [B<-vl> I<VL server names and ranks> [I<VL server names and ranks> ...]]
+
+[B<-f> I<input from named file>] [B<-st>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setserverprefs> command sets the local Cache Manager's
+preference ranks for one or more file server machine interfaces or, if
+the B<-vlserver> argument is provided, for Volume Location (VL) Server
+machines. For file server machines, the numerical ranks determine the
+order in which the Cache Manager attempts to contact the interfaces of
+machines that are housing a volume. For VL Server machines, the ranks
+determine the order in which the Cache Manager attempts to contact a
+cell's VL Servers when requesting VLDB information.
+
+The L<fs_getserverprefs(1)> reference page explains how the Cache Manager
+uses preference ranks when contacting file server machines or VL
+Server machines. The following paragraphs explain how the Cache
+Manager calculates default ranks, and how to use this command to
+change the defaults.
+
+=head2 Calculation of Default Preference Ranks
+
+The Cache Manager stores a preference rank in kernel memory as a
+paired IP address and numerical rank. If a file server machine is
+multihomed, the Cache Manager assigns a distinct rank to each of the
+machine's addresses (up to the number of addresses that the VLDB can
+store per machine, which is specified in the IBM AFS Release Notes).
+Once calculated, a rank persists until the machine reboots, or until
+this command is used to change it.
+
+The Cache Manager sets default VL Server preference ranks as it
+initializes, randomly assigning a rank from the range 10,000 to 10,126
+to each of the machines listed in the local B</usr/vice/etc/CellServDB>
+file. Machines from different cells can have the same rank, but this
+does not present a problem because the Cache Manager consults only one
+cell's ranks at a time.
+
+The Cache Manager sets default preference ranks for file server
+machine as it fetches volume location information from the VLDB. Each
+time it learns about file server machine interfaces for which it has
+not already set ranks, it assigns a rank to each interface. If the
+local client machine has only one IP address, the Cache Manager
+compares it to the server interface's IP address and sets a rank
+according to the following algorithm. If the client machine is
+multihomed, the Cache Manager applies the algorithm to each of the
+client machine's addresses and assigns to the file server machine
+interface the lowest rank that results.
+
+=over
+
+=item *
+
+If the local machine is a file server machine, the base rank for
+each of its interfaces is 5,000.
+
+=item *
+
+If the file server machine interface is on the same subnetwork as
+the client interface, its base rank is 20,000.
+
+=item *
+
+If the file server machine interface is on the same network as the
+client interface, or is at the distant end of a point-to-point
+link with the client interface, its base rank is 30,000.
+
+=item *
+
+If the file server machine interface is on a different network
+than the client interface, or the Cache Manager cannot obtain
+network information about it, its base rank is 40,000.
+
+=back
+
+After assigning a base rank to a file server machine interface, the
+Cache Manager adds to it a number randomly chosen from the range 0
+(zero) to 14. As an example, a file server machine interface in the
+same subnetwork as the local machine receives a base rank of 20,000,
+but the Cache Manager records the actual rank as an integer between
+20,000 and 20,014. This process reduces the number of interfaces that
+have exactly the same rank. As with VL Server machine ranks, it is
+possible for file server machine interfaces from foreign cells to have
+the same rank as interfaces in the local cell, but this does not
+present a problem. Only the relative ranks of the interfaces that
+house a given volume are relevant, and AFS only supports storage of a
+volume in one cell at a time.
+
+=head2 Setting Non-default Preference Ranks
+
+Use the C<fs setserverprefs> command to reset an existing preference
+rank, or to set the initial rank of a file server machine interface or
+VL Server machine for which the Cache Manager has no rank. To make a
+rank persist across a reboot of the local machine, place the
+appropriate C<fs setserverprefs> command in the machine's AFS
+initialization file.
+
+Specify each preference rank as a pair of values separated by one or
+more spaces:
+
+=over
+
+=item *
+
+The first member of the pair is the fully-qualified hostname (for
+example, B<fs1.abc.com>), or the IP address in dotted decimal format,
+of a file server machine interface or VL Server machine
+
+=item *
+
+The second member of the pair is an integer. The possible ranks
+range from B<1> through B<65535>.
+
+=back
+
+As with default ranks, the Cache Manager adds a randomly chosen
+integer to a rank specified by this command. For file server machine
+interfaces, the integer is from the range 0 (zero) to 14; for VL
+Server machines, it is from the range 0 (zero) to 126. For example, if
+the administrator assigns a rank of 15,000 to a file server machine
+interface, the Cache Manager stores an integer between 15,000 to
+15,014.
+
+There are several ways to provide ranks for file server machine
+interfaces (but not for VL Server machines):
+
+=over
+
+=item *
+
+On the command line, following the B<-servers> argument.
+
+=item *
+
+In a file named by the B<-file> argument. Place each pair on its own
+line in the file. Directing the output from the C<fs getserverprefs>
+command to a file automatically generates a file with the proper
+format.
+
+=item *
+
+Via the standard input stream, by providing the B<-stdin> flag. This
+method enables the issuer to feed in values directly from a
+program or script that generates preference ranks by using an
+algorithm appropriate to the local cell. The AFS distribution does
+not include such programs or scripts.
+
+=back
+
+When setting file server machine preference ranks, it is legal to
+combine the B<-servers>, B<-file>, and B<-stdin> options on a single command
+line. If different options specify a different rank for the same
+interface, the Cache Manager stores and uses the rank assigned with
+the B<-servers> argument.
+
+The B<-vlservers> argument is the only way to assign VL Server machine
+ranks. It can be combined with one or more of the B<-servers>, B<-file>, and
+B<-stdin> options, but the Cache Manager applies the values provided for
+those options to file server machine ranks only.
+
+The C<fs> command interpreter does not verify hostnames or IP addresses,
+and so assigns preference ranks to invalid machine names or addresses.
+The Cache Manager never uses such ranks unless the same incorrect
+information is in the VLDB.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-servers> I<fileserver names and ranks> [I<fileserver names and ranks> ...]
+
+Specifies one or more file server machine preference ranks.
+Each rank pairs the fully-qualified hostname or IP address (in
+dotted decimal format) of a file server machine's interface
+with an integer rank, separated by one or more spaces; also
+separate each pair with one or more spaces. Acceptable values
+for the rank range from B<1> through B<65521>; a lower value
+indicates a greater preference. Providing ranks outside this
+range can have unpredictable results. Providing a value no
+larger than B<65521> guarantees that the rank does not exceed the
+maximum possible value of 65,535 even if the largest random
+factor (14) is added.
+
+This argument can be combined with the B<-file> argument, B<-stdin>
+flag, or both. If more than one of the arguments sets a rank
+for the same interface, the rank set by this argument takes
+precedence. It can also be combined with the B<-vlservers>
+argument, but does not interact with it.
+
+=item B<-vlservers> I<VL server names and ranks> [I<VL server names and ranks> ...]
+
+Specifies one or more VL Server preference ranks. Each rank
+pairs the fully-qualified hostname or IP address (in dotted
+decimal format) of a VL Server machine with an integer rank,
+separated by one or more spaces; also separate each pair with
+one or more spaces. Acceptable values for the rank range from B<1>
+through B<65521>; a lower value indicates a greater preference.
+Providing ranks outside this range can have unpredictable
+results. Providing a value no larger than B<65521> guarantees that
+the rank does not exceed the maximum possible value of 65,535
+even if the largest random factor (14) is added.
+
+This argument can be combined with the B<-servers> argument, B<-file>
+argument, B<-stdin> flag, or any combination of the three, but
+does not interact with any of them. They apply only to file
+server machine ranks.
+
+=item B<-file> I<input from named file>
+
+Specifies the full pathname of a file from which to read pairs
+of file server machine interfaces and their ranks, using the
+same notation and range of values as for the B<-servers> argument.
+In the file, place each pair on its own line and separate the
+two parts of each pair with one or more spaces.
+
+This argument can be combined with the B<-servers> argument,
+B<-stdin> flag, or both. If more than one of the arguments sets a
+rank for the same interface, the rank set by the B<-server>
+argument takes precedence. It can also be combined with the
+B<-vlservers> argument, but does not interact with it.
+
+=item B<-stdin>
+
+Reads pairs of file server machine interface and integer rank
+from the standard input stream. The intended use is to accept
+input piped in from a user-defined program or script that
+generates ranks in the appropriate format, but it also accepts
+input typed to the shell. Format the interface and rank pairs
+as for the B<-file> argument. If typing at the shell, type
+B<E<lt>Ctrl-dE<gt>> after the final newline to complete the input.
+
+This argument can be combined with the B<-servers> argument, the
+B<-file> argument, or both. If more than one of the arguments sets
+a rank for the same interface, the rank set by the B<-server>
+argument takes precedence. It can also be combined with the
+B<-vlservers> argument, but does not interact with it.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the Cache Manager's preference ranks for
+the file server machines named B<fs3.abc.com> and B<fs4.abc.com>, the latter
+of which is specified by its IP address, 192.12.105.100. The machines
+reside in another subnetwork of the local machine's network, so their
+default base rank is 30,000. To increase the Cache Manager's
+preference for these machines, the issuer assigns a rank of B<25000>, to
+which the Cache Manager adds an integer in the range from 0 to 15.
+
+ fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000
+
+The following command uses the B<-servers> argument to set the Cache
+Manager's preference ranks for the same two file server machines, but
+it also uses the B<-file> argument to read a collection of preference
+ranks from a file that resides in the local file B</etc/fs.prefs>:
+
+ fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \
+ -file /etc/fs.prefs
+
+The B</etc/fs.prefs> file has the following contents and format:
+
+ 192.12.108.214 7500
+ 192.12.108.212 7500
+ 138.255.33.41 39000
+ 138.255.33.34 39000
+ 128.0.45.36 41000
+ 128.0.45.37 41000
+
+The following command uses the B<-stdin> flag to read preference ranks
+from the standard input stream. The ranks are piped to the command
+from a program, B<calc_prefs>, which was written by the issuer to
+calculate preferences based on values significant to the local cell.
+
+ calc_prefs | fs setserverprefs -stdin
+
+The following command uses the B<-vlservers> argument to set the Cache
+Manager's preferences for the VL server machines named B<fs1.abc.com>,
+B<fs3.abc.com>, and B<fs4.abc.com> to base ranks of 1, 11000, and 65521,
+respectively:
+
+ fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \
+ fs4.abc.com 65521
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<fs_getserverprefs(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs setvol - Set maximum quota and messages for the volume containing a file or
+directory
+
+=head1 SYNOPSIS
+
+fs setvol [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-max> I<disk space quota in 1K units>]
+[B<-offlinemsg> I<offline message>] [B<-help>]
+
+fs setv [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-ma> I<disk space quota in 1K units>]
+[B<-o> I<offline message>] [B<-h>]
+
+fs sv [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-ma> I<disk space quota in 1K units>]
+[B<-o> I<offline message>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs setvol> command sets the quota (maximum possible size) of the
+read/write volume that contains each directory or file named by the
+B<-path> argument. To associate a message with the volume which then
+appears in the output of the C<fs examine> command, include the
+B<-offlinemsg> argument.
+
+To display all of the settings made with this command, use the C<fs
+examine> command. The C<fs listquota> command reports a fileset's quota,
+and the C<fs quota> command the percent of quota used.
+
+To set quota on one volume at a time, use the C<fs setquota> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each file or directory for which to set the host volume's
+quota and offline message. Partial pathnames are interpreted
+relative to the current working directory, which is also the
+default value if this argument is omitted.
+
+Specify the read/write path to the file or directory, to avoid
+the failure that results from attempting to change a read-only
+volume. By convention, the read/write path is indicated by
+placing a period before the cell name at the pathname's second
+level (for example, B</afs/.abc.com>). For further discussion of
+the concept of read/write and read-only paths through the
+filespace, see the L<fs_mkmount(1)> reference page.
+
+=item B<-max> I<disk space quota in 1K units>
+
+Sets the maximum amount of file server disk space the volume
+can occupy. Provide a positive integer to indicate the number
+of one-kilobyte blocks (B<1024> is one megabyte). A value of B<0>
+sets an unlimited quota, but the size of the disk partition
+that houses the volume places an absolute limit on the volume's
+size.
+
+If the B<-path> argument is omitted (so that the command sets the
+quota of the volume housing the current working directory), the
+B<-max> switch must be provided.
+
+=item B<-offlinemsg> I<offline message>
+
+Associates a message with the volume which then appears in the
+output of the C<fs examine> command. Its intended use is to
+explain why the volume is currently offline.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command imposes a 6500 kilobyte quota on the volumes
+mounted at the home directories B</afs/abc.com/usr/smith> and
+B</afs/abc.com/usr/pat>:
+
+ cd /afs/abc.com/usr
+
+ fs setvol -path smith pat -max 6500
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the B<system:administrators> group.
+
+=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<fs_examine(1)>,
+L<fs_listquota(1)>,
+L<fs_mkmount(1)>,
+L<fs_quota(1)>,
+L<fs_setquota(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs storebehind - Enables asynchronous writes to the file server
+
+=head1 SYNOPSIS
+
+fs storebehind [B<-kbytes> I<asynchrony for specified names>]
+[B<-files> I<specific pathnames> [I<specific pathnames> ...]]
+[B<-allfiles> I<new default (KB)>] [B<-verbose>] [B<-help>]
+
+fs st [B<-k> I<asynchrony for specified names>] [B<-f> I<specific pathnames> [I<specific pathnames> ...]]
+[B<-a> I<new default (KB)>] [B<-v>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs storebehind> command enables the Cache Manager to perform a
+delayed asynchronous write to the File Server when an application
+closes a file. By default, the Cache Manager writes all data to the
+File Server immediately and synchronously when an application program
+closes a file--that is, the B<close> system call does not return until
+the Cache Manager has actually transferred the final chunk of the file
+to the File Server. This command specifies the number of kilobytes of
+a file that can still remain to be written to the File Server when the
+Cache Manager returns control to the application. It is useful if
+users working on the machine commonly work with very large files, but
+also introduces the complications discussed in the L</"CAVEATS"> section.
+
+Set either or both of the following in a single command:
+
+=over
+
+=item *
+
+To set a value that applies to all AFS files manipulated by
+applications running on the machine, use the B<-allfiles> argument.
+This value is termed the I<default store asynchrony> for the machine,
+and persists until the machine reboots. If it is not set, the
+default value is zero, indicating that the Cache Manager performs
+synchronous writes.
+
+As an example, the following setting means that when an
+application closes a file, the Cache Manager can return control to
+the application as soon as no more than 10 kilobytes of the file
+remain to be written to the File Server.
+
+ -allfiles 10
+
+=item *
+
+To set a value that applies to one or more individual files, and
+overrides the value of the B<-allfiles> argument for them, combine
+the B<-kbytes> and B<-files> arguments. The setting persists as long as
+there is an entry for the file in the kernel table that the Cache
+Manager uses to track certain information about files. In general,
+such an entry persists at least until an application closes the
+file or exits, but the Cache Manager is free to recycle the entry
+if the file is inactive and it needs to free up slots in the
+table. To increase the certainty that there is an entry for the
+file in the table, issue the C<fs storebehind> command shortly before
+closing the file.
+
+As an example, the following setting means that when an
+application closes either of the files B<bigfile> and B<biggerfile>, the
+Cache Manager can return control to the application as soon as no
+more than a megabyte of the file remains to be written to the File
+Server.
+
+ -kbytes 1024 -files bigfile biggerfile
+
+Note that once an explicit value has been set for a file, the only
+way to make it subject to the default store asynchrony once again
+is to set B<-kbytes> to that value. In other words, there is no
+combination of arguments that automatically makes a file subject
+to the default store asynchrony once another value has been set
+for the file.
+
+=back
+
+To display the settings that currently apply to individual files or to
+all files, provide the command's arguments in certain combinations as
+specified in the L</"OUTPUT"> section of this reference page.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-kbytes> I<asynchrony for specified names>
+
+Specifies the number of kilobytes of data from each file named
+by the B<-files> argument that can remain to be written to the
+file server when the Cache Manager returns control to an
+application program that closed the file. The B<-files> argument
+is required along with this argument. Provide an integer from
+the range B<0> (which reinstates the Cache Manager's default
+behavior or writing synchronously) to the maximum AFS file
+size.
+
+=item B<-files> I<specific pathnames> [I<specific pathnames> ...]
+
+Names each file to which the value set with the B<-kbytes>
+argument applies. The setting persists as long as there is an
+entry for the file in the kernel table that the Cache Manager
+uses to track certain information about files. Because closing
+a file generally erases the entry, when reopening a file the
+only way to guarantee that the setting still applies is to
+reissue the command. If this argument is provided without the
+B<-kbytes> argument, the command reports the current setting for
+the specified files, and the default store asynchrony.
+
+=item B<-allfiles> I<new default (KB)>
+
+Sets the default store asynchrony for the local machine, which
+is the number of kilobytes of data that can remain to be
+written to the file server when the Cache Manager returns
+control to the application program that closed a file. The
+value applies to all AFS files manipulated by applications
+running on the machine, except those for which settings have
+been made with the B<-kbytes> and B<-files> arguments. Provide an
+integer from the range B<0> (which indicates the default of
+synchronous writes) to the maximum AFS file size.
+
+=item B<-verbose>
+
+Produces output confirming the settings made with the
+accompanying B<-kbytes> and B<-files> arguments, the B<-allfiles>
+argument, or all three. If provided by itself, reports the
+current default store asynchrony.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If none of the command's options are included, or if only the B<-verbose>
+flag is included, the following message reports the default store
+asynchrony (the setting that applies to all files manipulated by
+applications running on the local machine and for which not more
+specific asynchrony is set).
+
+ Default store asynchrony is x kbytes.
+
+A value of C<0> (zero) indicates synchronous writes and is the default if
+no one has included the B<-allfiles> argument on this command since the
+machine last rebooted.
+
+If the B<-files> argument is provided without the B<-kbytes> argument, the
+output reports the value that applies to each specified file along
+with the default store asynchrony. If a particular value has
+previously been set for a file, the following message reports it:
+
+ Will store up to y kbytes of file asynchronously.
+ Default store asynchrony is x kbytes.
+
+If the default store asynchrony applies to a file because no explicit
+B<-kbytes> value has been set for it, the message is instead as follows:
+
+ Will store file according to default.
+ Default store asynchrony is x kbytes.
+
+If the B<-verbose> flag is combined with arguments that set values
+(B<-files> and B<-kbytes>, or B<-allfiles>, or all three), there is a message
+that confirms immediately that the setting has taken effect. When
+included without other arguments or flags, the B<-verbose> flag reports
+the default store asynchrony only.
+
+=head1 EXAMPLES
+
+The following command enables the Cache Manager to return control to
+the application program that closed the file B<test.data> when 100
+kilobytes still remain to be written to the File Server. The B<-verbose>
+flag produces output that confirms the new setting, and that the
+default store asynchrony is zero.
+
+ fs storebehind -kbytes 100 -files test.data -verbose
+ Will store up to 100 kbytes of test.data asynchronously.
+ Default store asynchrony is 0 kbytes.
+
+=head1 PRIVILEGE REQUIRED
+
+To include the B<-allfiles> argument, the issuer must be logged in as the
+local superuser B<root>.
+
+To include the B<-kbytes> and B<-files> arguments, the issuer must either be
+logged in as the local superuser B<root> or have the B<w> (B<write>) permission
+on the ACL of each file's directory.
+
+To view the current settings (by including no arguments, the B<-file>
+argument alone, or the B<-verbose> argument alone), no privilege is
+required.
+
+=head1 CAVEATS
+
+For the following reasons, use of this command is not recommended in
+most cases.
+
+In normal circumstances, an asynchronous setting results in the Cache
+Manager returning control to applications earlier than it otherwise
+does, but this is not guaranteed.
+
+If a delayed write fails, there is no way to notify the application,
+since the B<close> system call has already returned with a code
+indicating success.
+
+Writing asynchronously increases the possibility that the user will
+not notice if a write operation makes the volume that houses the file
+exceed its quota. As always, the portion of the file that exceeds the
+volume's quota is lost, which prompts a message such as the following:
+
+C<No space left on device>
+
+To avoid losing data, it is advisable to verify that the volume
+housing the file has space available for the amount of data
+anticipated to be written.
+
+=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<afsd(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs sysname - Reports or sets the CPU/operating system type
+
+=head1 SYNOPSIS
+
+fs sysname [B<-newsys> I<new sysname>] [B<-help>]
+
+fs sy [B<-n> I<new sysname>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs sysname> command sets or displays the local machine's
+CPU/operating system type as recorded in kernel memory. The Cache
+Manager substitutes the string for the I<@sys> variable which can occur
+in AFS pathnames; the IBM AFS Quick Beginnings and IBM AFS
+Administration Guide explain how using I<@sys> can simplify cell
+configuration. It is best to use it sparingly, however, because it can
+make the effect of changing directories unpredictable.
+
+The command always applies to the local machine only. If issued on an
+NFS client machine accessing AFS via the NFS/AFS Translator, the
+string is set or reported for the NFS client machine. The Cache
+Manager on the AFS client machine serving as the NFS client's NFS/AFS
+translator machine stores the value in its kernel memory, and so can
+provide the NFS client with the proper version of program binaries
+when the user issues commands for which the pathname to the binaries
+includes I<@sys>. There is a separate record for each user logged into
+the NFS client, which implies that if a user adopts a new identity
+(UNIX UID) during a login session on the NFS client--perhaps by using
+the UNIX C<su> command--he or she must verify that the correct string is
+set for the new identity also.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-newsys> I<new sysname>
+
+Sets the CPU/operating system indicator string for the local
+machine. If this argument is omitted, the output displays the
+current setting instead. AFS uses a standardized set of
+strings; consult the IBM AFS Quick Beginnings or AFS Release
+Notes.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+When the B<-newsys> argument is omitted, the output reports the machine's
+system type in the following format:
+
+Current sysname is 'I<system_type>'
+
+=head1 EXAMPLES
+
+The following example shows the output produced on a Sun SPARCStation
+running Solaris 5.7:
+
+ fs sysname
+ Current sysname is 'sun4x_57'
+
+The following command defines a machine to be a IBM RS/6000 running
+AIX 4.2:
+
+ fs sysname -newsys rs_aix42
+
+=head1 PRIVILEGE REQUIRED
+
+To display the current setting, no privilege is required. To include
+the B<-newsys> argument on an AFS client machine, the issuer must be
+logged in 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<fs_exportafs(1)>,
+L<sys(1)>,
+IBM AFS Quick Beginnings,
+IBM AFS Administration Guide
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs whereis - Reports the name of each file server machine housing a file or
+directory
+
+=head1 SYNOPSIS
+
+fs whereis [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs whe [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs whereis> command returns the name of each file server machine
+that houses the volume containing each directory or file named by the
+B<-path> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each AFS file or directory for which to return the host
+file server machine. Partial pathnames are interpreted relative
+to the current working directory, which is also the default
+value if this argument is omitted.
+
+=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 specified directory or file. It
+names the file server machine on which the volume that houses the
+specified directory or file resides. A list of multiple machines
+indicates that the directory or file is in a replicated volume.
+
+Machine names usually have a suffix indicating their cell membership.
+If the cell is not clear, use the C<fs whichcell> command to display the
+cell in which the directory or file resides. To display the cell
+membership of the local machine, use the C<fs wscell> command.
+
+=head1 EXAMPLES
+
+The following example indicates that volume housing the directory
+B</afs/abc.com> resides is replicated on both B<fs1.abc.com> and
+B<fs3.abc.com>:
+
+ fs whereis -path /afs/abc.com
+ File /afs/abc.com is on hosts fs1.abc.com fs3.abc.com
+
+=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<fs_whichcell(1)>,
+L<fs_wscell(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs whichcell - Returns the name of the cell to which a file or directory belongs
+
+=head1 SYNOPSIS
+
+fs whichcell [B<-path> I<dir/file path> [I<dir/file path> ...]] [B<-help>]
+
+fs whi [B<-p> I<dir/file path> [I<dir/file path> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs whichcell> command returns the name of the cell in which the
+volume that houses each indicated directory or file resides.
+
+To display the file server machine on which the volume housing a
+directory or file resides, use the C<fs whichcell> command. To display
+the cell membership of the local machine, use the C<fs wscell> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<dir/file path> [I<dir/file path> ...]
+
+Names each AFS file or directory for which to return the cell
+membership. Partial pathnames are interpreted relative to the
+current working directory, which is also the default value if
+this argument is omitted.
+
+=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 directory or file, naming the cell
+to which the volume that houses the directory or file resides.
+
+=head1 EXAMPLES
+
+The following example shows that the current working directory resides
+in a volume in the ABC Corporation cell:
+
+ fs whichcell
+ File . lives in cell 'abc.com'
+
+=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<fs_wscell(1)>,
+L<fs_whereis(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fs wscell - Returns the name of the cell to which a machine belongs
+
+=head1 SYNOPSIS
+
+fs wscell [B<-help>]
+
+fs ws [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fs wscell> command returns the name of the local machine's home
+cell.
+
+=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 displays the contents of the local B</usr/vice/etc/ThisCell>
+file, in the format
+
+This workstation belongs to cell 'I<cellname>'
+
+=head1 EXAMPLES
+
+The following example results when the C<fs wscell> is issued on a
+machine in the State University cell:
+
+ fs wscell
+ This workstation belongs to cell 'stateu.edu'
+
+=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<fs_whereis(1)>,
+L<fs_whichcell(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace - Introduction to the C<fstrace> command suite
+
+=head1 DESCRIPTION
+
+The commands in the C<fstrace> command suite are the interface that
+system administrators employ to trace Cache Manager operations for
+debugging purposes. Examples of Cache Manager operations are fetching
+file data or the status information used to produce output for the
+UNIX B<ls> command.
+
+The C<fstrace> command interpreter defines an extensive set of Cache
+Manager operations as the B<cm> I<event set>. When the event set is
+activated, the Cache Manager writes a message to the B<cmfx> I<trace log> in
+kernel memory each time it performs one of the defined operations. The
+log expands only to a defined size (by default, 60 KB), after which it
+is overwritten in a circular fashion (new trace messages overwrite the
+oldest ones). If an operation of particular interest occurs, the
+administrator can afterward display the log on the standard output
+stream or write it to a file for later study. For more specific
+procedural instructions, see the IBM AFS Administration Guide.
+
+There are several categories of commands in the C<fstrace> command suite:
+
+=over
+
+=item *
+
+Commands to administer or display information about the trace log:
+C<fstrace clear>, C<fstrace lslog>, C<fstrace setlog>
+
+=item *
+
+Commands to set or display the status of the event set:
+C<fstrace lsset> and C<fstrace setset>
+
+=item *
+
+A command to display the contents of the trace log: C<fstrace dump>
+
+=item *
+
+Commands to obtain help: C<fstrace apropos> and C<fstrace help>
+
+=back
+
+=head1 OPTIONS
+
+All C<fstrace> commands accept the following optional flag. It is listed
+in the command descriptions and described in detail here:
+
+=over 4
+
+=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.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue most C<fstrace> commands, the issuer must be logged on as the
+local superuser B<root> on the machine that is generating the trace log.
+
+=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<fstrace_apropos(1)>,
+L<fstrace_clear(1)>,
+L<fstrace_dump(1)>,
+L<fstrace_help(1)>,
+L<fstrace_lslog(1)>,
+L<fstrace_lsset(1)>,
+L<fstrace_setlog(1)>,
+L<fstrace_setset(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+fstrace apropos B<-topic> I<help string> [B<-help>]
+
+fstrace ap B<-t> I<help string> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace apropos> command displays the first line of the online help
+entry for any C<fstrace> command that contains in its name or short
+description the string specified with the B<-topic> argument.
+
+To display a command's complete syntax, use the C<fstrace 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<fstrace> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all C<fstrace> commands that include the word
+B<set> in their names or short descriptions:
+
+ fstrace apropos set
+ clear: clear logs by logname or by event set
+ lsset: list available event sets
+ setlog: set the size of a log
+ setset: set state of event sets
+
+=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<fstrace(1)>,
+L<fstrace_help(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace clear - Clears the trace log
+
+=head1 SYNOPSIS
+
+fstrace clear [B<-set> I<set_name> [I<set_name> ...]] [B<-log> I<log_name> [I<log_name> ...]] [B<-help>]
+
+fstrace c [B<-s> I<set_name> [I<set_name> ...]] [B<-l> I<log_name> [I<log_name> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace clear> command erases the contents of the trace log from
+kernel memory, but leaves kernel memory allocated for the log.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-set> I<set_name> [I<set_name> ...]
+
+Names the event set for which to clear the associated trace
+log. The only acceptable value is B<cm> (for which the associated
+trace log is B<cmfx>). Provide either this argument or the B<-log>
+argument, or omit both to clear the B<cmfx> log by default.
+
+=item B<-log> I<log_name> [I<log_name> ...]
+
+Names the trace log to clear. The only acceptable value is
+B<cmfx>. Provide either this argument or the B<-set> argument, or
+omit both to clear the B<cmfx> log by default.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command clears the B<cmfx> trace log on the local machine:
+
+ fstrace clear
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<fstrace(1)>,
+L<fstrace_lslog(1)>,
+L<fstrace_lsset(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace dump - Dumps a trace log
+
+=head1 SYNOPSIS
+
+fstrace dump [B<-set> I<set_name> [I<set_name> ...]] [B<-follow> I<log_name>]
+[B<-file> I<output_filename>]
+[B<-sleep> I<seconds_between_reads>] [B<-help>]
+
+fstrace d [B<-se> I<set_name> [I<set_name> ...]] [B<-fo> I<log_name>] [B<-fi> I<output_filename>]
+[B<-sl> I<seconds_between_reads>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace dump> command displays the current contents of the B<cmfx>
+trace log on the standard output stream or writes it to the file named
+by the B<-file> argument.
+
+To write the log continuously to the standard output stream or to a
+file, use the B<-follow> argument. By default, the log's contents are
+written out every ten seconds and then automatically cleared. To
+change the interval between writes, use the B<-sleep> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-set> I<set_name> [I<set_name> ...]
+
+Names the event set for which to write out the associated trace
+log. The only acceptable value is B<cm> (for which the associated
+trace log is B<cmfx>). Provide either this argument or the B<-follow>
+argument, or omit both to write out the B<cmfx> log by default.
+
+=item B<-follow> I<log_name>
+
+Names the trace log to write out continuously at a specified
+interval (by default, every ten seconds; use the B<-sleep>
+argument to change the interval). The log is cleared after each
+write operation.
+
+The only acceptable value is B<cmfx>. Provide either this argument
+or the B<-set> argument, or omit both to write out the B<cmfx> log by
+default.
+
+=item B<-file> I<output_filename>
+
+Specifies the pathname of the file to which to write the trace
+log's contents. It can be in AFS or on the local disk. Partial
+pathnames are interpreted relative to the current working
+directory. If this argument is omitted, the trace log appears
+on the standard output stream.
+
+=item B<-sleep> I<seconds_between_reads>
+
+Sets the number of seconds between writes of the trace log's
+contents when it is dumped continuously. Provide the B<-follow>
+argument along with this one. If this argument is omitted, the
+default interval is ten seconds.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output begins with a header specifying the date and time at which
+the write operation began. If the B<-follow> argument is not included,
+the header also reports the number of logs being dumped; it is always
+1, since there is only the B<cmfx> trace log. The format of the header is
+as follows:
+
+ AFS Trace Dump -
+ Date: starting_timestamp
+ Found 1 logs.
+ Contents of log cmfx:
+
+Each subsequent message describes a Cache Manager operation in the
+following format:
+
+time I<timestamp>, pid I<pid>:I<event_message>
+
+where
+
+=over
+
+=item B<timestamp>
+
+Specifies the time at which the Cache Manager performed the
+operation, as the number of seconds since the dump began
+
+=item B<pid>
+
+Specifies the process ID of the process or thread associated
+with the message
+
+=item B<event_message>
+
+Is the message itself. They are generally meaningful only to
+someone familiar with the AFS source code.
+
+=back
+
+In addition, every 1024 seconds the C<fstrace> command interpreter writes
+a message that records the current clock time, in the following
+format:
+
+time I<timestamp>, pid I<pid>: Current time: I<unix_time>
+
+where
+
+=over
+
+=item B<timestamp>
+
+Is the number of seconds from the start of trace logging
+
+=item B<pid>
+
+Is the process ID number
+
+=item B<unix_time>
+
+Is the machine's clock time, represent in the standard UNIX
+time format as the number of seconds since midnight on January
+1, 1970.
+
+=back
+
+Use this message to determine the actual clock time associated with
+each log message. Determine the actual time as follows:
+
+=over
+
+=item 1.
+
+Locate the message of interest.
+
+=item 2.
+
+Search backward through the trace file for the closest current
+time message.
+
+=item 3.
+
+If the current time message's I<timestamp> is smaller than the log
+message's I<timestamp>, subtract former from the latter. If the
+current time message's I<timestamp> is larger than the log message's
+I<timestamp>, add 1024 to the latter and subtract the former from the
+result.
+
+=item 4.
+
+Add the resulting number to the current time message's I<unix_time>
+to determine the log message's actual time.
+
+=back
+
+If any of the data in the kernel trace buffer has been overwritten
+since tracing was activated, the following message appears at the
+appropriate place in the output:
+
+ Log wrapped; data missing.
+
+To reduce the likelihood of overwriting, use the C<fstrace setlog>
+command to increase the kernel buffer's size. To display the current
+defined buffer size, use the C<fstrace lslog> command with the B<-long>
+argument.
+
+The following message at the end of the log dump indicates that it is
+completed:
+
+ AFS Trace Dump - Completed
+
+=head1 EXAMPLES
+
+The following command dumps the log associated with the cm event set
+to the standard output stream.
+
+ fstrace dump -set cm
+ AFS Trace Dump -
+ Date: Tue Apr 7 10:54:57 1998
+ Found 1 logs.
+ time 32.965783, pid 0: Tue Apr 7 10:45:52 1998
+ time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
+ time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0)
+ time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0)
+ time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0)
+ .
+ .
+ .
+ time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \
+ fid (756 4fb7e:588d240.2ff978a8.6)
+ time 71.440569, pid 33658: Returning code 2 from 19
+ time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2)
+ time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0)
+ AFS Trace Dump - Completed
+
+The following command dumps the trace log associated with the B<cm> event
+set on the local machine to the file B<cmfx.dump.file.1>, using the
+default interval of 10 seconds between successive dumps:
+
+ fstrace dump -follow cmfx -file cmfx.dump.file.1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+This command produces output only if the B<cm> event set is active. To
+display or set the event set's state, use the C<fstrace lsset> or C<fstrace
+setset> command respectively.
+
+To make the output from this command maximally readable, the message
+catalog file called B<afszcm.cat> must reside in the local
+B</usr/vice/etc/C> directory. If necessary, copy the file to that
+directory from the AFS Binary Distribution before activating tracing.
+
+When the B<cm> event set is active, a defined amount of kernel memory (by
+default, 60 KB) is allocated for the B<cmfx> trace log. As described on
+the introductory L<fstrace(1)> reference page, when the buffer is full,
+messages are overwritten in a circular fashion (new messages overwrite
+the oldest ones). To allocate more kernel memory for the log, use the
+C<fstrace setlog> command; to display the log buffer's current size, use
+the C<fstrace lslog> command with the B<-long> argument.
+
+=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<afszcm.cat(1)>,
+L<fstrace(1)>,
+L<fstrace_lslog(1)>,
+L<fstrace_setlog(1)>,
+L<fstrace_lsset(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace help - Displays the syntax of specified C<fstrace> commands or lists functional
+descriptions of all C<fstrace> commands
+
+=head1 SYNOPSIS
+
+fstrace help [B<-topic> I<help string> [I<help string> ...]] [B<-help>]
+
+fstrace h [B<-t> I<help string> [I<help string> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace help> command displays the complete online help entry
+(short description and syntax statement) for each command 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<fstrace> command.
+
+To list every C<fstrace> command whose name or short description includes
+a specified keyword, use the C<fstrace 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<fstrace> part of the command name,
+providing only the operation code (for example, specify C<clear>,
+not C<fstrace clear>). If this argument is omitted, the output
+briefly describes every C<fstrace> 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<fstrace> command consists of 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 command displays the online help entry for the C<fstrace
+setset> command:
+
+ fstrace help -topic setset
+ fstrace setset: set state of event sets
+ Usage: fstrace setset [-set <set_name>+] [-active] [-inactive]
+ [-dormant] [-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<fstrace(1)>,
+L<fstrace_apropos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace lslog - Displays information about a log
+
+=head1 SYNOPSIS
+
+fstrace lslog [B<-set> I<set_name> [I<set_name> ...]] [B<-log> I<log_name>] [B<-long>] [B<-help>]
+
+fstrace lsl [B<-s> I<set_name> [I<set_name> ...]] [B<-log> I<log_name>] [B<-lon>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace lslog> command reports whether the B<cmfx> log is available
+for use. If the B<-long> argument is included, the output reports the
+log's defined size, and whether that amount of space is currently
+allocated in kernel memory or not.
+
+To change the B<cmfx> trace log's size, use the C<fstrace setlog> command.
+To display or set whether space is allocated for it in kernel memory,
+use the C<fstrace lsset> or C<fstrace setset> command to display or set the
+state of the corresponding B<cm> event set, respectively.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-set> I<set_name> [I<set_name> ...]
+
+Names the event set for which to display information about the
+corresponding trace log. The only acceptable value is B<cm> (for
+which the associated trace log is B<cmfx>). Provide either this
+argument or the B<-log> argument, or omit both to display
+information about the B<cmfx> log by default.
+
+=item B<-log> I<log_name>
+
+Names the trace log about which to report. The only acceptable
+value is B<cmfx>. Provide either this argument or the B<-set>
+argument, or omit both to report on the B<cmfx> log by default.
+
+=item B<-long>
+
+Reports the defined size of the log in kilobyte units and
+whether that amount of space is currently allocated in kernel
+memory.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+By default, the C<fstrace lslog> command displays only the name of the
+available log, B<cmfx>, in the following format:
+
+ Available logs:
+ cmfx
+
+When the B<-long> flag is included, the output also reports the defined
+size of the log in kilobytes, and whether or not that amount of space
+is currently allocated in kernel memory, in the following format:
+
+ Available logs:
+ cmfx : log_size kbytes (allocated | unallocated)
+
+The C<allocated> state indicates that the indicated number of kilobytes
+is reserved for the B<cmfx> trace log in kernel memory. The B<cm> event
+set's state is either active or inactive, as reported by the C<fstrace
+lsset> command, and set by the C<fstrace setset> command's B<-active> or
+B<-inactive> flags respectively.
+
+The C<unallocated> state indicates that no kernel memory is currently
+reserved for the B<cmfx> trace log. The B<cm> event set's state is dormant,
+as reported by the C<fstrace lsset> command and set by the C<fstrace setset>
+command's B<-dormant> flag. If the event set's state is later changed to
+active or inactive, the number of kilobytes indicated as I<log_size> are
+again allocated in kernel memory.
+
+=head1 EXAMPLES
+
+The following example uses the -long flag to display information about
+the B<cmfx> log:
+
+ fstrace lslog -log cmfx -long
+ Available logs:
+ cmfx : 60 kbytes (allocated)
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<fstrace(1)>,
+L<fstrace_lsset(1)>,
+L<fstrace_setlog(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace lsset - Reports the status of an event set
+
+=head1 SYNOPSIS
+
+fstrace lsset [B<-set> I<set_name> [I<set_name> ...]] [B<-help>]
+
+fstrace lss [B<-s> I<set_name> [I<set_name> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace lsset> command displays a list of the available event sets
+and reports their current status (active, inactive, or dormant).
+
+To change an event set's status, use the C<fstrace setset> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-set> I<set_name> [I<set_name> ...]
+
+Names the event set for which to display the status. The only
+acceptable value is B<cm>, which is also the default if this
+argument is omitted.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output lists the available event sets and the status of each, in
+the following format:
+
+ Available sets:
+ cm {active | inactive | dormant}
+
+where
+
+=over
+
+=item B<active>
+
+Indicates that tracing is enabled for the event set, and kernel
+memory allocated for the corresponding trace log.
+
+=item B<inactive>
+
+Indicates that tracing is temporarily disabled for the event
+set, but kernel memory still allocated for the corresponding
+trace log.
+
+=item B<dormant>
+
+Indicates that tracing is disabled for the event set, and no
+kernel memory allocated for the corresponding trace log.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the available event set and its status:
+
+ fstrace lsset
+ Available sets:
+ cm active
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<fstrace(1)>,
+L<fstrace_setset(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace setlog - Sets the size of a trace log
+
+=head1 SYNOPSIS
+
+fstrace setlog [B<-log> I<log_name> [I<log_name> ...]] B<-buffersize> I<1-kilobyte_units> [B<-help>]
+
+fstrace setl [B<-l> I<log_name> [I<log_name> ...]] B<-b> I<1-kilobyte_units> [B<-h>]
+
+fstrace sl [B<-l> I<log_name> [I<log_name> ...]] B<-b> I<1-kilobyte_units> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace setlog> command defines the number of kilobytes of kernel
+memory allocated for the B<cmfx> trace log. If kernel memory is currently
+allocated, the command clears the current log and creates a new log
+buffer of the specified size.
+
+To display the current defined size of the log buffer, issue the
+C<fstrace lslog> command with the B<-long> argument. To control whether the
+indicated amount of space is actually allocated, use the C<fstrace
+setset> command to set the status of the cm event set; to display the
+event set's status, use the C<fstrace lsset> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-log> I<log_name> [I<log_name> ...]
+
+Names trace log for which to set the size. The only acceptable
+value is B<cmfx>, which is also the default if this argument is
+omitted.
+
+=item B<-buffersize> I<1-kilobyte_units>
+
+Specifies the number of 1-kilobyte blocks of kernel memory to
+allocate for the trace log.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command allocated 80 KB of kernel memory for the B<cmfx>
+trace log:
+
+ fstrace setlog -log cmfx -buffersize 80
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<fstrace(1)>,
+L<fstrace_lslog(1)>,
+L<fstrace_lsset(1)>,
+L<fstrace_setset(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+fstrace setset - Sets the status of an event set
+
+=head1 SYNOPSIS
+
+fstrace setset [B<-set> I<set_name> [I<set_name> ...]] [B<-active>] [B<-inactive>] [B<-dormant>] [B<-help>]
+
+
+fs set [B<-s> I<set_name> [I<set_name> ...]] [B<-a>] [B<-i>] [B<-d>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<fstrace setset> command sets the status of the B<cm> kernel event set
+on the local machine, which determines whether trace messages are
+recorded in the log buffer in kernel memory.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-set> I<set_name> [I<set_name> ...]
+
+Names the event set for which to set the status. The only
+acceptable value is B<cm>, which is also the default if this argument
+is omitted.
+
+=item B<-active>
+
+Enables tracing for the event set and allocates kernel memory
+for the associated trace log buffer. Provide one of this flag,
+the B<-inactive> flag, or the B<-dormant> flag.
+
+=item B<-inactive>
+
+Temporarily disables tracing for the event set, but does not
+change the allocation of kernel memory for the associated trace
+log buffer. Provide one of this flag, the B<-active> flag, or the
+B<-dormant> flag.
+
+=item B<-dormant>
+
+Disables tracing for the event set and frees the kernel memory
+previously allocated for the associated trace log buffer.
+Provide one of this flag, the B<-active> flag, or the B<-inactive>
+flag.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example sets the B<cm> event set's status to B<inactive>:
+
+ fstrace setset -set cm -inactive
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in 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<fstrace(1)>,
+L<fstrace_lsset(1)>,
+L<fstrace_setlog(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kadb_check - Checks the integrity of the Authentication Database
+
+=head1 SYNOPSIS
+
+kadb_check B<-database> I<kadb_file> [B<-uheader>] [B<-kheader>] [B<-entries>]
+[B<-verbose>] [B<-rebuild> I<out_file>] [B<-help>]
+
+kadb_check B<-d> I<kadb_file> [B<-u>] [B<-k>] [B<-e>] [B<-v>] [B<-r> I<out_file>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kadb_check> command checks the integrity of the Protection
+Database, reporting any errors or corruption it finds. If there are
+problems, do not issue any C<kas> commands until the database is
+repaired.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-database> I<kadb_file>
+
+Names the Authentication Database (copy of the B<kaserver.DB0>
+file) to check. If the current working directory is not the
+location of the file, provide a pathname, either full or
+relative to the current working directory.
+
+=item B<-uheader>
+
+Displays information which Ubik maintains in the database's
+header.
+
+=item B<-kheader>
+
+Displays information which the Authentication Server maintains
+in the database's header.
+
+=item B<-entries>
+
+Outputs every entry in the database, providing information
+similar to that returned by the C<kas examine> command.
+
+=item B<-verbose>
+
+Reports additional information about the database, including
+the number of free (allocated but unused) entries in the
+database.
+
+=item B<-rebuild> I<out_file>
+
+Names the file in which to record a list of C<kas> commands which,
+if issued in the command shell, recreate the current state of
+the database being verified. Partial pathnames are interpreted
+relative to the current working directory.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If there are errors in the database, the output always reports them on
+the standard error stream. If any options other than B<-database> or
+B<-help> are provided, the output written to the standard output stream
+includes additional information as described for each option in the
+preceding L</"OPTIONS"> section of this reference page. The output is
+intended for debugging purposes and is meaningful to someone familiar
+with the internal structure of the Authentication Database.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+The results can be unpredictable if the Authentication Server makes
+changes to the Authentication Database while this command is running.
+Use the C<bos shutdown> command to shutdown the local B<kaserver> process
+before running this command, or before creating a second copy of the
+B<kaserver.DB0> file (with a different name) on which to run the 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,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+kaserver.DB0 and kaserver.DBSYS1,
+L<bos_shutdown(1)>,
+L<kas_examine(1)>,
+L<kaserver(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas - Introduction to the C<kas> command suite
+
+=head1 DESCRIPTION
+
+The commands in the C<kas> command suite are the administrative interface
+to the Authentication Server, which runs on each database server
+machine in a cell, maintains the Authentication Database, and provides
+the authentication tickets that client applications must present to
+AFS servers in order to obtain access to AFS data and other services.
+
+There are several categories of commands in the C<kas> command suite:
+
+=over
+
+=item *
+
+Commands to create, modify, examine and delete entries in the
+Authentication Database, including passwords: C<kas create>, C<kas
+delete>, C<kas examine>, C<kas list>, C<kas setfields>, C<kas setkey>, C<kas
+setpassword>, and C<kas unlock>
+
+=item *
+
+Commands to create, delete, and examine tokens and server tickets:
+C<kas forgetticket>, C<kas listtickets>, C<kas noauthentication>, and C<kas
+stringtokey>
+
+=item *
+
+A command to enter interactive mode: C<kas interactive>
+
+=item *
+
+A command to trace Authentication Server operations: C<kas
+statistics>
+
+=item *
+
+Commands to obtain help: C<kas apropos> and C<kas help>
+
+=back
+
+Because of the sensitivity of information in the Authentication
+Database, the Authentication Server authenticates issuers of C<kas>
+commands directly, rather than accepting the standard token generated
+by the Ticket Granting Service. Any C<kas> command that requires
+administrative privilege prompts the issuer for a password. The
+resulting ticket is valid for six hours unless the maximum ticket
+lifetime for the issuer or the Authentication Server's Ticket Granting
+Service is shorter.
+
+To avoid having to provide a password repeatedly when issuing a
+sequence of C<kas> commands, enter I<interactive mode> by issuing the C<kas
+interactive> command, typing C<kas> without any operation code, or typing
+C<kas> followed by a user and cell name, separated by an at-sign (@; an
+example is C<kas smith.admin@abc.com>). After prompting once for a
+password, the Authentication Server accepts the resulting token for
+every command issued during the interactive session. See the reference
+page for the C<kas interactive> command for a discussion of when to use
+each method for entering interactive mode and of the effects of
+entering a session.
+
+The Authentication Server maintains two databases on the local disk of
+the machine where it runs:
+
+=over
+
+=item *
+
+The Authentication Database (B</usr/afs/db/kaserver.DB0>) stores the
+information used to provide AFS authentication services to users
+and servers, including the password scrambled as an encryption
+key. The reference page for the C<kas examine> command describes the
+information in a database entry.
+
+=item *
+
+An auxiliary file (B</usr/afs/local/kaauxdb> by default) that tracks
+how often the user has provided an incorrect password to the local
+Authentication Server. The reference page for the C<kas setfields>
+command describes how the Authentication Server uses this file to
+enforce the limit on consecutive authentication failures. To
+designate an alternate directory for the file, use the C<kaserver>
+command's B<-localfiles> argument.
+
+=back
+
+=head1 OPTIONS
+
+The following arguments and flags are available on many commands in
+the C<kas> suite. (Some of them are unavailable on commands entered in
+interactive mode, because the information they specify is established
+when entering interactive mode and cannot be changed except by leaving
+interactive mode.) The reference page for each command also lists
+them, but they are described here in greater detail.
+
+=over 4
+
+=item B<-admin_username>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. If this
+argument is omitted, the C<kas> command interpreter requests
+authentication for the identity under which the issuer is
+logged onto the local machine. Do not combine this argument
+with the B<-noauth> flag.
+
+=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
+
+The B<-cell> argument is not available on commands issued in
+interactive mode. The cell defined when the C<kas> 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<-noauth>
+
+Establishes an unauthenticated connection to the Authentication
+Server, in which the Authentication Server treats the issuer as
+the unprivileged user B<anonymous>. It is useful only when
+authorization checking is disabled on the server machine
+(during the installation of a server machine or when the C<bos
+setauth> command has been used during other unusual
+circumstances). In normal circumstances, the Authentication
+Server allows only privileged users to issue most C<kas> commands,
+and refuses to perform such an action even if the B<-noauth> flag
+is provided. Do not combine this flag with the B<-admin_username>
+and B<-password_for_admin> arguments.
+
+=item B<-password_for_admin>
+
+Specifies the password of the command's issuer. It is best to
+omit this argument, which echoes the password visibly in the
+command shell, instead enter the password at the prompt. Do not
+combine this argument with the B<-noauth> flag.
+
+=item B<-servers>
+
+Establishes a connection with the Authentication Server running
+on each specified database server machine, instead of on each
+machine listed in the local B</usr/vice/etc/CellServDB> file. In
+either case, the C<kas> command interpreter then chooses one of
+the machines at random to contact for execution of each
+subsequent command. The issuer can abbreviate the machine name
+to the shortest form that allows the local name service to
+identify it uniquely.
+
+=back
+
+=head1 PRIVILEGE REQUIRED
+
+To issue most C<kas> commands, the issuer must have the C<ADMIN> flag set in
+his or her Authentication Database entry (use the C<kas setfields>
+command to turn the flag on).
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<CellServDB_client_version(1)>,
+L<kaserver.DB0(1)> and L<kaserver.DBSYS1(1)>,
+L<kaserverauxdb(1)>,
+L<kas_apropos(1)>,
+L<kas_create(1)>,
+L<kas_delete(1)>,
+L<kas_examine(1)>,
+L<kas_forgetticket(1)>,
+L<kas_help(1)>,
+L<kas_interactive(1)>,
+L<kas_list(1)>,
+L<kas_listtickets(1)>,
+L<kas_noauthentication(1)>,
+L<kas_quit(1)>,
+L<kas_setfields(1)>,
+L<kas_setpassword(1)>,
+L<kas_statistics(1)>,
+L<kas_stringtokey(1)>,
+L<kas_unlock(1)>,
+L<kaserver(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+kas apropos B<-topic> I<help string> [B<-help>]
+
+kas a B<-t> I<help string> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas apropos> command displays the first line of the online help
+entry for any C<kas> command that has the string specified by the B<-topic>
+argument in its name or short description.
+
+To display the syntax for a command, use the C<kas 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<kas> command where the string specified with the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all C<kas> commands that include the word B<key>
+in their names or short descriptions:
+
+ kas apropos key
+ setkey: set a user's key
+ stringtokey: convert a string to a key
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<kas(1)>,
+L<kas_help(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas create - Creates an entry in the Authentication Database
+
+=head1 SYNOPSIS
+
+kas create S<B<-name> I<name of user>>
+S<[B<-initial_password> I<initial password>]>
+S<[B<-admin_username> I<admin principal to use for authentication>]>
+S<[B<-password_for_admin> I<admin password>]>
+S<[B<-cell> I<cell name>]>
+S<[B<-servers> I<explicit list of authentication servers> ...]>
+[B<-noauth>] [B<-help>]
+
+kas c B<-na> I<name of user> S<[B<-i> I<initial password>]>
+S<[B<-a> I<admin principal to use for authentication>]>
+S<[B<-p> I<admin password>]> S<[B<-c> I<cell name>]>
+S<[B<-s> I<explicit list of authentication servers> ...]> [B<-no>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas create> command creates an entry in the Authentication Database
+for the user named by the B<-name> argument.
+
+To avoid having the account's initial password echo visibly at the
+shell prompt, omit the B<-initial_password> argument; the command
+interpreter prompts for the password and does not echo it visibly.
+Whether or not B<-initial_password> is omitted, the Authentication Server
+converts the password into a form suitable for use as an encryption
+key, and records it in the entry's key field.
+
+To alter settings in an Authentication Database entry, use the C<kas
+setfields> command. To examine an entry, use the C<kas examine> command.
+To list every entry in the database, use the C<kas list> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<name of user>
+
+Names the new Authentication Database entry. Because it is the
+name under which the user logs in, it must obey the
+restrictions that many operating systems impose on user names
+(usually, to contain no more than eight lowercase letters).
+
+=item B<-initial_password> I<initial password>
+
+Sets the user's password; provide a character string that can
+include uppercase and lowercase letters, numerals and
+punctuation. The Authentication Server scrambles the string
+into an octal string suitable for use as an encryption key
+before placing it in the entry's key field. If this argument is
+omitted, the command interpreter prompts for the string and
+does not echo it visibly.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(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 prompts that appear when an
+administrator logged in as B<admin> creates an Authentication Database
+entry for the user B<smith>, and does not include either the
+B<-initial_password> or B<-password_for_admin arguments>.
+
+ kas create smith
+ Password for admin:
+ initial_password:
+ Verifying, please re-enter initial_password:
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=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<kas(1)>,
+L<kas_examine(1)>,
+L<kas_list(1)>,
+L<kas_setfields(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas delete - Deletes an entry from the Authentication Database
+
+=head1 SYNOPSIS
+
+kas delete B<-name> I<name of user>
+S<[B<-admin_username> I<admin principal to use for authentication>]>
+S<[B<-password_for_admin> I<admin password>]> S<[B<-cell> I<cell name>]>
+S<[B<-servers> I<explicit list of authentication servers> ...]>
+[B<-noauth>] [B<-help>]
+
+kas d B<-na> I<name of user> [B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+kas rm B<-na> I<name of user> [B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas delete> command removes from the Authentication Database the
+user entry named by the B<-name> argument. The indicated user becomes
+unable to log in, or the indicated server becomes unreachable (because
+the Authentication Server's Ticket Granting Service module no longer
+has a key with which to seal tickets for the server).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<name of user>
+
+Names the Authentication Database entry to delete.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(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 administrative user B<admin> entering
+interactive mode to delete three accounts.
+
+ kas
+ Password for admin:
+ ka> delete smith
+ ka> delete pat
+ ka> delete terry
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=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<kas(1)>,
+L<kas_create(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas examine - Displays information from an Authentication Database entry
+
+=head1 SYNOPSIS
+
+kas examine B<-name> I<name of user> [B<-showkey>]
+[B<-admin_username> I<admin principal to use for authentication>]
+[B<-password_for_admin> I<admin password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of authentication servers> ...]
+[B<-noauth>] [B<-help>]
+
+kas e B<-na> I<name of user> [B<-sh>]
+[B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-se> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas examine> command formats and displays information from the
+Authentication Database entry of the user named by the B<-name> argument.
+
+To alter the settings displayed with this command, issue the C<kas
+setfields> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<name of user>
+
+Names the Authentication Database entry from which to display
+information.
+
+=item B<-showkey>
+
+Displays the octal digits that constitute the key. The issuer
+must have the C<ADMIN> flag on his or her Authentication Database
+entry.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(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:
+
+=over
+
+=item *
+
+The entry name, following the string C<User data for>.
+
+=item *
+
+One or more status flags in parentheses; they appear only if an
+administrator has used the C<kas setfields> command to change them
+from their default values. A plus sign (+) separates the flags if
+there is more than one. The nondefault values that can appear, and
+their meanings, are as follows:
+
+=over
+
+=item B<ADMIN>
+
+Enables the user to issue privileged C<kas> commands
+(default is C<NOADMIN>)
+
+=item B<NOTGS>
+
+Prevents the user from obtaining tickets from the
+Authentication Server's Ticket Granting Service (default
+is C<TGS>)
+
+=item B<NOSEAL>
+
+Prevents the Ticket Granting Service from using the
+entry's key field as an encryption key (default is C<SEAL>)
+
+=item B<NOCPW>
+
+Prevents the user from changing his or her password
+(default is C<CPW>)
+
+=back
+
+=item *
+
+The key version number, in parentheses, following the word C<key>,
+then one of the following.
+
+=over
+
+=item *
+
+A checksum equivalent of the key, following the string C<cksum
+is>, if the B<-showkey> flag is not included. The checksum is a
+decimal number derived by encrypting a constant with the key.
+In the case of the B<afs> entry, this number must match the
+checksum with the corresponding key version number in the
+output of the C<bos listkeys> command; if not, follow the
+instructions in the IBM AFS Administration Guide for creating
+a new server encryption key.
+
+=item *
+
+The actual key, following a colon, if the B<-showkey> flag is
+included. The key consists of eight octal numbers, each
+represented as a backslash followed by three decimal digits.
+
+=back
+
+=item *
+
+The date the user last changed his or her own password, following
+the string C<last cpw> (which stands for "last change of password").
+
+=item *
+
+The string C<password will never expire> indicates that the
+associated password never expires; the string C<password will expire>
+is followed by the password's expiration date. After the indicated
+date, the user cannot authenticate, but has 30 days after it in
+which to use the C<kpasswd> or C<kas setpassword> command to set a new
+password. After 30 days, only an administrator (one whose account
+is marked with the C<ADMIN> flag) can change the password by using
+the C<kas setpassword> command. To set the password expiration date,
+use the C<kas setfields> command's B<-pwexpires> argument.
+
+=item *
+
+The number of times the user can fail to provide the correct
+password before the account locks, followed by the string
+C<consecutive unsuccessful authentications are permitted>, or the
+string C<An unlimited number of unsuccessful authentications is
+permitted> to indicate that there is no limit. To set the limit,
+use the C<kas setfields> command's B<-attempts> argument. To unlock a
+locked account, use the C<kas unlock> command. The L<kas_setfields(1)>
+reference page discusses how the implementation of the lockout
+feature interacts with this setting.
+
+=item *
+
+The number of minutes for which the Authentication Server refuses
+the user's login attempts after the limit on consecutive
+unsuccessful authentication attempts is exceeded, following the
+string C<The lock time for this user is>. Use the C<kas> command's
+B<-locktime> argument to set the lockout time. This line appears only
+if a limit on the number of unsuccessful authentication attempts
+has been set with the the C<kas setfields> command's B<-attempts>
+argument.
+
+=item *
+
+An indication of whether the Authentication Server is currently
+refusing the user's login attempts. The string C<User is not locked>
+indicates that authentication can succeed, whereas the string C<User
+is locked until> I<time> indicates that the user cannot authenticate
+until the indicated time. Use the C<kas unlock> command to enable a
+user to attempt authentication. This line appears only if a limit
+on the number of unsuccessful authentication attempts has been set
+with the C<kas setfields> command's B<-attempts> argument.
+
+=item *
+
+The date on which the Authentication Server entry expires, or the
+string C<entry never expires> to indicate that the entry does not
+expire. A user becomes unable to authenticate when his or her
+entry expires. Use the C<kas setfields> command's B<-expiration>
+argument to set the expiration date.
+
+=item *
+
+The maximum possible lifetime of the tokens that the
+Authentication Server grants the user. This value interacts with
+several others to determine the actual lifetime of the token, as
+described on the L<klog(1)> reference page. Use the C<kas setfields>
+command's B<-lifetime> argument to set this value.
+
+=item *
+
+The date on which the entry was last modified, following the
+string C<last mod on> and the user name of the administrator who
+modified it. The date on which a user changed his or her own
+password is recorded on the second line of output as C<last cpw>
+instead.
+
+=item *
+
+An indication of whether the user can reuse one of his or her last
+twenty passwords when issuing the C<kpasswd>, C<kas setpassword>, or C<kas
+setkey> commands. Use the C<kas setfields> command's B<-reuse> argument
+to set this restriction.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command shows the user B<smith> displaying her own
+Authentication Database entry. Note the C<ADMIN> flag, which shows that
+B<smith> is privileged.
+
+B< kas examine smith>
+ Password for smith:
+ User data for smith (ADMIN)
+ key (0) cksum is 3414844392, last cpw: Thu Mar 25 16:05:44 1999
+ password will expire: Fri Apr 30 20:44:36 1999
+ 5 consecutive unsuccessful authentications are permitted.
+ The lock time for this user is 25.5 minutes.
+ User is not locked.
+ entry never expires. Max ticket lifetime 100.00 hours.
+ last mod on Tue Jan 5 08:22:29 1999 by admin
+ permit password reuse
+
+In the following example, the user B<pat> examines his Authentication
+Database entry to determine when the account lockout currently in
+effect will end.
+
+B< kas examine pat>
+ Password for pat:
+ User data for pat
+ key (0) cksum is 73829292912, last cpw: Wed Apr 7 11:23:01 1999
+ password will expire: Fri Jun 11 11:23:01 1999
+ 5 consecutive unsuccessful authentications are permitted.
+ The lock time for this user is 25.5 minutes.
+ User is locked until Tue Sep 21 12:25:07 1999
+ entry expires on never. Max ticket lifetime 100.00 hours.
+ last mod on Thu Feb 4 08:22:29 1999 by admin
+ permit password reuse
+
+In the following example, an administrator logged in as B<admin> uses the
+B<-showkey> flag to display the octal digits that constitute the key in
+the B<afs> entry.
+
+B< kas examine -name afs -showkey>
+ Password for admin:
+ User data for afs
+ key (12): \357\253\304\352\234\236\253\352, last cpw: no date
+ entry never expires. Max ticket lifetime 100.00 hours.
+ last mod on Thu Mar 25 14:53:29 1999 by admin
+ permit password reuse
+
+=head1 PRIVILEGE REQUIRED
+
+A user can examine his or her own entry. To examine others' entries or
+to include the B<-showkey> flag, the issuer must have the C<ADMIN> flag set
+in his or her Authentication Database entry.
+
+=head1 CAVEATS
+
+Displaying actual keys on the standard output stream by including the
+B<-showkey> flag constitutes a security exposure. For most purposes, it
+is sufficient to display a checksum.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos_addkey(1)>,
+L<bos_listkeys(1)>,
+L<bos_setauth(1)>,
+L<kas(1)>,
+L<kas_setfields(1)>,
+L<kas_setpassword(1)>,
+L<kas_unlock(1)>,
+L<klog(1)>,
+L<kpasswd(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas forgetticket - Discards all tickets for the issuer
+
+=head1 SYNOPSIS
+
+kas forgetticket [B<-all>] [B<-help>]
+
+kas f [B<-a>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas forgetticket> command discards all of the issuer's tickets
+stored in the local machine's kernel memory. This includes the AFS
+server ticket from each cell in which the user has authenticated, and
+any tickets that the user have acquired during the current kas session
+(either when entering the session or by using the C<kas getticket>
+command).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-all>
+
+Discards all tickets. This argument explicitly invokes the
+command's default behavior.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command discards all of the issuer's tickets.
+
+B< kas forgetticket>
+
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<kas(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas help - Displays the syntax of each specified C<kas> command or lists functional
+descriptions of all C<kas> commands
+
+=head1 SYNOPSIS
+
+kas help [B<-topic> I<help string> [I<help string> ...]] [B<-help>]
+
+kas h [B<-t> I<help string> [I<help string> ...]] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas help> command displays the complete online help entry (short
+description and syntax statement) for each command 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<kas> command.
+
+To list every C<kas> command whose name or short description includes a
+specified keyword, use the C<kas 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 kas part of the command name, providing
+only the operation code (for example, specify B<setpassword>, not
+B<kas setpassword>). If this argument is omitted, the output
+briefly describes every C<kas> 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<kas> 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 command displays the online help entry for the C<kas
+setpassword> command:
+
+B< kas help setpassword>
+ kas setpassword: set a user's password
+ aliases: sp
+ Usage: kas setpassword -name <name of user>
+ [-new_password <new password>] [-kvno <key version number>]
+ [-admin_username <admin principal to use for authentication>]
+ [-password_for_admin <password>] [-cell <cell name>]
+ [-servers <explicit list of authentication servers>+] [-help]
+
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<kas(1)>,
+L<kas_apropos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas interactive - Enters interactive mode
+
+=head1 SYNOPSIS
+
+kas interactive [B<-admin_username> I<admin principal to use for authentication>]
+[B<-password_for_admin> I<admin password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of authentication servers> ...]
+[B<-noauth>] [B<-help>]
+
+kas i [B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas interactive> command establishes an interactive session for the
+issuer of the command. By default, the command interpreter establishes
+an authenticated connection for the user logged into the local file
+system with all of the Authentication Servers listed in the local
+B</usr/vice/etc/CellServDB> file for the cell named in the local
+B</usr/vice/etc/ThisCell> file. To specify an alternate identity, cell
+name, or list of Authentication Servers, include the B<-admin_username>,
+B<-cell>, or B<-servers> arguments respectively. Interactive mode lasts for
+six hours unless the maximum ticket lifetime for the issuer or the
+Authentication Server's Ticket Granting Service is shorter.
+
+There are two other ways to enter interactive mode, in addition to the
+C<kas interactive> command:
+
+=over
+
+=item 1.
+
+Type the C<kas> command at the shell prompt without any operation
+code. If appropriate, include one or more of the B<-admin_username>,
+B<-password_for_admin>, B<-cell>, and B<-servers> arguments.
+
+=item 2.
+
+Type the C<kas> command followed by a user name and cell name,
+separated by an @ sign (for example: C<kas admin@abc.com>), to
+establish a connection under the specified identity with the
+Authentication Servers listed in the local
+B</usr/vice/etc/CellServDB> file for the indicated cell. If
+appropriate, provide the B<-servers> argument to specify an alternate
+list of Authentication Server machines that belong to the
+indicated cell.
+
+=back
+
+There are several consequences of entering interactive mode:
+
+=over
+
+=item *
+
+The ka> prompt replaces the system (shell) prompt. When typing
+commands at this prompt, provide only the operation code (omit the
+command suite name, C<kas>).
+
+=item *
+
+The command interpreter does not prompt for the issuer's password.
+
+The issuer's identity and password, the relevant cell, and the set
+of Authentication Server machines specified when entering
+interactive mode apply to all commands issued during the session.
+They cannot be changed without leaving the session, except by
+using the C<(kas) noauthentication> command to replace the current
+authenticated connections with unauthenticated ones. The
+B<-admin_username>, B<-password_for_admin>, B<-cell>, and B<-servers>
+arguments are ignored if provided on a command issued during
+interactive mode.
+
+=back
+
+To establish an unauthenticated connection to the Authentication
+Server, include the B<-noauth> flag or provide an incorrect password.
+Unless authorization checking is disabled on each Authentication
+Server machine involved, however, it is not possible to perform any
+privileged operations within such a session.
+
+To end the current authenticated connection and establish an
+unauthenticated one, issue the C<(kas) noauthentication> command. To
+leave interactive mode and return to the regular shell prompt, issue
+the C<(kas) quit> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(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 a user entering interactive mode as the
+privileged user B<admin>.
+
+B< kas interactive admin>
+ Password for admin: admin_password
+ ka>
+
+=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<kas(1)>,
+L<kas_noauthentication(1)>,
+L<kas_quit(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas list - Displays all entries in the Authentication Database
+
+=head1 SYNOPSIS
+
+kas list [B<-long>] [B<-showadmin>] [B<-showkey>]
+[B<-admin_username> I<admin principal to use for authentication>]
+[B<-password_for_admin> I<admin password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of authentication servers> ...]
+[B<-noauth>] [B<-help>]
+
+kas ls [B<-l>] [B<-showa>] [B<-showk>]
+[B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-se> I<explicit list of authentication servers> ...] [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas list> command either displays all entries from the
+Authentication Database by name, or displays the full database entry
+for a defined set of entries, as determined by the flag provided:
+
+=over
+
+=item *
+
+To display every entry in the Authentication Database in full,
+include the B<-long> flag.
+
+=item *
+
+To display only those entries in full that have the C<ADMIN> flag
+set, include the B<-showadmin> flag.
+
+=item *
+
+To list only the name of each Authentication Database entry, omit
+both the B<-long> and B<-showadmin> flags.
+
+=back
+
+By default, full entries include a checksum for the encryption key,
+rather than the actual octal digits that constitute the key. To
+display the octal digits, include the B<-showkey> flag with the B<-long> or
+B<-showadmin> flag.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-long>
+
+Displays every Authentication Database entry in full. Provide
+this flag or the B<-showadmin> flag, or omit both to display just
+the name of every database entry.
+
+=item B<-showadmin>
+
+Displays in full only the Authentication Database entries that
+have the ADMIN flag set. Provide this flag or the B<-long> flag,
+or omit both to display just the name of every database entry.
+
+=item B<-showkey>
+
+Displays the octal digits that constitute the key in each full
+entry. Provide either the B<-long> or B<-showadmin> flag along with
+this one.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+If neither the B<-long> or B<-showadmin> flag is provided, the output lists
+the name of each entry in the Authentication Database on its own line.
+
+If the B<-long> flag is included, the output includes every
+Authentication Database entry in full. If the B<-showadmin> flag is
+included, the output includes in full only the Authentication Database
+entries that have the C<ADMIN> flag set. If the B<-showkey> is provided
+along with either one, the output includes the octal digits that
+constitute the encryption key in each entry.
+
+A full Authentication Database entry includes the same information
+displayed by the C<kas examine> command; for details, see that command's
+reference page.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=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<kas(1)>,
+L<kas_examine(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas listtickets - Displays all of the issuer's tickets (tokens)
+
+=head1 SYNOPSIS
+
+kas listtickets [B<-name> I<name of server>] [B<-long>] [B<-help>]
+
+kas listt [B<-n> I<name of server>] [B<-l>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas listtickets> command displays the associated user ID (AFS UID),
+cell name, and expiration date of some or all of the issuer's tickets
+(tokens), depending on which options are provided:
+
+=over
+
+=item *
+
+To display all tokens, provide neither the B<-name> argument nor
+B<-long> flag. The output is similar to that of the C<tokens> command.
+
+=item *
+
+To display a single token, provide the B<-name> argument to specify
+name of the Authentication Database entry for the entity that
+accepts the token. All AFS server processes accept tokens sealed
+with the key from the B<afs> entry.
+
+=item *
+
+To display in addition the octal numbers that constitute the token
+and session key, provide the B<-long> flag.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<name of server>
+
+Names the Authentication Database entry of the entity (usually
+a server process) that accepts the token to display.
+
+=item B<-long>
+
+Displays the octal numbers that constitute the session key and
+ticket.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output reports the AFS UID of the user who owns the token, the
+service (usually, C<afs>) and cell for which it is valid, and its
+expiration date, using the following format. If the message does not
+specify a cell, the ticket is for the local cell.
+
+User's (AFS ID I<AFS UID>) tokens for I<service>[@I<cellname>] [Expires I<date>]
+
+If the B<-long> flag is provided, the output also includes the octal
+numbers making up the session key and token, along with the key
+version number and the number of bytes in the token (if the number of
+bytes is not 56, there is an error).
+
+If the marker C<[E<gt>E<gt> POSTDATED E<lt>]> appears instead of an expiration date,
+the ticket does not become valid until the indicated time. (Only
+internal calls can create a postdated ticket; there is no standard
+interface that allows users to do this.)
+
+=head1 EXAMPLES
+
+The following two examples are for a user with AFS UID 1020 in the
+B<abc.com> cell and AFS UID 35 in the B<test.abc.com> cell. He is working on
+a machine in the first cell and is authenticated in both cells.
+
+B< kas listtickets>
+ User's (AFS ID 1020) tokens for afs [Expires Wed Mar 31 9:30:54 1999]
+ User's (AFS ID 35@test.abc.com) tokens for afs@test.abc.com \
+ [Expires Wed Mar 31 13:54:26 1999]
+
+B< kas listtickets -name afs -long>
+ User's (AFS ID 1020) tokens for afs [Expires Wed Mar 31 9:30:54 1999]
+ SessionKey: \375\205\351\227\032\310\263\013
+ Ticket: (kvno = 0, len = 56): \033\005\221\156\203\278\312\058\016\133 (etc.)
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<kas(1)>,
+L<tokens(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas noauthentication - Discards an authenticated identity in interactive mode
+
+=head1 SYNOPSIS
+
+noauthentication [B<-help>]
+
+n [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas noauthentication> command closes the (presumably authenticated)
+connection that the issuer established with one or more Authentication
+Server processes when entering interactive mode. It opens a new
+unauthenticated connection to each server, assigning the issuer the
+unprivileged identity B<anonymous>. It does not actually discard the
+user's tokens from the Cache Manager's memory (as the C<unlog> or C<kas
+forgetticket> command does). Unless authorization checking is disabled
+on each Authentication Server machine, it becomes impossible to
+perform any privileged operations within the session established by
+this command.
+
+This command is operative only during interactive mode, so omit the
+C<kas> command suite name from the command line.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example command discards the authentication information
+with which the user entered interactive mode.
+
+ka> B<noauthentication>
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<kas(1)>,
+L<kas_forgetticket(1)>,
+L<kas_interactive(1)>,
+L<unlog(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas quit - Leaves interactive mode
+
+=head1 SYNOPSIS
+
+quit [B<-help>]
+
+q [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas quit> command ends interactive mode, severing the authenticated
+connection to one or more Authentication Server processes and
+returning the issuer to the normal shell prompt.
+
+This command is operative only during interactive mode, so omit the
+C<kas> command suite name from the command line.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example demonstrates how the normal command shell prompt
+returns when the issuer leaves interactive mode.
+
+ka> B<quit>
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<kas(1)>,
+L<kas_interactive(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas setfields - Sets optional characteristics in an Authentication Database entry
+
+=head1 SYNOPSIS
+
+kas setfields B<-name> I<name of user>
+S<[B<-flags> I<hex flag value or flag name expression>]>
+S<[B<-expiration> I<date of account expiration>]>
+S<[B<-lifetime> I<maximum ticket lifetime>]>
+S<[B<-pwexpires> I<number days password is valid ([0..254])>]>
+S<[B<-reuse> I<permit password reuse (yes/no)>]>
+S<[B<-attempts> I<maximum successive failed login tries ([0..254])>]>
+S<[B<-locktime> I<failure penalty [hh:mm or minutes]>]>
+S<[B<-admin_username> I<admin principal to use for authentication>]>
+S<[B<-password_for_admin> I<admin password>]>
+S<[B<-cell> I<cell name>]>
+S<[B<-servers> I<explicit list of authentication servers> ...]>
+[B<-noauth>]
+[B<-help>]
+
+kas setf B<-na> I<name of user>
+S<[B<-f> I<hex flag value or flag name expression>]>
+S<[B<-e> I<date of account expiration>]>
+S<[B<-li> I<maximum ticket lifetime>]>
+S<[B<-pw> I<number days password is valid ([0..254])>]>
+S<[B<-r> I<permit password reuse (yes/no)>]>
+S<[B<-at> I<maximum successive failed login tries ([0..254])>]>
+S<[B<-lo> I<failure penalty [hh:mm or minutes]>]>
+S<[B<-ad> I<admin principal to use for authentication>]>
+S<[B<-pa> I<admin password>]>
+S<[B<-c> I<cell name>]>
+S<[B<-s> I<explicit list of authentication servers> ...]>
+[B<-no>]
+[B<-h>]
+
+kas sf B<-na> I<name of user>
+S<[B<-f> I<hex flag value or flag name expression>]>
+S<[B<-e> I<date of account expiration>]>
+S<[B<-li> I<maximum ticket lifetime>]>
+S<[B<-pw> I<number days password is valid ([0..254])>]>
+S<[B<-r> I<permit password reuse (yes/no)>]>
+S<[B<-at> I<maximum successive failed login tries ([0..254])>]>
+S<[B<-lo> I<failure penalty [hh:mm or minutes]>]>
+S<[B<-ad> I<admin principal to use for authentication>]>
+S<[B<-pa> I<admin password>]>
+S<[B<-c> I<cell name>]>
+S<[B<-s> I<explicit list of authentication servers> ...]>
+[B<-no>]
+[B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas setfields> command changes the Authentication Database entry
+for the user named by the B<-name> argument in the manner specified by
+the various optional arguments, which can occur singly or in
+combination:
+
+=over
+
+=item *
+
+To set the flags that determine whether the user has
+administrative privileges to the Authentication Server, can obtain
+a ticket, can change his or her password, and so on, include the
+B<-flags> argument.
+
+=item *
+
+To set when the Authentication Database entry expires, include the
+B<-expiration> argument.
+
+=item *
+
+To set the maximum ticket lifetime associated with the entry,
+include the B<-lifetime> argument. The reference page for the C<klog>
+command explains how this value interacts with others to determine
+the actual lifetime of a token.
+
+=item *
+
+To set when the user's password expires, include the B<-pwexpires>
+argument.
+
+=item *
+
+To set whether the user can reuse any of the previous twenty
+passwords when creating a new one, include the B<-reuse> argument.
+
+=item *
+
+To set the maximum number of times the user can provide an
+incorrect password before the Authentication Server refuses to
+accept any more attempts (locks the issuer out), include the
+B<-attempts> argument. After the sixth failed authentication attempt,
+the Authentication Server logs a message in the UNIX system log
+file (the B<syslog> file or equivalent, for which the standard
+location varies depending on the operating system).
+
+=item *
+
+To set how long the Authentication Server refuses to process
+authentication attempts for a locked-out user, set the B<-locktime>
+argument.
+
+=back
+
+The C<kas examine> command displays the settings made with this command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<name of user>
+
+Names the Authentication Database account for which to change
+settings.
+
+=item B<-flags> I<hex flag value or flag name expression>
+
+Sets one or more of four toggling flags, adding them to any
+flags currently set. Either specify one or more of the
+following strings, or specify a hexidecimal number that
+combines the indicated values. To return all four flags to
+their defaults, provide a value of B<0> (zero). To set more than
+one flag at once using the strings, connect them with plus
+signs (example: B<NOTGS+ADMIN+CPW>). To remove all the current
+flag settings before setting new ones, precede the list with an
+equal sign (example: B<=NOTGS+ADMIN+CPW>).
+
+=over
+
+=item B<ADMIN>
+
+The user is allowed to issue privileged C<kas> commands
+(hexadecimal equivalent is B<0x004>, default is B<NOADMIN>).
+
+=item B<NOTGS>
+
+The Authentication Server's Ticket Granting Service (TGS)
+refuses to issue tickets to the user (hexadecimal
+equivalent is B<0x008>, default is B<TGS>).
+
+=item B<NOSEAL>
+
+The Ticket Granting Service cannot use the contents of
+this entry's key field as an encryption key (hexadecimal
+equivalent is B<0x020>, default is B<SEAL>).
+
+=item B<NOCPW>
+
+The user cannot change his or her own password or key
+(hexadecimal equivalent is B<0x040>, default is B<CPW>).
+
+=back
+
+=item B<-expiration> I<date of account expiration>
+
+Determines when the entry itself expires. When a user entry
+expires, the user becomes unable to log in; when a server entry
+such as B<afs> expires, all server processes that use the
+associated key become inaccessible. Provide one of the three
+acceptable values:
+
+=over
+
+=item B<never>
+
+The account never expires (the default).
+
+=item B<I<mm>/I<dd>/I<yyyy>>
+
+Sets the expiration date to 12:00 a.m. on the indicated
+date (month/day/year). Examples: B<01/23/1999>, B<10/07/2000>.
+
+=item B<"I<mm>/I<dd>/I<yyyy> I<hh>:I<MM>">
+
+Sets the expiration date to the indicated time
+(hours:minutes) on the indicated date (month/day/year).
+Specify the time in 24-hour format (for example, B<20:30> is
+8:30 p.m.) Date format is the same as for a date alone.
+Surround the entire instance with quotes because it
+contains a space. Examples: "B<01/23/1999 22:30>",
+"B<10/07/2000 3:45>".
+
+=back
+
+Acceptable values for the year range from B<1970> (1 January 1970
+is time 0 in the standard UNIX date representation) through
+B<2037> (2037 is the maximum because the UNIX representation
+cannot accommodate dates later than a value in February 2038).
+
+=item B<-lifetime> I<maximum ticket lifetime>
+
+Specifies the maximum lifetime that the Authentication Server's
+Ticket Granting Service (TGS) can assign to a ticket. If the
+account belongs to a user, this value is the maximum lifetime
+of a token issued to the user. If the account corresponds to a
+server such as B<afs>, this value is the maximum lifetime of a
+ticket that the TGS issues to clients for presentation to the
+server during mutual authentication.
+
+Specify an integer that represents a number of seconds (B<3600>
+equals one hour), or include a colon in the number to indicate
+a number of hours and minutes (B<10:00> equals 10 hours). If this
+argument is omitted, the default setting is 100:00 hours
+(360000 seconds).
+
+=item B<-pwexpires> I<number days password is valid ([0..254])>
+
+Sets the number of days after the user's password was last
+changed that it remains valid. Provide an integer from the
+range B<1> through B<254> to specify the number of days until
+expiration, or the value B<0> to indicate that the password never
+expires (the default).
+
+When the password expires, the user is unable to authenticate,
+but has 30 days after the expiration date in which to use the
+C<kpasswd> command to change the password (after that, only an
+administrator can change it by using the C<kas setpassword>
+command). Note that the clock starts at the time the password
+was last changed, not when the C<kas setfields> command is issued.
+To avoid retroactive expiration, have the user change the
+password just before issuing a command that includes this
+argument.
+
+=item B<-reuse> I<permit password reuse (yes/no)>
+
+Specifies whether or not the user can reuse any of his or her
+last 20 passwords. The acceptable values are B<yes> to allow reuse
+of old passwords (the default) and B<no> to prohibit reuse of a
+password that is similar to one of the previous 20 passwords.
+
+=item B<-attempts> I<maximum successive failed login tries ([0..254])>
+
+Sets the number of consecutive times the user can provide an
+incorrect password during authentication (using the C<klog>
+command or a login utility that grants AFS tokens). When the
+user exceeds the limit, the Authentication Server rejects
+further attempts (locks the user out) for the amount of time
+specified by the B<-locktime> argument. Provide an integer from
+the range B<1> through B<254> to specify the number of failures
+allowed, or B<0> to indicate that there is no limit on
+authentication attempts (the default value).
+
+=item B<-locktime> I<failure penalty [hh:mm or minutes]>
+
+Specifies how long the Authentication Server refuses
+authentication attempts from a user who has exceeded the
+failure limit set by the B<-attempts> argument.
+
+Specify a number of hours and minutes (I<hh>:I<mm>) or minutes only
+(I<mm>), from the range B<01> (one minute) through B<36:00> (36 hours).
+The C<kas> command interpreter automatically reduces any larger
+value to B<36:00> and also rounds up any non-zero value to the
+next higher multiple of 8.5 minutes. A value of B<0> (zero) sets
+an infinite lockout time; an administrator must issue the C<kas
+unlock> command to unlock the account.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+In the following example, an administrator using the B<admin> account
+grants administrative privilege to the user B<smith>, and sets the
+Authentication Database entry to expire at midnight on 31 December
+2000.
+
+B< kas setfields -name smith -flags ADMIN -expiration 12/31/2000>
+ Password for admin:
+
+In the following example, an administrator using the B<admin> account
+sets the user B<pat>'s password to expire in 60 days from when it last
+changed, and prohibits reuse of passwords.
+
+B< kas setfields -name pat -pwexpires 60 -reuse no>
+ Password for admin:
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=head1 CAVEATS
+
+The password lifetime set with the B<-pwexpires> argument begins at the
+time the user's password was last changed, rather than when this
+command is issued. It can therefore be retroactive. If, for example, a
+user changed her password 100 days ago and the password lifetime is
+set to 100 days or less, the password effectively expires immediately.
+To avoid retroactive expiration, instruct the user to change the
+password just before setting a password lifetime.
+
+Administrators whose authentication accounts have the C<ADMIN> flag enjoy
+complete access to the sensitive information in the Authentication
+Database. To prevent access by unauthorized users, use the B<-attempts>
+argument to impose a fairly strict limit on the number of times that a
+user obtaining administrative tokens can provide an incorrect
+password. Note, however, that there must be more than one account in
+the cell with the C<ADMIN> flag. The C<kas unlock> command requires the
+C<ADMIN> privilege, so it is important that the locked-out administrator
+(or a colleague) can access another C<ADMIN>-privileged account to unlock
+the current account.
+
+In certain circumstances, the mechanism used to enforce the number of
+failed authentication attempts can cause a lockout even though the
+number of failed attempts is less than the limit set by the B<-attempts>
+argument. Client-side authentication programs such as B<klog> and an
+AFS-modified login utility normally choose an Authentication Server at
+random for each authentication attempt, and in case of a failure are
+likely to choose a different Authentication Server for the next
+attempt. The Authentication Servers running on the various database
+server machines do not communicate with each other about how many
+times a user has failed to provide the correct password to them.
+Instead, each Authentication Server maintains its own separate copy of
+the auxiliary database file B<kaserverauxdb> (located in the
+B</usr/afs/local> directory by default), which records the number of
+consecutive authentication failures for each user account and the time
+of the most recent failure. This implementation means that on average
+each Authentication Server knows about only a fraction of the total
+number of failed attempts. The only way to avoid allowing more than
+the number of attempts set by the B<-attempts> argument is to have each
+Authentication Server allow only some fraction of the total. More
+specifically, if the limit on failed attempts is I<f>, and the number of
+Authentication Servers is I<S>, then each Authentication Server can only
+permit a number of attempts equal to I<f> divided by I<S> (the Ubik
+synchronization site for the Authentication Server tracks any
+remainder, I<f>I<mod>I<S>).
+
+Normally, this implementation does not reduce the number of allowed
+attempts to less than the configured limit (I<f>). If one Authentication
+Server refuses an attempt, the client contacts another instance of the
+server, continuing until either it successfully authenticates or has
+contacted all of the servers. However, if one or more of the
+Authentication Server processes is unavailable, the limit is
+effectively reduced by a percentage equal to the quantity I<U> divided by
+I<S>, where I<U> is the number of unavailable servers and I<S> is the number
+normally available.
+
+To avoid the undesirable consequences of setting a limit on failed
+authentication attempts, note the following recommendations:
+
+=over
+
+=item *
+
+Do not set the B<-attempts> argument (the limit on failed
+authentication attempts) too low. A limit of nine failed attempts
+is recommended for regular user accounts, to allow three failed
+attempts per Authentication Server in a cell with three database
+server machines.
+
+=item *
+
+Set fairly short lockout times when including the B<-locktime>
+argument. Although guessing passwords is a common method of
+attack, it is not a very sophisticated one. Setting a lockout time
+can help discourage attackers, but excessively long times are
+likely to be more of a burden to authorized users than to
+potential attackers. A lockout time of 25 minutes is recommended
+for regular user accounts.
+
+=item *
+
+Do not assign an infinite lockout time on an account (by setting
+the B<-locktime> argument to B<0> [zero]) unless there is a highly
+compelling reason. Such accounts almost inevitably become locked
+at some point, because each Authentication Server never resets the
+account's failure counter in its copy of the B<kaauxdb> file (in
+contrast, when the lockout time is not infinite, the counter
+resets after the specified amount of time has passed since the
+last failed attempt to that Authentication Server). Furthermore,
+the only way to unlock an account with an infinite lockout time is
+for an administrator to issue the C<kas unlock> command. It is
+especially dangerous to set an infinite lockout time on an
+administrative account; if all administrative accounts become
+locked, the only way to unlock them is to shut down all instances
+of the Authentication Server and remove the B<kaauxdb> file on each.
+
+=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<kaserverauxdb(1)>,
+L<kas(1)>,
+L<kas_examine(1)>,
+L<kas_setpassword(1)>,
+L<kas_unlock(1)>,
+L<klog(1)>,
+L<kpasswd(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas setpassword - Changes the key field in an Authentication Database entry
+
+=head1 SYNOPSIS
+
+kas setpassword B<-name> I<name of user> [B<-new_password> I<new password>]
+[B<-kvno> I<key version number>]
+[B<-admin_username> I<admin principal to use for authentication>]
+[B<-password_for_admin> I<admin password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of authentication servers> ...]
+[B<-noauth>] [B<-help>]
+
+kas setpasswd B<-na> I<name of user> [B<-ne> I<new password>]
+[B<-k> I<key version number>]
+[B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+kas setp B<-na> I<name of user> [B<-ne> I<new password>] [B<-k> I<key version number>]
+[B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+kas sp B<-na> I<name of user> [B<-ne> I<new password>] [B<-k> I<key version number>]
+[B<-a> I<admin principal to use for authentication >]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas setpassword> command accepts a character string of unlimited
+length, scrambles it into a form suitable for use as an encryption
+key, places it in the key field of the Authentication Database entry
+named by the B<-name> argument, and assigns it the key version number
+specified by the B<-kvno> argument.
+
+To avoid making the password string visible at the shell prompt, omit
+the B<-new_password> argument. Prompts then appear at the shell which do
+not echo the password visibly.
+
+When changing the B<afs> server key, also issue C<bos addkey> command to add
+the key (with the same key version number) to the B</usr/afs/etc/KeyFile>
+file. See the IBM AFS Administration Guide for instructions.
+
+The command interpreter checks the password string subject to the
+following conditions:
+
+=over
+
+=item *
+
+If there is a program called B<kpwvalid> in the same directory as the
+B<kas> binary, the command interpreter invokes it to process the
+password. For details, see the L<kpwvalid(1)> reference page.
+
+=item *
+
+If the B<-reuse> argument to the C<kas setfields> command has been used
+to prohibit reuse of previous passwords, the command interpreter
+verifies that the password is not too similar too any of the
+user's previous 20 passwords. It generates the following error
+message at the shell:
+
+ Password was not changed because it seems like a reused password
+
+To prevent a user from subverting this restriction by changing the
+password twenty times in quick succession (manually or by running
+a script), use the B<-minhours> argument on the C<kaserver>
+initialization command. The following error message appears if a
+user attempts to change a password before the minimum time has
+passed:
+
+ Password was not changed because you changed it too
+ recently; see your systems administrator
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<name of user>
+
+Names the entry in which to record the new key.
+
+=item B<-new_password> I<new password>
+
+Specifies the character string the user types when
+authenticating to AFS. Omit this argument and type the string
+at the resulting prompts so that the password does not echo
+visibly. Note that some non-AFS programs cannot handle
+passwords longer than eight characters.
+
+=item B<-kvno> I<key version number>
+
+Specifies the key version number associated with the new key.
+Provide an integer in the range from B<0> through B<255>. If omitted,
+the default is 0 (zero), which is probably not desirable for
+server keys.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+In the following example, an administrator using the B<admin> account
+changes the password for B<pat> (presumably because B<pat> forgot the former
+password or got locked out of his account in some other way).
+
+B< kas setpassword pat>
+ Password for admin:
+ new_password:
+ Verifying, please re-enter new_password:
+
+=head1 PRIVILEGE REQUIRED
+
+Individual users can change their own passwords. To change another
+user's password or the password (server encryption key) for server
+entries such as B<afs>, the issuer must have the C<ADMIN> flag set in his or
+her Authentication Database entry.
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+
+Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<bos_addkey(1)>,
+L<kas(1)>,
+L<kaserver(1)>,
+L<kpwvalid(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas statistics - Displays statistics from an Authentication Server process
+
+=head1 SYNOPSIS
+
+kas statistics [B<-admin_username> I<admin principal to use for authentication>]
+[B<-password_for_admin> I<admin password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of authentication servers> [I<explicit list of authentication servers> ...]]
+[B<-noauth>] [B<-help>]
+
+kas sta [B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> [I<explicit list of authentication servers> ...]] [B<-n>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas statistics> command displays statistics from the Authentication
+Server running on one of the cell's database server machines. Use the
+B<-servers> argument to name a specific machine, or the command
+interpreter chooses one at random from all the database server
+machines with which it has established connections.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> [I<explicit list of authentication servers> ...]
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The information in the output includes:
+
+=over
+
+=item *
+
+The number of allocation and freeing operations the Authentication
+Server has performed, and how many password change requests it has
+processed.
+
+=item *
+
+An indication of its hash table use.
+
+=item *
+
+The server machine's IP address in hexadecimal and the date when
+the current instance of the Authentication Server started.
+
+=item *
+
+The number of requests and aborted requests for various services:
+authentication, ticket granting, password setting, entry listing,
+and so on.
+
+=item *
+
+The amount of CPU time that the Authentication Server has used to
+process requests since it started. The amount is not accurate on
+all system types, however.
+
+=item *
+
+The number of entries in the Authentication Database that are
+marked with the C<ADMIN> flag.
+
+=back
+
+=head1 EXAMPLES
+
+In the following example, an administrator using the B<admin> account
+gathers statistics from the Authentication Server running on the
+machine B<fs1.abc.com>.
+
+B< kas statistics -servers fs1.abc.com>
+ 56 allocs, 46 frees, 0 password changes
+ Hash table utilization = 0.100000%
+ From host bfff21a7 started at Tue Mar 23 12:42:02 1999:
+ of 88 requests for Authenticate, 18 were aborted.
+ of 14 requests for GetTicket, 0 were aborted.
+ of 4 requests for CreateUser, 1 were aborted.
+ of 12 requests for SetFields, 4 were aborted.
+ of 3 requests for DeleteUser, 0 were aborted.
+ of 23 requests for GetEntry, 4 were aborted.
+ of 18 requests for ListEntry, 0 were aborted.
+ of 2 requests for GetStats, 1 were aborted.
+ of 2 requests for GetRandomKey, 0 were aborted.
+ Used 6.015 seconds of CPU time.
+ 3 admin accounts
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=head1 CAVEATS
+
+The B<-servers> argument is not available in interactive mode, making it
+impossible to specify a certain machine.
+
+=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<kas(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas stringtokey - Converts a character string into an octal key
+
+=head1 SYNOPSIS
+
+kas stringtokey B<-string> I<password string> [B<-cell> I<cell name>] [B<-help>]
+
+kas str B<-s> I<password string> [B<-c> I<cell name>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas stringtokey> command converts the character string specified
+with the B<-string> argument into an octal string suitable for use as an
+encryption key.
+
+The C<kas> command interpreter generates the octal key by using an
+encryption algorithm on the combination of the specified string and
+the name of the local cell (as recorded in the local
+B</usr/vice/etc/ThisCell> file). Use the B<-cell> argument to convert a
+string into a key appropriate for a cell other than the local one.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-string> I<password string>
+
+Specifies the character string to convert into an octal key.
+
+=item B<-cell> I<cell name>
+
+Specifies the complete Internet domain name of the cell to
+combine with the password string while generating the key. If
+this argument is omitted, the C<kas> command interpreter
+determines the name of the local cell by consulting:
+
+=over
+
+=item *
+
+First, the value of the environment variable AFSCELL.
+
+=item *
+
+Second, the cellname in the B</usr/vice/etc/ThisCell> file on
+the local machine.
+
+=back
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output is of the following form:
+
+Converting I<password string> in realm 'I<cell_name>' yields key='I<key>'.
+
+=head1 EXAMPLES
+
+The following example shows the octal key equivalent of the string
+B<new_pswd> in the ABC Corporation cell.
+
+B< kas stringtokey new_pswd>
+ Converting new_pswd in realm 'ABC.COM' yields
+ key='\346\307\364\320\263\233\342\354'.
+
+=head1 PRIVILEGE REQUIRED
+
+None, and no password is required.
+
+=head1 CAVEATS
+
+This command writes the key to the standard output stream, on which it
+can possibly be intercepted by third parties. It is not very secure to
+use the key in an actual Authentication Database entry.
+
+=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<ThisCell_client_version(1)>,
+L<kas(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kas unlock - Unlocks a locked user account
+
+=head1 SYNOPSIS
+
+kas unlock B<-name> I<authentication ID>
+[B<-admin_username> I<admin principal to use for authentication>]
+[B<-password_for_admin> I<admin password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of authentication servers> ...]
+[B<-noauth>] [B<-help>]
+
+kas u B<-na> I<authentication ID>
+[B<-a> I<admin principal to use for authentication>]
+[B<-p> I<admin password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of authentication servers> ...] [B<-no>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kas unlock> command unlocks the Authentication Database entry named
+by the B<-name> argument. An entry becomes locked when the user exceeds
+the limit on failed authentication attempts, generally by providing
+the wrong password to either an AFS-modified login utility or the C<klog>
+command. Use the C<kas setfields> command to set the limit and the
+lockout time, and the C<kas examine> command to examine the settings.
+
+To unlock all locked user accounts at once, shutdown the B<kaserver>
+process on every database server machine, and remove the
+B</usr/afs/local/kaauxdb> file from each one. The B<kaserver> process
+recreates the file as it restarts.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<authentication ID>
+
+Names the Authentication Database entry to unlock.
+
+=item B<-admin_username> I<admin principal to use for authentication>
+
+Specifies the user identity under which to authenticate with
+the Authentication Server for execution of the command. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-password_for_admin> I<admin password>
+
+Specifies the password of the command's issuer. If it is
+omitted (as recommended), the C<kas> command interpreter prompts
+for it and does not echo it visibly. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<kas(1)> reference page.
+
+=item B<-servers> I<explicit list of authentication servers> ...
+
+Names each machine running an Authentication Server with which
+to establish a connection. For more details, see the
+introductory L<kas(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<kas(1)> reference page.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+In the following example, an administrator using the B<admin> account
+unlocks the entry for B<jones>:
+
+B< kas unlock -name jones -admin_username admin>
+ Administrator's (admin) Password:
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must have the C<ADMIN> flag set on his or her Authentication
+Database entry.
+
+=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<kas(1)>,
+L<kas_examine(1)>,
+L<kas_setfields(1)>,
+L<klog(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kaserver - Initializes the Authentication Server
+
+=head1 SYNOPSIS
+
+kaserver [B<-noAuth>] [B<-fastKeys>] [B<-database> I<dbpath>]
+[B<-localfiles> I<lclpath>] [B<-minhours> I<n>]
+[B<-servers> I<serverlist>] [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<kaserver> command initializes the Authentication Server, which runs
+on every database server machine. In the conventional configuration,
+its binary file is located in the B</usr/afs/bin> directory on a file
+server machine.
+
+The C<kaserver> command is not normally issued at the command shell
+prompt but rather placed into a file server machine's
+B</usr/afs/local/BosConfig> file with the C<bos create> command. If it is
+ever issued at the command shell prompt, the issuer must be logged
+onto a database server machine as the local superuser B<root>.
+
+As it initializes, the Authentication Server process creates the two
+files that constitute the Authentication Database, B<kaserver.DB0> and
+B<kaserver.DBSYS1>, in the B</usr/afs/db> directory if they do not already
+exist. Use the commands in the C<kas> suite to administer the database.
+
+The Authentication Server is responsible for several aspects of AFS
+security, including:
+
+=over
+
+=item *
+
+Maintenance of all AFS server encryption keys and user passwords
+in the Authentication Database.
+
+=item *
+
+Creation of the tickets and tokens that users and servers use to
+establish secure connections. Its Ticket Granting Service (TGS)
+component performs this function.
+
+=back
+
+The Authentication Server records a trace of its activity in the
+B</usr/afs/logs/AuthLog> file. Use the C<bos getlog> command to display the
+contents of the file. Use the C<kdb> command to read the protected files
+associated with the B<AuthLog> file, B<AuthLog.dir> and B<AuthLog.pag>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-noAuth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer.
+Thus, it establishes an unauthenticated connection between the
+issuer and the Authentication Server. It is useful only when
+authorization checking is disabled on the database server
+machine. In normal circumstances, the Authentication Server
+allows only authorized (privileged) users to issue commands
+that affect or contact the Authentication Database and will
+refuse to perform such an action even if the B<-noAuth> flag is
+used.
+
+=item B<-fastKeys>
+
+Is a test flag for use by the AFS Development staff; it serves
+no functional purpose.
+
+=item B<-database> I<dbpath>
+
+Specifies the pathname of an alternate directory in which the
+Authentication Database files reside. Provide the complete
+pathname, ending in the base filename to which the B<.DB0> and
+B<.DBSYS1> extensions are appended. For example, the appropriate
+value for the default database files is B</usr/afs/db/kaserver>.
+
+Provide the B<-localfiles> argument along with this one;
+otherwise, the B<-localfiles> argument is also set to the value of
+this argument, which is probably inappropriate.
+
+=item B<-localfiles> I<lclpath>
+
+Specifies the pathname of an alternate directory in which the
+auxiliary Authentication Database file resides. Provide the
+complete pathname, ending in the base filename to which the
+B<auxdb> suffix is appended. For example, the appropriate value
+for the default auxiliary database file is
+B</usr/afs/local/C><kaserver>.
+
+=item B<-minhours> I<n>
+
+Specifies the minimum number of hours that must pass between
+password changes made by any regular user. System
+administrators (with the C<ADMIN> flag in their Authentication
+Database entry) can change passwords as often as desired.
+Setting a minimum time between password changes is not
+recommended.
+
+=item B<-servers> I<serverlist>
+
+Names each database server machine running an Authentication
+Server with which the local Authentication Server is to
+synchronize its copy of the Authentication Database , rather
+than with the machines listed in the local
+B</usr/afs/etc/CellServDB> file.
+
+=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 following C<bos create> command creates a B<kaserver> process on
+B<fs3.abc.com>:
+
+B< bos create S<-server fs3.abc.com> S<-instance kaserver>>
+B<S<-type simple> S<-cmd /usr/afs/bin/kaserver>>
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the superuser B<root> on a file server
+machine to issue the command at a command shell prompt. It is
+conventional instead to create and start the process by issuing the
+C<bos create> 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,
+and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<AuthLog(1)>,
+L<BosConfig(1)>,
+L<CellServDB_server_version(1)>,
+L<kaserver.DB0> and L<kaserver.DBSYS1>,
+L<kaserverauxdb(1)>,
+L<bos(1)>,
+L<bos_create(1)>,
+L<bos_getlog(1)>,
+L<kas(1)>,
+L<kdb(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kdb - Displays log or privileged actions performed by the Authentication
+Server
+
+=head1 SYNOPSIS
+
+kdb [B<-dbmfile> I<dbmfile to use (default /usr/afs/logs/AuthLog)>]
+[B<-key> I<extract entries that match specified key>] [B<-help>]
+
+=head1 DESCRIPTION
+
+The C<kdb> command displays the contents of the B<AuthLog.dir> and
+B<AuthLog.pag> files associated with the B<AuthLog> file that resides on the
+local disk, by default in the B</usr/afs/logs> directory. The files must
+exist in that directory, which normally implies that the
+Authentication Server is running on the machine. The files contain
+information on privileged actions performed by the Authentication
+Server.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-dbmfile> I<dbmfile to use (default /usr/afs/logs/AuthLog)>
+
+Specifies the pathname of the file to display. Provide either a
+complete pathname, a pathname relative to the B</usr/afs/logs>
+directory, or a filename only, in which case the file must
+reside in the B</usr/afs/logs> directory. Omit this argument to
+display information from the B<AuthLog.dir> and B<AuthLog.pag> files
+in the B</usr/afs/logs> directory.
+
+=item B<-key> I<extract entries that match specified key>
+
+Specifies each entry to be displayed from the indicated file.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The first line of output indicates the location of the files from
+which the subsequent information is derived:
+
+Printing all entries found in I<file_location>
+
+Each entry then includes the following two fields, separated by a
+colon:
+
+=over
+
+=item C<user/server>
+
+Identifies the user requesting the corresponding service and
+the server that performed that service. In cases where no user
+is directly involved, only the server appears; in cases where
+no server is directly involved, only the user appears.
+
+=item C<service>
+
+Identifies one of the following actions or services performed
+by the user or server process.
+
+=over
+
+=item *
+
+C<auth>: Obtained a ticket-granting ticket
+
+=item *
+
+C<chp>: Changed a user password
+
+=item *
+
+C<cruser>: Created a user entry in the Authentication Database
+
+=item *
+
+C<delu>: Deleted a user entry from the Authentication Database
+
+=item *
+
+C<gtck>: Obtained a ticket other than a ticket-granting ticket
+
+=item *
+
+C<setf>: Set fields in an Authentication Database entry
+
+=item *
+
+C<unlok>: Unlocked an Authentication Database entry
+
+=back
+
+=back
+
+The final line of output sums the number of entries.
+
+=head1 EXAMPLES
+
+The following example shows the output of the C<kdb> command in the ABC
+Corporation cell (B<abc.com>):
+
+B< kdb>
+ Printing all entries found in /usr/afs/logs/AuthLog
+ admin,krbtgt.ABC.COM:auth
+ admin,afs:gtck
+ admin:cruser
+ admin:delu
+ 4 entries were found
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser B<root>.
+
+=head1 CAVEATS
+
+It is possible that on some operating systems that AFS otherwise
+supports, the Authentication Server cannot create the
+B</usr/afs/logs/AuthLog.dir> and B</usr/afs/logs/AuthLog.pag> files, making
+this command inoperative. See the IBM AFS Release Notes for details.
+
+=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<AuthLog.dir(1)>, L<AuthLog.pag(1)>,
+L<bos_getlog(1)>,
+L<kaserver(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+klog - Authenticates with the Authentication Server
+
+=head1 SYNOPSIS
+
+klog [B<-x>] [B<-principal> I<user name>] [B<-password> I<user's password>]
+[B<-cell> I<cell name>] [B<-servers> I<explicit list of servers> ...]
+[B<-pipe>] [B<-silent>] [B<-lifetime> I<ticket lifetime in hh[:mm[:ss]]>]
+[B<-setpag>] [B<-tmp>] [B<-help>]
+
+klog [B<-x>] [B<-pr> I<user name>] [B<-pa> I<user's password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of servers> ...] [B<-pi>] [B<-si>]
+[B<-l> I<ticket lifetime in hh[:mm[:ss]]>] [B<-se>] [B<-t>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<klog> command obtains an AFS token from the Authentication Server.
+The Cache Manager on the local machine stores the token in a
+credential structure in kernel memory and uses it when obtaining
+authenticated access to the AFS filespace. This command does not
+affect the issuer's identity (UNIX UID) in the local file system.
+
+By default, the command interpreter obtains a token for the AFS user
+name that matches the issuer's identity in the local file system. To
+specify an alternate user, include the B<-principal> argument. The user
+named by the B<-principal> argument does not have to appear in the local
+password file (the B</etc/passwd> file or equivalent).
+
+By default, the command interpreter obtains a token for the local
+cell, as defined by the AFSCELL environment variable set in the
+command shell or by the B</usr/vice/etc/ThisCell> file on the local
+machine. To specify an alternate cell, include the B<-cell> argument. The
+command interpreter contacts an Authentication Server chosen at random
+from the cell's entry in the local B</usr/afs/etc/CellServDB> file,
+unless the B<-servers> argument is used to name one or more database
+server machines.
+
+A user can have tokens in multiple cells simultaneously, but only one
+token per cell per connection to the client machine. If the user's
+credential structure already contains a token for the requested cell,
+the token resulting from this command replaces it.
+
+Sites that employ standard Kerberos authentication instead of the AFS
+Authentication Server must use the Kerberos version of this command,
+B<klog.krb>, on all client machines. It automatically places the issuer's
+Kerberos tickets in the file named by the KRBTKFILE environment
+variable, which the B<pagsh.krb> command defines automatically as
+B</tmp/tktp>I<X> where I<X> is the number of the user's PAG.
+
+The lifetime of the token resulting from this command is the smallest
+of the following.
+
+=over
+
+=item *
+
+The lifetime specified by the issuer with the B<-lifetime> argument.
+If the issuer does not include this argument, the value defaults
+to 720 hours (30 days).
+
+=item *
+
+The maximum ticket lifetime recorded for the B<afs> entry in the
+Authentication Database. The default is 100 hours.
+
+=item *
+
+The maximum ticket lifetime recorded in the specified user's
+Authentication Database entry. The default is 25 hours for user
+entries created by an Authentication Server running AFS B<3.1> or
+later.
+
+=item *
+
+The maximum ticket lifetime recorded in the B<krbtgt.>I<CELLNAME> entry
+in the Authentication Database; this entry corresponds to the
+ticket-granting ticket used internally in generating the token.
+The default is 720 hours (30 days).
+
+=back
+
+The output from the C<kas examine> command displays an Authentication
+Database entry's maximum ticket lifetime as C<Max ticket lifetime>.
+Administrators can display any entry, and users can display their own
+entries.
+
+If none of the defaults have been changed, the token lifetime is 25
+hours for user accounts created by an Authentication Server running
+AFS B<3.1> or higher. The maximum lifetime for any token is 720 hours (30
+days), and the minimum is 5 minutes.
+
+Between the minimum and maximum values, the Authentication Server uses
+a defined set of values, according to the following rules. Requested
+lifetimes between 5 minutes and 10 hours 40 minutes are granted at 5
+minute intervals, rounding up. For example, if the issuer requests a
+lifetime of 12 minutes, the token's actual lifetime is 15 minutes.
+
+For token lifetimes greater than 10 hours 40 minutes, consult the
+following table, which presents all the possible times in units of
+I<hours>:I<minutes>:I<seconds>. The number in parentheses is an approximation
+of the corresponding time in days and hours (as indicated by the C<d> and
+C<h> letters). For example, C<282:22:17> means 282 hours, 22 minutes, and 17
+seconds, which translates to approximately 11 days and 18 hours (C<11d
+18h>). The Authentication Server rounds up a requested lifetime to the
+next highest possible lifetime.
+
+ 11:24:15 (0d 11h) 46:26:01 (1d 22h) 189:03:38 (7d 21h)
+ 12:11:34 (0d 12h) 49:38:40 (2d 01h) 202:08:00 (8d 10h)
+ 13:02:09 (0d 13h) 53:04:37 (2d 05h) 216:06:35 (9d 00h)
+ 13:56:14 (0d 13h) 56:44:49 (2d 08h) 231:03:09 (9d 15h)
+ 14:54:03 (0d 14h) 60:40:15 (2d 12h) 247:01:43 (10d 07h)
+ 15:55:52 (0d 15h) 64:51:57 (2d 16h) 264:06:34 (11d 00h)
+ 17:01:58 (0d 17h) 69:21:04 (2d 21h) 282:22:17 (11d 18h)
+ 18:12:38 (0d 18h) 74:08:46 (3d 02h) 301:53:45 (12d 13h)
+ 19:28:11 (0d 19h) 79:16:23 (3d 07h) 322:46:13 (13d 10h)
+ 20:48:57 (0d 20h) 84:45:16 (3d 12h) 345:05:18 (14d 09h)
+ 22:15:19 (0d 22h) 90:36:53 (3d 18h) 368:56:58 (15d 08h)
+ 23:47:38 (0d 23h) 96:52:49 (4d 00h) 394:27:37 (16d 10h)
+ 25:26:21 (1d 01h) 103:34:45 (4d 07h) 421:44:07 (17d 13h)
+ 27:11:54 (1d 03h) 110:44:28 (4d 14h) 450:53:46 (18d 18h)
+ 29:04:44 (1d 05h) 118:23:54 (4d 22h) 482:04:24 (20d 02h)
+ 31:05:22 (1d 07h) 126:35:05 (5d 06h) 515:24:22 (21d 11h)
+ 33:14:21 (1d 09h) 135:20:15 (5d 15h) 551:02:38 (22d 23h)
+ 35:32:15 (1d 11h) 144:41:44 (6d 00h) 589:08:45 (24d 13h)
+ 37:59:41 (1d 13h) 154:42:01 (6d 10h) 629:52:56 (26d 05h)
+ 40:37:19 (1d 16h) 165:23:50 (6d 21h) 673:26:07 (28d 01h)
+ 43:25:50 (1d 19h) 176:50:01 (7d 08h)
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-x>
+
+Appears only for backwards compatibility. Its former function
+is now the default behavior of this command.
+
+=item B<-principal> I<user name>
+
+Specifies the user name to authenticate. If this argument is
+omitted, the Authentication Server attempts to authenticate the
+user logged into the local file system.
+
+=item B<-password> I<user's password>
+
+Specifies the issuer's password (or that of the alternate user
+identified by the B<-principal> argument). Omit this argument to
+have the command interpreter prompt for the password, in which
+case it does not echo visibly in the command shell.
+
+=item B<-cell> I<cell name>
+
+Specifies the cell for which to obtain a token. The command is
+directed to that cell's Authentication Servers. During a single
+login session on a given machine, a user can be authenticated
+in multiple cells simultaneously, but can have only one token
+at a time for each of them (that is, can only authenticate
+under one identity per cell per session on a machine). It is
+acceptable to abbreviate the cell name to the shortest form
+that distinguishes it from the other cells listed in the
+B</usr/vice/etc/CellServDB> file on the client machine on which
+the command is issued.
+
+If this argument is omitted, the command is executed in the
+local cell, as defined
+
+=over
+
+=item *
+
+First, by the value of the environment variable AFSCELL
+
+=item *
+
+Second, in the B</usr/vice/etc/ThisCell> file on the client
+machine on which the command is issued
+
+=back
+
+=item B<-servers> I<explicit list of servers> ...
+
+Establishes a connection with the Authentication Server running
+on each specified database server machine. The command
+interpreter then chooses one of these at random to execute the
+command. It is best to provide fully-qualified hostnames, but
+abbreviated forms are possibly acceptable depending on the
+state of the cell's name server at the time the command is
+issued. This option is useful for testing specific servers if
+problems are encountered.
+
+If this argument is omitted, the command interpreter
+establishes a connection with each machine listed for the
+indicated cell in the local copy of the
+B</usr/vice/etc/CellServDB> file, and then chooses one of them at
+random for command execution.
+
+=item B<-pipe>
+
+Suppresses all output to the standard output stream, including
+prompts and error messages. The C<klog> command interpreter
+expects to receive the password from the standard input stream.
+Do not use this argument; it is designed for use by application
+programs rather than human users.
+
+=item B<-silent>
+
+Suppresses some of the trace messages that the C<klog> command
+produces on the standard output stream by default. It still
+reports on major problems encountered.
+
+=item B<-lifetime> I<ticket lifetime in hh[:mm[:ss]]>
+
+Requests a specific lifetime for the token. Provide a number of
+hours and optionally minutes and seconds in the format
+I<hh>[:I<mm>[:I<ss>]]. The value is used in calculating the token
+lifetime as described in the L</"DESCRIPTION"> section.
+
+=item B<-setpag>
+
+Creates a process authentication group (PAG) prior to
+requesting authentication. The token is associated with the
+newly created PAG.
+
+=item B<-tmp>
+
+Creates a Kerberos-style ticket file in the B</tmp> directory of
+the local machine. The file is called B<tkt.>I<AFS_UID> where I<AFS_UID>
+is the AFS UID of the issuer.
+
+=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 limit on consecutive
+authentication failures has been exceeded. An administrator can use
+the C<kas unlock> command to unlock the account, or the issuer can wait
+until the lockout time for the account has passed. (The time is set
+with the B<-locktime> argument to the C<kas setfields> command and displayed
+in the output from the C<kas examine> command).
+
+ Unable to authenticate to AFS because ID is locked - see your system admin
+
+If the B<-tmp> flag is included, the following message confirms that a
+Kerberos-style ticket file was created:
+
+ Wrote ticket file to /tmp
+
+=head1 EXAMPLES
+
+Most often, this command is issued without arguments. The appropriate
+password is for the person currently logged into the local file
+system. The ticket's lifetime is calculated as described in the
+L</"DESCRIPTION"> section (if no defaults have been changed, it is 25 hours
+for a user whose Authentication Database entry was created in AFS 3.1
+or later).
+
+B< klog>
+ Password:
+
+The following example authenticates the user as B<admin> in the ABC
+Corporation's test cell:
+
+B< klog -principal admin -cell test.abc.com>
+ Password:
+
+In the following, the issuer requests a ticket lifetime of 104 hours
+30 minutes (4 days 8 hours 30 minutes). Presuming that this lifetime
+is allowed by the maximum ticket lifetimes and other factors described
+in the L</"DESCRIPTION"> section, the token's lifetime is 110:44:28, which
+is the next largest possible value.
+
+B< klog -lifetime 104:30>
+ Password:
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 CAVEATS
+
+By default, this command does not create a new process authentication
+group (PAG); see the description of the C<pagsh> command to learn about
+PAGs. If a cell does not use an AFS-modified login utility, users must
+include B<-setpag> option to this command, or issue the C<pagsh> command
+before this one, to have their tokens stored in a credential structure
+that is identified by PAG rather than by local UID.
+
+When a credential structure is identified by local UID, the potential
+security exposure is that the local superuser B<root> can use the UNIX C<su>
+command to assume any other identity and automatically inherit the
+tokens associated with that UID. Identifying the credential structure
+by PAG eliminates this exposure.
+
+If the B<-password> argument is used, the specified password cannot begin
+with a hyphen, because it is interpreted as another option name. Use
+of the B<-password> argument is not recommended in any case.
+
+By default, it is possible to issue this command on a properly
+configured NFS client machine that is accessing AFS via the NFS/AFS
+Translator, assuming that the NFS client machine is a supported system
+type. However, if the translator machine's administrator has enabled
+UID checking by including the B<-uidcheck> B<on> argument to the C<fs
+exportafs> command, the command fails with an error message similar to
+the following:
+
+ Warning: Remote pioctl to translator_machine has failed (err=8). . .
+ Unable to authenticate to AFS because a pioctl failed.
+
+Enabling UID checking means that the credential structure in which
+tokens are stored on the translator machine must be identified by a
+UID that matches the local UID of the process that is placing the
+tokens in the credential structure. After the C<klog> command interpreter
+obtains the token on the NFS client, it passes it to the remote
+executor daemon on the translator machine, which makes the system call
+that stores the token in a credential structure on the translator
+machine. The remote executor generally runs as the local superuser
+B<root>, so in most cases its local UID (normally zero) does not match
+the local UID of the user who issued the C<klog> command on the NFS
+client machine.
+
+Issuing the C<klog> command on an NFS client machine creates a security
+exposure: the command interpreter passes the token across the network
+to the remote executor daemon in clear text 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<fs_exportafs(1)>,
+L<kas_examine(1)>,
+L<kas_setfields(1)>,
+L<kas_unlock(1)>,
+L<kaserver(1)>,
+L<pagsh(1)>,
+L<tokens(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+knfs - Establishes basis for authenticated access to AFS from a non-supported
+NFS client using the NFS/AFS Translator
+
+=head1 SYNOPSIS
+
+knfs B<-host> I<host name> [B<-id> I<user ID (decimal)>]
+[B<-sysname> I<host's '@sys' value>] [B<-unlog>] [B<-tokens>] [B<-help>]
+
+knfs B<-ho> I<host name> [B<-i> I<user ID (decimal)>]
+[B<-s> I<host's '@sys' value>] [B<-u>] [B<-t>] [B<-he>]
+
+=head1 DESCRIPTION
+
+The C<knfs> command creates an AFS credential structure on the local
+machine, identifying it by a process authentication group (PAG) number
+associated with the NFS client machine named by the B<-hostname> argument
+and by default with a local UID on the NFS client machine that matches
+the issuer's local UID on the local machine. It places in the
+credential structure the AFS tokens that the issuer has previously
+obtained (by logging onto the local machine if an AFS-modified login
+utility is installed, by issuing the C<klog> command, or both). To
+associate the credential structure with an NFS UID that does not match
+the issuer's local UID, use the B<-id> argument.
+
+Issue this command only on the NFS/AFS translator machine that is
+serving the NFS client machine, after obtaining AFS tokens on the
+translator machine for every cell to which authenticated access is
+required. The Cache Manager on the translator machine uses the tokens
+to obtain authenticated AFS access for the designated user working on
+the NFS client machine. This command is not effective if issued on an
+NFS client machine.
+
+To enable the user on the NFS client machine to issue AFS commands,
+use the B<-sysname> argument to specify the NFS client machine's system
+type, which can differ from the translator machine's. The NFS client
+machine must be a system type for which AFS is supported.
+
+The B<-unlog> flag discards the tokens in the credential structure, but
+does not destroy the credential structure itself. The Cache Manager on
+the translator machine retains the credential structure until the next
+reboot, and uses it each time the issuer accesses AFS through the
+translator machine. The credential structure only has tokens in it if
+the user reissues the C<knfs> command on the translator machine each time
+the user logs into the NFS client machine.
+
+To display the tokens associated with the designated user on the NFS
+client machine, include the B<-tokens> flag.
+
+Users working on NFS client machines of system types for which AFS
+binaries are available (and for which the cell has purchased a
+license) can use the C<klog> command rather than the C<knfs> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-host> I<host name>
+
+Names the NFS client machine on which the issuer is to work.
+Providing a fully-qualified hostname is best, but abbreviated
+forms are possibly acceptable depending on the state of the
+cell's name server at the time the command is issued.
+
+=item B<-id> I<user ID (decimal)>
+
+Specifies the local UID on the NFS client to which to assign
+the tokens. The NFS client identifies file requests by the NFS
+UID, so creating the association enables the Cache Manager on
+the translator machine to use the appropriate tokens when
+filling the requests. If this argument is omitted, the command
+interpreter uses an NFS UID that matches the issuer's local UID
+on the translator machine (as returned by the B<getuid> function).
+
+=item B<-sysname> I<host's '@sys' value>
+
+Specifies the value that the local (translator) machine's
+remote executor daemon substitutes for the B<@sys> variable in
+pathnames when executing AFS commands issued on the NFS client
+machine (which must be a supported system type). If the NFS
+user's PATH environment variable uses the B<@sys> variable in the
+pathnames for directories that house AFS binaries (as
+recommended), then setting this argument enables NFS users to
+issue AFS commands by leading the remote executor daemon to
+access the AFS binaries appropriate to the NFS client machine
+even if its system type differs from the translator machine's.
+
+=item B<-unlog>
+
+Discards the tokens stored in the credential structure
+identified by the PAG associated with the B<-host> argument and,
+optionally, the B<-id> argument.
+
+=item B<-tokens>
+
+Displays the AFS tokens assigned to the designated user on the
+indicated NFS client machine.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following error message indicates that UID checking is enabled on
+the translator machine and that the value provided for the B<-id>
+argument differs from the issuer's local UID.
+
+ knfs: Translator in 'passwd sync' mode; remote uid must be the same as local uid
+
+=head1 EXAMPLES
+
+The following example illustrates a typical use of this command. The
+issuer B<smith> is working on the machine B<nfscli1.abc.com> and has user ID
+B<1020> on that machine. The translator machine B<tx4.abc.com> uses an
+AFS-modified login utility, so B<smith> obtains tokens for the ABC
+Corporation cell automatically upon login via the C<telnet> program. She
+then issues the C<klog> command to obtain tokens as B<admin> in the ABC
+Corporation's test cell, B<test.abc.com>, and the C<knfs> command to
+associate both tokens with the credential structure identified by
+machine name B<nfs-cli1> and user ID B<1020>. She breaks the connection to
+B<tx4> and works on B<nfscli1>.
+
+B< telnet tx4.abc.com>
+ . . .
+ login: smith
+ Password:
+ AFS(R) login
+
+B< klog admin -cell test.abc.com>
+ Password:
+
+B< knfs nfscli1.abc.com 1020>
+
+B< exit>
+
+The following example shows user B<smith> again connecting to the machine
+B<tx4> via the C<telnet> program and discarding the tokens.
+
+B< telnet translator4.abc.com>
+ . . .
+ login: smith
+ Password:
+ AFS(R) login
+
+B< knfs nfscli1.abc.com 1020 -unlog>
+
+B< exit>
+
+=head1 PRIVILEGE REQUIRED
+
+None
+
+=head1 CAVEATS
+
+If the translator machine's administrator has enabled UID checking by
+issuing the C<fs exportafs> command with the B<-uidcheck on> argument, it is
+not possible to use the B<-id> argument to assign the tokens to an NFS
+UID that differs from the issuer's local UID. In this case, there is
+no point in including the B<-id> argument, because the only acceptable
+value (the issuer's local UID) is the value used when the B<-id> argument
+is omitted. Requiring matching UIDs is effective only when users have
+the same local UID on the translator machine as on NFS client
+machines. In that case, it guarantees that users assign their tokens
+only to their own NFS sessions.
+
+This command does not make it possible for users working on
+non-supported system types to issue AFS commands. This is possible
+only on NFS clients of a system type for which AFS is available.
+
+=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<klog(1)>,
+L<pagsh(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kpasswd - Changes the issuer's password in the Authentication Database
+
+=head1 SYNOPSIS
+
+kpasswd [B<-x>] [B<-principal> I<user name>] [B<-password> I<user's password>]
+[B<-newpassword> I<user's new password>] [B<-cell> I<cell name>]
+[B<-servers> I<explicit list of servers> [I<explicit list of servers> ...]] [B<-pipe>] [B<-help>]
+
+kpasswd [B<-x>] [B<-pr> I<user name>] [B<-pa> I<user's password>]
+[B<-n> I<user's new password>] [B<-c> I<cell name>]
+[B<-s> I<explicit list of servers> [I<explicit list of servers> ...]] [B<-pi>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<kpasswd> command changes the password recorded in an Authentication
+Database entry. By default, the command interpreter changes the
+password for the AFS user name that matches the issuer's local
+identity (UNIX UID). To specify an alternate user, include the
+B<-principal> argument. The user named by the B<-principal> argument does
+not have to appear in the local password file (the B</etc/passwd> file or
+equivalent).
+
+By default, the command interpreter sends the password change request
+to the Authentication Server running on one of the database server
+machines listed for the local cell in the B</usr/afs/etc/CellServDB> file
+on the local disk; it chooses the machine at random. It consults the
+B</usr/vice/etc/ThisCell> file on the local disk to learn the local cell
+name. To specify an alternate cell, include the B<-cell> argument.
+
+Unlike the UNIX C<passwd> command, the C<kpasswd> command does not restrict
+passwords to eight characters or less; it accepts passwords of
+virtually any length. All AFS commands that require passwords
+(including the C<klog>, C<kpasswd>, and AFS-modified login utilities, and
+the commands in the C<kas> suite) accept passwords longer than eight
+characters, but some other applications and operating system utilities
+do not. Selecting an AFS password of eight characters or less enables
+the user to maintain matching AFS and UNIX passwords.
+
+The command interpreter makes the following checks:
+
+=over
+
+=item *
+
+If the program B<kpwvalid> exists in the same directory as the
+C<kpasswd> command, the command interpreter pass the new password to
+it for verification. For details, see the L<kpwvalid(1)> reference page.
+
+=item *
+
+If the B<-reuse> argument to the C<kas setfields> command has been used
+to prohibit reuse of previous passwords, the command interpreter
+verifies that the password is not too similar too any of the
+user's previous 20 passwords. It generates the following error
+message at the shell:
+
+ Password was not changed because it seems like a reused password
+
+To prevent a user from subverting this restriction by changing the
+password twenty times in quick succession (manually or by running
+a script), use the B<-minhours> argument on the B<kaserver>
+initialization command. The following error message appears if a
+user attempts to change a password before the minimum time has
+passed:
+
+ Password was not changed because you changed it too
+ recently; see your systems administrator
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-x>
+
+Appears only for backwards compatibility.
+
+=item B<-principal> I<user name>
+
+Names the Authentication Database entry for which to change the
+password. If this argument is omitted, the database entry with
+the same name as the issuer's local identity (UNIX UID) is
+changed.
+
+=item B<-password> I<user's password>
+
+Specifies the current password. Omit this argument to have the
+command interpreter prompt for the password, which does not
+echo visibly:
+
+Old password: I<current_password>
+
+=item B<-newpassword> I<user's new password>
+
+Specifies the new password, which the C<kpasswd> command
+interpreter converts into an encryption key (string of octal
+numbers) before sending it to the Authentication Server for
+storage in the user's Authentication Database entry.
+
+Omit this argument to have the command interpreter prompt for
+the password, which does not echo visibly:
+
+ New password (RETURN to abort): new_password
+ Retype new password: new_password
+
+=item B<-cell> I<cell name>
+
+Specifies the cell in which to change the password, by
+directing the command to that cell's Authentication Servers.
+The issuer can abbreviate the cell name to the shortest form
+that distinguishes it from the other cells listed in the local
+B</usr/vice/etc/CellServDB> file.
+
+By default, the command is executed in the local cell, as
+defined
+
+=over
+
+=item *
+
+First, by the value of the environment variable AFSCELL
+
+=item *
+
+Second, in the B</usr/vice/etc/ThisCell> file on the client
+machine on which the command is issued
+
+=back
+
+=item B<-servers> I<explicit list of servers> ...
+
+Establishes a connection with the Authentication Server running
+on each specified machine, rather than with all of the database
+server machines listed for the relevant cell in the local copy
+of the B</usr/vice/etc/CellServDB> file. The C<kpasswd> command
+interpreter then sends the password-changing request to one
+machine chosen at random from the set.
+
+=item B<-pipe>
+
+Suppresses all output to the standard output stream or standard
+error stream. The C<kpasswd> command interpreter expects to
+receive all necessary arguments, each on a separate line, from
+the standard input stream. Do not use this argument, which is
+provided for use by application programs rather than human
+users.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example shows user B<pat> changing her password in the ABC
+Corporation cell.
+
+B< kpasswd>
+ Changing password for 'pat' in cell 'abc.com'.
+ Old password:
+ New password (RETURN to abort):
+ Verifying, please re-enter new_password:
+
+=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<kas_setfields(1)>,
+L<kas_setpassword(1)>,
+L<klog(1)>,
+L<kpwvalid(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+kpwvalid - Checks quality of new password
+
+=head1 DESCRIPTION
+
+The C<kpwvalid> command checks the quality of a new password passed to it
+from the C<kpasswd> or C<kas setpassword> command. It is optional. If it
+exists, it must reside in the same AFS directory as the binaries for
+the C<kpasswd> and C<kas> command suites (create a symbolic link from the
+client machine's local disk to this directory). The directory's ACL
+must extend the B<a> (B<administer>) and B<w> (B<write>) permissions to the
+B<system:administrators> group only. These requirements prevent
+unauthorized users from substituting a spurious C<kpwvalid> binary.
+
+The AFS distribution includes an example C<kpwvalid> program that checks
+that the password is at least eight characters long; the code for it
+appears in the following L</"EXAMPLES"> section.
+
+The script or program must accept a sequence of password strings, one
+per line, on the standard input stream. The first is the current
+password and is ignored. Each subsequent string is a candidate
+password to be checked. The program must write the following to the
+standard output stream for each one:
+
+=over
+
+=item *
+
+0 (zero) and a newline character to indicate that the password is
+acceptable
+
+=item *
+
+A non-zero decimal number and a newline character to indicate that
+the password is not acceptable
+
+=back
+
+Further, it must write any error messages only to the standard error
+stream, not to the standard output stream.
+
+=head1 EXAMPLES
+
+The following example program, included in the AFS distribution,
+verifies that the requested password includes eight or more
+characters.
+
+ #include <stdio.h>
+ /* prints 0 if the password is long enough, otherwise non-zero */
+ main()
+ {
+ char oldpassword[512];
+ char password[512];
+
+ if (fgets(oldpassword, 512, stdin))
+ while (fgets(password, 512, stdin)) {
+ if (strlen(password) > 8) { /* password includes a newline */
+ fputs("0\n",stdout);
+ fflush(stdout);
+ }
+ else {
+ fputs("Passwords must contain at least 8 characters.\n",
+ stderr);
+ fputs("1\n",stdout);
+ fflush(stdout);
+ }
+ }
+ return 0;
+ }
+
+=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<kas_setpassword(1)>,
+L<kpasswd(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts - Interface to the AFS Protection Server
+
+=head1 SYNOPSIS
+
+pts I<command> [I<options> ...]
+
+=head1 DESCRIPTION
+
+The commands in the pts command suite are the administrative interface to
+the Protection Server, which runs on each database server machine in a
+cell and maintains the Protection Database. The database stores the
+information that AFS uses to augment and refine the standard UNIX scheme
+for controlling access to files and directories.
+
+Instead of relying only on the mode bits that define access rights for
+individual files, AFS associates an access control list (ACL) with each
+directory. The ACL lists users and groups and specifies which of seven
+possible access permissions they have for the directory and the files it
+contains. (It is still possible to set a directory or file's mode bits,
+but AFS interprets them in its own way; see the chapter on protection in
+the AFS Administration Guide for details.)
+
+AFS enables users to define groups in the Protection Database and place
+them on ACLs to extend a set of rights to multiple users simultaneously.
+Groups simplify administration by making it possible to add someone to
+many ACLs by adding them to a group that already exists on those ACLs.
+Machines can also be members of a group, so that users logged into the
+machine automatically inherit the permissions granted to the group.
+
+There are several categories of commands in the pts command suite:
+
+=over 4
+
+=item *
+
+Commands to create and remove Protection Database entries: C<pts
+creategroup>, C<pts createuser>, and C<pts delete>
+
+=item *
+
+Commands to administer and display group membership: C<pts adduser>,
+C<pts listowned>, C<pts membership>, and C<pts removeuser>.
+
+=item *
+
+Commands to administer and display properties of user and group entries
+other than membership: C<pts chown>, C<pts examine>, C<pts listentries>,
+C<pts rename>, and C<pts setfields>.
+
+=item *
+
+Commands to set and examine the counters used when assigning IDs to users
+and groups: C<pts listmax> and C<pts setmax>.
+
+=item *
+
+Commands to obtain help: C<pts apropos> and C<pts help>.
+
+=back
+
+All of these commands are described in separate manual pages.
+
+=head1 OPTIONS
+
+The following arguments and flags are available on many commands in the
+pts 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 F</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 4
+
+=item 1.
+
+The value of the AFSCELL environment variable.
+
+=item 2.
+
+The local F</usr/vice/etc/ThisCell> file.
+
+=back
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution immediately.
+Without it, the command halts as soon as the first error is encountered.
+In either case, the pts command interpreter reports errors at the command
+shell. This flag is especially useful if the issuer provides many values
+for a command line argument; if one of them is invalid, the command
+interpreter continues on to process the remaining arguments.
+
+=item B<-help>
+
+Prints a command's online help message to standard output. 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<-noauth>
+
+Establishes an unauthenticated connection to the Protection Server, in
+which the server treats the issuer as the unprivileged user anonymous. It
+is useful only when authorization checking is disabled on the server
+machine (during the installation of a file server machine or when the bos
+setauth command has been used during other unusual circumstances). In
+normal circumstances, the Protection Server allows only privileged users
+to issue commands that change the Protection Database, and refuses to
+perform such an action even if the B<-noauth> flag is provided.
+
+=back
+
+The individual pts subcommands take many other flags which vary from
+command to command. See their individual documentation for details.
+
+=head1 PRIVILEGE REQUIRED
+
+Members of the system:administrators group can issue all pts commands on
+any entry in the Protection Database.
+
+Users who do not belong to the system:administrators group can list
+information about their own entry and any group entries they own. The
+privacy flags set with the C<pts setfields> command control access to
+entries owned by other users.
+
+=head1 SEE ALSO
+
+L<pts_adduser(1)>,
+L<pts_apropos(1)>,
+L<pts_chown(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_delete(1)>,
+L<pts_examine(1)>,
+L<pts_help(1)>,
+L<pts_listentries(1)>,
+L<pts_listmax(1)>,
+L<pts_listowned(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>,
+L<pts_rename(1)>,
+L<pts_setfields(1)>,
+L<pts_setmax(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts adduser - Add a user or machine to a Protection Database group
+
+=head1 SYNOPSIS
+
+pts adduser B<-user> I<user> [I<user> ...] B<-group> I<group> [I<group>
+...] [B<-cell> I<cell>] [B<-noauth>] [B<-force>] [B<-help>]
+
+pts ad B<-u> I<user> [I<user> ...] B<-g> I<group> [I<group> ...] [B<-c>
+I<cell>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts adduser> command adds each user or machine entry named by the
+B<-user> argument as a member of each group named by the B<-group>
+argument.
+
+To remove members of a group, use the C<pts removeuser> command. To list
+the groups to which a user or machine belongs, or the members of a
+specified group, use the C<pts membership> command.
+
+If no explicit B<-user> or B<-group> flags are given, the first argument
+to C<pts adduser> is taken to be the user and the second argument is taken
+to be the group to which to add that user. For any more complex
+operation, the explicit flags must be provided.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-user> I<user> [I<user> ...]
+
+Specifies the name of each user or machine entry to add to each group
+named by the B<-group> argument. The name of a machine entry resembles an
+IP address and can use the wildcard notation described on the C<pts
+createuser> reference page. The user or machine entry must already exist
+in the Protection Database.
+
+=item B<-group> I<group> [I<group> ...]
+
+Specifies the complete name (including the owner prefix if applicable) of
+each group to which to add members. The group entry must already exist in
+the Protection Database.
+
+=item B<-cell> I<cell>
+
+Names the cell in which to run the command. For more details, see the
+introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible when errors
+or other problems occur, rather than halting execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example adds user smith to the group system:administrators.
+
+ pts adduser -user smith -group system:administrators
+
+The following example adds users jones, terry, and pat to the
+smith:colleagues group.
+
+ pts adduser -user jones terry pat -group smith:colleagues
+
+The following example adds the machine entries in the ABC Corporation
+subnet to the group bin-prot. Because of the IP address range of the ABC
+Corporation subnet, the system administrator was able to group the
+machines into three machine entries (using the wildcard notation discussed
+on the C<pts createuser> reference page).
+
+ pts adduser -user 138.255.0.0 192.12.105.0 -group bin-prot
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the fourth privacy flag
+in the Protection Database entry for each group named by the B<-group>
+argument (use the C<pts examine> command to display the flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen, only the group's owner and members of the
+system:administrators group can add members.
+
+=item *
+
+If it is lowercase a, current members of the group can add new members.
+
+=item *
+
+If it is uppercase A, anyone who can access the cell's database server
+machines can add new members.
+
+=back
+
+=head1 CAVEATS
+
+After being added as a group member, a currently authenticated user must
+reauthenticate (for example, by issuing the B<klog> command) to obtain
+permissions granted to the group on an access control list (ACL).
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_createuser(1)>,
+L<pts_examine(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>,
+L<pts_setfields(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts apropos - Displays each help entry containing a keyword string
+
+=head1 SYNOPSIS
+
+pts apropos B<-topic> I<help string> [B<-help>]
+
+pts ap B<-t> I<help string> [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts apropos> command displays the first line of the online help
+entry for any pts 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 "pts help" command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-topic>
+
+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
+pts command in which the string specified by the B<-topic> argument is
+part of the command name or first line.
+
+=head1 EXAMPLES
+
+The following command lists all pts commands that include the word
+create in their names or short descriptions:
+
+ pts apropos create
+ creategroup: create a new group
+ createuser: create a new user
+
+=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<pts(1)>,
+L<pts_help(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts chown - Changes the owner of a Protection Database entry
+
+=head1 SYNOPSIS
+
+pts chown B<-name> I<group name> B<-owner> I<new owner>
+[B<-cell> I<cell name>] [B<-noauth>] [B<-force>] [B<-help>]
+
+pts cho B<-na> I<group name> B<-o> I<new owner> [B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts chown> command designates the user or group named by the B<-owner>
+argument as the owner of the group named by the B<-name> argument, and
+records the new owner in the owner field of the group's Protection
+Database entry.
+In the case of regular groups, this command automatically changes the
+group name's owner prefix (the part of the group name before the
+colon) to match the new owner. If the new owner is itself a group,
+then only its owner prefix, not its complete name, becomes the owner
+prefix in the new name. The change to the owner prefix does not
+propagate to any groups owned by the group, however. To make the owner
+prefix of such group-owned groups reflect the new owning group, use
+the pts rename command.
+It is not possible to change a user or machine entry's owner from the
+default set at creation time, the system:administrators group.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<group name>
+
+Specifies the current name of the group to which to assign a
+new owner.
+
+=item B<-owner> I<new owner>
+
+Names the user or group to become the group's owner.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 EXAMPLES
+
+The following example changes the owner of the group terry:friends
+from the user terry to the user pat. A side effect is that the group
+name changes to pat:friends.
+
+ pts chown -name terry:friends -owner pat
+
+The following example changes the owner of the group terry:friends
+from the user terry to the group pat:buddies. A side effect is that
+the group name changes to pat:friends.
+
+ pts chown -name terry:friends -owner pat:buddies
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group or currently
+own the group.
+
+=head1 CAVEATS
+
+While designating a machine as a group's owner does not cause an
+error, it is not recommended. The Protection Server does not extend
+the usual privileges of group ownership to users logged onto the
+machine.
+
+=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<pts(1)>,
+L<pts_rename(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts creategroup - Creates an (empty) Protection Database group entry
+
+=head1 SYNOPSIS
+
+pts creategroup B<-name> I<group name> [I<group name> ...]
+[B<-owner> I<owner of the group>]
+[B<-id> I<id (negated) for the group> [I<id (negated) for the group> ...]]
+[B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts createg B<-na> I<group name> [I<group name> ...]
+[B<-o> I<owner of the group>]
+[B<-i> I<id (negated) for the group> [I<id (negated) for the group> ...]]
+[B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+pts cg B<-na> I<group name> [I<group name> ...]
+[B<-o> I<owner of the group>]
+[B<-i> I<id (negated) for the group> [I<id (negated) for the group> ...]]
+[B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts creategroup> command creates an entry in the Protection
+Database for each group specified by the B<-name> argument. The entry
+records the issuer of the command as the group's creator, and as the
+group's owner unless the B<-owner> argument names an alternate user or
+group as the owner.
+There are two types of groups:
+
+=over 4
+
+=item *
+
+regular, the names of which have two parts separated by a colon.
+The part before the colon names the group's owner. Any user can
+create such groups.
+
+=item *
+
+prefix-less, which do not have an owner prefix. Only members of
+the system:administrators group can create prefix-less groups.
+
+=back
+
+Creating a group lowers the issuer's group-creation quota by one. This
+is true even if the B<-owner> argument is used to assign ownership to an
+alternate user or group. To display a user's group-creation quota, use
+the pts examine command; to set it, use the pts setfields command.
+AFS group ID (AFS GID) numbers are negative integers and by default
+the Protection Server assigns a GID that is one less (more negative)
+than the current value of the max group id counter in the Protection
+Database, decrementing the counter by one for each group. Members of
+the system:administrators group can use the B<-id> argument to assign
+specific AFS GID numbers. If any of the specified GIDs is lower (more
+negative) than the current value of the max group id counter, the
+counter is reset to that value. It is acceptable to specify a GID
+greater (less negative) than the current value of the counter, but the
+creation operation fails if an existing group already has it. To
+display or set the value of the max group id counter, use the pts
+listmax or pts setmax command, respectively.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<group name> [I<group name> ...]
+
+Specifies the name of each group to create. Provide a string of
+up to 63 characters, which can include lowercase (but not
+uppercase) letters, numbers, and punctuation marks. A regular
+name includes a single colon (:) to separate the two parts of
+the name; the colon cannot appear in a prefix-less group name.
+A regular group's name must have the following format:
+owner_name:group_name and the owner_name field must reflect the
+actual owner of the group, as follows:
+
+=over 4
+
+=item *
+
+If the optional B<-owner> argument is not included, the field
+must match the AFS username under which the issuer is
+currently authenticated.
+
+=item *
+
+If the B<-owner> argument names an alternate AFS user, the field
+must match that AFS username.
+
+=item *
+
+If the B<-owner> argument names another regular group, the field
+must match the owning group's owner field (the part of its
+name before the colon). If the B<-owner> argument names a
+prefix-less group, the field must match the owning group's
+complete name.
+
+=back
+
+
+=item B<-owner> I<owner of the group>
+
+Specifies a user or group as the owner for each group, rather
+than the issuer of the command. Provide either an AFS username
+or the name of a regular or prefix-less group. An owning group
+must already have at least one member. This requirement
+prevents assignment of self-ownership to a group during its
+creation; use the C<pts chown> command after issuing this command,
+if desired.
+
+=item B<-id> I<id (negated) for the group> [I<id (negated) for the group> ...]
+
+Specifies a negative integer AFS GID number for each group,
+rather than allowing the Protection Server to assign it.
+Precede the integer with a hyphen (-) to indicate that it is
+negative. If this argument is used and the B<-name> argument names multiple
+new groups, it is best to provide an equivalent number of AFS
+GIDs. The first GID is assigned to the first group, the second
+to the second group, and so on. If there are fewer GIDs than
+groups, the Protection Server assigns GIDs to the unmatched
+groups based on the max group id counter. If there are more
+GIDs than groups, the excess GIDs are ignored. If any of the
+GIDs is lower (more negative) than the current value of the max
+group id counter, the counter is reset to that value.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 OUTPUT
+
+The command generates the following string to confirm creation of each
+group:
+group name has id AFS GID
+
+=head1 EXAMPLES
+
+In the following example, the user pat creates groups called
+pat:friends and pat:colleagues.
+
+ pts creategroup -name pat:friends pat:colleagues
+
+The following example shows a member of the system:administrators
+group creating the prefix-less group staff and assigning its ownership
+to the system:administrators group rather than to herself.
+
+ pts creategroup -name staff -owner system:administrators
+
+In the following example, the user pat creates a group called
+smith:team-members, which is allowed because the -owner argument
+specifies the required value (smith).
+
+ pts creategroup -name smith:team-members -owner smith
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group to create
+prefix-less groups or include the B<-id> argument.
+To create a regular group, the issuer must
+
+=over
+
+=item *
+
+Be authenticated. The command fails if the B<-noauth> flag is
+provided.
+
+=item *
+
+Have a group-creation quota greater than zero. The C<pts examine>
+command displays this quota.
+
+=back
+
+=head1 CAVEATS
+
+Although using the -owner argument to designate a machine entry as a
+group's owner does not generate an error, it is not recommended. The
+Protection Server does not extend the usual privileges of group
+ownership to users logged onto the machine.
+
+=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<pts(1)>,
+L<pts_examine(1)>,
+L<pts_listmax(1)>,
+L<pts_setfields(1)>,
+L<pts_setmax(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts createuser - Creates a user or machine entry in the Protection Database
+
+=head1 SYNOPSIS
+
+pts createuser B<-name> I<user name> [I<user name> ...]
+[B<-id> I<user id> [I<user id> ...]] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts createu B<-na> I<user name> [I<user name> ...]
+[B<-i> I<user id> [I<user id> ...]] [B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+pts cu B<-na> I<user name> [I<user name> ...]
+[B<-i> I<user id> [I<user id> ...]]
+[B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts createuser> command creates an entry in the Protection Database
+for each user or machine specified by the B<-name> argument. A user entry
+name becomes the user's AFS username (the one to provide when
+authenticating with the AFS Authentication Server). A machine entry's
+name is the machine's IP address or a wildcard notation that
+represents a range of consecutive IP addresses (a group of machines on
+the same network). It is not possible to authenticate as a machine,
+but a group to which a machine entry belongs can appear on a
+directory's access control list (ACL), thereby granting the indicated
+permissions to any user logged on to the machine.
+AFS user IDs (AFS UIDs) are positive integers and by default the
+Protection Server assigns an AFS UID that is one greater than the
+current value of the max user id counter in the Protection Database,
+incrementing the counter by one for each user. To assign a specific
+AFS UID, use the B<-id> argument. If any of the specified AFS UIDs is
+greater than the current value of the max user id counter, the counter
+is reset to that value. It is acceptable to specify an AFS UID smaller
+than the current value of the counter, but the creation operation
+fails if an existing user or machine entry already has it. To display
+or set the value of the max user id counter, use the pts listmax or
+pts setmax command, respectively.
+The issuer of the C<pts createuser> command is recorded as the entry's
+creator and the group system:administrators as its owner.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<user name> [I<user name> ...]
+
+Specifies either a username for a user entry, or an IP address
+(complete or wildcarded) for a machine entry:
+
+=over 4
+
+=item *
+
+A username can include up to 63 numbers and lowercase
+letters, but it is best to make it shorter than eight
+characters, because many application programs cannot handle
+longer names. Also, it is best not to include shell
+metacharacters or other punctuation marks. In particular, the
+colon (:) and at-sign (@) characters are not acceptable. The
+period is generally used only in special administrative
+names, to separate the username and an instance, as in the
+example pat.admin.
+
+=item *
+
+A machine identifier is its IP address in dotted decimal
+notation (for example, 192.12.108.240), or a wildcard
+notation that represents a set of IP addresses (a group of
+machines on the same network). The following are acceptable
+wildcard formats. The letters W, X, Y and Z each represent an
+actual number from the range 1 through 255.
+
+=over 4
+
+=item *
+
+W.X.Y.Z represents a single machine, for example
+192.12.108.240.
+
+=item *
+
+W.X.Y.0 matches all machines whose IP addresses start
+with the first three numbers. For example, 192.12.108.0
+matches both 192.12.108.119 and 192.12.108.120, but does
+not match 192.12.105.144.
+
+=item *
+
+W.X.0.0 matches all machines whose IP addresses start
+with the first two numbers. For example, the address
+192.12.0.0 matches both 192.12.106.23 and
+192.12.108.120, but does not match 192.5.30.95.
+
+=item *
+
+W.0.0.0 matches all machines whose IP addresses start
+with the first number in the specified address. For
+example, the address 192.0.0.0 matches both 192.5.30.95
+and 192.12.108.120, but does not match 138.255.63.52.
+
+=back
+
+Do not define a machine entry with the name 0.0.0.0 to match
+every machine. The system:anyuser group is equivalent.
+
+=back
+
+=item B<-id> I<user id> [I<user id> ...]
+
+Specifies an AFS UID for each user or machine entry, rather
+than allowing the Protection Server to assign it. Provide a
+positive integer.
+If this argument is used and the B<-name> argument names multiple
+new entries, it is best to provide an equivalent number of AFS
+UIDs. The first UID is assigned to the first entry, the second
+to the second entry, and so on. If there are fewer UIDs than
+entries, the Protection Server assigns UIDs to the unmatched
+entries based on the max user id counter. If there are more
+UIDs than entries, the excess UIDs are ignored. If any of the
+UIDs is greater than the current value of the max user id
+counter, the counter is reset to that value.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The command generates the following string to confirm creation of each
+user:
+User name has id id
+
+=head1 EXAMPLES
+
+The following example creates a Protection Database entry for the user
+johnson.
+
+ pts createuser -name johnson
+
+The following example creates three wildcarded machine entries in the
+ABC Corporation cell. The three entries encompass all of the machines
+on the company's networks without including machines on other
+networks:
+
+ pts createuser -name 138.255.0.0 192.12.105.0 192.12.106.0
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=head1 CAVEATS
+
+The Protection Server reserves AFS UID 0 (zero) and returns an error
+if the B<-id> argument has that value.
+
+=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<pts(1)>,
+L<pts_listmax(1)>,
+L<pts_setmax(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts delete - Deletes a Protection Database entry
+
+=head1 SYNOPSIS
+
+pts delete B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+[B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts d B<-na> I<user or group name or id> [I<user or group name or id> ...]
+[B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts delete> command removes each entry specified by the B<-nameorid>
+argument from the Protection Database. Deleting entries affects other
+parts of the system in various ways:
+
+=over 4
+
+=item *
+
+Deleted users and groups still appear on access control lists
+(ACLs), but are listed by AFS UID or GID rather than by name,
+because there is no longer an associated name to which to
+translate the ID. To remove these obsolete entries from ACLs, use
+the C<fs cleanacl> command.
+
+=item *
+
+Deleting a user or machine's entry removes it from the membership
+list of any group to which it belonged.
+
+=item *
+
+Deleting a group entry removes it from the membership list of any
+user or machine entry that belonged to the group, and also
+increments the group-creation quota of the group's creator by one,
+even if the creator no longer owns the group.
+To remove a user or machine from a group without actually deleting the
+entry, use the pts removeuser command.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+
+Specifies the name or AFS UID of each user, the name or AFS GID
+of each group, or the IP address (complete or wildcard-style)
+or AFS UID of each machine entry to delete. It is acceptable to
+mix users, machines, and groups on the same command line, as
+well as names (IP addresses for machines) and IDs. Precede the
+GID of each group with a hyphen to indicate that it is
+negative.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 EXAMPLES
+
+The following example deletes the user entries pat and terry:
+
+ pts delete pat terry
+
+The following example deletes the Protection Database entry of the
+group with AFS GID -215.
+
+ pts delete -215
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group to delete
+user and machine entries. To delete group entries, the issuer must
+either own the group or belong to the system:administrators group.
+
+=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<fs_cleanacl(1)>,
+L<pts(1)>,
+L<pts_removeuser(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts examine - Displays a Protection Database entry
+
+=head1 SYNOPSIS
+
+pts examine B<-nameorid> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts e B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+pts check B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+pts che B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts examine> command displays information from the Protection
+Database entry of each user, machine or group specified by the
+B<-nameorid> argument.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+
+Specifies the name or AFS UID of each user, the name or AFS GID
+of each group, or the IP address (complete or wildcard-style)
+or AFS UID of each machine for which to display the Protection
+Database entry. It is acceptable to mix users, machines, and
+groups on the same command line, as well as names (IP addresses
+for machines) and IDs. Precede the GID of each group with a
+hyphen to indicate that it is negative.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output for each entry consists of two lines that include the
+following fields:
+
+=over 4
+
+=item Name
+
+The contents of this field depend on the type of entry:
+
+=over 4
+
+=item *
+
+For a user entry, it is the username that the user types when
+authenticating with AFS.
+
+=item *
+
+For a machine entry, it is either the IP address of a single
+machine in dotted decimal format, or a wildcard notation that
+represents a group of machines on the same network. See the
+C<pts createuser> reference page for an explanation of the
+wildcard notation.
+
+=item *
+
+For a group entry, it is one of two types of group name. If
+the name has a colon between the two parts, it represents a
+regular group and the part before the prefix reflects the
+group's owner. A prefix-less group does not have the owner
+field or the colon. For more details on group names, see the
+C<pts creategroup> reference page.
+
+=back
+
+=item id
+
+A unique number that the AFS server processes use to identify
+AFS users, machines and groups. AFS UIDs for user and machine
+entries are positive integers, and AFS GIDs for group entries
+are negative integers. AFS UIDs and GIDs are similar in
+function to the UIDs and GIDs used in local file systems such
+as UFS, but apply only to AFS operations.
+
+=item owner
+
+The user or group that owns the entry and thus can administer
+it (change the values in most of the fields displayed in the
+output of this command), or delete it entirely. The Protection
+Server automatically records the system:administrators group in
+this field for user and machine entries at creation time.
+
+=item creator
+
+The user who issued the pts createuser or pts creategroup
+command to create the entry. This field serves as an audit
+trail, and cannot be changed.
+
+=item membership
+
+An integer that for users and machines represents the number of
+groups to which the user or machine belongs. For groups, it
+represents the number of group members.
+
+=item flags
+
+A string of five characters, referred to as privacy flags,
+which indicate who can display or administer certain aspects of
+the entry.
+
+=over 4
+
+=item s
+
+Controls who can issue the pts examine command to display
+the entry.
+
+=item o
+
+Controls who can issue the pts listowned command to
+display the groups that a user or group owns.
+
+=item m
+
+Controls who can issue the pts membership command to
+display the groups a user or machine belongs to, or which
+users or machines belong to a group.
+
+=item a
+
+Controls who can issue the pts adduser command to add a
+user or machine to a group. It is meaningful only for
+groups, but a value must always be set for it even on
+user and machine entries.
+
+=item r
+
+Controls who can issue the pts removeuser command to
+remove a user or machine from a group. It is meaningful
+only for groups, but a value must always be set for it
+even on user and machine entries.
+
+=back
+
+Each flag can take three possible types of values to enable a
+different set of users to issue the corresponding command:
+
+=over 4
+
+=item *
+
+A hyphen (-) designates the members of the
+system:administrators group and the entry's owner. For user
+entries, it designates the user in addition.
+
+=item *
+
+The lowercase version of the letter applies meaningfully to
+groups only, and designates members of the group in addition
+to the individuals designated by the hyphen.
+
+=item *
+
+The uppercase version of the letter designates everyone.
+For example, the flags SOmar on a group entry indicate that
+anyone can examine the group's entry and display the groups
+that it owns, and that only the group's members can display,
+add, or remove its members.
+
+=back
+
+The default privacy flags for user and machine entries are
+S----, meaning that anyone can display the entry. The ability
+to perform any other functions is restricted to members of the
+system:administrators group and the entry's owner (as well as
+the user for a user entry).
+The default privacy flags for group entries are S-M--, meaning
+that all users can display the entry and the members of the
+group, but only the entry owner and members of the
+system:administrators group can perform other functions.
+
+=item group quota
+
+The number of additional groups the user is allowed to create.
+The pts createuser command sets it to 20 for both users and
+machines, but it has no meaningful interpretation for a
+machine, because it is not possible to authenticate as a
+machine. Similarly, it has no meaning in group entries and the
+pts creategroup command sets it to 0 (zero); do not change this
+value.
+
+=back
+
+=head1 EXAMPLES
+
+The following example displays the user entry for terry and the
+machine entry 158.12.105.44.
+
+ pts examine terry 158.12.105.44
+
+ Name: terry, id: 1045, owner: system:administrators, creator: admin,
+ membership: 9, flags: S----, group quota: 15.
+ Name: 158.12.105.44, id: 5151, owner: system:administrators,
+ creator: byu, membership: 1, flags: S----, group quota: 20.
+
+The following example displays the entries for the AFS groups with
+GIDs -673 and -674.
+
+ pts examine -673 -674
+
+ Name: terry:friends, id: -673, owner: terry, creator: terry,
+ membership: 5, flags: S-M--, group quota: 0.
+ Name: smith:colleagues, id: -674, owner: smith, creator: smith,
+ membership: 14, flags: SOM--, group quota: 0.
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the first privacy
+flag in the Protection Database entry of each entry specified by the
+B<-nameorid> argument:
+
+=over 4
+
+=item *
+
+If it is lowercase s, members of the system:administrators group
+and the user associated with a user entry can examine it, and only
+members of the system:administrators group can examine a machine
+or group entry.
+
+=item *
+
+If it is uppercase S, anyone who can access the cell's database
+server machines can examine the entry.
+
+=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,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_chown(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_listowned(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>,
+L<pts_rename(1)>,
+L<pts_setfields(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts help - Displays the syntax of specified pts commands or lists functional
+descriptions for all pts commands
+
+=head1 SYNOPSIS
+
+pts help [B<-topic> I<help string> [I<help string> ...]]
+[B<-help>]
+
+pts h [B<-t> I<help string> [I<help string> ...]]
+[B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts help> command displays the complete online help entry (short
+description and syntax statement) for each command 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 pts command.
+To list every pts command whose name or short description includes a
+specified keyword, use the pts 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 pts part of the command name, providing
+only the operation code (for example, specify membership, not
+pts membership). If this argument is omitted, the output
+briefly describes every pts 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 pts command consists of the following
+two or three lines:
+
+=over 4
+
+=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 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 command displays the online help entry for the pts
+membership command:
+
+ pts help membership
+
+ pts membership: list membership of a user or group
+ aliases: groups
+ Usage: pts membership -nameorid <user or group name or id>+
+ [-cell <cell name>] [-noauth] [-force] [-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,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_apropos(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts listentries - Displays all user or group entries in the Protection Database
+
+=head1 SYNOPSIS
+
+pts listentries [B<-users>] [B<-groups>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts liste [B<-u>] [B<-g>] [B<-c> I<cell name>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts listentries> command displays the name and AFS ID of all
+Protection Database entries of the indicated type. It also displays
+the AFS ID of each entry's owner and creator.
+To display all user and machine entries, either include the B<-users>
+flag or omit both it and the B<-groups> flag. To display all group
+entries, include the B<-groups> flag. To display all entries, provide
+both flags.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-users>
+
+Displays user and machine entries.
+
+=item B<-groups>
+
+Displays group entries.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=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 entry, with information in four
+columns that have the following headers:
+
+=over 4
+
+=item Name
+
+The entry's name
+
+=item ID
+
+The entry's AFS ID (AFS UID for a user or machine, negative AFS
+GID for a group)
+
+=item Owner
+
+The AFS ID of the user or group that owns the entry
+
+=item Creator
+
+The AFS ID of the user who created the entry (the
+system:administrators group is listed as the creator of the
+entry for anonymous and the system groups, but it is not
+otherwise possible for a group to create groups)
+
+=back
+
+In general, the entries appear in the order in which they were
+created.
+
+=head1 EXAMPLES
+
+The following example displays both user and group entries.
+
+ pts listentries -users -groups
+
+ Name ID Owner Creator
+ system:administrators -204 -204 -204
+ system:anyuser -101 -204 -204
+ system:authuser -102 -204 -204
+ anonymous 32766 -204 -204
+ admin 1 -204 32766
+ pat 100 -204 1
+ smith 101 -204 1
+ pat:friends -206 100 100
+ staff -207 -204 1
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the system:administrators group.
+
+=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<pts(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_examine(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts listmax - Displays the max user id and max group id counters
+
+=head1 SYNOPSIS
+
+pts listmax [B<-cell> I<cell name>] [B<-noauth>] [B<-force>] [B<-help>]
+
+pts listm [B<-c> I<cell name>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts listmax> command displays the values of the max user id and max
+group id counters, which the Protection Server uses to track the AFS
+user IDs (AFS UIDs) it allocates to new users or machines, and the AFS
+group IDs (AFS GIDs) it allocates to new groups, respectively. When an
+administrator next issues the pts createuser command and does not
+include the B<-id> argument, the new user or machine receives an AFS UID
+one greater than the max user id counter, and when a user issues the
+pts creategroup command and does not include the B<-id> argument, the new
+group receives an AFS UID one less (more negative) than the max group
+id counter.
+To reset one or both counters, members of the system:administrators
+group can issue the pts setmax command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 OUTPUT
+
+The command displays the counters in the following format:
+Max user id is user_counter and max group id is group_counter.
+
+=head1 EXAMPLES
+
+The following example displays the output of this command:
+
+ pts listmax
+
+ Max user name is 1271 and max group id is -382.
+
+=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<pts(1)>,
+L<pts_setmax(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts listowned - Displays the Protection Database groups owned by a user or group
+
+=head1 SYNOPSIS
+
+pts listowned B<-nameorid> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts listo B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts listowned> command lists the groups owned by each user or group
+specified by the B<-nameorid> argument.
+To list any orphaned groups, whose owners have themselves been deleted
+from the Protection Database, provide a value of 0 (zero) for the
+B<-nameorid> argument. To change the owner to a user or group that still
+exists, use the pts chown command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+
+Specifies the name or AFS UID of each user, or the name or AFS
+GID of each group, for which to display the list of owned
+groups. It is acceptable to mix users and groups on the same
+command line, as well as names and IDs. Precede the GID of each
+group with a hyphen to indicate that it is negative.
+A value of 0 (zero) lists group entries for groups whose owners
+no longer have entries in the Protection Database.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 OUTPUT
+
+The first line of the output indicates the name and AFS UID or AFS GID
+of each user or group for which ownership information is requested, in
+the following format:
+
+Groups owned by name (id: ID) are:
+
+A list of groups follows. The list does not include groups owned by
+groups that the user or group owns, or to which the user or group
+belongs. If the user or group does not own any groups, only the header
+line appears.
+
+The following error message appears if the issuer is not privileged to
+view ownership information. By default, for both user and group
+entries the second privacy flag is the hyphen, which denies permission
+to anyone other than the user (for a user entry) and the members of
+the system:administrators group.
+
+pts: Permission denied so failed to get owner list for name (id: ID)
+
+=head1 EXAMPLES
+
+The following example lists the groups owned by user terry and shows
+that the group terry:friends does not own any groups:
+
+ pts listowned terry terry:friends
+
+ Groups owned by terry (id: 1045) are:
+ terry:friends
+ terry:project1
+ terry:project2
+ Groups owned by terry:friends (id: -673) are:
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the second privacy
+flag in the Protection Database entry of each user or group indicated
+by the B<-nameorid> argument (use the C<pts examine> command to display the
+flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a group,
+only the members of the system:administrators group and the owner
+of a group can list the groups it owns.
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a user,
+only the members of the system:administrators group and the
+associated user can list the groups he or she owns.
+
+=item *
+
+If it is uppercase letter O, anyone who can access the cell's
+database server machines can list the groups owned by this user or
+group.
+
+=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,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_chown(1)>,
+L<pts_examine(1)>,
+L<pts_setfields(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts membership - Displays the membership list for a user or group
+
+=head1 SYNOPSIS
+
+pts membership B<-nameorid> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts m B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+pts groups B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+pts g B<-na> I<user or group name or id>
+[I<user or group name or id> ...]
+[B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts membership> command lists the groups to which each user or
+machine specified by the B<-nameorid> argument belongs, or lists the
+users and machines that belong to each group specified by the
+B<-nameorid> argument.
+It is not possible to list the members of the system:anyuser or
+system:authuser groups, and they do not appear in the list of groups
+to which a user belongs.
+To add users or machine to groups, use the pts adduser command; to
+remove them, use the pts removeuser command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+
+Specifies the name or AFS UID of each user entry, the IP
+address (complete or wildcard-style) or AFS UID of each machine
+entry, or the name or AFS GID of each group, for which to list
+group membership. It is acceptable to mix users, machines, and
+groups on the same command line, as well as names and IDs.
+Precede the GID of each group with a hyphen to indicate that it
+is negative.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 OUTPUT
+
+For each user and machine, the output begins with the following header
+line, followed by a list of the groups to which the user or machine
+belongs:
+
+Groups name (id: AFS UID) is a member of:
+
+For each group, the output begins with the following header line,
+followed by a list of the users and machines who belong to the group:
+
+Members of group_name (id: AFS GID) are:
+
+=head1 EXAMPLES
+
+The following example lists the groups to which the user pat belongs
+and the members of the group smith:friends. Note that third privacy
+flag for the pat entry was changed from the default hyphen to enable a
+non-administrative user to obtain this listing.
+
+ pts membership pat smith:friends
+
+ Groups pat (id: 1144) is a member of:
+ smith:friends
+ staff
+ johnson:project-team
+ Members of smith:friends (id: -562) are:
+ pat
+ terry
+ jones
+ richard
+ thompson
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the third privacy
+flag in the Protection Database entry of each user or group indicated
+by the B<-nameorid> argument (use the pts examine command to display the
+flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a user,
+only the associated user and members of the system:administrators
+group can list the groups to which the user belongs.
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a
+machine, only the members of the system:administrators group can
+list the groups to which the machine belongs.
+
+=item *
+
+If it is the hyphen and the B<-nameorid> argument specifies a group,
+only the owner of the group and members of the
+system:administrators group can list the members of the group.
+
+=item *
+
+If it is lowercase m and the B<-nameorid> argument specifies a user
+or machine entry, the meaning is equivalent to the hyphen.
+
+=item *
+
+If it is lowercase m and the B<-nameorid> argument specifies a group,
+members of the group can also list the other members.
+
+=item *
+
+If it is uppercase M, anyone who can access the cell's database
+server machines can list group memberships.
+
+=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,
+Stanford Linear Accelerator Center, a department of Stanford University.
+
+=head1 SEE ALSO
+
+L<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_examine(1)>,
+L<pts_removeuser(1)>,
+L<pts_setfields(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts removeuser - Removes a user from a Protection Database group
+
+=head1 SYNOPSIS
+
+pts removeuser B<-user> I<user name> [I<user name> ...]
+B<-group> I<group name> [I<group name> ...]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-force>] [B<-help>]
+
+pts rem B<-u> I<user name> [I<user name> ...]
+B<-g> I<group name> [I<group name> ...]
+[B<-c> I<cell name>]
+[B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts removeuser> command removes each user or machine named by the
+B<-user> argument from each group named by the B<-group> argument.
+To add users to a group, use the pts adduser command. To list group
+membership, use the C<pts membership> command. To remove users from a
+group and delete the group's entry completely in a single step, use
+the C<pts delete> command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-name> I<user name> [I<user name> ...]
+
+Specifies the name of each user entry or the IP address
+(complete or wildcard-style) of each machine entry to remove.
+
+=item B<-group> I<group name> [I<group name> ...]
+
+Names each group from which to remove members.
+
+=item B<-cell>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity anonymous to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+==back
+
+=head1 EXAMPLES
+
+The following example removes user smith from the groups staff and
+staff:finance. Note that no switch names are necessary because only a
+single instance is provided for the first argument (the username).
+
+ pts removeuser smith staff staff:finance
+
+The following example removes three machine entries, which represent
+all machines in the ABC Corporation network, from the group bin-prot:
+
+ pts removeuser -user 138.255.0.0 192.12.105.0 192.12.106.0 -group bin-prot
+
+=head1 PRIVILEGE REQUIRED
+
+The required privilege depends on the setting of the fifth privacy
+flag in the Protection Database for the group named by the B<-group>
+argument (use the pts examine command to display the flags):
+
+=over 4
+
+=item *
+
+If it is the hyphen, only the group's owner and members of the
+system:administrators group can remove members.
+
+=item *
+
+If it is lowercase r, members of the group can also remove other
+members.
+(It is not possible to set the fifth flag to uppercase R.)
+
+=back
+
+=head1 CAVEATS
+
+AFS compiles each user's group membership as he or she authenticates.
+Any users who have valid tokens when they are removed from a group
+retain the privileges extended to that group's members until they
+discard their tokens or reauthenticate.
+
+=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<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_examine(1)>,
+L<pts_membership(1)>,
+L<pts_setfields(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts rename - Changes the name of a Protection Database entry
+
+=head1 SYNOPSIS
+
+pts rename B<-oldname> I<old name> B<-newname> I<new name>
+ [B<-cell> I<cell name>] [B<-noauth>] [B<-force>] [B<-help>]
+
+pts ren B<-o> I<old name> B<-ne> I<new name> [B<-c> I<cell name>] [B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts rename> command changes the name of the user, machine, or group
+entry specified by the B<-oldname> argument to the name specified by the
+B<-newname> argument. It is not possible to change a user or machine
+entry's name to look like a regular group entry's name (have a colon
+in it).
+
+Members of the B<system:administrators> group can change a regular group
+name into a prefix-less name and vice versa. When changing a
+prefix-less group name into a regular group name or a regular group
+name to another regular group name, the owner field of the new name
+(the part before the colon) must correctly reflect the group's owner.
+
+Changing a regular group's owner with the C<pts chown> command
+automatically changes the owner field (the part before the colon) of
+the group's name, but does not change the owner field of any groups
+owned by the group. Use this command to rename those groups to a form
+that accurately reflects their ownership.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-oldname> I<old name>
+
+Specifies the current full name of the entry.
+
+=item B<-newname> I<new name>
+
+Specifies the new full name for the entry. For regular groups,
+the owner field (the part before the colon) of the new name
+must reflect the actual ownership of the group.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the name of the group B<staff>, owned by
+the privileged user B<admin>, to B<admin:staff>:
+
+ pts rename -oldname staff -newname admin:staff
+
+The following example changes the name of the group B<admin:finance> to
+the group B<finance>. The issuer must belong to the B<system:administrators>
+group.
+
+ pts rename -oldname admin:finance -newname finance
+
+=head1 PRIVILEGE REQUIRED
+
+To change a regular group name to a prefix-less name or vice versa, or
+to change a user or machine entry's name, the issuer must belong to
+the B<system:administrators> group.
+
+To change a group name to a new name of the same type (regular or
+prefix-less), the issuer must own the group or belong to the
+B<system:administrators> group.
+
+=head1 CAVEATS
+
+By convention, many aspects of an AFS user account have the same name
+as the user's Protection Database entry, including the Authentication
+Database entry, volume, and mount point. When using this command to
+change a user name, also change the names of all related entities to
+maintain consistency. For instructions, see the chapter on user
+accounts in the IBM AFS Administration Guide.
+
+=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<pts(1)>,
+L<pts_chown(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts setfields - Sets privacy flags or the group-creation quota for a Protection
+Database entry.
+
+=head1 SYNOPSIS
+
+pts setfields B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+[B<-access> I<set privacy flags>]
+[B<-groupquota> I<set limit on group creation>]
+[B<-cell> I<cell name>] [B<-noauth>] [B<-force>] [B<-help>]
+
+pts setf B<-na> I<user or group name or id> [I<user or group name or id> ...] [B<-a> I<set privacy flags>]
+[B<-g> I<set limit on group creation>] [B<-c> I<cell name>]
+[B<-no>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts setfields> command sets the group-creation quota, the privacy
+flags, or both, associated with each user, machine, or group entry
+specified by the B<-nameorid> argument.
+
+To examine the current quota and privacy flags, use the C<pts examine>
+command.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-nameorid> I<user or group name or id> [I<user or group name or id> ...]
+
+Specifies the name or AFS UID of each user, the IP address
+(complete or wildcard-style) of each machine, or the name or
+AFS GID of each machine for which to set privacy flags or
+group-creation quota. It is acceptable to mix users, machines,
+and groups on the same command line, as well as names (IP
+addresses for machines) and IDs. Precede the GID of each group
+with a hyphen to indicate that it is negative.
+
+=item B<-access> I<set privacy flags>
+
+Specifies the privacy flags to apply to each entry. Provide a
+string of five characters, one for each of the permissions. If
+this option is omitted, the current setting remains unchanged.
+
+Set each flag to achieve the desired combination of
+permissions. If the following list does not mention a certain
+setting, it is not acceptable. For further discussion of the
+privacy flags, see the L<pts_examine(1)> reference page.
+
+=over
+
+=item *
+
+The first flag determines who can use the C<pts examine> command
+to display information from a user, machine or group's
+Protection Database entry.
+
+=over
+
+=item *
+
+Set it to lowercase B<s> to permit the members of the
+B<system:administrators> group to display a user, machine,
+or group entry, and the associated user to display a
+user entry.
+
+=item *
+
+Set it to uppercase B<S> to permit anyone who can access
+the cell's database server machines to display a user,
+machine, or group entry.
+
+=back
+
+=item *
+
+The second flag determines who can use the C<pts listowned>
+command to list the groups that a user or group owns.
+
+=over
+
+=item *
+
+Set it to the hyphen (B<->) to permit the members of the
+B<system:administrators> group and a user to list the
+groups he or she owns, or to permit the members of the
+B<system:administrators> group and a group's owner to list
+the groups that a group owns.
+
+=item *
+
+Set it to uppercase letter B<O> to permit anyone who can
+access the cell's database server machines to list the
+groups owned by a machine or group entry.
+
+=back
+
+=item *
+
+The third flag determines who can use the C<pts membership>
+command to list the groups to which a user or machine
+belongs, or the users and machines that belong to a group.
+
+=over
+
+=item *
+
+Set it to the hyphen (B<->) to permit the members of the
+B<system:administrators> group and a user to list the
+groups he or she belongs to, to permit the members of
+the B<system:administrators> group to list the groups a
+machine belongs to, or to permit the members of the
+B<system:administrators> group and a group's owner to list
+the users and machines that belong to it.
+
+=item *
+
+Set it to lowercase B<m> to permit members of a group to
+list the other members. (For user and machine entries,
+this setting is equivalent to the hyphen.)
+
+=item *
+
+Set it to uppercase B<M> to permit anyone who can access
+the cell's database server machines to list membership
+information for a user, machine or group.
+
+=back
+
+=item *
+
+The fourth flag determines who can use the C<pts adduser>
+command to add users and machines as members of a group. This
+flag has no sensible interpretation for user and machine
+entries, but must be set nonetheless, preferably to the
+hyphen.
+
+=over
+
+=item *
+
+Set it to the hyphen (B<->) to permit the members of the
+system:administrators group and the owner of the group
+to add members.
+
+=item *
+
+Set it to lowercase B<a> to permit members of a group to
+add other members.
+
+=item *
+
+Set it to uppercase B<A> to permit anyone who can access
+the cell's database server machines to add members to a
+group.
+
+=back
+
+=item *
+
+The fifth flag determines who can use the C<pts removeuser>
+command to remove users and machines from membership in a
+group. This flag has no sensible interpretation for user and
+machine entries, but must be set nonetheless, preferably to
+the hyphen.
+
+=over
+
+=item *
+
+Set it to the hyphen (B<->) to permit the members of the
+B<system:administrators> group and the owner of the group
+to remove members.
+
+=item *
+
+Set it to lowercase B<r> to permit members of a group to
+remove other members.
+
+=back
+
+=back
+
+=item B<-groupquota> I<set limit on group creation>
+
+Specifies the number of additional groups a user can create (it
+does not matter how many he or she has created already). Do not
+include this argument for a group or machine entry.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following example changes the privacy flags on the group
+B<operators>, retaining the default values of the first, second and third
+flags, but setting the fourth and fifth flags to enable the group's
+members to add and remove other members.
+
+ pts setfields -nameorid operators -access S-Mar
+
+The following example changes the privacy flags and sets group quota
+on the user entry B<admin>. It retains the default values of the first,
+fourth, and fifth flags, but sets the second and third flags, to
+enable anyone to list the groups that B<admin> owns and belongs to. Users
+authenticated as B<admin> can create an additional 50 groups.
+
+ pts setfields -nameorid admin -access SOM-- -groupquota 50
+
+=head1 PRIVILEGE REQUIRED
+
+To edit group entries or set the privacy flags on any type of entry,
+the issuer must own the entry or belong to the B<system:administrators>
+group. To set group-creation quota on a user entry, the issuer must
+belong to the B<system:administrators> group.
+
+=head1 CAVEATS
+
+Changing a machine or group's group-creation quota is allowed, but not
+recommended. The concept is meaningless for machines and groups,
+because it is impossible to authenticate as a group or machine.
+
+Similarly, some privacy flag settings do not have a sensible
+interpretation. The B<Arguments> section specifies the appropriate
+settings.
+
+=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<pts(1)>,
+L<pts_adduser(1)>,
+L<pts_examine(1)>,
+L<pts_listowned(1)>,
+L<pts_membership(1)>,
+L<pts_removeuser(1)>
+
+=cut
--- /dev/null
+=head1 NAME
+
+pts setmax - Sets the value of the C<max group id> or C<max user id> counter
+
+=head1 SYNOPSIS
+
+pts setmax [B<-group> I<group max>] [B<-user> I<user max>] [B<-cell> I<cell name>]
+[B<-noauth>] [B<-force>] [B<-help>]
+
+pts setm [B<-g> I<group max>] [B<-u> I<user max>] [B<-c> I<cell name>] [B<-n>] [B<-f>] [B<-h>]
+
+=head1 DESCRIPTION
+
+The C<pts setmax> command sets the value of one or both counters that
+track the IDs the Protection Server allocates to new users, machines,
+or groups: the C<max user id> counter for the AFS user IDs (AFS UIDs)
+assigned to users and machines, and the C<max group id> counter for the
+AFS group IDs (AFS GIDs) assigned to groups.
+
+Use the C<pts listmax> command to display the current value of both
+counters.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-group> I<group max>
+
+Sets the C<max group id> counter. Precede the value with a hyphen
+to indicate that it is negative. When an administrator next
+uses the C<pts creategroup> command to create a group entry and
+does not include that command's B<-id> argument, the Protection
+Server assigns the group an AFS GID one less (more negative)
+than this value.
+
+=item B<-user> I<user max>
+
+Sets the C<max user id> counter. When an administrator next uses
+the C<pts createuser> command to create a user or machine entry
+and does not include that command's B<-id> argument, the
+Protection Server assigns the group an AFS UID one greater than
+this value.
+
+=item B<-cell> I<cell name>
+
+Names the cell in which to run the command. For more details,
+see the introductory L<pts(1)> reference page.
+
+=item B<-noauth>
+
+Assigns the unprivileged identity B<anonymous> to the issuer. For
+more details, see the introductory L<pts(1)> reference page.
+
+=item B<-force>
+
+Enables the command to continue executing as far as possible
+when errors or other problems occur, rather than halting
+execution at the first error.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid
+options are ignored.
+
+=back
+
+=head1 EXAMPLES
+
+The following command sets the C<max group id> counter to -500 and the
+C<max user id> counter to 1000.
+
+ pts setmax -group -500 -user 1000
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must belong to the B<system:administrators> group.
+
+=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<pts(1)>,
+L<pts_creategroup(1)>,
+L<pts_createuser(1)>,
+L<pts_listmax(1)>
+
+=cut
projects / packages / o / openafs.git / commitdiff