jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-18 06:50:12 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

pod-man-pages-20051015

Browse Source 
FIXES 19268

add pod generation of man pages
This commit is contained in:
Russ Allbery 2005-10-15 16:00:57 +00:00 committed by Derrick Brashear
parent 3d96fdb182
commit 351a1e3d51
166 changed files with 26487 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Makefile.in
View File

@ -340,6 +340,11 @@ login: cmd comerr kauth rxkad pam sia tsm41 sgistuff aklog
echo Skipping login for ${SYS_NAME} ; \
fi
man-pages:
if test -d "doc/man-pages" ; then \
cd doc/man-pages ${COMPILE_PART2} ; \
fi
#
# _depinstall targets - only build and install headers/sources that are needed by libafs/libuafs
#
@ -566,13 +571,13 @@ jafsadm: libjafsadm
finale: project cmd comerr afsd butc tbutc @ENABLE_KERNEL_MODULE@ libuafs audit kauth log package \
ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \
venus update xstat afsmonitor dauth rxdebug libafsrpc \
libafsauthent shlibafsrpc shlibafsauthent libadmin login
libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages
${COMPILE_PART1} finale ${COMPILE_PART2}
finale_nolibafs: project cmd comerr afsd butc tbutc libuafs audit kauth log package \
ptserver scout bu_utils ubik uss bozo vfsck volser tvolser \
venus update xstat afsmonitor dauth rxdebug libafsrpc \
libafsauthent shlibafsrpc shlibafsauthent libadmin login
libafsauthent shlibafsrpc shlibafsauthent libadmin login man-pages
${COMPILE_PART1} finale ${COMPILE_PART2}
# Use washtool to ensure MakefileProto is current and obj/libafs exists.
@ -807,6 +812,7 @@ distclean: clean
src/wsadmin.src/Makefile \
src/xstat/Makefile \
src/helper-splint.sh
if test -d doc/man-pages ; then rm -f doc/man-pages/Makefile ; fi
pristine: distclean
/bin/rm -f src/config/afsconfig.h.in configure configure-libafs aclocal.m4

7
configure.in
View File

@ -5,8 +5,15 @@ AC_CONFIG_HEADER(src/config/afsconfig.h)
AC_PROG_CC
OPENAFS_CONFIGURE_COMMON
if test -d 'doc/man-pages' ; then
MAN_MAKEFILE=doc/man-pages/Makefile
else
MAN_MAKEFILE=
fi
AC_OUTPUT( \
Makefile \
${MAN_MAKEFILE} \
src/afs/Makefile \
src/afsd/Makefile \
src/afsmonitor/Makefile \

199
doc/man-pages/Makefile.in Normal file
View File

@ -0,0 +1,199 @@
# Makefile for AFS man pages
srcdir=@srcdir@
include @TOP_OBJDIR@/src/config/Makefile.config
MAN1 = \
afs_intro.1 \
fs.1 \
fs_apropos.1 \
fs_checkservers.1 \
fs_checkvolumes.1 \
fs_cleanacl.1 \
fs_copyacl.1 \
fs_diskfree.1 \
fs_examine.1 \
fs_exportafs.1 \
fs_flush.1 \
fs_flushmount.1 \
fs_flushvolume.1 \
fs_getcacheparms.1 \
fs_getcellstatus.1 \
fs_getclientaddrs.1 \
fs_getserverprefs.1 \
fs_help.1 \
fs_listacl.1 \
fs_listcells.1 \
fs_listquota.1 \
fs_lsmount.1 \
fs_messages.1 \
fs_mkmount.1 \
fs_newcell.1 \
fs_quota.1 \
fs_rmmount.1 \
fs_setacl.1 \
fs_setcachesize.1 \
fs_setcell.1 \
fs_setclientaddrs.1 \
fs_setquota.1 \
fs_setserverprefs.1 \
fs_setvol.1 \
fs_storebehind.1 \
fs_sysname.1 \
fs_whereis.1 \
fs_whichcell.1 \
fs_wscell.1 \
klog.1 \
kpasswd.1 \
kpwvalid.1 \
pts.1 \
pts_adduser.1 \
pts_apropos.1 \
pts_chown.1 \
pts_creategroup.1 \
pts_createuser.1 \
pts_delete.1 \
pts_examine.1 \
pts_help.1 \
pts_listentries.1 \
pts_listmax.1 \
pts_listowned.1 \
pts_membership.1 \
pts_removeuser.1 \
pts_rename.1 \
pts_setfields.1 \
pts_setmax.1
MAN8 = \
afsd.8 \
afsmonitor.8 \
backup.8 \
backup_adddump.8 \
backup_addhost.8 \
backup_addvolentry.8 \
backup_addvolset.8 \
backup_apropos.8 \
backup_dbverify.8 \
backup_deldump.8 \
backup_deletedump.8 \
backup_delhost.8 \
backup_delvolentry.8 \
backup_delvolset.8 \
backup_diskrestore.8 \
backup_dump.8 \
backup_dumpinfo.8 \
backup_help.8 \
backup_interactive.8 \
backup_jobs.8 \
backup_kill.8 \
backup_labeltape.8 \
backup_listdumps.8 \
backup_listhosts.8 \
backup_listvolsets.8 \
backup_quit.8 \
backup_readlabel.8 \
backup_restoredb.8 \
backup_savedb.8 \
backup_scantape.8 \
backup_setexp.8 \
backup_status.8 \
backup_volinfo.8 \
backup_volrestore.8 \
backup_volsetrestore.8 \
bos.8 \
bos_addhost.8 \
bos_addkey.8 \
bos_adduser.8 \
bos_apropos.8 \
bos_create.8 \
bos_delete.8 \
bos_exec.8 \
bos_getdate.8 \
bos_getlog.8 \
bos_getrestart.8 \
bos_help.8 \
bos_install.8 \
bos_listhosts.8 \
bos_listkeys.8 \
bos_listusers.8 \
bos_prune.8 \
bos_removehost.8 \
bos_removekey.8 \
bos_removeuser.8 \
bos_restart.8 \
bos_salvage.8 \
bos_setauth.8 \
bos_setcellname.8 \
bos_setrestart.8 \
bos_shutdown.8 \
bos_start.8 \
bos_startup.8 \
bos_status.8 \
bos_stop.8 \
bos_uninstall.8 \
bosserver.8 \
buserver.8 \
butc.8 \
dlog.8 \
dpass.8 \
fileserver.8 \
fms.8 \
fstrace.8 \
fstrace_apropos.8 \
fstrace_clear.8 \
fstrace_dump.8 \
fstrace_help.8 \
fstrace_lslog.8 \
fstrace_lsset.8 \
fstrace_setlog.8 \
fstrace_setset.8 \
kadb_check.8 \
kas.8 \
kas_apropos.8 \
kas_create.8 \
kas_delete.8 \
kas_examine.8 \
kas_forgetticket.8 \
kas_help.8 \
kas_interactive.8 \
kas_list.8 \
kas_listtickets.8 \
kas_noauthentication.8 \
kas_quit.8 \
kas_setfields.8 \
kas_setpassword.8 \
kas_statistics.8 \
kas_stringtokey.8 \
kas_unlock.8 \
kaserver.8 \
kdb.8 \
knfs.8
all: $(MAN1) $(MAN8)
%.1: $(srcdir)/pod/%.pod
pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 $< $@
%.8: $(srcdir)/pod/%.pod
pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 $< $@
clean:
rm -f *.1 *.8
dest: $(MAN1) $(MAN8)
mkdir -p $(DEST)/man/man1 $(DEST)/man/man8
set -e; for M in $(MAN1) ; do \
$(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \
done
set -e; for M in $(MAN8) ; do \
$(INSTALL) -c -m 0644 $$M $(DEST)/man/man8/$$M ; \
done
install: $(MAN1) $(MAN8)
mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man8
set -e; for M in $(MAN1) ; do \
$(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \
done
set -e; for M in $(MAN8) ; do \
$(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \
done

178
doc/man-pages/generate-pod Executable file
View File

@ -0,0 +1,178 @@
#!/usr/bin/perl -w
#
# Parser for files obtained via
# lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt
use strict;
my $DEBUG = 0;
my $RAW = 0;
my %hash;
my %options;
######################################################################
## Input Section:
######################################################################
my $del = $/;
undef $/;
my $text = <STDIN>;
$/ = $del;
my $sections = 'Purpose|Synopsis|Description|Cautions|Options|Output|Examples|Privilege\ Required|Related\ Information|References';
$text =~ s/^.*\[7\]\s*(.+?)\n//xs;
$hash{Command} = $1;
my $Cmd_fam = "backup|bos|fs|kas|pts|uss|vos";
$Cmd_fam .= '|' . (split(" ", $hash{Command}))[0];
while ($text !~ /^\s+$/xs) {
$text =~ s/($sections)(.*?)(\n\s*(?:$sections)\n\s*|$)/$3/xs;
$hash{$1} = $2;
}
$hash{'Related Information'} =~ s/\s*(.+?)\s*___________.*$/$1/xs;
if (! $RAW) {
######################################################################
## Clean-up Section:
######################################################################
# make C<pts adduser> out of pts adduser:
$hash{Description} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Description});
$hash{Options} =~ s/\b($hash{Command})\b/C<$1>/g if ($hash{Options});
# strip leading and trailing whitespace:
my $pattern = '^\s*(.*?)\s*$';
foreach (keys(%hash)) {
$hash{$_} =~ s/$pattern/$1/sxg;
$hash{$_} =~ s/\n\ +/\n/sxg;
$hash{$_} =~ s/((?:$Cmd_fam)\s?\w*)(\s)reference(\s)page/L<$1(1)>$2reference$3page/g;
$hash{$_} =~ s/the(\s)(\w+(?:\s\w+)?)(\s)reference(\s)page/the$1L<$2(1)>$3reference$4page/g;
$hash{$_} =~ s/(\(?\b(?:$Cmd_fam)\)?\s?\w*)(\s)command/C<$1>$2command/g;
$hash{$_} =~ s/the(\s)(\w+)(\s)command/the$1C<$2>$3command/g;
$hash{$_} =~ s/\n\*\ /\n\n=item \*\n\n/g;
$hash{$_} =~ s/\n\+\ /\n\n=item \*\n\n/g;
$hash{$_} =~ s"(\s)((?:/\w+)+)"$1B<$2>"g if($_ ne "Synopsis");
$hash{$_} =~ s/(superuser\s)root/$1B<root>/g;
$hash{$_} =~ s/(unprivileged\s(?:identity|user)\s)anonymous/$1B<anonymous>/g;
$hash{$_} =~ s/system\:administrators/B<system:administrators>/g;
$hash{$_} =~ s/(\s)(\w)(\s)\((\w+)\)(\s)/$1B<$2>$3(B<$4>)$5/g;
}
######################################################################
## POD-ify Section:
######################################################################
# Make B<-group> out of -group:
$hash{Synopsis} =~ s/(\s|^|\[)(-\w+)\b/$1B<$2>/g if ($hash{Synopsis});
$hash{Description} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Description});
$hash{Options} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Options});
$hash{Output} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Output});
$hash{Cautions} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{Cautions});
$hash{'Privilege Required'} =~ s/(\s|^)(-\w+)\b/$1B<$2>/g if ($hash{'Privilege Required'});
$hash{Description} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Description});
$hash{Options} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Options});
$hash{Output} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Output});
$hash{'Privilege Required'} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{'Privilege Required'});
$hash{Cautions} =~ s/(\w*?(?:\.\w+)+)/B<$1>/g if ($hash{Cautions});
$hash{Synopsis} =~ s/<([^>]*?)>\^\+/I<$1> [I<$1> ...]/g if ($hash{Synopsis});
$hash{Synopsis} =~ s/( |\n)<(.*?)>/$1I<$2>/g if ($hash{Synopsis});
$text = $hash{Synopsis};
while ($text && $text =~ /B<-\w+> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?/s) {
$text =~ s/B<(-\w+)> ?(I<.*?>(?: \[I<.*?> \.\.\.\])?)?//s;
if ($2) {
$options{$1} = ' '.$2;
} else {
$options{$1} = "";
}
}
$hash{Options} =~ s/(?:\n|^)B<([^>]*?)>\ \n/\n=item B<$1>$options{$1}\n\n/sxg if ($hash{Options});
$hash{Examples} =~ s/\n\s*%(.*?)(?:\n|$)/\n\nB<\ \ \ $1>\n/sxg if ($hash{Examples});
$hash{'Related Information'} =~ s/\[\d+\](.*?)\s*\n/L<$1(1)>,\n/msxg if ($hash{'Related Information'});
$hash{'Related Information'} =~ s/\[\d+\](.*)\s*/L<$1(1)>/msxg if ($hash{'Related Information'});
$hash{'Related Information'} =~ s/(\w+)\s+(\w+)/$1_$2/msxg if ($hash{'Related Information'});
foreach (keys(%hash)) {
$hash{$_} =~ s/((?:\n\n=item\ \*\n(?:\n.+$)+)+)/\n\n=over$1\n\n=back/mxg;
}
};
######################################################################
## Output Section:
######################################################################
my $file;
($file = $hash{Command} . ".pod") =~ s/\s/_/g;
my $FH;
if ($DEBUG) {
$FH = *STDOUT
} else {
open(FILE, "> $file") || die("Could not open $file\n");
$FH = *FILE;
}
print $FH "=head1 NAME\n\n";
print $FH "$hash{Command} - $hash{Purpose}\n\n";
if (exists $hash{Synopsis}) {
print $FH "=head1 SYNOPSIS\n\n";
print $FH "$hash{Synopsis}\n\n";
}
print $FH "=head1 DESCRIPTION\n\n";
print $FH "$hash{Description}\n\n";
if (exists $hash{Options}) {
print $FH "=head1 OPTIONS\n\n";
print $FH "=over 4\n";
print $FH "$hash{Options}\n\n";
print $FH "=back\n\n";
}
if (exists $hash{Output}) {
print $FH "=head1 OUTPUT\n\n";
print $FH "$hash{Output}\n\n";
}
if (exists $hash{Examples}) {
print $FH "=head1 EXAMPLES\n\n";
print $FH "$hash{Examples}\n\n";
}
if (exists $hash{'Privilege Required'}) {
print $FH "=head1 PRIVILEGE REQUIRED\n\n";
print $FH "$hash{'Privilege Required'}\n\n";
}
if (exists $hash{Cautions}) {
print $FH "=head1 CAVEATS\n\n";
print $FH "$hash{Cautions}\n\n";
}
print $FH "=head1 COPYRIGHT\n\n";
print $FH "IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.\n\n";
print $FH "Converted from html to pod by Alf Wachsmann <alfw\@slac.stanford.edu>, 2003,\n";
print $FH "and Elizabeth Cassell <e_a_c\@mailsnare.net>, 2004,\n";
print $FH "Stanford Linear Accelerator Center, a department of Stanford University.\n\n";
if (exists $hash{'Related Information'}) {
print $FH "=head1 SEE ALSO\n\n";
print $FH "$hash{'Related Information'}\n\n";
print $FH "=cut\n";
}
close(FILE) unless $DEBUG;

570
doc/man-pages/pod/afs_intro.pod Normal file
View File

@ -0,0 +1,570 @@
=head1 NAME
afs_intro - Introduction to AFS commands
=head1 DESCRIPTION
AFS provides many commands that enable users and system administrators
to use and customize its features. Many of the commands belong to the
following categories, called command suites.
=over
=item B<backup>
Interface for configuring and operating the AFS Backup System
=item B<bos>
Interface to the Basic Overseer (BOS) Server for administering
server processes and configuration files
=item B<fs>
Interface for administering access control lists (ACLs), the
Cache Manager, and other miscellaneous file system functions
=item B<fstrace>
Interface for tracing Cache Manager operations when debugging
problems
=item B<kas>
Interface to the Authentication Server for administering
security and authentication information
=item B<pts>
Interface to the Protection Server for administering AFS ID and
group membership information
=item B<uss>
Interface for automated administration of user accounts
=item B<vos>
Interface to the Volume Server and Volume Location (VL) Server
for administering volumes
=back
In addition, there are several commands that do not belong to suites.
=head2 AFS Command Syntax
AFS commands that belong to suites have the following structure:
B<command_suite> B<operation_code> B<-switch> I<value> [I<value> ...] [B<-flag>]
=head2 Command Names
Together, the B<command_suite> and B<operation_code> make up the command
name.
The B<command_suite> specifies the group of related commands to which the
command belongs, and indicates which command interpreter and server
process perform the command. AFS has several command suites, including
B<bos>, B<fs>, B<kas>, B<package>, B<pts>, B<scout>, B<uss> and B<vos>. Some of these suites
have an interactive mode in which the issuer omits the B<command_suite>
portion of the command name.
The B<operation_code> tells the command interpreter and server process
which action to perform. Most command suites include several operation
codes. The IBM AFS Administration Reference describes each operation
code in detail, and the IBM AFS Administration Guide describes how to
use them in the context of performing administrative tasks.
Several AFS commands do not belong to a suite and so their names do
not have a B<command_suite> portion. Their structure is otherwise similar
to the commands in the suites.
=head1 OPTIONS
The term option refers to both arguments and flags, which are
described in the following sections.
=head2 Arguments
One or more arguments can follow the command name. Arguments specify
the entities on which to act while performing the command (for
example, which server machine, server process, or file). To minimize
the potential for error, provide a command's arguments in the order
prescribed in its syntax definition.
Each argument has two parts, which appear in the indicated order:
=over
=item *
The switch specifies the argument's type and is preceded by a
hyphen ( B<-> ). For instance, the switch B<-server> usually indicates
that the argument names a server machine. Switches can often be
omitted, subject to the rules outlined in L</"Conditions for
Omitting Switches">.
=item *
The I<value> names a particular entity of the type specified by the
preceding switch. For example, the proper value for a B<-server>
switch is a server machine name like B<fs3.abc.com>. Unlike switches
(which have a required form), values vary depending on what the
issuer wants to accomplish. Values appear surrounded by angle
brackets (B<E<lt> E<gt>>) in command descriptions and the online help to show
that they are user-supplied variable information.
=back
Some arguments accept multiple values, as indicated by trailing ellipsis
( B<...> ) in the command descriptions and online help. How many of a
command's arguments take multiple values, and their ordering with
respect to other arguments, determine when it is acceptable to omit
switches. See L</"Conditions for Omitting Switches">.
Some commands have optional as well as required arguments; the command
descriptions and online help show optional arguments in square
brackets ([ ]).
=head2 Flags
Some commands have one or more flags, which specify the manner in
which the command interpreter and server process perform the command,
or what kind of output it produces. Flags are preceded by hyphens like
switches, but they take no values. Although the command descriptions
and online help generally list a command's flags after its arguments,
there is no prescribed order for flags. They can appear anywhere on
the command line following the operation code, except in between the
parts of an argument. Flags are always optional.
=head2 An Example Command
The following example illustrates the different parts of a command
that belongs to an AFS command suite.
bos getdate -server fs1.abc.com -file ptserver kaserver
where
=over
=item *
B<bos> is the command suite. The BOS Server executes most of the
commands in this suite.
=item *
B<getdate> is the operation code. It tells the BOS Server on the
specified server machine (in this case B<fs1.abc.com>) to report the
modification dates of binary files in the local B</usr/afs/bin>
directory.
=item *
B<-server> B<fs1.abc.com> is one argument, with B<-server> as the switch
and B<fs1.abc.com> as the value. This argument specifies the server
machine on which BOS Server is to collect and report binary dates.
=item *
B<-file> B<ptserver> B<kaserver> is an argument that takes multiple values.
The switch is B<-file> and the values are B<ptserver> and B<kaserver>. This
argument tells the BOS Server to report the modification dates on
the files B</usr/afs/bin/kaserver> and B</usr/afs/bin/ptserver>.
=back
=head2 Rules for Entering AFS Commands
Enter each AFS command on a single line (press B<E<lt>ReturnE<gt>> only at the
end of the command). Some commands in this document appear broken
across multiple lines, but that is for legibility only.
Use a space to separate each element on a command line from its
neighbors. Spaces rather than commas also separate multiple values of
an argument.
In many cases, the issuer of a command can reduce the amount of typing
necessary by using one or both of the following methods:
=over
=item *
Omitting switches
=item *
Using accepted abbreviations for operation codes, switches (if
they are included at all), and some types of values
=back
The following sections explain the conditions for omitting or
shortening parts of the command line. It is always acceptable to type
a command in full, with all of its switches and no abbreviations.
=head3 Conditions for Omitting Switches
It is always acceptable to type the switch part of an argument, but in
many cases it is not necessary. Specifically, switches can be omitted
if the following conditions are met.
=over
=item *
All of the command's required arguments appear in the order
prescribed by the syntax statement
=item *
No switch is provided for any argument
=item *
There is only one value for each argument (but note the important
exception discussed in the following paragraph)
=back
Omitting switches is possible only because there is a prescribed order
for each command's arguments. When the issuer does not include
switches, the command interpreter relies instead on the order of
arguments; it assumes that the first element after the operation code
is the command's first argument, the next element is the command's
second argument, and so on. The important exception is when a
command's final required argument accepts multiple values. In this
case, the command interpreter assumes that the issuer has correctly
provided one value for each argument up through the final one, so any
additional values at the end belong to the final argument.
The following list describes the rules for omitting switches from the
opposite perspective: an argument's switch must be provided when any
of the following conditions apply.
=over
=item *
The command's arguments do not appear in the prescribed order
=item *
An optional argument is omitted but a subsequent optional argument
is provided
=item *
A switch is provided for a preceding argument
=item *
More than one value is supplied for a preceding argument (which
must take multiple values, of course); without a switch on the
current argument, the command interpreter assumes that the current
argument is another value for the preceding argument
=back
=head3 An Example of Omitting Switches
Consider again the example command from L</"An Example Command">.
bos getdate -server fs1.abc.com -file ptserver kaserver
This command has two required arguments: the server machine name
(identified by the B<-server> switch) and binary file name (identified by
the B<-file> switch). The second argument accepts multiple values. By
complying with all three conditions, the issuer can omit the switches:
bos getdate fs1.abc.com ptserver kaserver
Because there are no switches, the C<bos> command interpreter relies on
the order of arguments. It assumes that the first element following
the operation code, B<fs1.abc.com>, is the server machine name, and that
the next argument, B<ptserver>, is a binary file name. Then, because the
command's second (and last) argument accepts multiple values, the
command interpreter correctly interprets B<kaserver> as an additional
value for it.
On the other hand, the following is not acceptable because it violates
the first two conditions in L</"Conditions for Omitting Switches">: even
though there is only one value per argument, the arguments do not
appear in the prescribed order, and a switch is provided for one
argument but not the other.
bos getdate ptserver -server fs1.abc.com
=head2 Rules for Using Abbreviations and Aliases
This section explains how to abbreviate operation codes, option names,
server machine names, partition names, and cell names. It is not
possible to abbreviate other types of values.
=head3 Abbreviating Operation Codes
It is acceptable to abbreviate an operation code to the shortest form
that still distinguishes it from the other operation codes in its suite.
For example, it is acceptable to shorten bos install to bos i because
there are no other operation codes in the bos command suite that begin
with the letter i. In contrast, there are several bos operation codes
that start with the letter s, so the abbreviations must be longer to
remain unambiguous:
C<bos sa> for C<bos salvage>
C<bos seta> for C<bos setauth>
C<bos setc> for C<bos setcellname>
C<bos setr> for C<bos setrestart>
C<bos sh> for C<bos shutdown>
C<bos start> for C<bos start>
C<bos startu> for C<bos startup>
C<bos stat> for C<bos status>
C<bos sto> for C<bos stop>
In addition to abbreviations, some operation codes have an I<alias>, a
short form that is not derived by abbreviating the operation code to
its shortest unambiguous form. For example, the alias for the C<fs
setacl> command is C<fs sa>, whereas the shortest unambiguous abbreviation
is C<fs seta>.
There are two usual reasons an operation code has an alias:
=over
=item *
Because the command is frequently issued, it is convenient to have
a form shorter than the one derived by abbreviating. The C<fs setacl>
command is an example.
=item *
Because the command's name has changed, but users of previous
versions of AFS know the former name. For example, C<bos listhosts>
has the alias C<bos getcell>, its former name. It is acceptable to
abbreviate aliases to their shortest unambiguous form (for
example, C<bos getcell> to C<bos getc>).
=back
Even if an operation code has an alias, it is still acceptable to use
the shortest unambiguous form. Thus, the C<fs setacl> command has three
acceptable forms: C<fs setacl> (the full form), C<fs seta> (the shortest
abbreviation), and C<fs sa> (the alias).
=head3 Abbreviating Switches and Flags
It is acceptable to shorten a switch or flag to the shortest form that
distinguishes it from the other switches and flags for its operation
code. It is often possible to omit switches entirely, subject to the
conditions listed in L</"Conditions for Omitting Switches">.
=head3 Abbreviating Server Machine Names
AFS server machines must have fully-qualified Internet-style host
names (for example, B<fs1.abc.com>), but it is not always necessary to
type the full name on the command line. AFS commands accept
unambiguous shortened forms, but depend on the cell's name service
(such as the Domain Name Service) or a local host table to resolve a
shortened name to the fully-qualified equivalent when the command is
issued.
Most commands also accept the dotted decimal form of the machine's IP
address as an identifier.
=head3 Abbreviating Partition Names
Partitions that house AFS volumes must have names of the form
B</vicep>I<x> or B</vicep>I<xx>, where the variable final portion is one or
two lowercase letters. By convention, the first server partition
created on a file server machine is called B</vicepa>, the second
B</vicepb>, and so on. The IBM AFS Quick Beginnings explains how to
configure and name a file server machine's partitions in
preparation for storing AFS volumes on them.
When issuing AFS commands, you can abbreviate a partition name using
any of the following forms:
/vicepa = vicepa = a = 0
/vicepb = vicepb = b = 1
After B</vicepz> (for which the index is 25) comes
/vicepaa = vicepaa = aa = 26
/vicepab = vicepab = ab = 27
and so on through
/vicepiv = vicepiv = iv = 255
=head3 Abbreviating Cell Names
A cell's full name usually matches its Internet domain name (such
as B<stateu.edu> for the State University or B<abc.com> for ABC Corporation).
Some AFS commands accept unambiguous shortened forms, usually with
respect to the local B</usr/vice/etc/CellServDB> file but sometimes
depending on the ability of the local name service to resolve the
corresponding domain name.
=head2 Displaying Online Help for AFS Commands
To display online help for AFS commands that belong to suites, use the
C<help> and C<apropos> operation codes. A B<-help> flag is also available on
almost every AFS command.
The online help entry for a command consists of two or three lines:
=over
=item *
The first line names the command and briefly describes what it
does
=item *
If the command has aliases, they appear on the next line
=item *
The final line, which begins with the string C<Usage:>, lists the
command's options in the prescribed order; online help entries use
the same typographical symbols (brackets and so on) as this
documentation.
=back
If no operation code is specified, the B<help> operation code displays
the first line (short description) for every operation code in the
suite:
command_suite help
If the issuer specifies one or more operation codes, the help
operation code displays each command's complete online entry (short
description, alias if any, and syntax):
command_suite help operation_code [operation_code ...]
The B<-help> flag displays a command's syntax but not the short
description or alias:
command_name -help
The B<apropos> operation code displays the short description of any
command in a suite whose operation code or short description includes
the specified keyword:
command_suite apropos "help string"
The following example command displays the complete online help entry
for the C<fs setacl> command:
fs help setacl
fs setacl: set access control list
aliases: sa
Usage: fs setacl B<-dir> <directory>+ B<-acl> <access list entries>+
[-clear] [-negative] [-id] [-if] [-help]
To see only the syntax statement, use the B<-help> flag:
fs setacl B<-help>
Usage: fs setacl B<-dir> <directory>+ B<-acl> <access list entries>+
[-clear] [-negative] [-id] [-if] [-help]
In the following example, a user wants to display the quota for her
home volume. She knows that the relevant command belongs to the C<fs>
suite, but cannot remember the operation code. She uses C<quota> as the
keyword:
fs apropos quota
listquota: list volume quota
quota: show volume quota usage
setquota: set volume quota
The following illustrates the error message that results if no command
name or short description contains the keyword:
fs apropos "list quota"
Sorry, no commands found
=head1 PRIVILEGE REQUIRED
Many AFS commands require one or more types of administrative
privilege. See the reference page for each command.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<afsd(1)>,
L<afsmonitor(1)>,
L<backup(1)>,
L<bos(1)>,
L<bosserver(1)>,
L<buserver(1)>,
L<butc(1)>,
L<dlog(1)>,
L<dpass(1)>,
L<fileserver(1)>,
L<fms(1)>,
L<fs(1)>,
L<fstrace(1)>,
L<ftpd_AFS_version(1)>,
L<inetd_AFS_version(1)>,
L<kadb_check(1)>,
L<kas(1)>,
L<kaserver(1)>,
L<kdb(1)>,
L<klog(1)>,
L<knfs(1)>,
L<kpasswd(1)>,
L<kpwvalid(1)>,
L<package(1)>,
L<package(1)>,
L<package_test(1)>,
L<pagsh(1)>,
L<prdb_check(1)>,
L<pts(1)>,
L<ptserver(1)>,
L<rcp_AFS_version(1)>,
L<rsh_AFS_version(1)>,
L<runntp(1)>,
L<rxdebug(1)>,
L<salvager(1)>,
L<scout(1)>,
L<sys(1)>,
L<tokens(1)>,
L<translate_et(1)>,
L<unlog(1)>,
L<up(1)>,
L<upclient(1)>,
L<upserver(1)>,
L<uss(1)>,
L<vldb_check(1)>,
L<vlserver(1)>,
L<volinfo(1)>,
L<volserver(1)>,
L<vos(1)>,
L<xfs_size_check(1)>,
L<xstat_cm_test(1)>,
L<xstat_fs_test(1)>
=cut

597
doc/man-pages/pod/afsd.pod Normal file
View File

@ -0,0 +1,597 @@
=head1 NAME
afsd - Initializes the Cache Manager and starts related daemons.
=head1 SYNOPSIS
afsd [B<-blocks> I<1024 byte blocks in cache>]
[B<-files> I<files in cache>]
[B<-rootvol> I<name of AFS root volume>]
[B<-stat> I<number of stat entries>]
[B<-memcache>] [B<-cachedir> I<cache directory>]
[B<-mountdir> I<mount location>]
[B<-daemons> I<number of daemons to use>]
[B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [B<-debug>]
[B<-chunksize> I<log(2) of chunk size>]
[B<-dcache> I<number of dcache entries>]
[B<-volumes> I<number of volume entries>]
[B<-biods> I<number of bkg I/O daemons (aix vm)>]
[B<-prealloc> I<number of 'small' preallocated blocks>]
[B<-confdir> I<configuration directory>]
[B<-logfile> I<Place to keep the CM log>]
[B<-waitclose>] [B<-shutdown>] [B<-enable_peer_stats>]
[B<-enable_process_stats>] [B<-help>]
This command does not use the syntax conventions of the AFS command
suites. Provide the command name and all option names in full.
=head1 DESCRIPTION
The C<afsd> command initializes the Cache Manager on an AFS client
machine by transferring AFS-related configuration information into
kernel memory and starting several daemons. More specifically, the
C<afsd> command performs the following actions:
=over
=item *
Sets a field in kernel memory that defines the machine's cell
membership. Some Cache Manager-internal operations and system
calls consult this field to learn which cell to execute in. (The
AFS command interpreters refer to the B</usr/vice/etc/ThisCell> file
instead.) This information is transferred into the kernel from the
B</usr/vice/etc/ThisCell> file and cannot be changed until the C<afsd>
program runs again.
=item *
Places in kernel memory the names and Internet addresses of the
database server machines in the local cell and (optionally)
foreign cells. The appearance of a cell's database server machines
in this list enables the Cache Manager to contact them and to
access files in the cell. Omission of a cell from this list, or
incorrect information about its database server machines, prevents
the Cache Manager from accessing files in it.
The list of database server machines is transferred into the
kernel from the B</usr/vice/etc/CellServDB> file. After
initialization, use the C<fs newcell> command to change the
kernel-resident list without having to reboot.
=item *
Mounts the root of the AFS filespace on a directory on the
machine's local disk, according to either the first field in the
B</usr/vice/etc/cacheinfo> file (the default) or the C<afsd> command's
B<-mountdir> argument. The conventional value is B</afs>.
=item *
Determines which volume to mount at the root of the AFS file tree.
The default is the volume B<root.afs>; use the B<-rootvol> argument to
override it. Although the base (read/write) form of the volume
name is the appropriate value, the Cache Manager has a bias for
accessing the read-only version of the volume (by convention,
B<root.afs.readonly>) if it is available.
=item *
Configures the cache on disk (the default) or in machine memory if
the B<-memcache> argument is provided. In the latter case, the C<afsd>
program allocates space in machine memory for caching, and the
Cache Manager uses no disk space for caching even if the machine
has a disk.
=item *
Defines the name of the local disk directory devoted to caching,
when the B<-memcache> argument is not used. If necessary, the C<afsd>
program creates the directory (its parent directory must already
exist). It does not remove the directory that formerly served this
function, if one exists.
The second field in the B</usr/vice/etc/cacheinfo> file is the source
for this name, and the standard value is the B</usr/vice/cache>
directory. Use the B<-cachedir> argument to override the value in the
B<cacheinfo> file.
=item *
Sets the size of the cache. The default source for the value is
the third field in the B</usr/vice/etc/cacheinfo> file, which
specifies a number of kilobytes.
For a memory cache, the following arguments to the C<afsd> command
override the value in the B<cacheinfo> file:
=over
=item *
The B<-blocks> argument, to specify a different number of
kilobyte blocks.
=item *
The B<-dcache> and B<-chunksize> arguments together, to set both
the number of dcache entries and the chunk size (see below
for definition of these parameters). In this case, the C<afsd>
program derives cache size by multiplying the two values.
Using this combination is not recommended, as it requires the
issuer to perform the calculation beforehand to determine the
resulting cache size.
=item *
The B<-dcache> argument by itself. In this case, the C<afsd>
program derives cache size by multiplying the value specified
by the B<-dcache> argument by the default memory cache chunk
size of eight kilobytes. Using this argument is not
recommended, as it requires the issuer to perform the
calculation beforehand to determine the resulting cache size.
=back
For satisfactory memory cache performance, the specified value
must leave enough memory free to accommodate all other processes
and commands that can run on the machine. If the value exceeds the
amount of memory available, the C<afsd> program exits without
initializing the Cache Manager and produces the following message
on the standard output stream:
afsd: memCache allocation failure at I<number> KB
where I<number> is how many kilobytes were allocated just before the
failure.
For a disk cache, use the B<-blocks> argument to the C<afsd> command to
override the value in the B<cacheinfo> file. The value specified in
either way sets an absolute upper limit on cache size; values
provided for other arguments (such as B<-dcache> and B<-chunksize>)
never result in a larger cache. The C<afsd> program rejects any
setting larger than 95% of the partition size, and exits after
generating an error message on the standard output stream, because
the cache implementation itself requires a small amount of disk
space and overfilling the partition can cause the client machine
to panic.
To change the size of a disk cache after initialization without
rebooting, use the C<fs setcachesize> command; the setting persists
until the C<afsd> command runs again or the C<fs setcachesize> command
is reissued. The C<fs setcachesize> command does not work for memory
caches.
=item *
Sets the size of each cache I<chunk>, and by implication the amount
of data that the Cache Manager requests at a time from the File
Server (how much data per fetch RPC, since AFS uses partial file
transfer).
For a disk cache, a chunk is a B<V>I<n> file and this parameter sets the
maximum size to which each one can expand; the default is 64 KB.
For a memory cache, each chunk is a collection of contiguous
memory blocks; the default is size is 8 KB.
To override the default chunk size for either type of cache, use
the B<-chunksize> argument to provide an integer to be used as an
exponent of two; see the B<Options> section for details. For a memory
cache, if total cache size divided by chunk size leaves a
remainder, the C<afsd> program rounds down the number of dcache
entries, resulting in a slightly smaller cache.
=item *
Sets the number of chunks in the cache. For a memory cache, the
number of chunks is equal to the cache size divided by the chunk
size. For a disk cache, the number of chunks (B<V>I<n> files) is set to
the largest of the following unless the B<-files> argument is used to
set the value explicitly:
=over
=item *
100
=item *
1.5 times the result of dividing cache size by chunk size
(I<cachesize>/I<chunksize> * 1.5)
=item *
The result of dividing cachesize by 10 KB (I<cachesize>/10240)
=back
=item *
Sets the number of I<dcache entries> allocated in machine memory for
storing information about the chunks in the cache.
For a disk cache, the B</usr/vice/cache/CacheItems> file contains one
entry for each B<V>I<n> file. By default, one half the number of these
entries (but not more that 2,000) are duplicated as dcache entries
in machine memory for quicker access.
For a memory cache, there is no B<CacheItems> file so all information
about cache chunks must be in memory as dcache entries. Thus,
there is no default number of dcache entries for a memory cache;
instead, the C<afsd> program derives it by dividing the cache size by
the chunk size.
To set the number of dcache entries, use the B<-dcache> argument; the
specified value can exceed the default limit of 2,000. Using this
argument is not recommended for either type of cache. Increasing
the number of dcache entries for a disk cache sometimes improves
performance (because more entries are retrieved from memory rather
than from disk), but only marginally. Using this argument for a
memory cache requires the issuer to calculate the cache size by
multiplying this value by the chunk size.
=item *
Sets the number of I<stat> entries available in machine memory for
caching status information about cached AFS files. The default is
300; use the B<-stat> argument to override the default.
=item *
Randomly selects a file server machine in the local cell as the
source for the correct time. Every five minutes thereafter, the
local clock is adjusted (if necessary) to match the file server
machine's clock.
Use the B<-nosettime> flag to prevent the C<afsd> command from selecting
a time standard. This is recommended only on file server machines
that are also acting as clients. File server machines maintain the
correct time using the Network Time Protocol Daemon instead.
=back
In addition to setting cache configuration parameters, the C<afsd>
program starts the following daemons. (On most system types, these
daemons appear as nameless entries in the output of the UNIX C<ps>
command.)
=over
=item *
One I<callback> daemon, which handles callbacks. It also responds to
the File Server's periodic probes, which check that the client
machine is still alive.
=item *
One I<maintenance> daemon, which performs the following tasks:
=over
=item *
Garbage collects obsolete data (for example, expired tokens)
from kernel memory
=item *
Synchronizes files
=item *
Refreshes information from read-only volumes once per hour
=item *
Does delayed writes for NFS clients if the machine is running
the NFS/AFS Translator
=back
=item *
One I<cache-truncation> daemon, which flushes the cache when free
space is required, by writing cached data and status information
to the File Server.
=item *
One I<server connection> daemon, which sends a probe to the File
Server every few minutes to check that it is still accessible. It
also synchronizes the machine's clock with the clock on a
randomly-chosen file server machine, unless the B<-nosettime> flag is
used. There is always one server connection daemon.
=item *
One or more I<background> daemons that improve performance by
pre-fetching files and performing background (delayed) writes of
saved data into AFS.
The default number of background daemons is two, enough to service
at least five simultaneous users of the machine. To increase the
number, use the B<-daemons> argument. A value greater than six is not
generally necessary.
=item *
On some system types, one I<Rx listener> daemon, which listens for
incoming RPCs.
=item *
On some system types, one I<Rx event> daemon, which reviews the Rx
system's queue of tasks and performs them as appropriate. Most
items in the queue are retransmissions of failed packets.
=item *
On machines that run AIX with virtual memory (VM) integration, one
or more I<VM> daemons (sometimes called I<I/O> daemons, which transfer
data between disk and machine memory. The number of them depends
on the setting of the B<-biods> and B<-daemons> arguments:
=over
=item *
If the B<-biods> argument is used, it sets the number of VM
daemons.
=item *
If only the B<-daemons> argument is used, the number of VM
daemons is twice the number of background daemons.
=item *
If neither argument is used, there are five VM daemons.
=back
=back
=head1 OPTIONS
=over 4
=item B<-blocks>
Specifies the number of kilobyte blocks to be made available
for caching in the machine's cache directory (for a disk cache)
or memory (for a memory cache), overriding the default defined
in the third field of the B</usr/vice/etc/cacheinfo> file. For a
disk cache, the value cannot exceed 95% of the space available
in the cache partition. If using a memory cache, do not combine
this argument with the B<-dcache> argument, since doing so can
possibly result in a chunk size that is not an exponent of 2.
=item B<-files>
Specifies the number of B<V>I<n> files to create in the cache
directory for a disk cache, overriding the default that is
calculated as described in the B<Description> section. Each B<V>I<n>
file accommodates a chunk of data, and can grow to a maximum
size of 64 KB by default. Do not combine this argument with the
B<-memcache> argument.
=item B<-rootvol>
Names the read/write volume corresponding to the root directory
for the AFS file tree (which is usually the B</afs> directory).
This value overrides the default of the B<root.afs> volume.
=item B<-stat>
Specifies the number of entries to allocate in the machine's
memory for recording status information about the AFS files in
the cache. This value overrides the default of 300.
=item B<-memcache>
Initializes a memory cache rather than a disk cache. Do not
combine this flag with the B<-files> argument.
=item B<-cachedir>
Names the local disk directory to be used as the cache. This
value overrides the default defined in the second field of the
B</usr/vice/etc/cacheinfo> file.
=item B<-mountdir>
Names the local disk directory on which to mount the root of
the AFS filespace. This value overrides the default defined in
the first field of the B</usr/vice/etc/cacheinfo> file. If a value
other than the B</afs> directory is used, the machine cannot
access the filespace of cells that do use that value.
=item B<-daemons>
Specifies the number of background daemons to run on the
machine. These daemons improve efficiency by doing prefetching
and background writing of saved data. This value overrides the
default of 2, which is adequate for a machine serving up to
five users. Values greater than B<6> are not generally more
effective than B<6>.
B<Note>: On AIX machines with integrated virtual memory (VM), the
number of VM daemons is set to twice the value of this
argument, if it is provided and the B<-biods> argument is not. If
both arguments are omitted, there are five VM daemons.
=item B<-nosettime>
Prevents the Cache Manager from synchronizing its clock with
the clock on a server machine selected at random, by checking
the time on the server machine every five minutes. Use this
flag only on a machine that is already using another time
synchronization protocol (for example, a server machine that is
running the B<runntp> process).
=item B<-verbose>
Generates a detailed trace of the C<afsd> program's actions on the
standard output stream.
=item B<-rmtsys>
Initializes an additional daemon to execute AFS-specific system
calls on behalf of NFS client machines. Use this flag only if
the machine is an NFS/AFS translator machine serving users of
NFS client machines who execute AFS commands.
=item B<-debug>
Generates a highly detailed trace of the C<afsd> program's actions
on the standard output stream. The information is useful mostly
for debugging purposes.
=item B<-chunksize>
Sets the size of each cache chunk. The integer provided, which
must be from the range B<0> to B<30>, is used as an exponent on the
number 2. It overrides the default of 16 for a disk cache (2^16
is 64 KB) and 13 for a memory cache (2^13 is 8 KB). A value of
B<0> or less, or greater than B<30>, sets chunk size to the
appropriate default. Values less than B<10> (which sets chunk size
to a 1 KB) are not recommended. Combining this argument with
the B<-dcache> argument is not recommended because it requires
that the issuer calculate the cache size that results.
=item B<-dcache>
Sets the number of dcache entries in memory, which are used to
store information about cache chunks. For a disk cache, this
overrides the default, which is 50% of the number of B<V>I<n> files
(cache chunks). For a memory cache, this argument effectively
sets the number of cache chunks, but its use is not
recommended, because it requires the issuer to calculate the
resulting total cache size (derived by multiplying this value
by the chunk size). Do not combine this argument with the
B<-blocks> argument, since doing so can possibly result in a chunk
size that is not an exponent of 2.
=item B<-volumes>
Specifies the number of memory structures to allocate for
storing volume location information. The default value is 50.
=item B<-biods>
Sets the number of VM daemons dedicated to performing I/O
operations on a machine running a version of AIX with virtual
memory (VM) integration. If both this argument and the B<-daemons>
argument are omitted, the default is five. If this argument is
omitted but the B<-daemons> argument is provided, the number of VM
daemons is set to twice the value of the B<-daemons> argument.
B<Note>: Provide this argument only on a machine that runs AIX with VM
integration.
=item B<-prealloc>
Specifies the number of pieces of memory to preallocate for the
Cache Manager's internal use. The default initial value is 400,
but the Cache Manager dynamically allocates more memory as it
needs it.
=item B<-confdir>
Names a directory other than the B</usr/vice/etc> directory from
which to fetch the B<cacheinfo>, B<ThisCell>, and B<CellServDB>
configuration files.
=item B<-logfile>
Is obsolete and has no real effect. It specifies an alternate
file in which to record a type of trace that the Cache Manager
no longer generates; the default value is B</usr/vice/etc/AFSLog>.
=item B<-waitclose>
Has no effect on the operation of the Cache Manager. The
behavior it affected in previous versions of the Cache Manager,
to perform synchronous writes to the File Server, is now the
default behavior. To perform asynchronous writes in certain
cases, use the C<fs storebehind> command.
=item B<-shutdown>
Shuts down the Cache Manager, but not in the most effective
possible way. Do not use this flag.
=item B<-enable_peer_stats>
Activates the collection of Rx statistics and allocates memory
for their storage. For each connection with a specific UDP port
on another machine, a separate record is kept for each type of
RPC (FetchFile, GetStatus, and so on) sent or received. To
display or otherwise access the records, use the Rx Monitoring
API.
=item B<-enable_process_stats>
Activates the collection of Rx statistics and allocates memory
for their storage. A separate record is kept for each type of
RPC (FetchFile, GetStatus, and so on) sent or received,
aggregated over all connections to other machines. To display
or otherwise access the records, use the Rx Monitoring API.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The C<afsd> command is normally included in the machine's AFS
initialization file, rather than typed at the command shell prompt.
For most disk caches, the appropriate form is
/usr/vice/etc/afsd
The following command is appropriate when enabling a machine to act as
an NFS/AFS Translator machine serving more than five users.
/usr/vice/etc/afsd -daemons 4 -rmtsys
The following command initializes a memory cache and sets chunk size
to 16 KB (2^14).
/usr/vice/etc/afsd -memcache -chunksize 14
=head1 PRIVILEGE REQUIRED
The issuer must be logged in as the local superuser B<root>.
=head1 CAVEATS
Do not use the B<-shutdown> parameter. It does not shutdown the Cache
Manager effectively. Instead, halt Cache Manager activity by using the
standard UNIX C<umount> command to unmount the AFS root directory (by
convention, B</afs>). The machine must then be rebooted to reinitialize
the Cache Manager.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<CacheItems(1)>,
L<CellServDB_client_version(1)>,
L<ThisCell_client_version(1)>,
L<Vn(1)>,
L<cacheinfo(1)>
=cut

432
doc/man-pages/pod/afsmonitor.pod Normal file
View File

@ -0,0 +1,432 @@
=head1 NAME
afsmonitor - Monitors File Servers and Cache Managers
=head1 SYNOPSIS
afsmonitor [B<initcmd>] [B<-config> I<configuration file>]
[B<-frequency> I<poll frequency, in seconds>]
[B<-output> I<storage file name>] [B<-detailed>]
[B<-debug> I<turn debugging output on to the named file>]
[B<-fshosts> I<list of file servers to monitor> ...]
[B<-cmhosts> I<list of cache managers to monitor> ...]
[B<-buffers> I<number of buffer slots>] [B<-help>]
afsmonitor [B<i>] [B<-co> I<configuration file>]
[B<-fr> I<poll frequency, in seconds>]
[B<-o> I<storage file name>] [B<-det>]
[B<-deb> I<turn debugging output on to the named file>]
[B<-fs> I<list of file servers to monitor> ...]
[B<-cm> I<list of cache managers to monitor> ...]
[B<-b> I<number of buffer slots>] [B<-h>]
=head1 DESCRIPTION
The C<afsmonitor> command initializes a program that gathers and displays
statistics about specified File Server and Cache Manager operations.
It allows the issuer to monitor, from a single location, a wide range
of File Server and Cache Manager operations on any number of machines
in both local and foreign cells.
There are 271 available File Server statistics and 570 available Cache
Manager statistics, listed in the appendix about C<afsmonitor> statistics
in the IBM AFS Administration Guide. By default, the command displays
all of the relevant statistics for the file server machines named by
the B<-fshosts> argument and the client machines named by the B<-cmhosts>
argument. To limit the display to only the statistics of interest,
list them in the configuration file specified by the B<-config> argument.
In addition, use the configuration file for the following purposes:
=over
=item *
To set threshold values for any monitored statistic. When the
value of a statistic exceeds the threshold, the C<afsmonitor> command
displays it in reverse video. There are no default threshold
values.
=item *
To invoke a program or script automatically when a statistic
exceeds its threshold. The AFS distribution does not include any
such scripts.
=item *
To list the file server and client machines to monitor, instead of
using the B<-fshosts> and B<-cmhosts> arguments.
=back
For a description of the configuration file, see the B<afsmonitor
Configuration File> reference page
=head1 OPTIONS
=over 4
=item B<initcmd>
Accommodates the command's use of the AFS command parser, and
is optional.
=item B<-config> I<configuration file>
Names the configuration file which lists the machines to
monitor, statistics to display, and threshold values, if any. A
partial pathname is interpreted relative to the current working
directory. Provide this argument if not providing the B<-fshosts>
argument, B<-cmhosts> argument, or neither. For instructions on
creating this file, see the preceding B<Description> section, and
the section on the C<afsmonitor> program in the IBM AFS
Administration Guide.
=item B<-frequency> I<poll frequency, in seconds>
Specifies in seconds how often the C<afsmonitor> program probes
the File Servers and Cache Managers. Valid values range from B<1>
to B<86400> (which is 24 hours); the default value is B<60>. This
frequency applies to both File Servers and Cache Managers, but
the C<afsmonitor> program initiates the two types of probes, and
processes their results, separately. The actual interval
between probes to a host is the probe frequency plus the time
required for all hosts to respond.
=item B<-output> I<storage file name>
Names the file to which the C<afsmonitor> program writes all of
the statistics that it collects. By default, no output file is
created. See the section on the C<afsmonitor> command in the IBM
AFS Administration Guide for information on this file.
=item B<-detailed>
Formats the information in the output file named by B<-output>
argument in a maximally readable format. Provide the B<-output>
argument along with this one.
=item B<-fshosts> I<list of file servers to monitor> ...
Names one or more machines from which to gather File Server
statistics. For each machine, provide either a fully qualified
host name, or an unambiguous abbreviation (the ability to
resolve an abbreviation depends on the state of the cell's name
service at the time the command is issued). This argument can
be combined with the B<-cmhosts> argument, but not with the
B<-config> argument.
=item B<-cmhosts> I<list of cache managers to monitor> ...
Names one or more machines from which to gather Cache Manager
statistics. For each machine, provide either a fully qualified
host name, or an unambiguous abbreviation (the ability to
resolve an abbreviation depends on the state of the cell's name
service at the time the command is issued). This argument can
be combined with the B<-fshosts> argument, but not with the
B<-config> argument.
=item B<-buffers> I<number of buffer slots>
Is nonoperational and provided to accommodate potential future
enhancements to the program.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The C<afsmonitor> program displays its data on three screens:
=over
=item *
C<System Overview>: This screen appears automatically when the
C<afsmonitor> program initializes. It summarizes separately for File
Servers and Cache Managers the number of machines being monitored
and how many of them have I<alerts> (statistics that have exceeded
their thresholds). It then lists the hostname and number of alerts
for each machine being monitored, indicating if appropriate that a
process failed to respond to the last probe.
=item *
C<File Server>: This screen displays File Server statistics for each
file server machine being monitored. It highlights statistics that
have exceeded their thresholds, and identifies machines that
failed to respond to the last probe.
=item *
C<Cache Managers>: This screen displays Cache Manager statistics for
each client machine being monitored. It highlights statistics that
have exceeded their thresholds, and identifies machines that
failed to respond to the last probe.
=back
Fields at the corners of every screen display the following
information:
=over
=item *
In the top left corner, the program name and version number.
=item *
In the top right corner, the screen name, current and total page
numbers, and current and total column numbers. The page number
(for example, p. 1 of 3) indicates the index of the current page
and the total number of (vertical) pages over which data is
displayed. The column number (for example, c. 1 of 235) indicates
the index of the current leftmost column and the total number of
columns in which data appears. (The symbol >>> indicates that
there is additional data to the right; the symbol <<< indicates
that there is additional data to the left.)
=item *
In the bottom left corner, a list of the available commands. Enter
the first letter in the command name to run that command. Only the
currently possible options appear; for example, if there is only
one page of data, the C<next> and C<prev> commands, which scroll the
screen up and down respectively, do not appear. For descriptions
of the commands, see the following section about navigating the
display screens.
=item *
In the bottom right corner, the C<probes> field reports how many
times the program has probed File Servers (C<fs>), Cache Managers
(C<cm>), or both. The counts for File Servers and Cache Managers can
differ. The C<freq> field reports how often the program sends probes.
=back
=head1 Navigating the afsmonitor Display Screens
As noted, the lower left hand corner of every display screen displays
the names of the commands currently available for moving to alternate
screens, which can either be a different type or display more
statistics or machines of the current type. To execute a command,
press the lowercase version of the first letter in its name. Some
commands also have an uppercase version that has a somewhat different
effect, as indicated in the following list.
=over
=item B<cm>
Switches to the C<Cache Managers> screen. Available only on the
C<System Overview> and C<File Servers> screens.
=item B<fs>
Switches to the C<File Servers> screen. Available only on the
C<System Overview> and the C<Cache Managers> screens.
=item B<left>
Scrolls horizontally to the left, to access the data columns
situated to the left of the current set. Available when the <<<
symbol appears at the top left of the screen. Press uppercase B<L>
to scroll horizontally all the way to the left (to display the
first set of data columns).
=item B<next>
Scrolls down vertically to the next page of machine names.
Available when there are two or more pages of machines and the
final page is not currently displayed. Press uppercase B<N> to
scroll to the final page.
=item B<oview>
Switches to the C<System Overview> screen. Available only on the
C<Cache Managers> and C<File Servers> screens.
=item B<prev>
Scrolls up vertically to the previous page of machine names.
Available when there are two or more pages of machines and the
first page is not currently displayed. Press uppercase B<P> to
scroll to the first page.
=item B<right>
Scrolls horizontally to the right, to access the data columns
situated to the right of the current set. This command is
available when the >>> symbol appears at the upper right of the
screen. Press uppercase B<R> to scroll horizontally all the way to
the right (to display the final set of data columns).
=back
=head1 The System Overview Screen
The C<System Overview> screen appears automatically as the C<afsmonitor>
program initializes. This screen displays the status of as many File
Server and Cache Manager processes as can fit in the current window;
scroll down to access additional information.
The information on this screen is split into File Server information
on the left and Cache Manager information on the right. The header for
each grouping reports two pieces of information:
=over
=item *
The number of machines on which the program is monitoring the
indicated process
=item *
The number of alerts and the number of machines affected by them
(an I<alert> means that a statistic has exceeded its threshold or a
process failed to respond to the last probe)
=back
A list of the machines being monitored follows. If there are any
alerts on a machine, the number of them appears in square brackets to
the left of the hostname. If a process failed to respond to the last
probe, the letters C<PF> (probe failure) appear in square brackets to the
left of the hostname.
=head1 The File Servers Screen
The C<File Servers> screen displays the values collected at the most
recent probe for File Server statistics.
A summary line at the top of the screen (just below the standard
program version and screen title blocks) specifies the number of
monitored File Servers, the number of alerts, and the number of
machines affected by the alerts.
The first column always displays the hostnames of the machines running
the monitored File Servers.
To the right of the hostname column appear as many columns of
statistics as can fit within the current width of the display screen
or window; each column requires space for 10 characters. The name of
the statistic appears at the top of each column. If the File Server on
a machine did not respond to the most recent probe, a pair of dashes
(--) appears in each column. If a value exceeds its configured
threshold, it is highlighted in reverse video. If a value is too large
to fit into the allotted column width, it overflows into the next row
in the same column.
=head1 The Cache Managers Screen
The Cache Managers screen displays the values collected at the most
recent probe for Cache Manager statistics.
A summary line at the top of the screen (just below the standard
program version and screen title blocks) specifies the number of
monitored Cache Managers, the number of alerts, and the number of
machines affected by the alerts.
The first column always displays the hostnames of the machines running
the monitored Cache Managers.
To the right of the hostname column appear as many columns of
statistics as can fit within the current width of the display screen
or window; each column requires space for 10 characters. The name of
the statistic appears at the top of each column. If the Cache Manager
on a machine did not respond to the most recent probe, a pair of
dashes (--) appears in each column. If a value exceeds its configured
threshold, it is highlighted in reverse video. If a value is too large
to fit into the allotted column width, it overflows into the next row
in the same column.
=head1 Writing to an Output File
Include the B<-output> argument to name the file into which the
C<afsmonitor> program writes all of the statistics it collects. The
output file can be useful for tracking performance over long periods
of time, and enables the administrator to apply post-processing
techniques that reveal system trends. The AFS distribution does not
include any post-processing programs.
The output file is in ASCII format and records the same information as
the File Server and Cache Manager display screens. Each line in the
file uses the following format to record the time at which the
C<afsmonitor> program gathered the indicated statistic from the Cache
Manager (C<CM>) or File Server (C<FS>) running on the machine called
I<host_name>. If a probe failed, the error code B<-1> appears in the
I<statistic> field.
I<time> I<host_name> CM|FS I<statistic>
If the administrator usually reviews the output file manually, rather
than using it as input to an automated analysis program or script,
including the B<-detail> flag formats the data in a more easily readable
form.
=head1 EXAMPLES
For examples of commands, display screens, and configuration files,
see the section about the C<afsmonitor> program in the IBM AFS
Administration Guide.
=head1 PRIVILEGE REQUIRED
None
=head1 CAVEATS
The following software must be accessible to a machine where the
C<afsmonitor> program is running:
=over
=item *
The AFS B<xstat> libraries, which the C<afsmonitor> program uses to
gather data
=item *
The B<curses> graphics package, which most UNIX distributions provide
as a standard utility
=back
The C<afsmonitor> screens format successfully both on so-called dumb
terminals and in windowing systems that emulate terminals. For the
output to looks its best, the display environment needs to support
reverse video and cursor addressing. Set the TERM environment variable
to the correct terminal type, or to a value that has characteristics
similar to the actual terminal type. The display window or terminal
must be at least 80 columns wide and 12 lines long.
The C<afsmonitor> program must run in the foreground, and in its own
separate, dedicated window or terminal. The window or terminal is
unavailable for any other activity as long as the C<afsmonitor> program
is running. Any number of instances of the C<afsmonitor> program can run
on a single machine, as long as each instance runs in its own
dedicated window or terminal. Note that it can take up to three
minutes to start an additional instance.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<afsmonitor_Configuration_File(1)>,
L<fstrace(1)>,
L<scout(1)>
=cut

306
doc/man-pages/pod/backup.pod Normal file
View File

@ -0,0 +1,306 @@
=head1 NAME
backup - Introduction to the C<backup> command suite
=head1 DESCRIPTION
The commands in the C<backup> command suite are the administrative
interface to the AFS Backup System. There are several categories of
commands in the suite:
=over
=item *
Commands to copy data from AFS volumes to tape or a backup data
file, and to restore it to the file system: C<backup diskrestore>,
C<backup dump>, C<backup volrestore>, and C<backup volsetrestore>
=item *
Commands to administer the records in the Backup Database: C<backup
adddump>, C<backup addhost>, C<backup addvolentry>, C<backup addvolset>,
C<backup deldump>, C<backup deletedump>, C<backup delhost>, C<backup
delvolentry>, C<backup delvolset>, C<backup dumpinfo>, C<backup listdumps>,
C<backup listhosts>, C<backup listvolsets>, C<backup scantape>, C<backup
setexp>, and C<backup volinfo>
=item *
Commands to write and read tape labels: C<backup labeltape> and
C<backup readlabel>
=item *
Commands to list and change the status of backup operations and
the machines performing them: C<(backup) jobs>, C<(backup) kill>, and
C<backup status>
=item *
Commands to enter and leave interactive mode: C<backup (interactive)>
and C<(backup) quit>
=item *
Commands to check for and repair corruption in the Backup
Database: C<backup dbverify>, C<backup restoredb>, and C<backup savedb>
=item *
Commands to obtain help: C<backup apropos> and C<backup help>
=back
The C<backup> command interpreter interacts with two other processes:
=over
=item *
The Backup Server (B<buserver>) process. It maintains the Backup
Database, which stores most of the administrative information used
by the Backup System. In the standard configuration, the Backup
Server runs on each database server machine in the cell, and uses
AFS's distributed database technology, Ubik, to synchronize its
copy of the database with the copies on the other database server
machines.
=item *
The Backup Tape Coordinator (B<butc>) process. A separate instance of
the process controls each tape device or backup data file used to
dump or restore data. The Tape Coordinator runs on a Tape
Coordinator machine, which is an AFS server or client machine that
has one or more tape devices attached, or has sufficient disk
space to accommodate one or more backup data files on its local
disk.
Each Tape Coordinator must be registered in the Backup Database
and in the B</usr/afs/backup/tapeconfig> configuration file on the
Tape Coordinator machine's local disk, and information in the two
places must be consistent for proper Backup System performance.
The optional B</usr/afs/backup/CFG>I<_device_name> for each Tape
Coordinator records information used to automate its operation.
=back
In addition to the standard command line interface, the C<backup> command
suite provides an I<interactive> interface, which has several useful
features described on the C<backup (interactive)> reference page. Three
of the commands in the suite are available only in interactive mode:
C<(backup) jobs>, C<(backup) kill>, and C<(backup) quit>.
=head1 OPTIONS
The following options are available on many commands in the C<backup>
suite. The reference page for each command also lists them, but they
are described here in greater detail.
=over 4
=item B<-cell> I<cell name>
Names the cell in which to run the command. It is acceptable to
abbreviate the cell name to the shortest form that
distinguishes it from the other entries in the
B</usr/vice/etc/CellServDB> file on the local machine. If the
B<-cell> argument is omitted, the command interpreter determines
the name of the local cell by reading the following in order:
=over
=item 1.
The value of the AFSCELL environment variable
=item 2.
The local B</usr/vice/etc/ThisCell> file
=back
Do not combine the B<-cell> and B<-localauth> options. A command on
which the B<-localauth> flag is included always runs in the local
cell (as defined in the server machine's local
B</usr/afs/etc/ThisCell> file), whereas a command on which the
B<-cell> argument is included runs in the specified foreign cell.
The B<-cell> argument is not available on commands issued in
interactive mode. The cell defined when the C<backup> command
interpreter enters interactive mode applies to all commands
issued during the interactive session.
=item B<-help>
Prints a command's online help message on the standard output
stream. Do not combine this flag with any of the command's
other options; when it is provided, the command interpreter
ignores all other options, and only prints the help message.
=item B<-localauth>
Constructs a server ticket using the server encryption key with
the highest key version number in the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents the ticket, which never expires, to the Backup Server,
Volume Server and Volume Location (VL) Server during mutual
authentication.
Use this flag only when issuing a command on a server machine;
client machines do not usually have a B</usr/afs/etc/KeyFile>
file. The issuer of a command that includes this flag must be
logged on to the server machine as the local superuser B<root>.
The flag is useful for commands invoked by an unattended
application program, such as a process controlled by the UNIX
B<cron> utility or by a cron entry in the machine's
B</usr/afs/local/BosConfig> file. It is also useful if an
administrator is unable to authenticate to AFS but is logged in
as the local superuser B<root>.
Do not combine the B<-cell> and B<-localauth> options. A command on
which the B<-localauth> flag is included always runs in the local
cell (as defined in the server machine's local
B</usr/afs/etc/ThisCell> file), whereas a command on which the
B<-cell> argument is included runs in the specified foreign cell.
The B<-localauth> argument is not available on commands issued in
interactive mode. The local identity and AFS tokens with which
the C<backup> command interpreter enters interactive mode apply to
all commands issued during the interactive session.
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator that
is to execute the C<backup> command. The port offset number
uniquely identifies a pairing of a Tape Coordinator (B<butc>)
process and tape device or C<backup> data file.
The C<backup> command interpreter and Tape Coordinator process
communicate via a UDP socket, or port. Before issuing a C<backup>
command that involves reading or writing a tape, the backup
operator must start a B<butc> process that controls the
appropriate tape device and listens for requests sent to its
port number. If a Backup System machine has multiple tape
devices attached, they can perform backup operations
simultaneously because each device has its own associated B<butc>
process and port offset number.
The Backup System associates a tape capacity and file mark size
with each port offset (as defined in the B<tapeconfig> file). For
a compressing tape device, the capacity and file mark values
differ for compression and non-compression modes, so the two
modes have distinct port offset numbers.
The Backup Database can store up to 58,511 port offsets, so the
legal values for this argument are the integers B<0> through
B<58510>. If the issuer omits the argument, it defaults to B<0>. (The
limit of 58,511 port offsets results from the fact that UDP
socket numbers are identified by a 16-bit integer, and the
lowest socket number used by the Backup System is 7025. The
largest number that a 16-bit integer can represent is 65,535.
Subtracting 7,025 yields 58,510. The addition of port offset 0
(zero) increases the maximum to 58,511.)
Although it is possible to define up to 58,511 port offset
numbers for a cell, it is not possible to run 58,511 tape
devices simultaneously, due to the following limits:
=over
=item *
The maximum number of dump or restore operations that can run
simultaneously is 64.
=item *
The maximum number of tape devices that can work together on
a restore operation is 128 (that is the maximum number of
values that can be provided for the B<-portoffset> argument to
the C<backup diskrestore>, C<backup volrestore>, or C<backup
volsetrestore> command).
=back
The Backup System does not reserve UDP sockets. If another
application is already using the Tape Coordinator's socket when
it tries to start, the B<butc> process fails and the following
error message appears at the shell prompt:
bind: Address already in use
rxi_GetUDPSocket: bind failed
=back
=head1 PRIVILEGE REQUIRED
To issue any C<backup> command that accesses the Backup Database only,
the issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running. To issue any C<backup> command
that accesses volume data, the issuer must appear in the
B<UserList> file on every Backup Server machine, every Volume Location
(VL) Server machine, and every file server machine that houses
affected volumes. By convention, a common B<UserList> file is distributed
to all database server and file server machines in the cell. See the
chapter on privileged users in the IBM AFS Administration Guide for
more information on this type of privilege.
If the B<-localauth> flag is included, the user must instead be logged on
as the local superuser root on the server machine where the C<backup> command is issued.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<BosConfig(1)>,
L<CFG_device_name(1)>,
L<CellServDB_client_version(1)>,
L<KeyFile(1)>,
L<ThisCell_client_version(1)>,
L<ThisCell_server_version(1)>,
L<UserList(1)>,
L<tapeconfig(1)>,
L<backup_adddump(1)>,
L<backup_addhost(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_dbverify(1)>,
L<backup_deldump(1)>,
L<backup_deletedump(1)>,
L<backup_delhost(1)>,
L<backup_delvolentry(1)>,
L<backup_delvolset(1)>,
L<backup_diskrestore(1)>,
L<backup_dump(1)>,
L<backup_dumpinfo(1)>,
L<backup_help(1)>,
L<backup_interactive(1)>,
L<backup_jobs(1)>,
L<backup_kill(1)>,
L<backup_labeltape(1)>,
L<backup_listdumps(1)>,
L<backup_listhosts(1)>,
L<backup_listvolsets(1)>,
L<backup_quit(1)>,
L<backup_readlabel(1)>,
L<backup_restoredb(1)>,
L<backup_savedb(1)>,
L<backup_scantape(1)>,
L<backup_setexp(1)>,
L<backup_status(1)>,
L<backup_volinfo(1)>,
L<backup_volrestore(1)>,
L<backup_volsetrestore(1)>,
L<buserver(1)>,
L<butc(1)>
=cut

202
doc/man-pages/pod/backup_adddump.pod Normal file
View File

@ -0,0 +1,202 @@
=head1 NAME
backup adddump - Defines a dump level in the dump hierarchy
=head1 SYNOPSIS
backup adddump B<-dump> I<dump level name> [I<dump level name> ...] [B<-expires> I<expiration date> ...]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup addd B<-d> I<dump level name> [I<dump level name> ...] [B<-e> I<expiration date> ...] [B<-l>]
[B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup adddump> command creates one or more dump levels in the dump
hierarchy stored in the Backup Database, and optionally assigns an
expiration date to each one. All of the dump levels in the Backup
Database collectively constitute the dump hierarchy.
Use the B<-expires> argument to associate an expiration date with each
dump level. When the Backup System subsequently creates a dump at the
dump level, it uses the specified value to derive the dump's
expiration date, which it records on the label of the tape (or backup
data file). The Backup System refuses to overwrite a tape until after
the latest expiration date of any dump that the tape contains, unless
the C<backup labeltape> command is used to relabel the tape. If a dump
level does not have an expiration date, the Backup System treats dumps
created at the level as expired as soon as it creates them.
(Note that the Backup System does not automatically remove a dump's
record from the Backup Database when the dump reaches its expiration
date, but only if the tape that contains the dump is recycled or
relabeled. To remove expired and other obsolete dump records, use the
C<backup deletedump> command.)
Define either an absolute or relative expiration date:
=over
=item *
An absolute expiration date defines the month/day/year (and,
optionally, hour and minutes) at which a dump expires. If the
expiration date predates the dump creation time, the Backup System
immediately treats the dump as expired.
=item *
A relative date defines the number of years, months, or days (or a
combination of the three) after the dump's creation that it
expires. When the Backup System creates a dump at the dump level,
it calculates an actual expiration date by adding the relative
date to the start time of the dump operation.
=back
=head1 OPTIONS
=over 4
=item B<-dump> I<dump level name> [I<dump level name> ...]
Names each dump level to add to the dump hierarchy. Precede
full dump level names with a slash (for example, B</full>).
Indicate an incremental dump level by preceding it with an
ordered list of the dump levels directly above it in the
hierarchy (its parent dump levels); use the slash as a
separator. The parent dump levels must already exist. For
example, the dump levels B</full> and B</full/incremental1> must
exist when the incremental dump level
B</full/incremental1/incremental2> is created.
Dump level names can have any number of levels, but cannot
exceed 256 characters in length, including the slashes. The
maximum length for any single level (the text between slashes)
is 28 characters, not including the preceding slash.
All alphanumeric characters are allowed in dump level names. Do
not use the period (.), however, because it is the separator
between the volume set name and dump level name in the dump
name assigned automatically by the C<backup dump> command. It is
best not to include other metacharacters either; if using them,
enclose them in double quotes (" ") when issuing the C<backup
adddump> command outside interactive mode.
=item B<-expires> I<expiration date> ...
Defines the absolute or relative expiration date to associate
with each dump level named by the B<-dump> argument. Absolute
expiration dates have the following format:
[B<at>] {B<NEVER> | I<mm/dd/yyyy> [I<hh:MM>] }
where the optional word B<at> is followed either by the string
B<NEVER>, which indicates that dumps created at the dump level
never expire, or by a date value with a required portion (I<mm>
for month, I<dd> for day, and I<yyyy> for year) and an optional
portion (I<hh> for hours and I<MM> for minutes).
Omit the I<hh>:I<MM> portion to use the default of midnight (00:00
hours), or provide a value in 24-hour format (for example,
B<20:30> is 8:30 p.m.). Valid values for the year range from B<1970>
to B<2037>; higher values are not valid because the latest
possible date in the standard UNIX representation is in
February 2038. The command interpreter automatically reduces
later dates to the maximum value.
Relative expiration dates have the following format:
[B<in>] [I<years>B<y>] [I<months>B<m>] [I<days>B<d>]
where the optional word B<in> is followed by at least one of a
number of years (maximum B<9999>) followed by the letter B<y>, a
number of months (maximum B<12>) followed by the letter B<m>, or a
number of days (maximum B<31>) followed by the letter B<d>. If
providing more than one of the three, list them in the
indicated order. If the date that results from adding the
relative expiration value to a dump's creation time is later
than the latest possible date in the UNIX time representation,
the Backup System automatically reduces it to that date.
=over
=item B<Note>:
A plus sign follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition to be associated with each dump level specified by the
B<-dump> argument.
=back
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command defines a full dump called B</1999> with a relative
expiration date of one year:
backup adddump -dump /1999 -expires in 1y
The following command defines an incremental dump called
B</sunday1/monday1> with a relative expiration date of 13 days:
backup adddump -dump /sunday1/monday1 -expires in 13d
The following command defines two dump incremental dump levels,
B</Monthly/Week1> and B</Monthly/Week2>. Their parent, the full dump level
B</Monthly>, must already exist. The expiration date for both levels is
12:00 a.m. on 1 January 2000.
backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_deldump(1)>,
L<backup_deletedump(1)>,
L<backup_listdumps(1)>,
L<backup_setexp(1)>
=cut

118
doc/man-pages/pod/backup_addhost.pod Normal file
View File

@ -0,0 +1,118 @@
=head1 NAME
backup addhost - Adds a Tape Coordinator entry to the Backup Database
=head1 SYNOPSIS
backup addhost B<-tapehost> I<tape machine name> [B<-portoffset> I<TC port offset>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup addh B<-t> I<tape machine name> [B<-p> I<TC port offset>]
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup addhost> command creates a Tape Coordinator entry in the
Backup Database. The entry records
=over
=item *
The host name of the Tape Coordinator machine where the Tape
Coordinator (B<butc>) process runs, as specified with the B<-tapehost>
argument.
=item *
The Tape Coordinator's port offset number, as specified with the
B<-portoffset> argument. An entry for the port offset must also
appear in the B</usr/afs/backup/tapeconfig> file on the Tape
Coordinator machine, where it is mapped to a UNIX device name (for
a tape device) or pathname (for a backup data file).
=back
Each Tape Coordinator must have its own port offset number, and the
command fails if a Backup Database entry already exists for the
requested port offset number. To display existing Tape Coordinator
entries, use the C<backup listhosts> command.
=head1 OPTIONS
=over 4
=item B<-tapehost> I<tape machine name>
Specifies the fully-qualified hostname of the machine for which
to create a Tape Coordinator entry in the Backup Database. The
machine must have an entry in either the cell's naming service
(such as the Domain Name Service) or the host file (B</etc/hosts>
or equivalent) on the machine where the command is issued.
=item B<-portoffset> I<TC port offset>
Specifies the Tape Coordinator's port offset number. Provide an
integer from the range B<0> through B<58510>, or omit this argument
to use the default value of B<0> (zero). The value must match the
port offset number recorded for the same combination of Tape
Coordinator and tape device or file in the
B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine
named by the B<-tapehost> argument.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile file>. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command creates an entry in the Backup Database that
assigns port offset number 4 to a Tape Coordinator running on the
machine B<backup1.abc.com>:
backup addhost -tapehost backup1.abc.com -portoffset 4
The following command creates a Backup Database entry that assigns
port offset number 0 to a Tape Coordinator on the machine
B<backup3.abc.com>:
backup addhost backup3.abc.com
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_delhost(1)>,
L<backup_listhosts(1)>
=cut

203
doc/man-pages/pod/backup_addvolentry.pod Normal file
View File

@ -0,0 +1,203 @@
=head1 NAME
backup addvolentry - Defines a volume entry in a volume set
=head1 SYNOPSIS
backup addvolentry B<-name> I<volume set name> B<-server> I<machine name>
B<-partition> I<partition name>
B<-volumes> I<volume name (regular expression)>
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup addvole B<-n> I<volume set name> B<-s> I<machine name> B<-p> I<partition name>
B<-v> I<volume name (regular expression)>
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup addvolentry> command adds a volume entry definition to the
existing volume set named by the B<-name> argument. A volume entry
definition can match one or more volumes, depending on the combination
of the B<-server>, B<-partition>, and B<-volumes> arguments.
For the B<-server> and B<-partition> arguments, provide either
=over
=item *
The name of one machine or partition
=item *
The metacharacter expression B<.*> (period and asterisk), which
matches every machine name or partition name in the Volume
Location Database (VLDB).
=back
For the B<-volumes> argument, specify a combination of alphanumeric
characters and one or more metacharacters to wildcard part or all of
the volume name. The B<Options> section lists the acceptable
metacharacters.
=head1 OPTIONS
=over 4
=item B<-name>
Names the volume set to which to add this volume entry
definition. The volume set must already exist (use the C<backup
addvolset> command to create it).
=item B<-server>
Defines the set of one or more file server machines that house
the volumes in the volume entry. Provide either one
fully-qualified hostname (such as B<fs1.abc.com>) or the
metacharacter expression B<.*> (period and asterisk), which
matches all machine names in the VLDB.
=item B<-partition>
Defines the set of one or more partitions that house the
volumes in the volume entry. Provide either one complete
partition name (such as B</vicepa>) or the metacharacter
expression B<.*> (period and asterisk), which matches all
partition names.
=item B<-volumes>
Defines the set of one or more volumes included in the volume
entry. Specify the volumes by name, by using any combination of
regular alphanumeric characters and one or more of the
following metacharacter expressions:
=over
=item B<.>
The period matches any single character.
=item B<*>
The asterisk matches zero or more instances of the
preceding character. Combine it with any other
alphanumeric character or metacharacter.
=item B<[ ]>
Square brackets around a list of characters match a
single instance of any of the characters, but no other
characters; for example, B<[abc]> matches a single B<a> or B<b> or
B<c>, but not B<d> or B<A>. This expression can be combined with
the asterisk.
=item B<^>
The caret, when used as the first character in a
square-bracketed set, designates a match with any single
character I<except> the characters that follow it; for
example, B<[^a]> matches any single character except
lowercase B<a>. This expression can be combined with the
asterisk.
=item B<\>
A backslash preceding any of the metacharacters in this
list makes it match its literal value only. For example,
the expression B<\.> (backslash and period) matches a single
period, B<\*> a single asterisk, and B<\\> a single backslash.
Such expressions can be combined with the asterisk (for
example, B<\.*> matches any number of periods).
=back
Perhaps the most common metacharacter expression is the period
followed by an asterisk (B<.*>). This expression matches any
string of any length, because the period matches any character
and the asterisk means any number of that character. As
mentioned, it is the only acceptable metacharacter expression
for the B<-server> and B<-partition> arguments. In a volume
definition it can stand alone (in which case it matches every
volume listed in the VLDB), or can combine with regular
characters. The following example matches any volume name that
begins with the string B<user> and ends with B<backup>:
B<user.*backup>
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command adds a volume entry to the volume set called
B<sys>. The entry matches all volumes on any machine or partition whose
names begin with the string B<sun4x_56> followed by a period:
backup> addvolentry sys .* .* sun4x_56\..*
The following command adds a volume entry to the volume set called
fs2, to match all volumes on the /vicepb partition of file server
machine fs2.abc.com. Because it is issued at the shell prompt, double
quotes surround the metacharacters in the -volumes argument. (The
command is shown here on two lines only for legibility reasons.)
backup addvolentry -name fs2 -server fs2.abc.com \
-partition /vicepb -volumes ".*"
The chapter in the IBM AFS Administration Guide about configuring the
AFS Backup System presents additional examples as well as advice on
grouping volumes.
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
It is best to issue this command in interactive mode. If issuing it at
the shell prompt, enclose any strings containing metacharacters in
double quotes, or escape the metacharacters with other delimiters, to
prevent the shell from interpreting them. Adding volume entries to a
temporary volume set is possible only within the interactive session
in which the volume set was created.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolset(1)>,
L<backup_delvolentry(1)>,
L<backup_delvolset(1)>,
L<backup_listvolsets(1)>
=cut

114
doc/man-pages/pod/backup_addvolset.pod Normal file
View File

@ -0,0 +1,114 @@
=head1 NAME
backup addvolset - Creates a new (empty) volume set
=head1 SYNOPSIS
backup addvolset B<-name> I<volume set name> [B<-temporary>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup addvols B<-n> I<volume set name> [B<-t>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup addvolset> command creates a new volume set, by default
adding it to the Backup Database. It is best that the volume set's
name indicate the volume set's contents; for example, define the
volume entries in the user volume set to match all user volumes. The
volume set name must be unique within the Backup Database of the local
cell.
After issuing this command, issue the C<backup addvolentry> command to
define the volume entries in the volume set.
Sometimes it is convenient to create volume sets without recording
them permanently in the Backup Database, for example when using the
C<backup volsetrestore> command to restore a group of volumes that were
not necessarily backed up together. To create a I<temporary> volume set,
include the B<-temporary> flag. A temporary volume set exists only during
the lifetime of the current interactive session, so the flag is
effective only when used during an interactive session (opened by
issuing the C<backup interactive> command). If it is included when the
command is issued at the regular command shell prompt, the command
appears to succeed, but the volume set is not created. As noted, a
temporary volume set ceases to exist when the current interactive
session ends, or use the C<backup delvolset> command to delete it before
that.
One advantage of temporary volume sets is that the C<backup addvolset>
command, and any C<backup addvolentry> commands subsequently used to add
volume entries to it, complete more quickly than for regular volume
sets, because no records are created in the Backup Database.
=head1 OPTIONS
=over 4
=item B<-name> I<volume set name>
Names the new volume set. The name can include up to 31 of any
character other than the period. Avoid other metacharacters as
well.
=item B<-temporary>
Creates a volume set that exists only within the context of the
current interactive session. It is not added to the Backup
Database.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command creates a volume set called sys:
backup addvolset sys
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolentry(1)>,
L<backup_delvolentry(1)>,
L<backup_delvolset(1)>,
L<backup_listvolsets(1)>,
L<backup_volsetrestore(1)>
=cut

72
doc/man-pages/pod/backup_apropos.pod Normal file
View File

@ -0,0 +1,72 @@
=head1 NAME
backup apropos - Displays each help entry containing a keyword string
=head1 SYNOPSIS
backup apropos B<-topic> I<help string> [B<-help>]
backup ap B<-t> I<help string> [B<-h>]
=head1 DESCRIPTION
The C<backup apropos> command displays the first line of the online help
entry for any C<backup> command that has in its name or short description
the string specified by the B<-topic> argument.
To display the syntax for a command, use the C<backup help> command.
=head1 OPTIONS
=over 4
=item B<-topic> I<help string>
Specifies the keyword string to match, in lowercase letters
only. If the string is more than a single word, surround it
with double quotes (" ") or other delimiters.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The first line of a command's online help entry names it and briefly
describes its function. This command displays the first line for any
C<backup> command where the string specified with the B<-topic> argument is
part of the command name or first line.
=head1 EXAMPLES
The following example lists all C<backup> commands that include the word
B<tape> in their names or short descriptions:
backup apropos tape
labeltape: label a tape
readlabel: read the label on tape
scantape: dump information recovery from tape
status: get tape coordinator status
=head1 PRIVILEGE REQUIRED
None
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_help(1)>
=cut

144
doc/man-pages/pod/backup_dbverify.pod Normal file
View File

@ -0,0 +1,144 @@
=head1 NAME
backup dbverify - Checks the integrity of the Backup Database
=head1 SYNOPSIS
backup dbverify [B<-detail>] [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup db [B<-d>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup dbverify> command checks the integrity of the Backup
Database. The command's output indicates whether the Backup Database
is damaged (data is corrupted) or not. If the Backup Database is
undamaged, it is safe to continue using it. If it is corrupted,
discontinue any backup operations until it is repaired.
=head1 OPTIONS
=over 4
=item B<-detail>
Reports the number of orphaned blocks found, any
inconsistencies, and the name of the server machine running the
Backup Server that is checking its copy of the database.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The command displays one of the following two messages:
=over
=item B<Database OK>
The database is undamaged and can be used.
=item B<Database not OK>
The database is damaged. You can use the C<backup savedb> command
to repair many kinds of corruption as it creates a backup copy.
For more detailed instructions, see the IBM AFS Administration
Guide chapter about performing backup operations.
=back
The B<-detail> flag provides additional information:
=over
=item *
The number of I<orphan blocks> found. These are ranges of memory that
the Backup Server preallocated in the database but cannot use.
Orphan blocks do not interfere with database access, but do waste
disk space. To free the unusable space, dump the database to tape
by using the C<backup savedb> command, and then restore it by using
the C<backup restoredb> command.
=item *
Any inconsistencies in the database, such as invalid hostnames for
Tape Coordinator machines.
=item *
The name of the database server machine on which the Backup
Database was checked, designated as the Database checker. For a
detailed trace of the verification operation, see the
B</usr/afs/logs/BackupLog> file on the indicated machine. You can use
the C<bos getlog> command to display it.
=back
=head1 EXAMPLES
The following command confirms that the Backup Database is undamaged:
backup dbverify
Database OK
The following command confirms that the Backup Database is undamaged
and that it has no orphan blocks or invalid Tape Coordinator entries.
The Backup Server running on the machine B<db1.abc.com> checked its copy
of the Database.
backup dbverify -detail
Database OK
Orphan blocks 0
Database checker was db1.abc.com
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
While this command runs, no other backup operation can access the
Backup Database; the other commands do not run until this command
completes. Avoid issuing this command when other backup operations are
likely to run. The C<backup savedb> command repairs some types of
corruption.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<BackupLog(1)>,
L<bos_getlog(1)>,
L<backup(1)>,
L<backup_restoredb(1)>,
L<backup_savedb(1)>
=cut

78
doc/man-pages/pod/backup_deldump.pod Normal file
View File

@ -0,0 +1,78 @@
=head1 NAME
backup deldump - Deletes a dump level from the Backup Database
=head1 SYNOPSIS
backup deldump B<-dump> I<dump level name> [B<-localauth>]
[B<-cell> I<cell name>] [B<-help>]
backup deld B<-d> I<dump level name> [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup deldump> command deletes the indicated dump level and all of
its child dump levels from the dump hierarchy in the Backup Database.
Use the C<backup listdumps> command to display the dump hierarchy.
=head1 OPTIONS
=over 4
=item B<-dump> I<dump level name>
Specifies the complete pathname of the dump level to delete.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command deletes the dump level B</sunday1/monday1> from the
dump hierarchy, along with any of its child dump levels.
backup deldump /sunday1/monday1
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_adddump(1)>,
L<backup_listdumps(1)>
=cut

212
doc/man-pages/pod/backup_deletedump.pod Normal file
View File

@ -0,0 +1,212 @@
=head1 NAME
backup deletedump - Deletes one or more dump records from the Backup Database
=head1 SYNOPSIS
backup deletedump [B<-dumpid> I<dump id> [I<dump id> ...]] [B<-from> I<date time> ...]
[B<-to> I<date time> ...] [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup dele [B<-d> I<dump id> [I<dump id> ...]] [B<-f> I<date time> [I<date time> ...]]
[B<-t> I<date time> [I<date time> ...]] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup deletedump> command deletes one or more dump records from
the Backup Database. Either use the B<-dumpid> argument to specify the
dump ID number of one or more dumps, or use the B<-from> and B<-to>
arguments to delete the records for all regular dumps created during
the time period bracketed by the specified values.
Use this command to remove dump records that are incorrect (possibly
because a dump operation was interrupted or failed), or that
correspond to dumps that are expired or otherwise no longer needed.
=head1 OPTIONS
=over 4
=item B<-dumpid> I<dump id> [I<dump id> ...]
Specifies the dump ID of each dump record to delete. The
corresponding dumps must be initial dumps; it is not possible
to delete appended dump records directly, but only by deleting
the record of their associated initial dump. Using this
argument is the only way to delete records of Backup Database
dumps (created with the C<backup savedb> command).
Provide either this argument or the B<-to> (and optionally B<-from>)
argument.
=item B<-from> I<date time> ...
Specifies the beginning of a range of dates; the record for any
dump created during the indicated period of time is deleted.
Omit this argument to indicate the default of midnight (00:00
hours) on 1 January 1970 (UNIX time zero), or provide a date
value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>]. The month (I<mm>), day
(I<dd>), and year (I<yyyy>) are required. The hour and minutes
(I<hh>:I<MM>) are optional, but if provided must be in 24-hour format
(for example, the value B<14:36> represents 2:36 p.m.). If
omitted, the time defaults to midnight (00:00 hours).
The B<-to> argument must be provided along with this one.
=over
=item B<Note:>
A ... follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition.
=back
=item B<-to> I<date time> ...
Specifies the end of a range of dates; the record of any dump
created during the range is deleted from the Backup Database.
Provide either the value B<NOW> to indicate the current date and
time, or a date value in the same format as for the B<-from>
argument. Valid values for the year (I<yyyy>) range from B<1970> to
B<2037>; higher values are not valid because the latest possible
date in the standard UNIX representation is in February 2038.
The command interpreter automatically reduces any later date to
the maximum value.
If the time portion (I<hh>:I<MM>) is omitted, it defaults to 59
seconds after midnight (00:00:59 hours). Similarly, the C<backup>
command interpreter automatically adds 59 seconds to any time
value provided. In both cases, adding 59 seconds compensates
for how the Backup Database and C<backup dumpinfo> command
represent dump creation times in hours and minutes only. For
example, the Database records a creation timestamp of 20:55 for
any dump operation that begins between 20:55:00 and 20:55:59.
Automatically adding 59 seconds to a time thus includes the
records for all dumps created during that minute.
Provide either this argument, or the B<-dumpid> argument. This
argument is required if the B<-from> argument is provided.
B<Caution>: Specifying the value B<NOW> for this argument when the
B<-from> argument is omitted deletes all dump records from the
Backup Database (except for Backup Database dump records
created with the C<backup savedb> command).
=over
=item B<Note:>
A ... follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition.
=back
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
At the conclusion of processing, the output lists the dump IDs of all
dump records deleted in the following format:
The following dumps were deleted:
dump ID 1
dump ID 2
etc.
=head1 EXAMPLES
The following command deletes the dump record with dump ID 653777462,
and for any appended dumps associated with it:
backup deletedump -dumpid 653777462
The following dumps were deleted:
653777462
The following command deletes the Backup Database record of all dumps
created between midnight on 1 January 1997 and 23:59:59 hours on 31
December 1997:
backup deletedump -from 01/01/1997 -to 12/31/1997
The following dumps were deleted:
598324045
598346873
...
...
653777523
653779648
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
The only way to remove the dump record for an appended dump is to
remove the record for its initial dump, and doing so removes the
records for all of the initial dump's associated appended dumps.
The only way to remove the record for a Backup Database dump (created
with the C<backup savedb> command) is to specify its dump ID number with
the B<-dumpid> argument. Using the B<-from> and B<-to> arguments never removes
database dump records.
Removing records of a dump makes it impossible to restore data from
the corresponding tapes or from any dump that refers to the deleted
dump as its parent, directly or indirectly. That is, restore
operations must begin with the full dump and continue with each
incremental dump in order. If the records for a specific dump are
removed, it is not possible to restore data from later incremental
dumps unless the deleted records are restored by running the C<backup
scantape> command with the B<-dbadd> flag.
If a dump set contains any dumps that were created outside the time
range specified by the B<-from> and B<-to> arguments, the command does not
delete any of the records associated with the dump set, even if some
of them represent dumps created during the time range.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dumpinfo(1)>,
L<backup_scantape(1)>
=cut

93
doc/man-pages/pod/backup_delhost.pod Normal file
View File

@ -0,0 +1,93 @@
=head1 NAME
backup delhost - Deletes a Tape Coordinator entry from the Backup Database
=head1 SYNOPSIS
backup delhost B<-tapehost> I<tape machine name> [B<-portoffset> I<TC port offset>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup delh B<-t> I<tape machine name> [B<-p> I<TC port offset>]
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup delhost> command deletes the indicated Tape Coordinator
entry from the Backup Database. It is then impossible to submit backup
operations to that Tape Coordinator, even if it is still running. To
keep configuration information consistent, also remove the
corresponding entry from the B</usr/afs/backup/tapeconfig> file on the
Tape Coordinator machine.
To list the Tape Coordinator machines and port offsets defined in the
Backup Database, issue the C<backup listhosts> command.
=head1 OPTIONS
=over 4
=item B<-tapehost> I<tape machine name>
Specifies the hostname of the machine housing the Tape
Coordinator to delete.
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator to
delete. If omitted, it defaults to B<0>. If provided, it is an
integer between B<0> (zero) and B<58510>, and must match the port
offset number assigned to the same combination of Tape
Coordinator and tape device or file in the
B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine
indicated by the B<-tapehost> argument.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command deletes the Backup Database entry for the Tape
Coordinator with port offset 2 on the Tape Coordinator machine
B<backup3.abc.com>:
backup delhost -tapehost backup3.abc.com -portoffset 2
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addhost(1)>,
L<backup_listhosts(1)>
=cut

93
doc/man-pages/pod/backup_delvolentry.pod Normal file
View File

@ -0,0 +1,93 @@
=head1 NAME
backup delvolentry - Deletes a volume entry from a volume set
=head1 SYNOPSIS
backup delvolentry B<-name> I<volume set name> B<-entry> I<volume set index>
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup delvole B<-n> I<volume set name> B<-e> I<volume set index>
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup delvolentry> command deletes the indicated volume entry from
the volume set specified with the B<-name> argument. Use the B<-entry>
argument to identify the volume entry by its index number. To display
the index numbers, use the C<backup listvolsets> command.
If there are any remaining volume entries with index numbers higher
than the deleted entry, their indexes are automatically decremented to
eliminate any gaps in the indexing sequence.
=head1 OPTIONS
=over 4
=item B<-name> I<volume set name>
Names the volume set from which to delete a volume entry.
=item B<-entry> I<volume set index>
Specifies the index number of the volume entry to delete. Use
the C<backup listvolsets> command to display the index numbers for
a volume set's volume entries.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command deletes the fourth volume entry from the volume
set called B<sys>:
backup delvolentry -name sys -entry 4
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
Deleting volume entries from a temporary volume set is possible only
within the interactive session in which the volume set was created.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_delvolset(1)>,
L<backup_listvolsets(1)>
=cut

83
doc/man-pages/pod/backup_delvolset.pod Normal file
View File

@ -0,0 +1,83 @@
=head1 NAME
backup delvolset - Deletes one or more volume sets from the Backup Database
=head1 SYNOPSIS
backup delvolset B<-name> I<volume set name> [I<volume set name> ...]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup delvols B<-n> I<volume set name> [I<volume set name> ...] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup delvolset> command deletes each volume set named by the
B<-name> argument, and the volume entries each contains, from the Backup
Database. The C<backup listvolsets> command lists the volume sets (and
their volume entries) currently defined in the Backup Database.
=head1 OPTIONS
=over 4
=item B<-name> I<volume set name> [I<volume set name> ...]
Names each volume set to delete.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command deletes the volume set called user and all
volume entries in it:
backup delvolset user
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
Deleting a temporary volume set is possible only within the
interactive session in which it was created. Exiting the interactive
session also destroys the temporary volume set automatically.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_delvolentry(1)>,
L<backup_listvolsets(1)>
=cut

280
doc/man-pages/pod/backup_diskrestore.pod Normal file
View File

@ -0,0 +1,280 @@
=head1 NAME
backup diskrestore - Restores the entire contents of a partition
=head1 SYNOPSIS
backup diskrestore B<-server> I<machine to restore>
B<-partition> I<partition to restore>
[B<-portoffset> I<TC port offset> [I<TC port offset> ...]]
[B<-newserver> I<destination machine>]
[B<-newpartition> I<destination partition>]
[B<-extension> I<new volume name extension>]
[B<-n>] [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup di B<-s> I<machine to restore> B<-pa> I<partition to restore>
[B<-po> I<TC port offset> [I<TC port offset> ...]] [B<-news> I<destination machine>]
[B<-newp> I<destination partition>] [B<-e> I<new volume name extension>]
[B<-n>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup diskrestore> command restores all of the volumes for which
the Volume Location Database (VLDB) lists a read/write site on the
partition specified with the B<-server> and B<-partition> arguments. It is
useful if a disk or machine failure corrupts or destroys the data on
an entire partition. (To restore any read-only or backup volumes that
resided on the partition, use the C<vos release> and C<vos backup> commands,
respectively, after restoring the read/write version.)
If restoring only selected volumes to a single site, it is usually
more efficient to use the C<backup volrestore> command. To restore
multiple volumes to many different sites, use the C<backup volsetrestore> command.
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG>I<_device_name> file on the Tape Coordinator machine
associated with the specified port offset, then the Backup System
restores data from the backup data file listed for that port offset in
the Tape Coordinator's B</usr/afs/backup/tapeconfig> file, instead of
from tape. For the sake of clarity, the following text refers to tapes
only, but the Backup System handles backup data files in much the same
way.)
The Backup System determines whether the read/write or backup version
of each volume was dumped more recently, and restores the dumps of
that version, starting with the most recent full dump. It resets the
creation timestamp of each restored volume to the date and time at
which it begins restoring the volume (the creation timestamp appears
in the Creation field of the output from the C<vos examine> and C<vos
listvol> commands).
If all of the full and incremental dumps of all relevant volumes were
not written on compatible tape devices, use the B<-portoffset> argument
to list multiple port offset numbers in the order in which the tapes
are needed (first list the port offset for the full dump, second the
port offset for the level 1 incremental dump, and so on). This implies
that the full dumps of all relevant volumes must have been written to
a type of tape that the first Tape Coordinator can read, the level 1
incremental dumps to a type of tape the second Tape Coordinator can
read, and so on. If dumps are on multiple incompatible tape types, use
the C<backup volrestore> command to restore individual volumes, or the
C<backup volsetrestore> command after defining groups of volumes that
were dumped to compatible tape types. For further discussion, see the
IBM AFS Administration Guide.
By default, the Backup System restores the contents of the specified
partition to that same partition. To restore the contents to an
alternate site, combine the following options as indicated. The Backup
System removes each volume from the original site, if it still exists,
and records the change of site in the VLDB.
=over
=item *
To restore to a different partition on the same file server
machine, provide the B<-newpartition> argument.
=item *
To restore to the partition with the same name on a different file
server machine, provide the B<-newserver> argument.
=item *
To restore to a completely different site, combine the B<-newserver>
and B<-newpartition> arguments.
=back
By default, the Backup System overwrites the contents of existing
volumes with the restored data. To create a new volume to house the
restored data instead, use the B<-extension> argument. The Backup System
creates the new volume at the site designated by the B<-newserver> and
B<-newpartition> arguments if they are used or the B<-server> and B<-partition>
arguments otherwise. It derives the volume name by adding the
extension to the read/write base name listed in the VLDB, and creates
a new VLDB entry. The command does not affect the existing volume in
any way. However, if a volume with the specified extension also
already exists, the command overwrites it.
To print out a list of the tapes containing the needed dumps, without
actually performing the restore operation, include the B<-n> flag along
with the other options to be used on the actual command.
The Tape Coordinator's default response to this command is to access
the first tape it needs by invoking the B<MOUNT> instruction in the local
B<CFG>I<_device_name> file, or by prompting the backup operator to insert
the tape if there is no B<MOUNT> instruction. However, if the B<AUTOQUERY
NO> instruction appears in the B<CFG>I<_device_name> file, or if the issuer
of the C<butc> command included the B<-noautoquery> flag, the Tape
Coordinator instead expects the tape to be in the device already. If
it is not, or is the wrong tape, the Tape Coordinator invokes the
B<MOUNT> instruction or prompts the operator. It also invokes the B<MOUNT>
instruction or prompts for any additional tapes needed to complete the
restore operation; the backup operator must arrange to provide them.
=head1 OPTIONS
=over 4
=item B<-server> I<machine to restore>
Names the file server machine that the VLDB lists as the site
of the volumes that need to be restored.
=item B<-partition> I<partition to restore>
Names the partition that the VLDB lists as the site of the
volumes that need to be restored.
=item B<-portoffset> I<TC port offset> [I<TC port offset> ...]
Specifies one or more port offset numbers (up to a maximum of
128), each corresponding to a Tape Coordinator to use in the
operation. If there is more than one value, the Backup System
uses the first one when restoring the full dump of each volume,
the second one when restoring the level 1 incremental dump of
each volume, and so on. It uses the final value in the list
when restoring dumps at the corresponding depth in the dump
hierarchy and at all lower levels.
Provide this argument unless the default value of 0 (zero) is
appropriate for all dumps. If B<0> is just one of the values in
the list, provide it explicitly in the appropriate order.
=item B<-newserver> I<destination machine>
Names an alternate file server machine to which to restore the
volumes. If this argument is omitted, the volumes are restored
to the file server machine named by the B<-server> argument.
=item B<-newpartition> I<destination partition>
Names an alternate partition to which to restore the data. If
this argument is omitted, the volumes are restored to the
partition named by the B<-partition> argument.
=item B<-extension> I<new volume name extension>
Creates a new volume for each volume being restored, to house
the restored data. The Backup System derives the new volume's
name by appending the specified string to the read/write base
name listed in the VLDB, and creates a new VLDB volume entry.
The Backup System preserves the contents of the volumes on the
partition, if any still exist. Any string other than B<.readonly>
or B<.backup> is acceptable, but the combination of the base name
and extension cannot exceed 22 characters in length. To use a
period to separate the extension from the name, specify it as
the first character of the string (as in B<.rst>, for example).
=item B<-n>
Displays a list of the tapes necessary to perform the requested
restore, without actually performing the operation.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
If a tape error occurs during the restore operation, the Tape
Coordinator displays the following messages:
Restore operation on volume name failed due to tape error
Do you want to continue (y/n)?
where I<name> is the name of the volume that was being restored when the
tape error occurred. Enter the value B<y> to continue the operation
without restoring the indicated volume or the value B<n> to terminate the
operation. In the latter case, the operator can then attempt to
determine the cause of the tape error.
If the issuer includes the B<-n> flag with the command, the following
string appears at the head of the list of the tapes necessary to
perform the restore operation:
Tapes needed:
=head1 EXAMPLES
The following command restores the volumes for which the VLDB lists a
read/write site on the B</vicepd> partition of the machine B<fs5.abc.com>.
The Tape Coordinator associated with port offset 3 performs the
operation.
backup diskrestore -server fs5.abc.com -partition /vicepd -portoffset 3
The following command restores the volumes for which the VLDB lists a
read/write site on the B</vicepb> partition of the machine B<fs1.abc.com> to
a new site: the B</vicepa> partition on the machine B<fs3.abc.com>. The Tape
Coordinator associated with port offset 0 performs the operation. (The
command appears here on two lines only for legibility.)
backup diskrestore -server fs1.abc.com -partition /vicepb \
-newserver fs3.abc.com -newpartition /vicepa
The following command lists the tapes required to restore the volumes
for which the VLDB lists a read/write site on the B</vicepm> partition of
the machine B<fs4.abc.com>:
backup diskrestore -server fs4.abc.com -partition /vicepm -n
Tapes needed:
user.sunday1.1
user.sunday1.2
user.monday1.1
user.tuesday1.1
user.wednesday1.1
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server or Volume Location (VL) Server is
running, and on every file server machine that houses an affected
volume. If the B<-localauth> flag is included, the issuer must instead be
logged on to a server machine as the local superuser B<root>.
=head1 CAVEATS
If issuing this command to recover data after a disk crash or other
damage, be sure not to issue the C<vos syncserv> command first. Doing so
destroys the VLDB record of the volumes that resided on the partition.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dump(1)>,
L<backup_volrestore(1)>,
L<backup_volsetrestore(1)>,
L<butc(1)>,
L<vos_backup(1)>,
L<vos_examine(1)>,
L<vos_listvol(1)>,
L<vos_release(1)>
=cut

547
doc/man-pages/pod/backup_dump.pod Normal file
View File

@ -0,0 +1,547 @@
=head1 NAME
backup dump - Creates a dump (dumps a volume set at a particular dump level)
=head1 SYNOPSIS
backup dump [B<-volumeset> I<volume set name>] [B<-dump> I<dump level name>]
[B<-portoffset> I<TC port offset>] [B<-at> I<Date/time to start dump> ...]
[B<-append>] [B<-n>] [B<-file> I<load file>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup dump [B<-v> I<volume set name>] [B<-d> I<dump level name>]
[B<-p> I<TC port offset>] [B<-at> I<Date/time to start dump> ...]
[B<-ap>] [B<-n>] [B<-f> I<load file>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup dump> command either dumps the volume set specified by the
B<-volumeset> argument at the dump level specified by the B<-dump> argument
and creates a Backup Database dump record about it, or executes the
dump instructions listed in the file named by the B<-file> argument. The
Tape Coordinator indicated by the B<-portoffset> argument (or on each
command in the file) executes the operation.
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG>I<_device_name> file on the Tape Coordinator machine
associated with the specified port offset, then the Backup System
dumps data to the backup data file listed for that port offset in the
Tape Coordinator's B</usr/afs/backup/tapeconfig> file, rather than to
tape. For the sake of clarity, the following text refers to tapes
only, but the Backup System handles backup data files in much the same
way.)
The term I<dumping> refers to copying a collection of data to tape or a
backup data file, and the resulting collection is termed a I<dump>. The
set of tapes that contain one or more dumps is called a I<dump set>. The
first dump in a dump set is its I<initial dump>, and any dumps
subsequently added to the dump set (by use of the B<-append> argument)
are I<appended dumps>. Creating appended dumps is optional, and appended
dumps can be of different volume sets, and at different dump levels,
than the initial dump.
A I<full dump>, created at a full dump level in the dump hierarchy,
contains all of the data that existed at the time of the dump in the
volumes belonging to the volume set. An I<incremental dump>, created at
an incremental dump level, contains only data that has changed since
the volume set was dumped at the incremental level's I<parent dump level>
(the dump level immediately above the incremental level in the
hierarchy), which can be a full or incremental level. More
specifically, an incremental dump includes only the files and
directories that have modification timestamps later than the I<clone
date> of the volume included at the parent dump level. For backup and
read-only volumes, the clone date is the time at which the volume was
cloned from its read/write source before being included in the parent
dump; for read/write volumes, it represents the time at which the
volume was locked for inclusion in the parent dump. The clone date
appears in the I<clone date> field of the output from the C<backup volinfo>
command. As an example, an incremental dump at the
B</full/week1/thursday> level includes only files and directories that
have changed since the volume set was dumped at the B</full/week1> level.
=head2 Initiating different types of dump operations
To initiate a dump operation that is to start as soon as the relevant
Tape Coordinator is available, provide only the B<-volumeset>, B<-dump>,
B<-portoffset>, and optionally B<-append> options. To schedule a single
C<backup dump> command to execute in the future, also include the B<-at>
argument to specify the start time.
To append a dump to an existing dump set, include the B<-append> flag.
The Backup System imposes the following conditions on appended dumps:
=over
=item *
If writing to tape, the Tape Coordinator checks that it is the
final one in a dump set for which there are complete and valid
tape and dump records in the Backup Database. If not, it rejects
the tape and requests an acceptable one. The operator can use the
B<-dbadd> argument to the C<backup scantape> command to insert the
necessary records into the database.
=item *
The most recent dump on the tape or in the backup data file must
have completed successfully.
=item *
The dump set must begin with an initial dump that is recorded in
the Backup Database. If there are no dumps on the tape, then the
Backup System treats the dump operation as an initial dump and
imposes the relevant requirements (for example, checks the AFS
tape name if appropriate).
=back
To schedule multiple dump operations, list the operations in the file
named by the B<-file> argument. Optionally include the B<-at> argument to
specify when the C<backup> command interpreter reads the file; otherwise
it reads it immediately. Do not combine the B<-file> argument with the
command's first three arguments or the B<-append> or B<-n> flags. The
commands in the file can include any of the C<backup dump> command's
arguments, including the B<-at> argument to schedule them to run even
later in the future.
To generate a list of the volumes included in a dump, without actually
dumping them, combine the B<-n> flag with the options to be used on the
actual command.
=head2 How the Backup System executes a dump operation
Before beginning a dump operation, the Backup System verifies that
there is a Backup Database entry for the volume set, dump level, and
port offset. If the command is correctly formed and issued in
interactive mode, it is assigned a job number and added to the jobs
list. List jobs in interactive mode by using the C<(backup) jobs>
command; terminate them with the C<(backup) kill> command.
After obtaining the list of volumes to dump from the Volume Location
(VL) Server, the Backup System sorts the list by site (server and
partition). It groups volumes from the same site together in the dump
to minimize the number of times the operator must change tapes during
restore operations.
The dependence of an incremental dump on its parent means that a valid
parent dump must already exist for the Backup System to create its
child incremental dump. If the Backup System does not find a record of
a dump created at the immediate parent dump level, it looks in the
Backup Database for a dump created at one level higher in the
hierarchy, and so on, up to the full dump level if necessary. It
creates an incremental dump at the level one below the lowest valid
parent dump set that it finds. If it fails to find even a full dump,
it dumps the volume set at the full dump level.
If the Backup System is unable to access a volume during a dump
operation, it skips the volume and dumps the remaining volumes from
the volume set. Possible reasons a volume is inaccessible include
server machine or process outages, or that the volume was moved
between the time the Volume Location (VL) Server generated the list of
sites for the volume in the volume set and the time the Backup System
actually attempts to dump the data in it. After the first dumping
pass, the Backup System attempts to dump each volume it skipped. If it
still cannot dump a volume and the B<ASK NO> instruction does not appear
in the B<CFG>I<_device_name> file, it queries the operator as to whether it
needs to attempt to dump the volume again, omit the volume from the
dump, or halt the dump operation altogether. When prompted, the
operator can attempt to solve whatever problem prevented the Backup
System from accessing the volumes. If the B<ASK NO> instruction appears
in the B<CFG>I<_device_name> file, the Backup System omits the volume from
the dump.
Before scheduling a dump operation, the Backup System verifies that
the date specified by the B<-at> argument is in the future, and checks
the validity of the volume set, dump level and port offset as for a
regular dump operation. It checks the validity of the parameters again
just before actually running the scheduled operation.
Before writing an initial dump to a tape that does not have a
permanent name on the label, the Backup System checks that the AFS
tape name on the label is acceptable. If desired, disable name
checking by including the B<NAME_CHECK NO> instruction in the
B<CFG>I<_device_name> file.
If AFS tape name checking is enabled, the Backup System accepts the
following three types of values for the AFS tape name. If the name on
the label does not conform, the Backup System obtains a tape with an
acceptable label by invoking the B<MOUNT> instruction in the
B<CFG>I<_device_name> file or prompting the operator.
=over
=item 1.
A name of the form I<volume_set_name>.I<dump_level_name>.I<tape_index>,
where I<volume_set_name> matches the value of the B<-volumeset>
argument, I<dump_level_name> matches the last element in the pathname
value of the B<-dump> argument, and I<tape_index> reflects the tape's
place in a multitape dump set. As an example, the first tape in a
dump set for which the initial dump is of volume set user at the
dump level B</sunday2/monday> has AFS tape name B<user.monday.1>. If the
label records this type of AFS tape name, the Backup System
retains the AFS tape name and writes the dump to the tape.
=item 2.
The string C<E<lt>NULLE<gt>>, which usually indicates that a backup operator
has used the C<backup labeltape> command to write a label on the
tape, but did not include the B<-name> argument to assign an AFS tape
name. Presumably, the operator did include the B<-pname> argument to
assign a permanent name. If the label records a C<E<lt>NULLE<gt>> value, the
Backup System constructs and records on the label the appropriate
AFS tape name, and writes the dump on the tape.
=item 3.
No value at all, because the tape has never been labeled or used
in the Backup System. As when the AFS tape name is C<E<lt>NULLE<gt>>, the
Backup System constructs and records on the label the appropriate
AFS tape name, and writes the dump on the tape.
=back
To determine how much data it can write to a tape, the Tape
Coordinator reads the capacity recorded on the tape's label (placed
there by including the B<-size> argument to the C<backup labeltape> command).
If the label's capacity field is empty, the Tape Coordinator
uses the capacity recorded for the specified port offset in the local
B<tapeconfig> file. If the capacity field in the B<tapeconfig> file is also
empty, the Tape Coordinator uses the maximum capacity of 2 TB.
During a dump operation, the Tape Coordinator tracks how much data it
has written and stops shortly before it reaches what it believes is
the tape's capacity. If it is in the middle of writing the data for a
volume when it reaches that point, it writes a special marker that
indicates an interrupted volume and continues writing the volume on
the next tape. It can split a volume this way during both an initial
and an appended dump, and the fact that the volume resides on multiple
tapes is automatically recorded in the Backup Database.
If the tape is actually larger than the expected capacity, then the
Tape Coordinator simply does not use the excess tape. If the tape is
smaller than the expected capacity, the Tape Coordinator can reach the
end-of-tape (EOT) unexpectedly while it is writing data. If the Tape
Coordinator is in the middle of the writing data from a volume, it
obtains a new tape and rewrites the entire contents of the interrupted
volume to it. The data from the volume that was written to the
previous tape remains there, but is never used.
The Backup System allows recycling of tapes (writing a new dump set
over an old dump set that is no longer needed), but imposes the
following conditions:
=over
=item *
All dumps in the old dump set must be expired. The Backup System
always checks expiration dates, even when name checking is
disabled.
=item *
If the tape to be recycled does not have a permanent name and name
checking is enabled, then the AFS tape name derived from the new
initial dump's volume set name and dump level name must match the
AFS tape name already recorded on the label.
=item *
The tape cannot already have data on it that belongs to the dump
currently being performed, because that implies that the operator
or automated tape device has not removed the previous tape from
the drive, or has mistakenly reinserted it. The Tape Coordinator
generates the following message and attempts to obtain another
tape:
Can't overwrite tape containing the dump in progress
=item *
The tape cannot contain data from a parent dump of the current
(incremental) dump, because overwriting a parent dump makes it
impossible to restore data from the current dump. The Tape
Coordinator generates the following message and attempts to obtain
another tape:
Can't overwrite the parent dump parent_name (parent_dump_ID)
=back
To recycle a tape before all dumps on it have expired or if the AFS
tape name is wrong, use the C<backup labeltape> command to overwrite the
tape's label and remove all associated tape and dump records from the
Backup Database.
The Tape Coordinator's default response to this command is to access
the first tape by invoking the B<MOUNT> instruction in the
B<CFG>I<_device_name> file, or by prompting the backup operator to insert
the tape if there is no B<MOUNT> instruction. However, if the B<AUTOQUERY
NO> instruction appears in the B<CFG>I<_device_name> file, or if the issuer
of the butc command included the B<-noautoquery> flag, the Tape
Coordinator instead expects the tape to be in the device already. If
it is not, the Tape Coordinator invokes the B<MOUNT> instruction or
prompts the operator. It also invokes the B<MOUNT> instruction or prompts
for any additional tapes needed to complete the dump operation; the
issuer must arrange to provide them.
=head1 OPTIONS
=over 4
=item B<-volumeset> I<volume set name>
Names the volume set to dump. The B<-dump> argument must be
provided along with this one; do not combine them with the
B<-file> argument. If using a temporary volume set, the C<vos dump>
command must be issued within the interactive session in which
the C<backup addvolset> command was issued with the B<-temporary>
flag.
=item B<-dump> I<dump level name>
Specifies the complete pathname of the dump level at which to
dump the volume set. The B<-volumeset> argument must be provided
along with this one; do not combine them with the B<-file>
argument.
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation. It must be provided
unless the default value of 0 (zero) is appropriate; do not
combine it with the B<-file> argument.
=item B<-at> I<Date/time to start dump> ...
Specifies the date and time in the future at which to run the
command, or to read the file named by the B<-file> argument.
Provide a value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>], where the
month (I<mm>), day (I<dd>), and year (I<yyyy>) are required. Valid
values for the year range from B<1970> to B<2037>; higher values are
not valid because the latest possible date in the standard UNIX
representation is in February 2038. The Backup System
automatically reduces any later date to the maximum value.
The hour and minutes (I<hh>:I<MM>) are optional, but if provided must
be in 24-hour format (for example, the value B<14:36> represents
2:36 p.m.). If omitted, the time defaults to midnight (00:00
hours).
As an example, the value B<04/23/1999 20:20> schedules the command
for 8:20 p.m. on 23 April 1999.
=over
=item B<Note:>
A ... follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition.
=back
=item B<-append>
Appends the dump onto the end of a tape that already contains
data from another dump. However, if the tape is not in fact
part of an existing dump set, the Backup System creates a new
dump set using the parameters of this dump. If the tape is not
the last tape in the dump set, the Tape Coordinator prompts for
insertion of the appropriate tape. Do not combine this argument
with the B<-file> argument.
=item B<-n>
Displays the names of volumes to be included in the indicated
dump, without actually performing the dump operation. Do not
combine this argument with the B<-file> argument.
=item B<-file> I<load file>
Specifies the local disk or AFS pathname of a file containing
C<backup> commands. The Backup System reads the file immediately,
or at the time specified by the B<-at> argument if it is provided.
A partial pathname is interpreted relative to the current
working directory.
Place each C<backup dump> command on its own line in the indicated
file, using the same syntax as for the command line, but
without the word B<backup> at the start of the line. Each command
must include a value for the B<-volumeset> and B<-dump> arguments,
and for the B<-portoffset> argument unless the default value of 0
is appropriate. Commands in the file can also include any of
the C<backup dump> command's optional options. In the following
example file, the first command runs as soon as the Backup
System reads the file, whereas the other commands are
themselves scheduled; the specified date and time must be later
than the date and time at which the Backup System reads the
file.
dump user /sunday1/wednesday -port 1
dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999
dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append
Do not combine this argument with the B<-volumeset>, B<-dump>,
B<-portoffset>, B<-append>, or B<-n> options.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The command interpreter first generates a list of the volumes to be
included in the dump by matching the entries in the volume set against
the volumes listed in the Volume Location Database (VLDB). It prints
the list following the header:
Preparing to dump the following volumes:
The following message then indicates that the command interpreter has
passed the dump request to the appropriate Tape Coordinator for
processing:
Starting dump.
If the issuer includes the B<-n> flag, the output is of the following
form:
Starting dump of volume set 'volume set' (dump set 'dump level')
Total number of volumes : number dumped
Would have dumped the following volumes:
list_of_volumes
where list_of_volumes identifies each volume by name and volume ID
number.
If the Tape Coordinator is unable to access a volume, it prints an
error message in its window and records the error in its log and error
files.
=head1 EXAMPLES
The following command dumps the volumes in the volume set called user
at the dump level B</full/sunday2/monday>. The issuer places the
necessary tapes in the device with port offset 5.
backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
Preparing to dump the following volumes:
user.jones.backup 387623900
user.pat.backup 486219245
user.smith.backup 597315841
. .
. .
Starting dump.
The following command displays the list of volumes to be dumped when
the user dumps the B<sys_sun> volume set at the B</full> dump level.
backup dump -volumeset sys_sun -dump /full -n
Starting dump of volume set 'sys_sun' (dump set '/full')
Total number of volumes: 24
Would have dumped the following volumes:
sun4x_56 124857238
sun4x_56.bin 124857241
. .
. .
sun4x_55 124857997
. .
. .
The following command schedules a dump of the volumes in the volume
set B<user> at the dump level B</sunday2/monday1> for 11:00 p.m. on 14 June
1999. The appropriate Tape Coordinator has port offset 0 (zero), so
that argument is omitted.
backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server or Volume Location (VL) Server is
running, and on every file server machine that houses an affected
volume. If the B<-localauth> flag is included, the issuer must instead be
logged on to a server machine as the local superuser B<root>.
=head1 CAVEATS
If a dump operation is interrupted or fails for any reason, data from
all volumes written to tape before the interrupt are valid can be used
in a restore operation. The Backup Database includes an entry for the
failed dump and for each volume that was successfully dumped. See the
IBM AFS Administration Guide for information on dealing with
interrupted dumps.
If dumping to tape rather than a backup data file, it is best to use
only compatible tape devices (ones that can read the same type of
tape). Using compatible devices greatly simplifies restore operations.
The B<-portoffset> argument to the C<backup diskrestore> and C<backup
volsetrestore> commands accepts multiple port offset numbers, but the
Backup System uses the first listed port offset when restoring all
full dumps, the second port offset when restoring all level 1 dumps,
and so on. At the very least, use compatible tape devices to perform
dumps at each level. If compatible tape devices are not used, the
C<backup volrestore> command must be used to restore one volume at a
time.
Valid (unexpired) administrative tokens must be available to the
C<backup> command interpreter both when it reads the file named by the
B<-file> argument and when it runs each operation listed in the file.
Presumably, the issuer is scheduling dumps for times when no human
operator is present, and so must arrange for valid tokens to be
available on the local machine. One option is to issue all commands
(or run all scripts) on file server machines and use the B<-localauth>
flag on the C<backup> and C<vos> commands. To protect against improper
access to the machine or the tokens, the machine must be physically
secure (perhaps even more protected than a Tape Coordinator machine
monitored by a human operator during operation). Also, if an
unattended dump requires multiple tapes, the operator must properly
configure a tape stacker or jukebox and the device configuration file.
When the command is issued in regular (non-interactive) mode, the
command shell prompt does not return until the dump operation
completes. To avoid having to open additional connections, issue the
command in interactive mode, especially when including the B<-at>
argument to schedule dump operations.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_adddump(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_diskrestore(1)>,
L<backup_labeltape(1)>,
L<backup_volrestore(1)>,
L<butc(1)>
=cut

427
doc/man-pages/pod/backup_dumpinfo.pod Normal file
View File

@ -0,0 +1,427 @@
=head1 NAME
backup dumpinfo - Displays a dump record from the Backup Database
=head1 SYNOPSIS
backup dumpinfo [B<-ndumps> I<no. of dumps>] [B<-id> I<dump id>]
[B<-verbose>] [B<-localauth>] [B<-cell> I<cell name>] [B<-help> ]
backup dumpi [B<-n> I<no. of dumps>] [B<-i> I<dump id>]
[B<-v>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup dumpinfo> command formats and displays the Backup Database
record for the specified dumps. To specify how many of the most recent
dumps to display, starting with the newest one and going back in time,
use the B<-ndumps> argument. To display more detailed information about a
single dump, use the B<-id> argument. To display the records for the 10
most recent dumps, omit both the B<-ndumps> and B<-id> arguments.
The B<-verbose> flag produces very detailed information that is useful
mostly for debugging purposes. It can be combined only with the B<-id>
argument.
=head1 OPTIONS
=over 4
=item B<-ndumps> I<no. of dumps>
Displays the Backup Database record for each of the specified
number of dumps that were most recently performed. If the
database contains fewer dumps than are requested, the output
includes the records for all existing dumps. Do not combine
this argument with the B<-id> or B<-verbose> options; omit all
options to display the records for the last 10 dumps.
=item B<-id> I<dump id>
Specifies the dump ID number of a single dump for which to
display the Backup Database record. Precede the I<dump id> value
with the B<-id> switch; otherwise, the command interpreter
interprets it as the value of the B<-ndumps> argument. Combine
this argument with the B<-verbose> flag, but not with the B<-ndumps>
argument; omit all options to display the records for the last
10 dumps.
=item B<-verbose>
Provides more detailed information about the dump specified
with the B<-id> argument, which must be provided along with it. Do
not combine this flag with the B<-ndumps> argument.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
If the B<-ndumps> argument is provided, the output presents the following
information in table form, with a separate line for each dump:
=over
=item B<dumpid>
The dump ID number.
=item B<parentid>
The dump ID number of the dump's parent dump. A value of 0
(zero) identifies a full dump.
=item B<lv>
The depth in the dump hierarchy of the dump level used to
create the dump. A value of 0 (zero) identifies a full dump, in
which case the value in the C<parentid> field is also 0. A value
of 1 or greater indicates an incremental dump made at the
corresponding level in the dump hierarchy.
=item B<created>
The date and time at which the Backup System started the dump
operation that created the dump.
=item B<nt>
The number of tapes that contain the data in the dump. A value
of 0 (zero) indicates that the dump operation was terminated or
failed. Use the C<backup deletedump> command to remove such
entries.
=item B<nvols>
The number of volumes from which the dump includes data. If a
volume spans tapes, it is counted twice. A value of 0 (zero)
indicates that the dump operation was terminated or failed; the
value in the nt field is also 0 in this case.
=item B<dump name>
The dump name in the form
I<volume_set_name>.I<dump_level_name> (I<initial_dump_ID>)
where I<volume_set_name> is the name of the volume set, and
I<dump_level_name> is the last element in the dump level pathname
at which the volume set was dumped.
The I<initial_dump_ID>, if displayed, is the dump ID of the
initial dump in the dump set to which this dump belongs. If
there is no value in parentheses, the dump is the initial dump
in a dump set that has no appended dumps.
=back
If the B<-id> argument is provided alone, the first line of output begins
with the string C<Dump> and reports information for the entire dump in
the following fields:
=over
=item B<id>
The dump ID number.
=item B<level>
The depth in the dump hierarchy of the dump level used to
create the dump. A value of 0 (zero) identifies a full dump. A
value of 1 (one) or greater indicates an incremental dump made
at the specified level in the dump hierarchy.
=item B<volumes>
The number of volumes for which the dump includes data.
=item B<created>
The date and time at which the dump operation began.
=back
If an XBSA server was the backup medium for the dump (rather than a
tape device or backup data file), the following line appears next:
Backup Service: I<XBSA_program>: Server: I<hostname>
where I<XBSA_program> is the name of the XBSA-compliant program and
I<hostname> is the name of the machine on which the program runs.
Next the output includes an entry for each tape that houses volume
data from the dump. Following the string C<Tape>, the first two lines of
each entry report information about that tape in the following fields:
=over
=item B<name>
The tape's permanent name if it has one, or its AFS tape name
otherwise, and its tape ID number in parentheses.
=item B<nVolumes>
The number of volumes for which this tape includes dump data.
=item B<created>
The date and time at which the Tape Coordinator began writing
data to this tape.
=back
Following another blank line, the tape-specific information concludes
with a table that includes a line for each volume dump on the tape.
The information appears in columns with the following headings:
=over
=item B<Pos>
The relative position of each volume in this tape or file. On a
tape, the counter begins at position 2 (the tape label occupies
position 1), and increments by one for each volume. For volumes
in a backup data file, the position numbers start with 1 and do
not usually increment only by one, because each is the ordinal
of the 16 KB offset in the file at which the volume's data
begins. The difference between the position numbers therefore
indicates how many 16 KB blocks each volume's data occupies.
For example, if the second volume is at position 5 and the
third volume in the list is at position 9, that means that the
dump of the second volume occupies 64 KB (four 16-KB blocks) of
space in the file.
=item B<Clone time>
For a backup or read-only volume, the time at which it was
cloned from its read/write source. For a Read/Write volume, it
is the same as the dump creation date reported on the first
line of the output.
=item B<Nbytes>
The number of bytes of data in the dump of the volume.
=item B<Volume>
The volume name, complete with C<.backup> or C<.readonly> extension
if appropriate.
=back
If both the B<-id> and B<-verbose> options are provided, the output is
divided into several sections:
=over
=item *
The first section, headed by the underlined string C<Dump>, includes
information about the entire dump. The fields labeled C<id>, C<level>,
C<created>, and C<nVolumes> report the same values (though in a
different order) as appear on the first line of output when the
B<-id> argument is provided by itself. Other fields of potential
interest to the backup operator are:
=over
=item B<Group id>
The dump's I<group ID number>, which is recorded in the
dump's Backup Database record if the B<GROUPID> instruction
appears in the Tape Coordinator's
B</usr/afs/backup/CFG_>I<tcid> file when the dump is created.
=item B<maxTapes>
The number of tapes that contain the dump set to which
this dump belongs.
=item B<Start Tape Seq>
The ordinal of the tape on which this dump begins in the
set of tapes that contain the dump set.
=back
=item *
For each tape that contains data from this dump, there follows a
section headed by the underlined string C<Tape>. The fields labeled
C<name>, C<written>, and C<nVolumes> report the same values (though in a
different order) as appear on the second and third lines of output
when the B<-id> argument is provided by itself. Other fields of
potential interest to the backup operator are:
=over
=item B<expires>
The date and time when this tape can be recycled, because
all dumps it contains have expired.
=item B<nMBytes Data and nBytes Data>
Summed together, these fields represent the total amount
of dumped data actually from volumes (as opposed to
labels, filemarks, and other markers).
=item B<KBytes Tape Used>
The number of kilobytes of tape (or disk space, for a
backup data file) used to store the dump data. It is
generally larger than the sum of the values in the
C<nMBytes> Data and C<nBytes> Data fields, because it includes
the space required for the label, file marks and other
markers, and because the Backup System writes data at 16
KB offsets, even if the data in a given block doesn't
fill the entire 16 KB.
=back
=item *
For each volume on a given tape, there follows a section headed by
the underlined string C<Volume>. The fields labeled C<name>, C<position>,
C<clone>, and C<nBytes> report the same values (though in a different
order) as appear in the table that lists the volumes in each tape
when the B<-id> argument is provided by itself. Other fields of
potential interest to the backup operator are:
=over
=item B<id>
The volume ID.
=item B<tape>
The name of the tape containing this volume data.
=back
=back
=head1 EXAMPLES
The following example displays information about the last five dumps:
backup dumpinfo -ndumps 5
dumpid parentid lv created nt nvols dump name
924424000 0 0 04/18/1999 04:26 1 22 usr.sun (924424000)
924685000 924424000 1 04/21/1999 04:56 1 62 usr.wed (924424000)
924773000 924424000 1 04/22/1999 05:23 1 46 usr.thu (924424000)
924860000 924424000 1 04/23/1999 05:33 1 58 usr.fri (924424000)
925033000 0 0 04/25/1999 05:36 2 73 sys.week
The following example displays a more detailed record for a single
dump.
backup dumpinfo -id 922097346
Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
Tape: name monday.user.backup (922097346)
nVolumes 1, created 03/22/1999 05:09
Pos Clone time Nbytes Volume
1 03/22/1999 04:43 27787914 user.pat.backup
The following example displays even more detailed information about
the dump displayed in the previous example (dump ID 922097346). This
example includes only one exemplar of each type of section (C<Dump>,
C<Tape>, and C<Volume>):
backup dumpinfo -id 922097346 -verbose
Dump
----
id = 922097346
Initial id = 0
Appended id = 922099568
parent = 0
level = 0
flags = 0x0
volumeSet = user
dump path = /monday1
name = user.monday1
created = Mon Mar 22 05:09:06 1999
nVolumes = 1
id = 0
tapeServer =
format= user.monday1.%d
maxTapes = 1
Start Tape Seq = 1
name = pat
instance =
cell =
Tape
----
tape name = monday.user.backup
AFS tape name = user.monday1.1
flags = 0x20
written = Mon Mar 22 05:09:06 1999
expires = NEVER
kBytes Tape Used = 121
nMBytes Data = 0
nBytes Data = 19092
nFiles = 0
nVolumes = 1
seq = 1
tapeid = 0
useCount = 1
dump = 922097346
Volume
------
name = user.pat.backup
flags = 0x18
id = 536871640
server =
partition = 0
nFrags = 1
position = 2
clone = Mon Mar 22 04:43:06 1999
startByte = 0
nBytes = 19092
seq = 0
dump = 922097346
tape = user.monday1.1
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_deletedump(1)>
=cut

95
doc/man-pages/pod/backup_help.pod Normal file
View File

@ -0,0 +1,95 @@
=head1 NAME
backup help - Displays the syntax of specified C<backup> commands or lists functional
descriptions of all C<backup> commands
=head1 SYNOPSIS
backup help [B<-topic> I<help string> [I<help string> ...]] [B<-help>]
backup h [B<-t> I<help string> [I<help string> ...]] [B<-h>]
=head1 DESCRIPTION
The C<backup help> command displays the complete online help entry (short
description and syntax statement) for each operation code specified by
the B<-topic> argument. If the B<-topic> argument is omitted, the output
includes the first line (name and short description) of the online
help entry for every C<backup> command.
To list every C<backup> command whose name or short description includes
a specified keyword, use the C<backup apropos> command.
=head1 OPTIONS
=over 4
=item B<-topic> I<help string> [I<help string> ...]
Indicates each command for which to display the complete online
help entry. Omit the C<backup> part of the command name, providing
only the operation code (for example, specify C<dump>, not C<backup
dump>). If this argument is omitted, the output briefly
describes every C<backup> command.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The online help entry for each C<backup> command consists of the
following two or three lines:
=over
=item *
The first line names the command and briefly describes its
function.
=item *
The second line lists aliases for the command, if any.
=item *
The final line, which begins with the string C<Usage>, lists the
command's options in the prescribed order. Online help entries use
the same symbols (for example, brackets) as the reference pages in
this document.
=back
=head1 EXAMPLES
The following example displays the online help entry for the C<backup
dump> command:
backup help dump
backup dump: start dump
Usage: backup dump -volumeset <volume set name> -dump <dump level name>
[-portoffset <TC port offset>] [-at <Date/time to start dump>+]
[-append] [-n] [-file <load file>] [-help]
=head1 PRIVILEGE REQUIRED
None
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_apropos(1)>
=cut

121
doc/man-pages/pod/backup_interactive.pod Normal file
View File

@ -0,0 +1,121 @@
=head1 NAME
backup interactive - Enters interactive mode
=head1 SYNOPSIS
backup [interactive] [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup [i] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup interactive> initiates an interactive session for issuing
C<backup> commands. As indicated in the syntax statement, the operation
code (C<interactive>) is optional.
Several features of interactive mode distinguish it from regular mode:
=over
=item *
In interactive mode, the C<backupE<gt>> prompt replaces the system
(shell) prompt. The operator enters only a command's operation
code (omitting the command suite name, C<backup>).
=item *
If the B<-localauth> flag or the B<-cell> argument is included on the
C<backup (interactive)> command, the settings apply to all commands
issued during that interactive session. The issuer does not need
to type them on every command. Another consequence is that the
flag and argument do not appear in the syntax statement generated
by the C<help> subcommand or B<-help> flag on an individual command
issued at the C<backupE<gt>> prompt.
=item *
The C<(backup) jobs> and C<(backup) kill> commands are available only in
interactive mode. It is not possible to track and terminate backup
operations as cleanly in non-interactive mode.
=item *
It is not necessary to enclose strings that include metacharacters
in double quotes or other delimiters.
=item *
The C<backup> command interpreter establishes a connection to the
Backup Server, Volume Server and Volume Location (VL) Server
processes as it enters interactive mode, and uses the same
connection for all commands during the session. Execution time can
therefore be faster than in non-interactive mode, in which the
command interpreter must establish a new connection for each
command.
=back
To exit an interactive session, issue the C<(backup) quit> command.
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)> reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following example shows how the B<-localauth> flag and B<-cell> argument
do not appear when the C<help dump> subcommand is issued in interactive
mode.
backup
backup> help dump
dump: start dump
Usage: dump [-volumeset <volume set name>] [-dump <dump level name>]
[-portoffset <TC port offset>] [-at <Date/time to start dump>+]
[-append ] [-n ] [-file <load file>] [-help ]
=head1 PRIVILEGE REQUIRED
None. However, C<backup> commands that require privilege in regular mode
still require it in interactive mode.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_jobs(1)>,
L<backup_kill(1)>,
L<backup_quit(1)>,
L<butc(1)>
=cut

229
doc/man-pages/pod/backup_jobs.pod Normal file
View File

@ -0,0 +1,229 @@
=head1 NAME
backup jobs - Lists pending and running operations in interactive mode
=head1 SYNOPSIS
jobs [B<-help>]
j [B<-h>]
=head1 DESCRIPTION
The C<(backup) jobs> command lists the job ID number and status of each
B<backup> operation running or pending in the current interactive
session.
This command can be issued in interactive mode only. If the issuer of
the C<backup (interactive)> command included the B<-localauth> flag, the
B<-cell> argument, or both, those settings apply to this command also.
To terminate operations that appear in the output, issue the C<(backup)
kill> command and identify the operation to cancel with the job ID
number from this command's output.
To check the status of a Tape Coordinator, rather than of a certain
operation, use the C<backup status> command.
=head1 OPTIONS
=over 4
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The output always includes the expiration date and time of the tokens
that the C<backup> command interpreter is using during the current
interactive session, in the following format:
I<date> I<time>: TOKEN EXPIRATION
If the execution date and time specified for a scheduled dump
operation is later than I<date time>, then its individual line (as
described in the following paragraphs) appears below this line to
indicate that the current tokens will not be available to it.
If the issuer of the C<backup> command included the B<-localauth> flag when
entering interactive mode, the line instead reads as follows:
: TOKEN NEVER EXPIRES
The entry for a scheduled dump operation has the following format:
Job I<job_ID>: I<timestamp>: dump I<volume_set> I<dump_level>
where
=over
=item B<I<job_ID>>
Is a job identification number assigned by the Backup System.
=item B<I<timestamp>>
Indicates the date and time the dump operation is to begin, in
the format I<month>/I<date>/I<year> I<hours>:I<minutes> (in 24-hour format)
=item B<I<volume_set>>
Indicates the volume set to dump.
=item B<I<dump_level>>
Indicates the dump level at which to perform the dump
operation.
=back
The line for a pending or running operation of any other type has the
following format:
Job I<job_ID>: I<operation> I<status>
where
=over
=item B<I<job_ID>>
Is a job identification number assigned by the Backup System.
=item B<I<operation>>
Identifies the operation the Tape Coordinator is performing,
which is initiated by the indicated command:
=over
=item B<C<Dump> (I<dump name>)>
Initiated by the C<backup dump> command. The I<dump name> has
the following format:
I<volume_set_name>.I<dump_level_name>
=item B<C<Restore>>
Initiated by the C<backup diskrestore>, C<backup volrestore>,
or C<backup volsetrestore> command.
=item B<C<Labeltape> (I<tape_label>)>
Initiated by the C<backup labeltape> command. The I<tape_label>
is the name specified by the C<backup labeltape> command's
B<-name> or B<-pname> argument.
=item B<C<Scantape>>
Initiated by the C<backup scantape> command.
=item B<C<SaveDb>>
Initiated by the C<backup savedb> command.
=item B<C<RestoreDb>>
Initiated by the C<backup restoredb> command.
=back
=item B<I<status>>
Indicates the job's current status in one of the following
messages. If no message appears, the job is either still
pending or has finished.
=over
=item B<I<number> Kbytes, volume I<volume_name>>
For a running dump operation, indicates the number of
kilobytes copied to tape or a backup data file so far,
and the volume currently being dumped.
=item B<I<number> Kbytes, restore.volume>
For a running restore operation, indicates the number of
kilobytes copied into AFS from a tape or a backup data
file so far.
=item B<[abort requested]>
The C<(backup) kill> command was issued, but the termination
signal has yet to reach the Tape Coordinator.
=item B<[abort sent]>
The operation is canceled by the C<(backup) kill> command.
Once the Backup System removes an operation from the
queue or stops it from running, it no longer appears at
all in the output from the command.
=item B<[butc contact lost]>
The C<backup> command interpreter cannot reach the Tape
Coordinator. The message can mean either that the Tape
Coordinator handling the operation was terminated or
failed while the operation was running, or that the
connection to the Tape Coordinator timed out.
=item B<[done]>
The Tape Coordinator has finished the operation.
=item B<[drive wait]>
The operation is waiting for the specified tape drive to
become free.
=item B<[operator wait]>
The Tape Coordinator is waiting for the backup operator
to insert a tape in the drive.
=back
=back
=head1 EXAMPLES
The following example shows that two restore operations and one dump
operation are running (presumably on different Tape Coordinators) and
that the C<backup> command interpreter's tokens expire on 22 April 1999
at 10:45 am:
backup> jobs
Job 1: Restore, 1306 Kbytes, restore.volume
Job 2: Dump (user.sunday1), 34 Kbytes, volume user.pat.backup
Job 3: Restore, 2498 Kbytes, restore.volume
04/22/1999 10:45: TOKEN EXPIRATION
=head1 PRIVILEGE REQUIRED
None. However, queuing any operation requires privilege, and it is
possible to issue this command only within the interactive session in
which the jobs are queued.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_interactive(1)>,
L<backup_kill(1)>,
L<backup_quit(1)>
=cut

165
doc/man-pages/pod/backup_kill.pod Normal file
View File

@ -0,0 +1,165 @@
=head1 NAME
backup kill - Terminates a pending or running operation
=head1 SYNOPSIS
kill B<-id> I<job ID or dump set name> [B<-help>]
k B<-i> I<job ID or dump set name> [B<-h>]
=head1 DESCRIPTION
The C<(backup) kill> command dequeues a Backup System operation that is
pending, or terminates an operation that is running, in the current
interactive session. It is available only in interactive mode. If the
issuer of the C<backup (interactive)> command included the B<-localauth>
flag, the B<-cell> argument, or both, then those settings apply to this
command also.
To terminate a dump operation, specify either the dump name
(I<volume_set_name>.I<dump_level_name>) or its job ID number, which appears
in the output from the C<(backup) jobs> command. To terminate any other
type of operation, provide the job ID number.
The effect of terminating an operation depends on the type and current
state of the operation:
=over
=item *
If an operation is still pending, the Tape Coordinator removes it
from the queue with no other lasting effects.
=item *
If the Tape Coordinator is unable to process the termination
signal before an operation completes, it simply confirms the
operation's completion. The operator must take the action
necessary to undo the effects of the incorrect operation.
=item *
If a tape labeling operation is running, the effect depends on
when the Tape Coordinator receives the termination signal. The
labeling operation is atomic, so it either completes or does not
begin at all. Use the C<backup readlabel> command to determine if the
labeling operation completed, and reissue the C<backup labeltape>
command to overwrite the incorrect label if necessary.
=item *
If a tape scanning operation is running, it terminates with no
other effects unless the B<-dbadd> flag was included on the C<backup>
command. In that case, the Backup System possibly has already
written new Backup Database records to represent dumps on the
scanned tape. If planning to restart the scanning operation, first
locate and remove the records created during the terminated
operation: a repeated C<backup scantape> operation exits
automatically when it finds that a record that it needs to create
already exists.
=item *
If a dump operation is running, all of the volumes written to the
tape or backup data file before the termination signal is received
are complete and usable. If the operation is restarted, the Backup
System performs all the dumps again from scratch, and assigns a
new dump ID number. If writing the new dumps to the same tape or
file, the operator must relabel it first if the interrupted dump
is not expired. If writing the new dump to a different tape or
file, the operator can remove the dump record associated with the
interrupted dump to free up space in the database.
=item *
If a restore operation is running, completely restored volumes are
online and usable. However, it is unlikely that many volumes are
completely restored, given that complete restoration usually
requires data from multiple tapes. If the termination signal comes
before the Backup System has accessed all of the necessary tapes,
each volume is only partially written and is never brought online.
It is best to restart the restore operation from scratch to avoid
possible inconsistencies. See also the L</"CAVEATS"> section.
=back
=head1 OPTIONS
=over 4
=item B<-id> I<job ID or dump set name>
Identifies the backup operation to terminate. Provide one of
two types of values:
=over
=item *
The operation's job ID number, as displayed in the output of
the C<(backup) jobs> command.
=item *
For a dump operation, either the job ID number or a dump name
of the form I<volume_set_name>.I<dump_level_name>, where
I<volume_set_name> is the name of the volume set being dumped
and I<dump_level_name> is the last element in the dump level
pathname at which the volume set is being dumped. The dump
name appears in the output of the C<(backup) jobs> command along
with the job ID number.
=back
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command terminates the operation with job ID 5:
backup> kill 5
The following command terminates the dump operation called
B<user.sunday1>:
backup> kill user.sunday1
=head1 PRIVILEGE REQUIRED
The issuer must have the privilege required to initiate the operation
being cancelled. Because this command can be issued only within the
interactive session during which the operation was initiated, the
required privilege is essentially guaranteed.
=head1 CAVEATS
It is best not to issue the C<(backup) kill> command against restore
operations. If the termination signal interrupts a restore operation
as the Backup System is overwriting an existing volume, it is possible
to lose the volume entirely (that is, to lose both the contents of the
volume as it was before the restore and any data that was restored
before the termination signal arrived). The data being restored still
exists on the tape, but some data can be lost permanently.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_interactive(1)>,
L<backup_jobs(1)>
=cut

228
doc/man-pages/pod/backup_labeltape.pod Normal file
View File

@ -0,0 +1,228 @@
=head1 NAME
backup labeltape - Creates the magnetic label on a tape
=head1 SYNOPSIS
backup labeltape [B<-name> I<AFS tape name, defaults to NULL>]
[B<-size> I<tape size in Kbytes, defaults to size in tapeconfig>]
[B<-portoffset> I<TC port offset>]
[B<-pname> I<permanent tape name>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup la [B<-n> I<AFS tape name, defaults to NULL>]
[B<-s> I<tape size in Kbytes, defaults to size in tapeconfig>]
[B<-po> I<TC port offset>] [B<-pn> I<permanent tape name>]
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup labeltape> command creates a magnetic label, readable by the
Backup System, at the beginning of a tape. The label records the
tape's name (either a I<permanent name>, or an I<AFS tape name> that
reflects the tape's contents in a prescribed format) and its capacity.
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file on the Tape Coordinator machine
associated with the specified port offset, then the C<backup> command
writes label information to the first 16 KB block in the backup data
file listed for that port offset in the Tape Coordinator's
B</usr/afs/backup/tapeconfig> file, rather than at the beginning of a
tape. For the sake of clarity, the following text refers to tapes
only, but the Backup System handles backup data files in much the same
way.)
Relabeling a tape that already contains AFS backup data effectively
makes the data unusable, because the command removes the Backup
Database record of the complete dump set of which the tape is a part.
Use this command to enable recycling of a tape that contains unexpired
dumps that are not actually still needed.
To write a permanent name on the label, include the B<-pname> argument to
specify a string of up to 32 characters. The permanent name persists
until the B<-pname> argument is again included on the C<backup labeltape>
command, regardless of the tape's contents and of how often the tape
is otherwise relabeled or recycled. Include this argument or the B<-name>
argument, but not both. If this argument is included, the AFS tape
name is set to C<E<lt>NULLE<gt>>. The permanent name is set to C<E<lt>NULLE<gt>> if this
argument is omitted and no permanent name already exists.
The issuer must ensure that a permanent name is unique among the tapes
used for AFS backup in the cell, because the C<backup> command
interpreter does not verify that another tape does not already have
the same permanent name. When a tape has a permanent name, the Backup
System uses it instead of the AFS tape name in most prompts and when
referring to the tape in output from C<backup> commands. The permanent
name appears in the C<tape name> field of the output from the C<backup
readlabel> command.
To write an AFS tape name on the label, provide a value for the B<-name>
argument in the required format described in the L</"OPTIONS"> section.
Include the B<-name> argument or the B<-pname> argument, but not both. If
this argument is omitted, the AFS tape name is set to C<E<lt>NULLE<gt>>, but the
Backup System automatically assigns the appropriate name when the tape
is used in a future C<backup dump> or C<backup savedb> operation. The AFS
tape name appears in the AFS C<tape name> field of the output from the
C<backup readlabel> and C<backup scantape> commands.
The C<backup> command interpreter does not accept the B<-name> argument if
the tape already has a permanent name. To erase a tape's permanent
name, provide a null value to the B<-pname> argument by issuing the
following command:
% backup labeltape -pname ""
To record the tape's capacity on the label, specify a number of
kilobytes as the B<-size> argument. If the argument is omitted the first
time a tape is labeled, the Backup System records the default tape
capacity recorded for the specified port offset in the
B</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine.
Subsequently, the value in the size field persists until the B<-size>
argument is again included on the C<backup labeltape> command.
To determine how much data can be written to a tape during a C<backup
dump> or C<backup savedb> operation, the Tape Coordinator reads the
capacity recorded on the tape's label (or uses the value associated
with its port offset in the B</usr/afs/backup/tapeconfig> file, if the
tape was never labeled). For further description, see the L<backup_dump(1)>
reference page.
The Tape Coordinator's default response to this command is to access
the tape by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the C<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, the Tape Coordinator invokes the B<MOUNT>
instruction or prompts the operator.
=head1 OPTIONS
=over 4
=item B<-name> I<AFS tape name, defaults to NULL>
Specifies the AFS tape name to record on the label. Include
this argument or the B<-pname> argument, but not both. If this
argument is omitted, the AFS tape name is set to C<E<lt>NULLE<gt>>. If
this argument is provided, it must have the following format:
I<volume_set_name>.I<dump_level_name>.I<tape_index>
for the tape to be acceptable for use in a future C<backup dump>
operation. The I<volume_set_name> must match the volume set name
of the initial dump to be written to the tape, I<dump_level_name>
must match the last element of the dump level pathname at which
the volume set will be dumped, and I<tape_index> indicates the
order of the tape in the dump set (indexing begins with B<1>). To
disable this type of name checking, include the B<NAME_CHECK NO>
instruction in the B<CFG_>I<device_name> file.
For the tape to be acceptable for use in a future C<backup savedb>
operation, the value specified for the B<-name> argument must have
the following format:
I<Ubik_db_dump>.I<tape_index>
where I<tape_index> indicates the order of the tape in the set of
tapes that house the Backup Database dump; indexing begins with
1 (one).
=item B<-size> I<tape size in Kbytes, defaults to size in tapeconfig>
Specifies the tape capacity to record on the label. Provide an
integer value followed by a letter that indicates units, with
no intervening space. A unit value of B<k> or B<K> indicates
kilobytes, B<m> or B<M> indicates megabytes, and B<g> or B<G> indicates
gigabytes. If the units letter is omitted, the default is
kilobytes.
If this argument is omitted the first time a tape is labeled,
the Backup System records the capacity that is associated with
the specified port offset in the B</usr/afs/backup/tapeconfig>
file on the Tape Coordinator machine. The value recorded the
first time then persists until the B<-size> argument is provided
on a future issuance of the command.
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator
handling the tape for this operation.
=item B<-pname> I<permanent tape name>
Specifies the permanent name to record on the label. It can be
up to 32 characters in length, and include any alphanumeric
characters. Avoid metacharacters that have a special meaning to
the shell, to avoid having to mark them as literal in commands
issued at the shell prompt.
Include this argument or the B<-name> argument, but not both. If
this argument is provided, the AFS tape name is set to C<E<lt>NULLE<gt>>.
If this argument is omitted, any existing permanent name is
retained.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command records the AFS tape name B<user.monthly.1> on the
label of the tape in the device with port offset 3:
backup labeltape -name user.monthly.1 -portoffset 3
The following three commands are equivalent in effect: they all record
a capacity of 2 GB on the label of the tape in the device with port
offset 4. They set the AFS tape name to C<E<lt>NULLE<gt>> and leave the permanent
name unchanged.
backup labeltape -size 2g -portoffset 4
backup labeltape -size 2048M -portoffset 4
backup labeltape -size 2097152 -portoffset 4
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<CFG_device_name(1)>,
L<backup(1)>,
L<backup_readlabel(1)>,
L<butc(1)>
=cut

135
doc/man-pages/pod/backup_listdumps.pod Normal file
View File

@ -0,0 +1,135 @@
=head1 NAME
backup listdumps - Displays the dump hierarchy from the Backup Database
=head1 SYNOPSIS
backup listdumps [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup listd [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup listdumps> command displays the dump hierarchy from the
Backup Database.
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The output displays the complete dump hierarchy and indicates the
relationship between full and incremental dump levels. Full dump
levels appear at the left margin. The hierarchy can include more than
one full dump level; each one defines a subhierarchy of dump levels
that can be used for dumping different volume sets.
Incremental dump levels appear below and indented to the right of
their parent dump levels, which can be either full or incremental.
Since multiple incremental dump levels can share the same parent, an
incremental dump level is not always directly below its parent; the
amount of indentation indicates the parent/child relationship.
If a dump level has an associated expiration date, it appears along
with the level name. Absolute expiration dates appear in the format
I<dump_level> expires at I<day> I<month> I<date> I<time> I<year>
and relative expiration dates in the format
I<dump_level> expires in {I<years>y | I<months>m | I<days>d}
to indicate the number of years, months, days, or combination of the
three after creation a dump expires when created at this level.
=head1 EXAMPLES
The following example depicts six dump hierarchies. The expiration
date for all incremental dump levels is 13 days so that the
corresponding tapes can be recycled two weeks after their creation.
The expiration dates for all full dump levels is 27 days so that the
corresponding tapes can be recycled four weeks after their creation.
backup listdumps
/week1 expires in 27d
/tuesday expires in 13d
/thursday expires in 13d
/sunday expires in 13d
/tuesday expires in 13d
/thursday expires in 13d
/week3 expires in 27d
/tuesday expires in 13d
/thursday expires in 13d
/sunday expires in 13d
/tuesday expires in 13d
/thursday expires in 13d
/sunday1 expires in 27d
/monday1 expires in 13d
/tuesday1 expires in 13d
/wednesday1 expires in 13d
/thursday1 expires in 13d
/friday1 expires in 13d
/sunday2 expires in 27d
/monday2 expires in 13d
/tuesday2 expires in 13d
/wednesday2 expires in 13d
/thursday2 expires in 13d
/friday2 expires in 13d
/sunday3 expires in 27d
/monday1 expires in 13d
/tuesday1 expires in 13d
/wednesday1 expires in 13d
/thursday1 expires in 13d
/friday1 expires in 13d
/sunday4 expires in 27d
/monday2 expires in 13d
/tuesday2 expires in 13d
/wednesday2 expires in 13d
/thursday2 expires in 13d
/friday2 expires in 13d
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_adddump(1)>,
L<backup_deldump(1)>
=cut

104
doc/man-pages/pod/backup_listhosts.pod Normal file
View File

@ -0,0 +1,104 @@
=head1 NAME
backup listhosts - Lists Tape Coordinator machines registered in the Backup Database
=head1 SYNOPSIS
backup listhosts [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup listh [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup listhosts> command displays the Backup Database record of
the port offset numbers defined for Tape Coordinator machines. A Tape
Coordinator must have an entry in the list to be available for backup
operations.
The existence of an entry does not necessarily indicate that the Tape
Coordinator process (B<butc>) is currently running at that port offset.
To check, issue the C<backup status> command.
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
After a C<Tape hosts:> header, the output reports two things about each
Tape Coordinator currently defined in the Backup Database:
=over
=item *
The hostname of the machine housing the Tape Coordinator. The
format of this name depends on the hostname format used when the
C<backup addhost> command was issued.
=item *
The Tape Coordinator's port offset number.
=back
The Tape Coordinators appear in the order in which they were added to
the Backup Database.
=head1 EXAMPLES
The following example shows the result of the command in the ABC
Corporation cell:
backup listhosts
Tape hosts:
Host backup1.abc.com, port offset 0
Host backup1.abc.com, port offset 1
Host backup3.abc.com, port offset 4
Host backup2.abc.com, port offset 3
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addhost(1)>,
L<backup_delhost(1)>,
L<backup_status(1)>
=cut

111
doc/man-pages/pod/backup_listvolsets.pod Normal file
View File

@ -0,0 +1,111 @@
=head1 NAME
backup listvolsets - Lists volume set entries from the Backup Database
=head1 SYNOPSIS
backup listvolsets [B<-name> I<volume set name>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup listv [B<-n> I<volume set name>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup listvolsets> command displays the Backup Database records
for either
=over
=item *
All volume sets and their volume entries, if the B<-name> argument is
omitted
=item *
The volume set specified by the B<-name> argument, along with its
volume entries
=back
=head1 OPTIONS
=over 4
=item B<-name> I<volume set name>
Names the volume set to display. If this argument is omitted,
the output lists all volume sets defined in the Backup
Database.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The entry for each volume set begins with the Volume set header and
the volume set's name. A temporary volume set's name is followed by
the string C<(temporary)>. Each volume entry follows on a separate line,
indicating the entry's index number and the server, partition, and
volume names it matches. The output uses the metacharacter notation
described on the L<backup_addvolentry(1)> reference page. Use the index
number to identify volume entries when deleting them with the C<backup
delvolentry> command.
=head1 EXAMPLES
The following example shows the volume entries in the three volume
sets currently defined in the Backup Database:
backup listvolsets
Volume set user:
Entry 1: server .*, partition .*, volumes: user.*\.backup
Volume set sun
Entry 1: server .*, partition .*, volumes: sun4x_55\..*
Entry 2: server .*, partition .*, volumes: sun4x_56\..*
Volume set rs
Entry 1: server .*, partition .*, volumes: rs_aix42\..*
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_delvolentry(1)>,
L<backup_delvolset(1)>
=cut

77
doc/man-pages/pod/backup_quit.pod Normal file
View File

@ -0,0 +1,77 @@
=head1 NAME
backup quit - Leaves interactive mode
=head1 SYNOPSIS
quit [B<-help>]
q [B<-h>]
=head1 DESCRIPTION
The C<(backup) quit> command exits interactive mode, returning the issuer
to the regular shell prompt at which the C<backup> or C<backup interactive>
command was issued to enter interactive mode. The command has no
effect when issued outside interactive mode. Issuing the <B<Ctrl-d>>
command also exits interactive mode.
=head1 OPTIONS
=over 4
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command exits interactive mode:
backup> quit
=head1 PRIVILEGE REQUIRED
None
=head1 CAVEATS
To exit interactive mode, all jobs must be completed. Use the C<(backup)
jobs> command to list any jobs currently pending or executing, and the
C<(backup) kill> command to terminate them as necessary.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_interactive(1)>,
L<backup_jobs(1)>,
L<backup_kill(1)>
=cut

242
doc/man-pages/pod/backup_readlabel.pod Normal file
View File

@ -0,0 +1,242 @@
=head1 NAME
backup readlabel - Reads and displays a tape's label
=head1 SYNOPSIS
backup readlabel [B<-portoffset> I<TC port offset>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup rea [B<-p> I<TC port offset>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup readlabel> command displays information from the magnetic
tape label of a tape. The information includes the tape's name (either
a I<permanent name>, or an I<AFS tape name> that reflects the tape's
contents in a prescribed format) and its capacity.
If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup readlabel> command reads the label
information from the first 16 KB block in the backup data file listed
for that port offset in the Tape Coordinator's
B</usr/afs/backup/tapeconfig> file, rather than from the beginning of a
tape.
The Tape Coordinator's default response to this command is to access
the tape by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the B<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, the Tape Coordinator invokes the B<MOUNT>
instruction or prompts the operator.
=head1 OPTIONS
=over 4
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
Output from this command appears in both the shell window where the
command is issued, and in the Tape Coordinator window.
If the tape is unlabeled or if the specified tape device is empty, the
output reads
Failed to read tape label.
Otherwise, the output in the shell window has the following format:
Tape read was labelled: tape name (dump id)
size: size Kbytes
where I<tape name> is the permanent name if the tape has one, or the AFS
tape name otherwise. The I<dump ID> is the dump ID of the initial dump on the
tape, and I<size> is the recorded capacity of the tape in kilobytes.
The output in the Tape Coordinator windows is bounded by an underlined
C<Tape label> header at the top, and the following string at the bottom:
-- End of tape label --
In between are lines reporting the following information:
=over
=item B<tape name>
The permanent name assigned by using the B<-pname> argument of the
C<backup labeltape> command. This name remains on the tape until
that argument is used again, no matter how many times the tape
is recycled or otherwise relabeled. If the tape does not have a
permanent name, the value C<E<lt>NULLE<gt>> appears in this field.
=item B<AFS tape name>
A tape name in one of the following prescribed formats. The
Backup System automatically writes the appropriate AFS tape
name to the label as part of a C<backup dump> or C<backup savedb>
operation, or the operator can assign it with the B<-name>
argument to the C<backup labeltape> command.
=over
=item *
I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape
contains volume data. The I<volume_set_name> is the name of the
volume set that was dumped to create the initial dump in the
dump set of to which this tape belongs; I<dump_level_name> is
the last pathname element of the dump level at which the
initial dump was backed up; and I<tape_index> is the numerical
position of the tape in the dump set.
=item *
C<Ubik.db.dump.>I<tape_index> if the tape contains a dump of the
Backup Database, created with the C<backup savedb> command. The
I<tape_index> is the ordinal of the tape in the dump set.
=item *
C<E<lt>NULLE<gt>> if the tape has no AFS tape name. This is normally the
case if the B<-name> argument was not included the last time the
C<backup labeltape> command was used on this tape, and no data
has been written to it since.
=back
=item B<creationTime>
The date and time at which the Backup System started performing
the dump operation that created the initial dump.
=item B<cell>
The cell in which the dump set was created. This is the cell
whose Backup Database contains a record of the dump set.
=item B<size>
The tape's capacity (in kilobytes) as recorded on the label,
rather than the amount of data on the tape. The value is
assigned by the B<-size> argument to the C<backup labeltape> command
or derived from the B</usr/afs/backup/tapeconfig> file on the Tape
Coordinator machine, not from a measurement of the tape.
=item B<dump path>
The dump level of the initial dump in the dump set
=item B<dump id>
The dump ID number of the initial dump in the dump set, as
recorded in the Backup Database
=item B<useCount>
The number of times a dump has been written to the tape, or it
has been relabeled
=back
The message C<ReadLabel: Finished> indicates the completion of the
output.
=head1 EXAMPLES
The following example shows the output for the tape with permanent
name B<oct.guest.dump> and capacity 2 MB, expressed in kilobyte units
(2097152 equals 2 times 1024^2).
backup readlabel -portoffset 6
Tape read was labelled: oct.guest.dump (907215000)
size: 2097152 Kbytes
The output in the Tape Coordinator window reads:
Tape label
----------
tape name = oct.guest.dump
AFS tape name = guests.monthly.3
creationTime = Thu Oct 1 00:10:00 1998
cell = abc.com
size = 2097152 Kbytes
dump path = B</monthly>
dump id = 907215000
useCount = 5
---- End of tape label ----
The following example is for a tape that does not have a permanent
tape.
backup readlabel -portoffset 6
Tape read was labelled: guests.monthly.2 (909899900)
size: 2097152 Kbytes
The output in the Tape Coordinator window reads:
Tape label
----------
tape name = <NULL>
AFS tape name = guests.monthly.2
creationTime = Sun Nov 1 00:58:20 1998
cell = abc.com
size = 2097152 Kbytes
dump path = B</monthly>
dump id = 909899900
useCount = 1
---- End of tape label ----
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_labeltape(1)>,
L<butc(1)>
=cut

122
doc/man-pages/pod/backup_restoredb.pod Normal file
View File

@ -0,0 +1,122 @@
=head1 NAME
backup restoredb - Restores a saved copy of the Backup Database
=head1 SYNOPSIS
backup restoredb [B<-portoffset> I<TC port offset>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup res [B<-p> I<TC port offset>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup restoredb> command restores to the Backup Server machine's
local disk a version of the Backup Database previously written to tape
by using the C<backup savedb> command.
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup restoredb> command restores data from the
backup data file listed for that port offset in the Tape Coordinator's
B</usr/afs/backup/tapeconfig> file, instead of from tape. For the sake of
clarity, the following text refers to tapes only, but the Backup
System handles backup data files in much the same way.)
The most common reason to run this command is to replace a corrupted
or otherwise damaged Backup Database; use the C<backup dbverify> command
to determine the database's status. The command can also be used to
restore records that were removed from the database when the B<-archive>
argument was included on a previous C<backup savedb> command.
The command completely overwrites the existing Backup Database records
for volume sets, Tape Coordinators, and the dump hierarchy with the
corresponding information from the saved version. It does not
overwrite existing dump records, but instead interleaves the records
from the copy being restored. If both the existing database (on the
Backup Server machine's disk) and the copy being restored include a
record about the same dump, the Backup System retains the one in the
existing database.
The Tape Coordinator's default response to this command is to access
the first tape it needs by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the B<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, or is the wrong tape, the Tape Coordinator
invokes the B<MOUNT> instruction or prompts the operator. It also invokes
the B<MOUNT> instruction or prompts for any additional tapes needed to
complete the restore operation; the backup operator must arrange to
provide them.
=head1 OPTIONS
=over 4
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following example shows the Backup Database being restored from
the Tape Coordinator with port offset 0:
backup restoredb
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
If the database is corrupted, do not attempt to restore a saved
database on top of it. Instead, use the instructions for repairing a
corrupted database in the IBM AFS Administration Guide chapter about
performing backup operations.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dbverify(1)>,
L<backup_savedb(1)>,
L<butc(1)>,
I<IBM AFS Administration Guide>
=cut

174
doc/man-pages/pod/backup_savedb.pod Normal file
View File

@ -0,0 +1,174 @@
=head1 NAME
backup savedb - Creates a saved copy of the Backup Database
=head1 SYNOPSIS
backup savedb [B<-portoffset> I<TC port offset>] [B<-archive> I<date time> ...]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup sa [B<-p> I<TC port offset>] [B<-a> I<date time> ...]
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup savedb> command creates a backup copy of the entire Backup
Database and writes it to the tape in the device controlled by the
Tape Coordinator indicated with the B<-portoffset> argument. If the
database is damaged (as reported by the C<backup dbverify> command), this
command repairs as much of the corruption as possible as it creates
the saved copy. The Backup Server creates a dump record for the saved
database in the Backup Database (but in the disk version of the
database only, not in the version written to tape).
If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup savedb> command dumps the database copy to
the backup data file listed for that port offset in the Tape
Coordinator's B</usr/afs/backup/tapeconfig> file, instead of to tape. For
the sake of clarity, the following text refers to tapes only, but the
Backup System handles backup data files in much the same way.
If the B<-archive> flag is provided, after writing the saved copy of the
database the Backup System truncates the copy of the database on disk
by deleting volume dump records with timestamps prior to the specified
date and time (it does not delete the dump records created by previous
C<backup savedb> commands, however).
If the tape to which the database copy is written has an AFS tape
name, it must be B<Ubik_db_dump.1> or C<E<lt>NULLE<gt>>. Any permanent name is
acceptable.
The Tape Coordinator's default response to this command is to access
the first tape by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the B<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, the Tape Coordinator invokes the B<MOUNT>
instruction or prompts the operator. It also invokes the B<MOUNT>
instruction or prompts for any additional tapes needed to complete the
operation; the backup operator must arrange to provide them.
=head1 OPTIONS
=over 4
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation.
=item B<-archive> I<date time> ...
Specifies a date and time; volume dump records with earlier
timestamps are deleted from the disk copy of the Backup
Database after the Backup System dumps the database (a dump's
timestamp appears in the created field of the output from the
C<backup dumpinfo> command). However, if a dump set contains any
dump created after the specified date, none of the dump records
associated with the dump set are deleted. Dump records for
previous dumps of the database (created with the C<backup savedb>
command) are never deleted; use the C<backup deletedump> command
to remove them.
Provide one of two values:
=over
=item *
The string C<NOW> to indicate the current date and time, in
which case the Backup System deletes all dump records except
those for dumps of the Backup Database itself.
=item *
A date value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>]. The month
(I<mm>), day (I<dd>), and year (I<yyyy>) are required, and valid
values for the year range from B<1970> to B<2037>; higher values
are not valid because the latest possible date in the
standard UNIX representation is in February 2038. The Backup
System automatically reduces any later date to the maximum
value.
The hour and minutes (I<hh>:I<MM>) are optional, but if provided
must be in 24-hour format (for example, the value B<14:36>
represents 2:36 p.m.). If omitted, the time defaults to 59
seconds after midnight (00:00:59 hours). Similarly, the
C<backup> command interpreter automatically adds 59 seconds to
any time value provided. In both cases, adding 59 seconds
compensates for how the Backup Database and C<backup dumpinfo>
command represent dump creation times in hours and minutes
only. That is, the Database records a creation timestamp of
C<20:55> for any dump created between 20:55:00 and 20:55:59.
Automatically adding 59 seconds to a time thus includes the
records for all dumps created during that minute.
=back
=over
=item B<Note:>
A ... follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition.
=back
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following example writes a copy of the Backup Database to the tape
device controlled by the Tape Coordinator with port offset 1:
backup savedb -portoffset 1
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dbverify(1)>,
L<backup_restoredb(1)>,
L<butc(1)>
=cut

359
doc/man-pages/pod/backup_scantape.pod Normal file
View File

@ -0,0 +1,359 @@
=head1 NAME
backup scantape - Extracts dump information from a tape
=head1 SYNOPSIS
backup scantape [B<-dbadd>] [B<-portoffset> I<TC port offset>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup sc [B<-d>] [B<-p> I<TC port offset>] [B<-l>] [B<-c> I<cell name>] [B<-help>]
=head1 DESCRIPTION
The C<backup scantape> command extracts information from the dump labels
and volume headers on the tape in the device controlled by the Tape
Coordinator indicated by the B<-portoffset> argument. The Tape
Coordinator displays the information for each volume in its window as
soon as it extracts it (rather than waiting until it has scanned the
entire tape).
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup scantape> command extracts dump
information from the backup data file named in that port offset's
entry in the B</usr/afs/backup/tapeconfig> file on the Tape Coordinator
machine, rather than from a tape. For the sake of clarity, the
following text refers to tapes only, but the Backup System handles
backup data files in much the same way.)
If the B<-dbadd> flag is provided, the C<backup scantape> command creates
new dump and volume records in the Backup Database for the scanned
information. However, if it finds that a record already exists in the
database for the same dump, it terminates the scanning operation.
The scanning operation works only on tapes containing volume data. The
command fails with an error message if the tape contains a copy of the
Backup Database (was created with the C<backup savedb> command, or has
the AFS tape name B<Ubik_db_dump.1>).
The Tape Coordinator's default response to this command is to access
the tape by invoking the B<MOUNT> instruction in the B<CFG_>I<device_name>
file, or by prompting the backup operator to insert the tape if there
is no B<MOUNT> instruction. However, if the B<AUTOQUERY NO> instruction
appears in the B<CFG_>I<device_name> file, or if the issuer of the B<butc>
command included the B<-noautoquery> flag, the Tape Coordinator instead
expects the tape to be in the device already. If it is not, the Tape
Coordinator invokes the B<MOUNT> instruction or prompts the operator.
To terminate a tape scanning operation in interactive mode, issue the
C<(backup) kill> command. In noninteractive mode, the only choice is to
use a termination signal such as <B<Ctrl-c>> to halt the Tape Coordinator
completely.
=head1 OPTIONS
=over 4
=item B<-dbadd>
Adds the information extracted from the tape to the Backup
Database (but only if the database does not already contain an
entry with the same dump ID number).
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
For every dump on a tape, the C<backup scantape> command displays in the
Tape Coordinator window the dump label and the volume header of each
volume in the dump. If a dump spans more than one tape, the dump label
does not repeat at the beginning of subsequent tapes.
A dump label contains the following fields, which are the same as in
the output from the C<backup readlabel> command:
=over
=item B<tape name>
The permanent name assigned by using the B<-pname> argument of the
C<backup labeltape> command. This name remains on the tape until
that argument is used again, no matter how many times the tape
is recycled or otherwise relabeled. If the tape does not have a
permanent name, the value C<E<lt>NULLE<gt>> appears in this field.
=item B<AFS tape name>
A tape name in one of the following prescribed formats. The
Backup System automatically writes the appropriate AFS tape
name to the label as part of a C<backup dump> operation, or the
operator can assign it with the B<-name> argument to the C<backup
labeltape> command.
=over
=item *
I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape
contains volume data. The I<volume_set_name> is the name of the
volume set that was dumped to create the initial dump in the
dump set of which this tape is a part; I<dump_level_name> is the
last pathname element of the dump level at which the initial
dump was backed up; and I<tape_index> is the numerical position
of the tape in the dump set.
=item *
C<E<lt>NULLE<gt>> if the tape has no AFS tape name. This is normally the
case if the B<-name> argument was not included the last time the
C<backup labeltape> command was used on this tape, and no data
has been written to it since.
=back
=item B<creationTime>
The date and time at which the Backup System started performing
the dump operation that created the initial dump.
=item B<cell>
The cell in which the dump set was created. This is the cell
whose Backup Database contains a record of the dump set.
=item B<size>
The tape's capacity (in kilobytes) as recorded on the label,
rather than the amount of data on the tape. The value is
assigned by the B<-size> argument to the C<backup labeltape> command
or derived from the B</usr/afs/backup/tapeconfig> file on the Tape
Coordinator machine, not from a measurement of the tape.
=item B<dump path>
The dump level of the initial dump in the dump set.
=item B<dump id>
The dump ID number of the initial dump in the dump set, as
recorded in the Backup Database.
=item B<useCount>
The number of times a dump has been written to the tape, or it
has been relabeled.
=back
The volume header contains the following fields:
=over
=item B<volume name>
The volume name, complete with a C<.backup> or C<.readonly>
extension, if appropriate.
=item B<volume ID>
The volume's volume ID.
=item B<dumpSetName>
The dump to which the volume belongs. The dump name is of the
form I<volume_set_name>.I<dump_level_name> and matches the name
displayed in the dump label.
=item B<dumpID>
The dump ID of the dump named in the C<dumpSetName> field.
=item B<level>
The depth in the dump hierarchy of the dump level used in
creating the dump. A value of 0 indicates a full dump. A value
of 1 or greater indicates an incremental dump made at the
indicated depth in the hierarchy. The value reported is for the
entire dump, not necessarily for the volume itself; for
example, it is possible for a dump performed at an incremental
level to include a full dump of an individual volume if the
volume was omitted from previous dumps.
=item B<parentID>
The dump ID number of C<dumpSetName>'s parent dump. It is 0 if the
value in the C<level> field is 0.
=item B<endTime>
Is always 0; it is reserved for internal use.
=item B<cloneDate>
The date and time at which the volume was created. For a backup
or read-only volume, this represents the time at which it was
cloned from its read/write source. For a read/write volume, it
indicates the time at which the Backup System locked the volume
for purposes of including it in the dump named in the
C<dumpSetName> field.
=back
The message C<Scantape: Finished> indicates the completion of the output.
In normal circumstances, the Backup System writes a marker to indicate
that a volume is the last one on a tape, or that the volume continues
on the next tape. However, if a backup operation terminated abnormally
(for example, because the operator terminated the Tape Coordinator by
issuing the <B<Ctrl-c>> command during the operation), then there is no
such marker. Some very early versions of the Backup System also did
not write these markers. If a tape does not conclude with one of the
expected markers, the Tape Coordinator cannot determine if there is a
subsequent tape in the dump set and so generates the following message
in its window:
Are there more tapes? (y/n)
=head1 EXAMPLES
The following example shows the output for the first two volumes on a
tape in the device with port offset 0:
backup scantape
Dump label
----------
tape name = monthly_guest
AFS tape name = guests.monthly.3
creationTime = Mon Feb 1 04:06:40 1999
cell = abc.com
size = 2150000 Kbytes
dump path = B</monthly>
dump id = 917860000
useCount = 44
-- End of dump label --
-- volume --
volume name: user.guest10.backup
volume ID 1937573829
dumpSetName: guests.monthly
dumpID 917860000
level 0
parentID 0
endTime 0
clonedate Mon Feb 1 03:03:23 1999
-- volume --
volume name: user.guest11.backup
volume ID 1938519386
dumpSetName: guests.monthly
dumpID 917860000
level 0
parentID 0
endTime 0
clonedate Mon Feb 1 03:05:15 1999
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
A scanning operation does not have to begin with the first tape in a
dump set, but the Backup System can process tapes only in sequential
order after the initial tape provided. The Tape Coordinator
automatically requests any subsequent tapes by invoking the B<MOUNT>
instruction in the local B</usr/afs/backup/CFG_>I<device_name> file, or by
prompting the operator if there is no B<MOUNT> instruction.
The Tape Coordinator's success in scanning a tape that is corrupted or
damaged depends on the extent of the damage and what type of data is
corrupted. It can almost always scan the tape successfully up to the
point of damage. If the damage is minor, the Tape Coordinator can
usually skip over it and scan the rest of the tape, but more major
damage can prevent further scanning. Because a scanning operation can
start on any tape in a dump set, damage on one tape does not prevent
scanning of the others in the dump set. However, it is possible to
scan either the tapes that precede the damaged one or the ones that
follow it, but not both.
If a tape is relabeled with the C<backup labeltape> command, it is not
possible to recover data from it for the purposes of rebuilding the
Backup Database.
If the B<-dbadd> flag is included on the command, it is best not to
terminate the tape scanning operation before it completes (for
example, by issuing the C<(backup) kill> command in interactive mode).
The Backup System writes a new record in the Backup Database for each
dump as soon as it scans the relevant information on the tape, and so
it possibly has already written new records. If the operator wants to
rerun the scanning operation, he or she must locate and remove the
records created during the terminated operation: the second operation
exits automatically if it finds that a record that it needs to create
already exists.
If the B<-dbadd> flag is included and the first tape provided is not the
first tape in the dump set, the following restrictions apply:
=over
=item *
If the first data on the tape is a continuation of a volume that
begins on the previous (unscanned) tape in the dump set, the
Backup System does not add a record for that volume to the Backup
Database.
=item *
The Backup System must read the marker that indicates the start of
an appended dump to add database records for the volumes in it. If
the first volume on the tape belongs to an appended dump, but is
not immediately preceded by the appended-dump marker, the Backup
System does not create a Backup Database record for it or any
subsequent volumes that belong to that appended dump.
=back
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dump(1)>,
L<backup_dumpinfo(1)>,
L<butc(1)>
=cut

175
doc/man-pages/pod/backup_setexp.pod Normal file
View File

@ -0,0 +1,175 @@
=head1 NAME
backup setexp - Sets the expiration date for existing dump levels.
=head1 SYNOPSIS
backup setexp B<-dump> I<dump level name> [I<dump level name> ...] [B<-expires> I<expiration date> ...]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup se B<-d> I<dump level name> [I<dump level name> ...] [B<-e> I<expiration date> ...]
[B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup setexp> command sets or changes the expiration date
associated with each specified dump level, which must already exist in
the dump hierarchy.
Use the B<-expires> argument to associate an expiration date with each
dump level. When the Backup System subsequently creates a dump at the
dump level, it uses the specified value to derive the dump's
expiration date, which it records on the label of the tape (or backup
data file). The Backup System refuses to overwrite a tape until after
the latest expiration date of any dump that the tape contains, unless
the C<backup labeltape> command is used to relabel the tape. If a dump
level does not have an expiration date, the Backup System treats dumps
created at the level as expired as soon as it creates them.
(Note that the Backup System does not automatically remove a dump's
record from the Backup Database when the dump reaches its expiration
date, but only if the tape that contains the dump is recycled or
relabeled. To remove expired and other obsolete dump records, use the
C<backup deletedump> command.)
Define either an absolute or relative expiration date:
=over
=item *
An absolute expiration date defines the month/day/year (and,
optionally, hour and minutes) at which a dump expires. If the
expiration date predates the dump creation time, the Backup System
immediately treats the dump as expired.
=item *
A relative date defines the number of years, months, or days (or a
combination of the three) after the dump's creation that it
expires. When the Backup System creates a dump at the dump level,
it calculates an actual expiration date by adding the relative
date to the start time of the dump operation.
=back
If the command is used to change an existing expiration date
associated with a dump level, the new date applies only to dumps
created after the change. Existing dumps retain the expiration date
assigned at the time they were created.
=head1 OPTIONS
=over 4
=item B<-dump> I<dump level name> [I<dump level name> ...]
Specifies the full pathname of each dump level to assign the
expiration date specified by the B<-expires> argument.
=item B<-expires> I<expiration date> ...
Defines the absolute or relative expiration date to associate
with each dump level named by the B<-dump> argument. Absolute
expiration dates have the following format:
[B<at>] {B<NEVER> | I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>] }
where the optional word C<at> is followed either by the string
C<NEVER>, which indicates that dumps created at the dump level
never expire, or by a date value with a required portion (I<mm>
for month, I<dd> for day, and I<yyyy> for year) and an optional
portion (I<hh> for hours and I<MM> for minutes).
Omit the I<hh>:I<MM> portion to use the default of midnight (00:00
hours), or provide a value in 24-hour format (for example,
B<20:30> is 8:30 p.m.). Valid values for the year range from B<1970>
to B<2037>; higher values are not valid because the latest
possible date in the standard UNIX representation is in
February 2038. The command interpreter automatically reduces
later dates to the maximum value.
Relative expiration dates have the following format:
[B<in>] [I<years>B<y>] [I<months>B<m>] [I<days>B<d>]
where the optional word C<in> is followed by at least one of a
number of years (maximum B<9999>) followed by the letter C<y>, a
number of months (maximum B<12>) followed by the letter C<m>, or a
number of days (maximum B<31>) followed by the letter C<d>. If
providing more than one of the three, list them in the
indicated order. If the date that results from adding the
relative expiration value to a dump's creation time is later
than the latest possible date in the UNIX time representation,
the Backup System automatically reduces it to that date.
=over
=item B<Note:>
A ... follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition to be associated with each dump level specified by the
B<-dump> argument.
=back
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following example associates an absolute expiration date of 10:00
p.m. on 31 December 1999 with the dump level B</1998/december>:
backup setexp -dump B</1998/december> -expires at 12/31/1999 22:00
The following example associates a relative expiration date of 7 days
with the two dump levels B</monthly/week1> and B</monthly/week2>:
backup setexp -dump B</monthly/week1> B</monthly/week> -expires 7d
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_adddump(1)>,
L<backup_deldump(1)>,
L<backup_listdumps(1)>
=cut

198
doc/man-pages/pod/backup_status.pod Normal file
View File

@ -0,0 +1,198 @@
=head1 NAME
backup status - Reports a Tape Coordinator's status
=head1 SYNOPSIS
backup status [B<-portoffset> I<TC port offset>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup st [B<-p> I<TC port offset>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup status> command displays which operation, if any, the
indicated Tape Coordinator is currently executing.
=head1 OPTIONS
=over 4
=item B<-portoffset> I<TC port offset>
Specifies the port offset number of the Tape Coordinator for
which to report the status.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The following message indicates that the Tape Coordinator is not
currently performing an operation:
Tape coordinator is idle
Otherwise, the output includes a message of the following format for
each running or pending operation:
Task I<task_ID>: I<operation>: I<status>
where
=over
=item B<I<task_ID>>
Is a task identification number assigned by the Tape
Coordinator. It begins with the Tape Coordinator's port offset
number.
=item B<I<operation>>
Identifies the operation the Tape Coordinator is performing,
which is initiated by the indicated command:
=over
=item *
Dump (the C<backup dump> command)
=item *
Restore (the backup diskrestore, backup volrestore, or C<backup
volsetrestore> commands)
=item *
Labeltape (the C<backup labeltape> command)
=item *
Scantape (the C<backup scantape> command)
=item *
SaveDb (the C<backup savedb> command)
=item *
RestoreDb (the C<backup restoredb> command)
=back
=item B<I<status>>
Indicates the job's current status in one of the following
messages.
=over
=item B<I<number> Kbytes transferred, volume I<volume_name>>
For a running dump operation, indicates the number of
kilobytes copied to tape or a backup data file so far,
and the volume currently being dumped.
=item B<I<number> Kbytes, restore.volume>
For a running restore operation, indicates the number of
kilobytes copied into AFS from a tape or a backup data
file so far.
=item B<[abort requested]>
The C<(backup) kill> command was issued, but the termination
signal has yet to reach the Tape Coordinator.
=item B<[abort sent]>
The operation is canceled by the C<(backup) kill> command.
Once the Backup System removes an operation from the
queue or stops it from running, it no longer appears at
all in the output from the command.
=item B<[butc contact lost]>
The C<backup> command interpreter cannot reach the Tape
Coordinator. The message can mean either that the Tape
Coordinator handling the operation was terminated or
failed while the operation was running, or that the
connection to the Tape Coordinator timed out.
=item B<[done]>
The Tape Coordinator has finished the operation.
=item B<[drive wait]>
The operation is waiting for the specified tape drive to
become free.
=item B<[operator wait]>
The Tape Coordinator is waiting for the backup operator
to insert a tape in the drive.
=back
=back
If the Tape Coordinator is communicating with an XBSA server (a
third-party backup utility that implements the Open Group's Backup
Service API [XBSA]), the following message appears last in the output:
I<XBSA_program> Tape coordinator
where I<XBSA_program> is the name of the XBSA-compliant program.
=head1 EXAMPLES
The following example shows that the Tape Coordinator with port offset
4 has so far dumped about 1.5 MB of data for the current dump
operation, and is currently dumping the volume named B<user.pat.backup>:
backup status -portoffset 4
Task 4001: Dump: 1520 Kbytes transferred, volume user.pat.backup
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<butc(1)>
=cut

134
doc/man-pages/pod/backup_volinfo.pod Normal file
View File

@ -0,0 +1,134 @@
=head1 NAME
backup volinfo - Displays a volume's dump history from the Backup Database
=head1 SYNOPSIS
backup volinfo B<-volume> I<volume name>
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup voli B<-v> I<volume name> [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup volinfo> command displays a dump history of the specified
volume, reporting information such as the date on which the volume was
dumped and the tapes that contain it. Include the C<.backup> extension on
the volume name if the backup version of the volume was dumped.
=head1 OPTIONS
=over 4
=item B<-volume> I<volume name>
Names the volume for which to display the dump history. Include
the C<.backup> or C<.readonly> extension if the backup or read-only
version of the volume was dumped.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The output includes a line for each Backup Database dump record that
mentions the specified volume, order from most to least recent. The
output for each record appears in a table with six columns:
=over
=item B<dumpID>
The dump ID of the dump that includes the volume.
=item B<lvl>
The depth in the dump hierarchy of the dump level at which the
volume was dumped. A value of 0 indicates a full dump. A value
of 1 or greater indicates an incremental dump made at the
specified depth in the dump hierarchy.
=item B<parentid>
The dump ID of the dump's parent dump. A value of 0 indicates a
full dump, which has no parent; in this case, the value in the
C<lvl> column is also 0.
=item B<creation date>
The date and time at which the Backup System started the dump
operation that created the dump.
=item B<clone date>
For a backup or read-only volume, the time at which it was
cloned from its read/write source. For a read/write volume, the
same as the value in the creation date field.
=item B<tape name>
The name of the tape containing the dump: either the permanent
tape name, or an AFS tape name in the format
I<volume_set_name>.I<dump_level_name>.I<tape_index> where
I<volume_set_name> is the name of the volume set associated with
the initial dump in the dump set of which this tape is a part;
I<dump_level_name> is the name of the dump level at which the
initial dump was backed up; I<tape_index> is the ordinal of the
tape in the dump set. Either type of name can be followed by a
dump ID in parentheses; if it appears, it is the dump ID of the
initial dump in the dump set to which this appended dump
belongs.
=back
=head1 EXAMPLES
The following example shows part of the dump history of the Backup
volume user.smith.backup:
backup volinfo -volume user.smith.backup
DumpID lvl parentID creation date clone date tape name
924600000 1 924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
924514392 1 924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2
924427600 0 0 04/18/1999 05:26 04/18/1999 04:58 user_full_6
. . . . . . . .
. . . . . . . .
=head1 PRIVILEGE REQUIRED
None
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dumpinfo(1)>,
L<backup_volrestore(1)>
=cut

336
doc/man-pages/pod/backup_volrestore.pod Normal file
View File

@ -0,0 +1,336 @@
=head1 NAME
backup volrestore - Restores one or more volumes
=head1 SYNOPSIS
backup volrestore B<-server> I<destination machine>
B<-partition> I<destination partition>
B<-volume> I<volume(s) to restore> [I<volume(s) to restore> ...]
[B<-extension> I<new volume name extension>]
[B<-date> I<date from which to restore> ...]
[B<-portoffset> I<TC port offsets> [I<TC port offsets> ...]] [B<-n>]
[B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup volr B<-s> I<destination machine> B<-pa> I<destination partition>
B<-v> I<volume(s) to restore> [I<volume(s) to restore> ...] [B<-e> I<new volume name extension>]
[B<-d> I<date from which to restore> ...] [B<-po> I<TC port offsets> [I<TC port offsets> ...]]
[B<-n>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup volrestore> command restores the contents of one or more
volumes to the site indicated by the B<-server> and B<-partition> arguments.
Use the command either to overwrite the contents of existing volumes
with the restored data or to create new volumes while retaining the
existing ones. The specified site does not have to be the current site
for the volumes.
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup volrestore> command restores data from the
backup data file listed for that port offset in the Tape Coordinator's
B</usr/afs/backup/tapeconfig> file, rather than from tape. For the sake
of clarity, the following text refers to tapes only, but the Backup
System handles backup data files in much the same way.)
The command's arguments can be combined as indicated:
=over
=item *
To preserve a volume's current contents and also create a new
volume to house the restored version, use the B<-extension> argument.
The Backup System creates the new volume on the server and
partition named by the B<-server> and B<-partition> arguments, assigns
it the same name as the current volume with the addition of the
specified extension, and creates a new Volume Location Database
(VLDB) entry for it. Creating a new volume enables the
administrator to compare the two versions.
=item *
To overwrite a volume's existing contents with the restored
version, omit the B<-extension> argument, and specify the site as
indicated:
=over
=item *
To retain the current site, specify it with the B<-server> and
B<-partition> arguments.
=item *
To move the volume to a different site while overwriting it,
specify the new site with the B<-server> argument, B<-partition>
argument, or both. The Backup System creates a new volume at
that site, removes the existing volume, and updates the site
information in the volume's VLDB entry. The backup version of
the volume is not removed automatically from the original
site, if it exists. Use the C<vos remove> command to remove it
and the C<vos backup> command to create a backup version at the
new site.
=back
=item *
To restore a volume that no longer exists in the file system,
specify its name with the B<-volume> argument and use the B<-server> and
B<-partition> arguments to place it at the desired site. The Backup
System creates a new volume and new VLDB entry.
=back
In each case, the command sets each volume's creation date to the date
and time at which it restores it. The creation date appears in the
Creation field in the output from the C<vos examine> and C<vos listvol>
commands.
If restoring all of the volumes that resided on a single partition, it
is usually more efficient to use the C<backup diskrestore> command. If
restoring multiple volumes to many different sites, it can be more
efficient to use the C<backup volsetrestore> command.
By default, the C<backup volrestore> command restores the most recent
full dump and all subsequent incremental dumps for each volume,
bringing the restored volumes to the most current possible state. To
restore the volumes to their state at some time in the past, use the
B<-date> argument. The Backup System restores the most recent full dump
and each subsequent incremental dump for which the I<clone date> of the
volume included in the dump is before the indicated date and time (the
clone date timestamp appears in the C<clone date> field of the output
from the C<backup volinfo> command). For backup and read-only volumes,
the clone date represents the time at which the volume was copied from
its read/write source; for read/write volumes, it represents the time
at which the volume was locked for inclusion in the dump. The
resemblance of a restored volume to its actual state at the indicated
time depends on the amount of time that elapsed between the volume's
clone date in the last eligible dump and the specified time.
If the B<-volume> argument specifies the base (read/write) form of the
volume name, the Backup System searches the Backup Database for the
newest dump set that includes a dump of either the read/write or the
backup version of the volume. It restores the dumps of that version of
the volume, starting with the most recent full dump. If, in contrast,
the volume name explicitly includes the C<.backup> or C<.readonly>
extension, the Backup System restores dumps of the corresponding
volume version only.
To generate a list of the tapes the Backup System needs to perform the
restore operation, without actually performing it, combine the B<-n> flag
with the options to be used on the actual command.
If all of the full and incremental dumps of all relevant volumes were
not written to a type of tape that a single Tape Coordinator can read,
use the B<-portoffset> argument to list multiple port offset numbers in
the order in which the tapes are needed (first list the port offset
for the full dump, second the port offset for the level 1 incremental
dump, and so on). If restoring multiple volumes, the same ordered list
of port offsets must apply to all of them. If not, either issue this
command separately for each volume, or use the C<vos volsetrestore>
command after defining groups of volumes that were dumped to
compatible tape types. For further discussion, see the IBM AFS
Administration Guide.
The Tape Coordinator's default response to this command is to access
the first tape it needs by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the B<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, or is the wrong tape, the Tape Coordinator
invokes the B<MOUNT> instruction or prompts the operator. It also invokes
the B<MOUNT> instruction or prompts for any additional tapes needed to
complete the restore operation; the backup operator must arrange to
provide them.
=head1 OPTIONS
=over 4
=item B<-server> I<destination machine>
Names the file server machine on which to restore each volume.
If this argument and the B<-partition> argument indicate a site
other than the current site for each volume, and the B<-extension>
argument is not also provided, the Backup System removes the
existing volumes from their current sites, places the restored
contents at the specified site, and changes the site
information in the volume's VLDB entry.
=item B<-partition> I<destination partition>
Names the partition to which to restore each volume. If this
argument and the B<-server> argument indicate a site other than
the current site for each volume, and the B<-extension> argument
is not also provided, the Backup System removes the existing
volumes from their current sites, places the restored contents
at the specified site, and changes the site information in the
volume's VLDB entry.
=item B<-volume> I<volume(s) to restore> [I<volume(s) to restore> ...]
Names one or more volumes to restore, using the volume name as
listed in the Backup Database. Provide the base (read/write)
name of each volume to have the Backup System search the Backup
Database for the newest dump set that includes a dump of either
the read/write or the backup version of the volume; it restores
the dumps of that version of the volume, starting with the most
recent full dump. If, in contrast, a volume name explicitly
includes the C<.backup> or C<.readonly> extension, the Backup System
restores dumps of the corresponding volume version only.
=item B<-extension> I<new volume name extension>
Creates a new volume to house the restored data, with a name
derived by appending the specified string to each volume named
by the B<-volume> argument. The Backup System creates a new VLDB
entry for the volume. Any string other than C<.readonly> or
C<.backup> is acceptable, but the combination of the existing
volume name and extension cannot exceed 22 characters in
length. To use a period to separate the extension from the
name, specify it as the first character of the string (as in
C<.rst>, for example).
=item B<-date> I<date from which to restore> ...
Specifies a date and optionally time; the restored volume
includes data from dumps performed before the date only.
Provide a value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>], where the
required I<mm>/I<dd>/I<yyyy> portion indicates the month (I<mm>), day (I<dd>),
and year (I<yyyy>), and the optional I<hh>:I<MM> portion indicates the
hour and minutes in 24-hour format (for example, the value
B<14:36> represents 2:36 p.m.). If omitted, the time defaults to
59 seconds after midnight (00:00:59 hours).
Valid values for the year range from B<1970> to B<2037>; higher
values are not valid because the latest possible date in the
standard UNIX representation is in February 2038. The command
interpreter automatically reduces any later date to the maximum
value.
If this argument is omitted, the Backup System restores all
possible dumps including the most recently created.
=over
=item B<Note:>
A plus sign follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition.
=back
=item B<-portoffset> I<TC port offsets> [I<TC port offsets> ...]
Specifies one or more port offset numbers (up to a maximum of
128), each corresponding to a Tape Coordinator to use in the
operation. If there is more than one value, the Backup System
uses the first one when restoring the full dump of each volume,
the second one when restoring the level 1 incremental dump of
each volume, and so on. It uses the final value in the list
when restoring dumps at the corresponding depth in the dump
hierarchy and all dumps at lower levels.
Provide this argument unless the default value of 0 (zero) is
appropriate for all dumps. If B<0> is just one of the values in
the list, provide it explicitly in the appropriate order.
=item B<-n>
Displays the list of tapes that contain the dumps required by
the restore operation, without actually performing the
operation.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
If the issuer includes the B<-n> flag with the command, the following
string appears at the head of the list of the tapes necessary to
complete the restore operation.
Tapes needed:
=head1 EXAMPLES
The following command restores the volume B<user.pat> to partition
B</vicepa> on machine B<fs5.abc.com>:
backup volrestore -server fs5.abc.com -partition a -volume user.pat
The following command restores the volumes B<user.smith> and B<user.terry>
to partition B</vicepb> on machine B<fs4.abc.com>, adding a B<.rst> extension
to each volume name and preserving the existing B<user.smith> and
B<user.terry> volumes. Only dumps created before 5:00 p.m. on 31 January
1998 are restored. (The command is shown here on multiple lines only
for legibility reasons.)
backup volrestore -server fs4.abc.com -partition b \
-volume user.smith user.terry \
-extension .rst -date 1/31/1998 17:00
The following command restores the volume B<user.pat> to partition
B</vicepb> on machine B<fs4.abc.com>. The Tape Coordinator with port offset
1 handles the tape containing the full dump; the Tape Coordinator with
port offset 0 handles all tapes containing incremental dumps. (The
command is shown here on two lines only for legibility reasons.)
backup volrestore -server fs5.abc.com -partition a \
-volume user.pat -portoffset 1 0
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server or Volume Location (VL) Server is
running, and on every file server machine that houses an affected
volume. If the B<-localauth> flag is included, the issuer must instead be
logged on to a server machine as the local superuser B<root>.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_dump(1)>,
L<backup_diskrestore(1)>,
L<backup_volsetrestore(1)>,
L<butc(1)>,
L<vos_backup(1)>,
L<vos_remove(1)>
=cut

424
doc/man-pages/pod/backup_volsetrestore.pod Normal file
View File

@ -0,0 +1,424 @@
=head1 NAME
backup volsetrestore - Restores all volumes in a volume set
=head1 SYNOPSIS
backup volsetrestore [B<-name> I<volume set name>] [B<-file> I<file name>]
[B<-portoffset> I<TC port offset> [I<TC port offset> ...]]
[B<-extension> I<new volume name extension>]
[B<-n>] [B<-localauth>] [B<-cell> I<cell name>] [B<-help>]
backup vols [B<-na> I<volume set name>] [B<-f> I<file name>]
[B<-p> I<TC port offset> [I<TC port offset> ...]] [B<-e> I<new volume name extension>]
[B<-n>] [B<-l>] [B<-c> I<cell name>] [B<-h>]
=head1 DESCRIPTION
The C<backup volsetrestore> command restores the complete contents of a
group of read/write volumes to the file system, by restoring data from
the last full dump and all subsequent incremental dumps of each
volume. It is most useful for recovering from loss of data on multiple
partitions, since it can restore each of a defined set of volumes to a
different site.
(If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup volsetrestore> command restores data from
the backup data file listed for that port offset in the Tape
Coordinator's B</usr/afs/backup/tapeconfig> file, instead of from tape.
For the sake of clarity, the following text refers to tapes only, but
the Backup System handles backup data files in much the same way.)
If restoring one or more volumes to a single site only, it is usually
more efficient to use the C<backup volrestore> command. If restoring all
volumes that resided on a single partition, it is usually more
efficient to use the C<backup diskrestore> command.
Indicate the volumes to restore by providing either the B<-name> argument
or the B<-file> argument:
=over
=item *
The B<-name> argument names a volume set. The Backup System restores
all volumes listed in the Volume Location Database (VLDB) that
match the server, partition, and volume name criteria defined in
the volume set's volume entries, and for which dumps are
available. It restores the volumes to their current site (machine
and partition), and by default overwrites the existing volume
contents.
It is not required that the volume set was previously used to back
up volumes (was used as the B<-volumeset> option to the C<backup dump>
command). It can be defined especially to match the volumes that
need to be restored with this command, and that is usually the
better choice. Indeed, a temporary volume set, created by
including the B<-temporary> flag to the C<backup addvolset> command, can
be especially useful in this context. A temporary volume set is
not added to the Backup Database and exists only during the
current interactive backup session, which is suitable if the
volume set is needed only to complete the single restore operation
initialized by this command.
The reason that a specially defined volume set is probably better
is that volume sets previously defined for use in dump operations
usually match the backup version of volumes, whereas for a restore
operation it is best to define volume entries that match the base
(read/write) name. In that case, the Backup System searches the
Backup Database for the newest dump set that includes either the
read/write or the backup version of the volume. If, in contrast, a
volume entry explicitly matches the volume's backup or read-only
version, the Backup System restores dumps of that volume version
only.
=item *
The B<-file> argument names a file that lists specific volumes and
the site to which to restore each. The volume name must match the
name used in Backup Database dump records rather than in the VLDB,
if they differ, because the Backup System does not look up volumes
in the VLDB. The specified site can be different than the volume's
current one; in that case, the Backup System removes the current
version of the volume and updates the volume's location
information in the VLDB.
=back
If all of the full and incremental dumps of all relevant volumes were
not written to a type of tape that a single Tape Coordinator can read,
use the B<-portoffset> argument to list multiple port offset numbers in
the order in which the tapes are needed (first list the port offset
for the full dump, second the port offset for the level 1 incremental
dump, and so on). This implies that the full dumps of all relevant
volumes must have been written to a type of tape that the first Tape
Coordinator can read, the level 1 incremental dumps to a type of tape
the second Tape Coordinator can read, and so on. If dumps are on
multiple incompatible tape types, use the C<backup volrestore> command to
restore individual volumes, or use this command after defining new
volume sets that group together volumes that were dumped to compatible
tape types. For further discussion, see the IBM AFS Administration
Guide.
By default, the Backup System overwrites the contents of an existing
volume with the restored data. To create a new volume to house the
restored version instead, use the B<-extension> argument. The Backup
System derives the new volume's name by adding the specified extension
to the read/write base name, and creates a new VLDB entry. The command
does not affect the existing volume in any way. However, if a volume
with the specified extension also already exists, the command
overwrites it.
The B<-n> flag produces a list of the volumes to be restored if the B<-n>
flag were not included, without actually restoring any volumes. See
the L</"OUTPUT"> section of this reference page for a detailed description
of the output, and suggestions on how to combine it most effectively
with the B<-file> and B<-name> arguments.
The execution time for a C<backup volsetrestore> command depends on the
number of volumes to be restored and the amount of data in them, but
it can take hours to restore a large number of volumes. One way to
reduce the time is to run multiple instances of the command
simultaneously, either using the B<-name> argument to specify disjoint
volume sets for each command, or the B<-file> argument to name files that
list different volumes. This is possible if there are multiple
available Tape Coordinators that can read the required tapes.
Depending on how the volumes to be restored were dumped to tape,
specifying disjoint volume sets can also reduce the number of tape
changes required.
The Tape Coordinator's default response to this command is to access
the first tape it needs by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the B<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, or is the wrong tape, the Tape Coordinator
invokes the B<MOUNT> instruction or prompts the operator. It also invokes
the B<MOUNT> instruction or prompts for any additional tapes needed to
complete the restore operation; the backup operator must arrange to
provide them.
=head1 OPTIONS
=over 4
=item B<-name> I<volume set name>
Names a volume set to restore. The Backup System restores all
of the volumes listed in the VLDB that match the volume set's
volume entries. Provide this argument or the B<-file> argument,
but not both.
=item B<-file> I<file name>
Specifies the full pathname of a file that lists one or more
volumes and the site (file server machine and partition) to
which to restore each. Use either this argument or the B<-name>
argument, but not both.
Each volume's entry must appear on its own (unbroken) line in
the file, and have the following format:
machine partition
volume [comments...]
where
=over
=item B<machine>
Names the file server machine to which to restore the
volume.
=item B<partition>
Names the partition to which to restore the volume.
=item B<volume>
Names the volume to restore. It is generally best to
specify the base (read/write) name of each volume. In
this case, the Backup System searches the Backup Database
for the newest dump set that includes a dump of either
the read/write or the backup version of the volume. It
restores the dumps of that version of the volume,
starting with the most recent full dump. If, in contrast,
the name explicitly includes the B<.backup> or B<.readonly>
extension, the Backup System restores dumps of that
volume version only.
=item B<comments...>
Is any other text. The Backup System ignores any text on
each line that appears after the volume name, so this
field can be used for notes helpful to the backup
operator or other administrator.
=back
Do not use wildcards (for example, B<.*>) in the I<machine>,
I<partition>, or I<volume> fields. It is acceptable for multiple
lines in the file to name the same volume, but the Backup
System processes only the first of them.
=item B<-extension> I<new volume name extension>
Creates a new volume for each volume specified by the B<-name> or
B<-file> argument, to house the restored data from that volume.
The Backup System derives the new volume's name by appending
the specified string to the read/write base name, and creates a
new VLDB volume entry. It preserves the contents of each
existing volume. Any string other than B<.readonly> or B<.backup> is
acceptable, but the combination of the base name and extension
cannot exceed 22 characters in length. To use a period to
separate the extension from the name, specify it as the first
character of the string (as in B<.rst>, for example).
=item B<-portoffset> I<TC port offset> [I<TC port offset> ...]
Specifies one or more port offset numbers (up to a maximum of
128), each corresponding to a Tape Coordinator to use in the
operation. If there is more than one value, the Backup System
uses the first one when restoring the full dump of each volume,
the second one when restoring the level 1 incremental dump of
each volume, and so on. It uses the final value in the list
when restoring dumps at the corresponding depth in the dump
hierarchy and all dumps at lower levels.
Provide this argument unless the default value of 0 (zero) is
appropriate for all dumps. If B<0> is just one of the values in
the list, provide it explicitly in the appropriate order.
=item B<-n>
Displays a list of the volumes to be restored if the flag were
not included, without actually restoring them. The L</"OUTPUT">
section of this reference page details the format of the
output. When combined with the B<-name> argument, its output is
easily edited for use as input to the B<-file> argument on a
subsequent C<backup volsetrestore> command.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
If the B<-n> flag is not provided, the command displays a unique task ID
number for the operation, in two places:
=over
=item *
In the shell window, directly following the command line
=item *
In the Tape Coordinator window, if the B<butc> process was started at
debug level 1
=back
The task ID number is not the same as the job ID number displayed by
the C<(backup) jobs> command when the C<(backup) volsetrestore> command is
issued in interactive mode. The Backup System does not assign either
type of ID number until the restoration process actually begins.
When the B<-n> flag is included, no task ID or job ID numbers are
reported because none are assigned. Instead, the output begins with a
count of the number of volumes to be restored, followed by a line for
each dump of a volume. For each volume, the line representing the most
recent full dump appears first, and lines for any subsequent
incremental dumps follow, ordered by dump level. The lines for a given
volume do not necessarily appear all together, however.
The format of each line is as follows (the output is shown here on two
lines only for legibility reasons):
machine partition volume_dumped # as volume_restored; tape_name (tape_ID); \
pos position_number; date
where
=over
=item B<machine>
Names the file server machine that currently houses the volume,
as listed in the VLDB.
=item B<partition>
Names the partition that currently houses the volume, as listed
in the VLDB.
=item B<volume_dumped>
Specifies the version (read/write or backup) of the volume that
was dumped, as listed in the Backup Database.
=item B<volume_restored>
Specifies the name under which to restore the volume. The
Backup System only restores data to read/write volumes. If the
B<-extension> argument is included, then the specified extension
appears on the name in this field (for example, C<user.pat.rst>).
=item B<tape_name>
Names the tape containing the dump of the volume, from the
Backup Database. If the tape has a permanent name, it appears
here; otherwise, it is the AFS tape name.
=item B<tape_ID>
The tape ID of the tape containing the dump of the volume, from
the Backup Database.
=item B<position_number>
Specifies the dump's position on the tape (for example, C<31>
indicates that 30 volume dumps precede the current one on the
tape). If the dump was written to a backup data file, this
number is the ordinal of the 16 KB-offset at which the volume's
data begins.
=item B<date>
The date and time when the volume was dumped.
=back
One way to generate a file for use as input to the B<-file> argument is
to combine the B<-name> and B<-n> options, directing the output to a file.
The IBM AFS Administration Guide section on using the Backup System to
restore data explains how to edit the file as necessary before using
it as input to the B<-file> argument.
The output of this command includes only volumes for which the Backup
Database includes at least one dump record. The command interpreter
generates a message on the standard error stream about volumes that do
not have dump records but either are listed in the file named by the
B<-file> argument, or appear in the VLDB as a match to a volume entry in
the volume set named by the B<-name> argument.
=head1 EXAMPLES
The following command restores all volumes included in entries in the
volume set named B<data.restore>, which was created expressly to restore
data to a pair of file server machines on which all data was corrupted
due to a software error. All volumes are restored to the sites
recorded in their entries in the VLDB.
backup volsetrestore -name data.restore
Starting restore
backup: task ID of restore operation: 112
backup: Finished doing restore
The following command restores all volumes that have entries in the
file named B</tmp/restore>:
backup volsetrestore -file B</tmp/restore>
Starting restore
backup: task ID of restore operation: 113
backup: Finished doing restore
The B</tmp/restore> file has the following contents:
fs1.abc.com b user.pat
fs1.abc.com b user.terry
fs1.abc.com b user.smith
fs2.abc.com c user.jones
. . .
. . .
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server or Volume Location (VL) Server is
running, and on every file server machine that houses an affected
volume. If the B<-localauth> flag is included, the issuer must instead be
logged on to a server machine as the local superuser B<root>.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<backup(1)>,
L<backup_addvolentry(1)>,
L<backup_addvolset(1)>,
L<backup_diskrestore(1)>,
L<backup_dump(1)>,
L<backup_volrestore(1)>,
L<butc(1)>
=cut

299
doc/man-pages/pod/bos.pod Normal file
View File

@ -0,0 +1,299 @@
=head1 NAME
bos - Introduction to the C<bos> command suite
=head1 DESCRIPTION
The commands in the C<bos> command suite are the administrative interface
to the Basic OverSeer (BOS) Server, which runs on every file server
machine to monitor the other server processes on it. If a process
fails, the BOS Server can restart it automatically, taking into
account interdependencies between it and other processes. The BOS
Server frees system administrators from constantly monitoring the
status of server machines and processes.
There are several categories of commands in the C<bos> command suite:
=over
=item *
Commands to administer server process binary files: C<bos getdate>,
C<bos install>, C<bos prune>, and C<bos uninstall>
=item *
Commands to maintain system configuration files: C<bos addhost>, C<bos
addkey>, C<bos adduser>, C<bos listhosts>, C<bos listkeys>, C<bos listusers>,
C<bos removehost>, C<bos removekey>, C<bos removeuser>, and C<bos setcellname>
=item *
Commands to start and stop processes: C<bos create>, C<bos delete>, C<bos
restart>, C<bos shutdown>, C<bos start>, C<bos startup>, and C<bos stop>
=item *
Commands to set and verify server process and server machine
status: C<bos getlog>, C<bos getrestart>, C<bos setauth>, C<bos setrestart>,
and C<bos status>
=item *
A command to restore file system consistency: C<bos salvage>
=item *
Commands to obtain help: C<bos apropos> and C<bos help>
=back
The BOS Server and the C<bos> commands use and maintain the following
configuration and log files:
=over
=item *
The B</usr/afs/etc/CellServDB> file lists the local cell's database
server machines. These machines run the Authentication, Backup,
Protection and Volume Location (VL) Server processes, which
maintain databases of administrative information. The database
server processes consult the file to learn about their peers,
whereas the other server processes consult it to learn where to
access database information as needed. To administer the
B<CellServDB> file, use the following commands: C<bos addhost>, C<bos
listhosts>, C<bos removehost>, and C<bos setcellname>.
=item *
The B</usr/afs/etc/KeyFile> file lists the server encryption keys
that the server processes use to decrypt tickets presented by
client processes and one another. To administer the KeyFile file,
use the following commands: C<bos addkey>, C<bos listkeys>, and C<bos
removekey>.
=item *
The B</usr/afs/etc/ThisCell> file defines the cell to which the
server machine belongs for the purposes of server-to-server
communication. Administer it with the C<bos setcellname> command.
There is also a B</usr/vice/etc/ThisCell> file that defines the
machine's cell membership with respect to the AFS command suites
and Cache Manager access to AFS data.
=item *
The B</usr/afs/etc/UserList> file lists the user name of each
administrator authorized to issue privileged C<bos> and C<vos> commands.
To administer the UserList file, use the following commands: C<bos
adduser>, C<bos listusers>, and C<bos removeuser>.
=item *
The B</usr/afs/local/BosConfig> file defines which AFS server
processes run on the server machine, and whether the BOS Server
restarts them automatically if they fail. It also defines when all
processes restart automatically (by default once per week), and
when the BOS Server restarts processes that have new binary files
(by default once per day). To administer the BosConfig file, use
the following commands: C<bos create>, C<bos delete>, C<bos getrestart>,
C<bos setrestart>, C<bos start>, and C<bos stop>.
=item *
The B</usr/afs/log/BosLog> file records important operations the BOS
Server performs and error conditions it encounters.
=back
For more details, see the reference page for each file.
=head1 OPTIONS
The following arguments and flags are available on many commands in
the C<bos> suite. The reference page for each command also lists them,
but they are described here in greater detail.
=over 4
=item B<-cell> I<cell name>
Names the cell in which to run the command. It is acceptable to
abbreviate the cell name to the shortest form that
distinguishes it from the other entries in the
B</usr/vice/etc/CellServDB> file on the local machine. If the
B<-cell> argument is omitted, the command interpreter determines
the name of the local cell by reading the following in order:
=over
=item 1.
The value of the AFSCELL environment variable
=item 2.
The local B</usr/vice/etc/ThisCell> file
=back
Do not combine the B<-cell> and B<-localauth> options. A command on
which the B<-localauth> flag is included always runs in the local
cell (as defined in the server machine's local
B</usr/afs/etc/ThisCell> file), whereas a command on which the
B<-cell> argument is included runs in the specified foreign cell.
=item B<-help>
Prints a command's online help message on the standard output
stream. Do not combine this flag with any of the command's
other options; when it is provided, the command interpreter
ignores all other options, and only prints the help message.
=item B<-localauth>
Constructs a server ticket using the server encryption key with
the highest key version number in the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket, which never expires, to the BOS Server during
mutual authentication.
Use this flag only when issuing a command on a server machine;
client machines do not usually have a B</usr/afs/etc/KeyFile>
file. The issuer of a command that includes this flag must be
logged on to the server machine as the local superuser B<root>.
The flag is useful for commands invoked by an unattended
application program, such as a process controlled by the UNIX
B<cron> utility or by a cron entry in the machine's
B</usr/afs/local/BosConfig> file. It is also useful if an
administrator is unable to authenticate to AFS but is logged in
as the local superuser B<root>.
Do not combine the B<-cell> and B<-localauth> options. A command on
which the B<-localauth> flag is included always runs in the local
cell (as defined in the server machine's local
B</usr/afs/etc/ThisCell> file), whereas a command on which the
B<-cell> argument is included runs in the specified foreign cell.
Also, do not combine the B<-localauth> and B<-noauth> flags.
=item B<-noauth>
Establishes an unauthenticated connection to the BOS Server, in
which the BOS Server treats the issuer as the unprivileged user
B<anonymous>. It is useful only when authorization checking is
disabled on the server machine (during the installation of a
file server machine or when the C<bos setauth> command has been
used during other unusual circumstances). In normal
circumstances, the BOS Server allows only privileged users to
issue commands that change the status of a server or
configuration file, and refuses to perform such an action even
if the B<-noauth> flag is provided. Do not combine the B<-noauth> and
B<-localauth> flags.
=item B<-server> I<machine name>
Indicates the AFS server machine on which to run the command.
Identify the machine by its IP address in dotted decimal
format, its fully-qualified host name (for example,
B<fs1.abc.com>), or by an abbreviated form of its host name that
distinguishes it from other machines. Successful use of an
abbreviated form depends on the availability of a name service
(such as the Domain Name Service or a local host table) at the
time the command is issued.
For the commands that alter the administrative files shared by
all server machines in the cell (the C<bos addhost>, C<bos addkey>,
C<bos adduser>, C<bos removehost>, C<bos removekey>, and C<bos removeuser>
commands), the appropriate machine depends on whether the cell
uses the United States or international version of AFS:
=over
=item *
If the cell runs the United States edition of AFS and (as
recommended) uses the Update Server to distribute the
contents of the B</usr/afs/etc> directory, provide the name of
the system control machine. After issuing the command, allow
up to five minutes for the Update Server to distribute the
changed file to the other AFS server machines in the cell. If
the specified machine is not the system control machine but
is running an B<upclientetc> process that refers to the system
control machine, then the change will be overwritten when the
process next brings over the relevant file from the system
control machine.
=item *
If the cell runs the international edition of AFS, do not use
the Update Server to distribute the contents of the
B</usr/afs/etc> directory. Instead, repeatedly issue the
command, naming each of the cell's server machines in turn.
To avoid possible inconsistency problems, finish issuing the
commands within a fairly short time.
=back
=back
=head1 PRIVILEGE REQUIRED
To issue any C<bos> command that changes a configuration file or alters
process status, the issuer must be listed in the B</usr/afs/etc/UserList>
file on the server machine named by the B<-server> argument.
Alternatively, if the B<-localauth> flag is included the issuer must be
logged on as the local superuser B<root>.
To issue a C<bos> command that only displays information (other than the
C<bos listkeys> command), no privilege is required.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<BosConfig(1)>,
L<CellServDB_client_version(1)>,
L<CellServDB_server_version(1)>,
L<KeyFile(1)>,
L<ThisCell_client_version(1)>,
L<ThisCell_server_version(1)>,
L<UserList(1)>,
L<bos_addhost(1)>,
L<bos_addkey(1)>,
L<bos_adduser(1)>,
L<bos_apropos(1)>,
L<bos_create(1)>,
L<bos_delete(1)>,
L<bos_exec(1)>,
L<bos_getdate(1)>,
L<bos_getlog(1)>,
L<bos_getrestart(1)>,
L<bos_help(1)>,
L<bos_install(1)>,
L<bos_listhosts(1)>,
L<bos_listkeys(1)>,
L<bos_listusers(1)>,
L<bos_prune(1)>,
L<bos_removehost(1)>,
L<bos_removekey(1)>,
L<bos_removeuser(1)>,
L<bos_restart(1)>,
L<bos_salvage(1)>,
L<bos_setauth(1)>,
L<bos_setcellname(1)>,
L<bos_setrestart(1)>,
L<bos_shutdown(1)>,
L<bos_start(1)>,
L<bos_startup(1)>,
L<bos_status(1)>,
L<bos_stop(1)>,
L<bos_uninstall(1)>
=cut

124
doc/man-pages/pod/bos_addhost.pod Normal file
View File

@ -0,0 +1,124 @@
=head1 NAME
bos addhost - Adds a database server machine to the B</usr/afs/etc/CellServDB> file
=head1 SYNOPSIS
bos addhost B<-server> I<machine name> B<-host> I<host name> [I<host name> ...]
[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
bos addh B<-s> I<machine name> B<-ho> I<host name> [I<host name> ...]
[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-he>]
=head1 DESCRIPTION
The C<bos addhost> command adds an entry for each database server machine
specified with the B<-host> argument to the B</usr/afs/etc/CellServDB> file
on the machine named by the B<-server> argument.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Identifies the server machine on which to change the
B</usr/afs/etc/CellServDB> file. Identify the machine by IP
address or its host name (either fully-qualified or abbreviated
unambiguously). For details, see the introductory reference
page for the C<bos> command suite.
In cells that run the United States edition of AFS and use the
Update Server to distribute the contents of the B</usr/afs/etc>
directory, it is conventional to specify only the system
control machine as a value for the B<-server> argument. In cells
that run the international version of AFS, repeat the command
for each file server machine. For further discussion, see the
introductory reference page for the C<bos> command suite.
=item B<-host> I<host name> [I<host name> ...]
Specifies the fully-qualified host name (such as B<db1.abc.com>)
of each database server machine to register in the B<CellServDB>
file.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command adds the database server machines B<db2.abc.com>
and B<db3.abc.com> to the B</usr/afs/etc/CellServDB> file on the machine
B<fs1.abc.com> (the system control machine).
bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 CAVEATS
After executing this command (and waiting for the Update Server to
propagate the changes, if it is used), restart the database server
processes on all database server machines to force election of a
quorum that includes the new set of machines listed in the
B</usr/afs/etc/CellServDB> file. The IBM AFS Quick Beginnings explains in
more detail how to add and remove database server machines.
It is best to maintain a one-to-one mapping between hostnames and IP
addresses on a multihomed database server machine (this is actually
the conventional configuration for any AFS machine). The BOS Server
uses the B<gethostbyname( )> routine to obtain the IP address associated
with the hostname specified by the -host argument. If there is more
than one address, the BOS Server records in the B<CellServDB> entry the
one that appears first in the list of addresses returned by the
routine. The routine possibly returns addresses in a different order
on different machines, which can create inconsistency.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<CellServDB_server_version(1)>,
L<KeyFile(1)>,
L<UserList(1)>,
L<bos(1)>,
L<bos_listhosts(1)>,
L<bos_removehost(1)>,
IBM AFS Quick Beginnings
=cut

141
doc/man-pages/pod/bos_addkey.pod Normal file
View File

@ -0,0 +1,141 @@
=head1 NAME
bos addkey - Adds a new server encryption key to the B</usr/afs/etc/KeyFile> file
=head1 SYNOPSIS
bos addkey B<-server> I<machine name> [B<-key> I<key>]
B<-kvno> I<key version number> [B<-cell> I<cell name>]
[B<-noauth>] [B<-localauth>] [B<-help>]
bos addk B<-s> I<machine name> [B<-ke> I<key>] B<-kv> I<key version number>
[B<-ce> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos addkey> command constructs a server encryption key from the
text string provided, assigns it the key version number specified with
the B<-kvno> argument, and adds it to the B</usr/afs/etc/KeyFile> file on
the machine specified with the B<-server> argument. Be sure to use the
C<kas setpassword> or C<kas setkey> command to add the same key to the B<afs>
entry in the Authentication Database.
Do not use the B<-key> argument, which echoes the password string visibly
on the screen. If the argument is omitted, the BOS Server prompts for
the string and does not echo it visibly:
Input key:
Retype input key:
The BOS Server prohibits reuse of any key version number already
listed in the B</usr/afs/etc/KeyFile> file. This ensures that users who
still have tickets sealed with the current key are not prevented from
communicating with a server process because the current key is
overwritten with a new key. Use the C<bos listkeys> command to display
the key version numbers in the B</usr/afs/etc/KeyFile> file.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine on which to change the
B</usr/afs/etc/KeyFile> file. Identify the machine by IP address
or its host name (either fully-qualified or abbreviated
unambiguously). For details, see the introductory reference
page for the C<bos> command suite.
In cells that run the United States edition of AFS and use the
Update Server to distribute the contents of the B</usr/afs/etc>
directory, it is conventional to specify only the system
control machine as a value for the B<-server> argument. In cells
that run the international version of AFS, repeat the command
for each file server machine. For further discussion, see the
introductory reference page for the C<bos> command suite.
=item B<-key> I<key>
Specifies a character string just like a password; the BOS
Server calls a DES conversion function to encode it into a form
appropriate for use as an encryption key. Omit this argument to
have the BOS Server prompt for the string instead.
=item B<-kvno> I<key version number>
Defines the new key's key version number. It must be an integer
in the range from B<0> (zero) through B<255>. For the sake of
simplicity, use the number one higher than the current highest
key version number; use the C<bos listkeys> command to display key
version numbers.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
If the strings typed at the C<Input key> and C<Retype input key> prompts do
not match, the following message appears, and the command exits
without adding a new key:
Input key mismatch
=head1 EXAMPLES
The following command adds a new server encryption key with key
version number 14 to the B<KeyFile> file kept on the machine B<fs1.abc.com>
(the system control machine). The issuer omits the B<-key> argument, as
recommended, and provides the password at the prompts.
bos addkey -server fs1.abc.com -kvno 14
Input key:
Retype input key:
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<KeyFile(1)>,
L<UserList(1)>,
L<bos(1)>,
L<bos_listkeys(1)>,
L<bos_removekey(1)>
=cut

104
doc/man-pages/pod/bos_adduser.pod Normal file
View File

@ -0,0 +1,104 @@
=head1 NAME
bos adduser - Adds a privileged user to the B</usr/afs/etc/UserList> file
=head1 SYNOPSIS
bos adduser B<-server> I<machine name> B<-user> I<user names> [I<user names> ...]
[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
bos addu B<-s> I<machine name> B<-u> I<user names> [I<user names> ...]
[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos adduser> command adds each user name specified with the B<-user>
argument to the B</usr/afs/etc/UserList> file on the machine named by the
B<-server> argument. It is the issuer's responsibility to verify that an
entry for the user exists in the Authentication and Protection
Databases.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine on which to change the
B</usr/afs/etc/UserList> file. Identify the machine by IP address
or its host name (either fully-qualified or abbreviated
unambiguously). For details, see the introductory reference
page for the C<bos> command suite.
In cells that run the United States edition of AFS and use the
Update Server to distribute the contents of the B</usr/afs/etc>
directory, it is conventional to specify only the system
control machine as a value for the B<-server> argument. In cells
that run the international version of AFS, repeat the command
for each file server machine. For further discussion, see the
introductory reference page for the C<bos> command suite.
=item B<-user> I<user names> [I<user names> ...]
Specifies each user name to insert into the
B</usr/afs/etc/UserList> file.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command adds the user names pat and smith to the
B</usr/afs/etc/UserList> file on the machine B<fs1.abc.com> (the system
control machine).
bos adduser -server fs1.abc.com -user pat smith
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<KeyFile(1)>,
L<UserList(1)>,
L<bos(1)>,
L<bos_listusers(1)>,
L<bos_removeuser(1)>
=cut

70
doc/man-pages/pod/bos_apropos.pod Normal file
View File

@ -0,0 +1,70 @@
=head1 NAME
bos apropos - Displays each help entry containing a keyword string
=head1 SYNOPSIS
bos apropos B<-topic> I<help string> [B<-help>]
bos ap B<-t> I<help string> [B<-h>]
=head1 DESCRIPTION
The C<bos apropos> command displays the first line of the online help
entry for any C<bos> command that has in its name or short description
the string specified by the B<-topic> argument.
To display the syntax for a command, use the C<bos help> command.
=head1 OPTIONS
=over 4
=item B<-topic> I<help string>
Specifies the keyword string to match, in lowercase letters
only. If the string is more than a single word, surround it
with double quotes ("") or other delimiters.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
The first line of a command's online help entry names it and briefly
describes its function. This command displays the first line for any
C<bos> command where the string specified with the B<-topic> argument is
part of the command name or first line.
=head1 EXAMPLES
The following command lists all C<bos> commands that include the word
B<restart> in their names or short descriptions:
bos apropos restart
getrestart: get restart times
restart: restart all processes
setrestart: set restart times
=head1 PRIVILEGE REQUIRED
None
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<bos(1)>,
L<bos_help(1)>
=cut

410
doc/man-pages/pod/bos_create.pod Normal file
View File

@ -0,0 +1,410 @@
=head1 NAME
bos create - Defines a new process in the B</usr/afs/local/BosConfig> file and starts
it running
=head1 SYNOPSIS
bos create B<-server> I<machine name> B<-instance> I<server process name>
B<-type> I<server type> B<-cmd> I<command lines> [I<command lines> ...]
[B<-notifier> I<Notifier program>] [B<-cell> I<cell name>]
[B<-noauth>] [B<-localauth>] [B<-help>]
bos c B<-s> I<machine name> B<-i> I<server process name> B<-t> I<server type>
B<-cm> I<command lines> [I<command lines> ...] [B<-not> I<Notifier program>] [B<-ce> I<cell name>]
[B<-noa>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos create> command creates a server process entry in the
B</usr/afs/local/BosConfig> file on the server machine named by the
B<-server> argument, sets the process's status to B<Run> in the B<BosConfig>
file and in memory, and starts the process.
A server process's entry in the B<BosConfig> file defines its name, its
type, the command that initializes it, and optionally, the name of a
notifier program that runs when the process terminates.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine on which to define and start the
new process. Identify the machine by IP address or its host
name (either fully-qualified or abbreviated unambiguously). For
details, see the introductory reference page for the C<bos>
command suite.
=item B<-instance> I<server process name>
Names the process to define and start. Any name is acceptable,
but for the sake of simplicity it is best to use the last
element of the process's binary file pathname, and to use the
same name on every server machine. The conventional names, as
used in all AFS documentation, are:
=over
=item B<buserver>
The Backup Server process
=item B<fs>
The process that combines the File Server, Volume Server,
and Salvager processes (B<fileserver>, B<volserver>, and
B<salvager>)
=item B<kaserver>
The Authentication Server process
=item B<ptserver>
The Protection Server process
=item B<runntp>
The controller process for the Network Time Protocol
Daemon
=item B<upclientbin>
The client portion of the Update Server process that
retrieves binary files from the B</usr/afs/bin> directory of
the binary distribution machine for this machine's
CPU/operating system type. (The name of the binary is
B<upclient>, but the B<bin> suffix distinguishes this process
from B<upclientetc>.)
=item B<upclientetc>
The client portion of the Update Server process that
retrieves configuration files from the B</usr/afs/etc>
directory of the system control machine. Do not run this
process in cells that use the international edition of
AFS. (The name of the binary is B<upclient>, but the B<etc>
suffix distinguishes this process from B<upclientbin>.)
=item B<upserver>
The server portion of the Update Server process
=item B<vlserver>
The Volume Location (VL) Server process
=back
=item B<-type> I<server type>
Specifies the process's type. The acceptable values are:
=over
=item B<cron>
Use this value for cron-type processes that the BOS
Server starts only at a defined daily or weekly time,
rather than whenever it detects that the process has
terminated. AFS does not define any such processes by
default, but makes this value available for administrator
use. Define the time for command execution as part of the
B<-cmd> argument to the C<bos create> command.
=item B<fs>
Use this value only for the B<fs> process, which combines
the File Server, Volume Server and Salvager processes. If
one of the component processes terminates, the BOS Server
shuts down and restarts the processes in the appropriate
order.
=item B<simple>
Use this value for all processes listed as acceptable
values to the B<-instance> argument, except for the B<fs>
process. There are no interdependencies between simple
processes, so the BOS Server can stop and start them
independently as necessary.
=back
=item B<-cmd> I<command lines> [I<command lines> ...]
Specifies each command the BOS Server runs to start the
process. Specify no more than six commands (which can include
the command's options, in which case the entire string is
surrounded by double quotes); any additional commands are
ignored.
For a simple process, provide the complete pathname of the
process's binary file on the local disk (for example,
B</usr/afs/bin/ptserver> for the Protection Server). If including
any of the initialization command's options, surround the
entire command in double quotes (" "). The B<upclient> process has
a required argument, and the commands for all other processes
take optional arguments.
For the B<fs> process, provide the complete pathname of the local
disk binary file for each of the component processes:
B<fileserver>, B<volserver>, and B<salvager>, in that order. The
standard binary directory is B</usr/afs/bin>. If including any of
an initialization command's options, surround the entire
command in double quotes (B<" ">).
For a B<cron> process, provide two parameters:
=over
=item *
The complete local disk pathname of either an executable file
or a command from one of the AFS suites (complete with all of
the necessary arguments). Surround this parameter with double
quotes (B<" ">) if it contains spaces.
=item *
A specification of when the BOS Server executes the file or
command indicated by the first parameter. There are three
acceptable values:
=over
=item *
The string C<now>, which directs the BOS Server to execute
the file or command immediately and only once. It is
usually simpler to issue the command directly or issue
the C<bos exec> command.
=item *
A time of day. The BOS Server executes the file or
command daily at the indicated time. Separate the hours
and minutes with a colon (I<hh>:I<MM>), and use either 24-hour
format, or a value in the range from B<1:00> through B<12:59>
with the addition of B<am> or B<pm>. For example, both B<14:30>
and B<"2:30 pm"> indicate 2:30 in the afternoon. Surround
this parameter with double quotes (B<" ">) if it contains a
space.
=item *
A day of the week and time of day, separated by a space
and surrounded with double quotes (B<" ">). The BOS Server
executes the file or command weekly at the indicated day
and time. For the day, provide either the whole name or
the first three letters, all in lowercase letters
(B<sunday> or B<sun>, B<thursday> or B<thu>, and so on). For the
time, use the same format as when specifying the time
alone.
=back
=back
=item B<-notifier> I<Notifier program>
Specifies the complete pathname on the local disk of a program
that the BOS Server invokes when the process terminates. The
AFS distribution does not include any notifier programs, but
this argument is available for administrator use. See the
L</"Related Information"> section.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command defines and starts the simple process kaserver
on the machine B<fs3.abc.com>:
bos create -server fs3.abc.com -instance kaserver -type simple \
-cmd /usr/afs/bin/kaserver
The following command defines and starts the simple process
B<upclientbin> on the machine B<fs4.abc.com>. It references B<fs1.abc.com> as
the source for updates to binary files, checking for changes to the
B</usr/afs/bin> directory every 120 seconds.
bos create -server fs4.abc.com -instance upclientbin -type simple \
-cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
/usr/afs/bin"
The following command creates the fs process B<fs> on the machine
B<fs4.abc.com>. Type the command on a single line.
bos create -server fs4.abc.com -instance fs -type fs \
-cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
/usr/afs/bin/salvager
The following command creates a B<cron> process called B<userbackup> on the
machine B<fs5.abc.com>, so that the BOS Server issues the indicated C<vos
backupsys> command each day at 3:00 a.m. (the command creates a backup
version of every volume in the file system whose name begins with
B<user>). Note that the issuer provides the complete pathname to the C<vos>
command, includes the B<-localauth> flag on it, and types the entire C<bos
create> command on one line.
bos create -server fs5.abc.com -instance userbackup -type cron \
-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 Related Information
If the B<-notifier> argument is included when this command is used to
define and start a process, the BOS Server invokes the indicated
I<notifier program> when the process exits. The intended use of a
notifier program is to inform administrators when a process exits
unexpectedly, but it can be used to perform any appropriate actions.
The following paragraphs describe the B<bnode> and B<bnode_proc> structures
in which the BOS Server records information about the exiting process.
The list of AFS commands related to this one follows.
The BOS Server constructs and sends on the standard output stream one
B<bnode> and one B<bnode_proc> structure for each exiting process associated
with the notifier program. It brackets each structure with appropriate
C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN bnode_proc>
and C<END bnode_proc>), which immediately follow the preceding newline
character with no intervening spaces or other characters. If the
notifier program does not need information from a structure, it can
scan ahead in the input stream for the C<END> statement.
In general, each field in a structure is a string of ASCII text
terminated by the newline character. The format of the information
within a structure possibly varies slightly depending on the type of
process associated with the notifier program.
The C code for the B<bnode> and B<bnode_proc> structures follows. Note that
the structures sent by the BOS Server do not necessarily include all
of the fields described here, because some are used only for internal
record keeping. The notifier process must robustly handle the absence
of expected fields, as well as the presence of unexpected fields, on
the standard input stream.
For proper performance, the notifier program must continue processing
the input stream until it detects the end-of-file (EOF). The BOS
Server closes the standard input file descriptor to the notifier
process when it has completed delivery of the data, and it is the
responsibility of the notifier process to terminate properly.
=head2 struct bnode contents
struct bnode {
struct bnode *next; /* next pointer in top-level's list */
char *name; /* instance name */
long nextTimeout; /* next time this guy should be awakened */
long period; /* period between calls */
long rsTime; /* time we started counting restarts */
long rsCount; /* count of restarts since rsTime */
struct bnode_type *type; /* type object */
struct bnode_ops *ops; /* functions implementing bnode class */
long procStartTime; /* last time a process was started */
long procStarts; /* number of process starts */
long lastAnyExit; /* last time a process exited for any reason */
long lastErrorExit; /* last time a process exited unexpectedly */
long errorCode; /* last exit return code */
long errorSignal; /* last proc terminating signal */
char *lastErrorName; /* name of proc that failed last */
short refCount; /* reference count */
short flags; /* random flags */
char goal; /* 1=running or 0=not running */
char fileGoal; /* same, but to be stored in file */
};
=head2 format of struct bnode explosion
printf("name: %s\n",tp->name);
printf("rsTime: %ld\n", tp->rsTime);
printf("rsCount: %ld\n", tp->rsCount);
printf("procStartTime: %ld\n", tp->procStartTime);
printf("procStarts: %ld\n", tp->procStarts);
printf("lastAnyExit: %ld\n", tp->lastAnyExit);
printf("lastErrorExit: %ld\n", tp->lastErrorExit);
printf("errorCode: %ld\n", tp->errorCode);
printf("errorSignal: %ld\n", tp->errorSignal);
printf("lastErrorName: %s\n", tp->lastErrorName);
printf("goal: %d\n", tp->goal);
=head2 struct bnode_proc contents
struct bnode_proc {
struct bnode_proc *next; /* next guy in top-level's list */
struct bnode *bnode; /* bnode creating this process */
char *comLine; /* command line used to start this process */
char *coreName; /* optional core file component name */
long pid; /* pid if created */
long lastExit; /* last termination code */
long lastSignal; /* last signal that killed this guy */
long flags; /* flags giving process state */
};
=head2 format of struct bnode_proc explosion
printf("comLine: %s\n", tp->comLine);
printf("coreName: %s\n", tp->coreName);
printf("pid: %ld\n", tp->pid);
printf("lastExit: %ld\n", tp->lastExit);
printf("lastSignal: %ld\n", tp->lastSignal);
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<BosConfig(1)>,
L<KeyFile(1)>,
L<UserList(1)>,
L<bos(1)>,
L<buserver(1)>,
L<fileserver(1)>,
L<kaserver(1)>,
L<ptserver(1)>,
L<runntp(1)>,
L<salvager(1)>,
L<upclient(1)>,
L<upserver(1)>,
L<vlserver(1)>,
L<volserver(1)>,
L<vos_backupsys(1)>
=cut

101
doc/man-pages/pod/bos_delete.pod Normal file
View File

@ -0,0 +1,101 @@
=head1 NAME
bos delete - Deletes a server process from the B</usr/afs/local/BosConfig> file
=head1 SYNOPSIS
bos delete B<-server> I<machine name> B<-instance> I<server process name> [I<server process name> ...]
[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
bos d B<-s> I<machine name> B<-i> I<server process name> [I<server process name> ...] [B<-c> I<cell name>]
[B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos delete> command removes the B</usr/afs/local/BosConfig> entry for
each process indicated by the B<-instance> argument, on the server
machine named by the B<-server> argument.
Before issuing this command, issue the C<bos stop> command to stop the
process and set its status flag in the B<BosConfig> file to C<NotRun>. The
C<bos delete> command fails with an error message if a process's status
flag is C<Run>.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine on which to delete the server
process entry from the B</usr/afs/local/BosConfig> file. Identify
the machine by IP address or its host name (either
fully-qualified or abbreviated unambiguously). For details, see
the introductory reference page for the C<bos> command suite.
=item B<-instance> I<server process name> [I<server process name> ...]
Names each process to delete. Use the name assigned with the
B<-instance> argument to the C<bos create> command; process names
appear in the output of the C<bos status> command.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command removes the B<buserver>, B<kaserver>, B<ptserver>, and
B<vlserver> entries from the B<BosConfig> file on B<db3.abc.com>, a database
server machine being decommissioned.
bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<BosConfig(1)>,
L<KeyFile(1)>,
L<UserList(1)>,
L<bos(1)>,
L<bos_create(1)>,
L<bos_status(1)>
=cut

90
doc/man-pages/pod/bos_exec.pod Normal file
View File

@ -0,0 +1,90 @@
=head1 NAME
bos exec - Executes a command on a remote server machine
=head1 SYNOPSIS
bos exec B<-server> I<machine name> B<-cmd> I<command to execute>
[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
bos e B<-s> I<machine name> B<-cm> I<command to execute> [B<-ce> I<cell name>]
[B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos exec> command executes the indicated command on the file server
machine named by the B<-server> argument. Its intended use is to reboot
the machine, using the B</etc/reboot> command or equivalent.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine on which to execute the command.
Identify the machine by IP address or its host name (either
fully-qualified or abbreviated unambiguously). For details, see
the introductory reference page for the C<bos> command suite.
=item B<-cmd> I<command to execute>
Specifies the complete local disk pathname of the command to
execute (for example, B</etc/reboot>). Surround this argument with
double quotes ("") if the command contains one or more spaces.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 EXAMPLES
The following command reboots the machine B<fs2.abc.com>. The issuer has
previously issued the C<bos shutdown> command to shutdown all processes
cleanly.
bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now
=head1 PRIVILEGE REQUIRED
The issuer must be listed in the B</usr/afs/etc/UserList> file on the
machine named by the B<-server> argument, or must be logged onto a server
machine as the local superuser B<root> if the B<-localauth> flag is
included.
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<bos(1)>
=cut

119
doc/man-pages/pod/bos_getdate.pod Normal file
View File

@ -0,0 +1,119 @@
=head1 NAME
bos getdate - Displays the time stamps on an AFS binary file
=head1 SYNOPSIS
bos getdate B<-server> I<machine name> B<-file> I<files to check> [I<files to check> ...]
[B<-dir> I<destination dir>] [B<-cell> I<cell name>]
[B<-noauth>] [B<-localauth>] [B<-help>]
bos getd B<-s> I<machine name> B<-f> I<files to check> [I<files to check> ...] [B<-d> I<destination dir>]
[B<-c> I<cell name>] [B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos getdate> command displays the time stamps on the current
version, C<.BAK> version (if any) and C<.OLD> version (if any) of each
binary file named by the B<-file> argument. (The BOS Server automatically
creates C<.BAK> and C<.OLD> versions when new binaries are installed with
the C<bos install> command.) The files must reside in the B</usr/afs/bin>
directory on the server machine named by the B<-server> argument unless
the B<-dir> argument indicates an alternate directory.
To revert to the C<.BAK> version of a binary, use the C<bos uninstall>
command. To remove obsolete binary files from the B</usr/afs/bin>
directory, use the C<bos prune> command.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine from which to list binary files.
Identify the machine by IP address or its host name (either
fully-qualified or abbreviated unambiguously). For details, see
the introductory reference page for the C<bos> command suite.
All server machines of the same AFS system type show the same
timestamps if the binaries were installed properly on the
binary distribution machine for this machine's system type, and
if all other machines of that type are running the appropriate
B<upclientbin> process.
=item B<-file> I<files to check> [I<files to check> ...]
Names each binary file to list.
=item B<-dir> I<destination dir>
Specifies the complete pathname of the local disk directory
containing each file named by the B<-file> argument. It is
necessary only if the files are not in the B</usr/afs/bin>
directory.
=item B<-cell> I<cell name>
Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<bos(1)> reference page.
=item B<-noauth>
Assigns the unprivileged identity B<anonymous> to the issuer. Do
not combine this flag with the B<-localauth> flag. For more
details, see the introductory L<bos(1)> reference page.
=item B<-localauth>
Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<bos> command interpreter presents
the ticket to the BOS Server during mutual authentication. Do
not combine this flag with the B<-cell> or B<-noauth> options. For
more details, see the introductory L<bos(1)> reference page.
=item B<-help>
Prints the online help for this command. All other valid
options are ignored.
=back
=head1 OUTPUT
For each file specified with the B<-file> argument, the output displays
the time stamp on the current (unmarked), C<.BAK>, and C<.OLD> version. The
output explicitly reports that a version does not exist, rather than
simply omitting it.
=head1 EXAMPLES
The following command examines the time stamps on the files with
basename B<kaserver> on the machine B<fs2.abc.com>:
bos getdate -server fs2.abc.com -file kaserver
File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999.
.BAK file dated Wed Dec 9 18:55:04 1998, no .OLD file.
=head1 PRIVILEGE REQUIRED
None
=head1 COPYRIGHT
IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.
=head1 SEE ALSO
L<KeyFile(1)>,
L<bos(1)>,
L<bos_install(1)>,
L<bos_prune(1)>,
L<bos_uninstall(1)>
=cut

154
doc/man-pages/pod/bos_getlog.pod Normal file
View File

@ -0,0 +1,154 @@
=head1 NAME
bos getlog - Prints a server process's log file
=head1 SYNOPSIS
bos getlog B<-server> I<machine name> B<-file> I<log file to examine>
[B<-cell> I<cell name>] [B<-noauth>] [B<-localauth>] [B<-help>]
bos getl B<-s> I<machine name> B<-f> I<log file to examine> [B<-c> I<cell name>]
[B<-n>] [B<-l>] [B<-h>]
=head1 DESCRIPTION
The C<bos getlog> command displays on the standard output stream the
specified log file from the machine named by the B<-server> argument. The
BOS Server fetches the log file from the B</usr/afs/logs> directory
unless an alternate pathname is provided as part of the B<-file>
argument.
=head1 OPTIONS
=over 4
=item B<-server> I<machine name>
Indicates the server machine from which to retrieve the log
file. Identify the machine by IP address or its host name
(either fully-qualified or abbreviated unambiguously). For
details, see the introductory reference page for the C<bos>
command suite.
=item B<-file> I<log file to examine>
Names the log file to display. If a filename only is provided,
the BOS Server fetches the log file from the B</usr/afs/logs>
directory; the standard values are:
=over
=item B<AuthLog>
The Authentication Server (B<kaserver>) log file
=item B<BackupLog>
The Backup Server (B<buserver>) log file
=item B<BosLog>
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

151
doc/man-pages/pod/bos_getrestart.pod Normal file
View File

@ -0,0 +1,151 @@
=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

95
doc/man-pages/pod/bos_help.pod Normal file
View File

@ -0,0 +1,95 @@
=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

139
doc/man-pages/pod/bos_install.pod Normal file
View File

@ -0,0 +1,139 @@
=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

111
doc/man-pages/pod/bos_listhosts.pod Normal file
View File

@ -0,0 +1,111 @@
=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

142
doc/man-pages/pod/bos_listkeys.pod Normal file
View File

@ -0,0 +1,142 @@
=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

98
doc/man-pages/pod/bos_listusers.pod Normal file
View File

@ -0,0 +1,98 @@
=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

144
doc/man-pages/pod/bos_prune.pod Normal file
View File

@ -0,0 +1,144 @@
=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

115
doc/man-pages/pod/bos_removehost.pod Normal file
View File

@ -0,0 +1,115 @@
=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

109
doc/man-pages/pod/bos_removekey.pod Normal file
View File

@ -0,0 +1,109 @@
=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

100
doc/man-pages/pod/bos_removeuser.pod Normal file
View File

@ -0,0 +1,100 @@
=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

152
doc/man-pages/pod/bos_restart.pod Normal file
View File

@ -0,0 +1,152 @@
=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

354
doc/man-pages/pod/bos_salvage.pod Normal file
View File

@ -0,0 +1,354 @@
=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

114
doc/man-pages/pod/bos_setauth.pod Normal file
View File

@ -0,0 +1,114 @@
=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

134
doc/man-pages/pod/bos_setcellname.pod Normal file
View File

@ -0,0 +1,134 @@
=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

190
doc/man-pages/pod/bos_setrestart.pod Normal file
View File

@ -0,0 +1,190 @@
=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

133
doc/man-pages/pod/bos_shutdown.pod Normal file
View File

@ -0,0 +1,133 @@
=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

103
doc/man-pages/pod/bos_start.pod Normal file
View File

@ -0,0 +1,103 @@
=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

119
doc/man-pages/pod/bos_startup.pod Normal file
View File

@ -0,0 +1,119 @@
=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

277
doc/man-pages/pod/bos_status.pod Normal file
View File

@ -0,0 +1,277 @@
=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

107
doc/man-pages/pod/bos_stop.pod Normal file
View File

@ -0,0 +1,107 @@
=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

120
doc/man-pages/pod/bos_uninstall.pod Normal file
View File

@ -0,0 +1,120 @@
=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

162
doc/man-pages/pod/bosserver.pod Normal file
View File

@ -0,0 +1,162 @@
=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

159
doc/man-pages/pod/buserver.pod Normal file
View File

@ -0,0 +1,159 @@
=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

230
doc/man-pages/pod/butc.pod Normal file
View File

@ -0,0 +1,230 @@
=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

230
doc/man-pages/pod/dlog.pod Normal file
View File

@ -0,0 +1,230 @@
=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

113
doc/man-pages/pod/dpass.pod Normal file
View File

@ -0,0 +1,113 @@
=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

493
doc/man-pages/pod/fileserver.pod Normal file
View File

@ -0,0 +1,493 @@
=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

145
doc/man-pages/pod/fms.pod Normal file
View File

@ -0,0 +1,145 @@
=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

203
doc/man-pages/pod/fs.pod Normal file
View File

@ -0,0 +1,203 @@
=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

71
doc/man-pages/pod/fs_apropos.pod Normal file
View File

@ -0,0 +1,71 @@
=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

234
doc/man-pages/pod/fs_checkservers.pod Normal file
View File

@ -0,0 +1,234 @@
=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

54
doc/man-pages/pod/fs_checkvolumes.pod Normal file
View File

@ -0,0 +1,54 @@
=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.

102
doc/man-pages/pod/fs_cleanacl.pod Normal file
View File

@ -0,0 +1,102 @@
=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

176
doc/man-pages/pod/fs_copyacl.pod Normal file
View File

@ -0,0 +1,176 @@
=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

121
doc/man-pages/pod/fs_diskfree.pod Normal file
View File

@ -0,0 +1,121 @@
=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

126
doc/man-pages/pod/fs_examine.pod Normal file
View File

@ -0,0 +1,126 @@
=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

215
doc/man-pages/pod/fs_exportafs.pod Normal file
View File

@ -0,0 +1,215 @@
=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

85
doc/man-pages/pod/fs_flush.pod Normal file
View File

@ -0,0 +1,85 @@
=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

76
doc/man-pages/pod/fs_flushmount.pod Normal file
View File

@ -0,0 +1,76 @@
=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

84
doc/man-pages/pod/fs_flushvolume.pod Normal file
View File

@ -0,0 +1,84 @@
=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

66
doc/man-pages/pod/fs_getcacheparms.pod Normal file
View File

@ -0,0 +1,66 @@
=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

70
doc/man-pages/pod/fs_getcellstatus.pod Normal file
View File

@ -0,0 +1,70 @@
=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

109
doc/man-pages/pod/fs_getclientaddrs.pod Normal file
View File

@ -0,0 +1,109 @@
=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

174
doc/man-pages/pod/fs_getserverprefs.pod Normal file
View File

@ -0,0 +1,174 @@
=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

95
doc/man-pages/pod/fs_help.pod Normal file
View File

@ -0,0 +1,95 @@
=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

196
doc/man-pages/pod/fs_listacl.pod Normal file
View File

@ -0,0 +1,196 @@
=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

83
doc/man-pages/pod/fs_listcells.pod Normal file
View File

@ -0,0 +1,83 @@
=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

111
doc/man-pages/pod/fs_listquota.pod Normal file
View File

@ -0,0 +1,111 @@
=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

130
doc/man-pages/pod/fs_lsmount.pod Normal file
View File

@ -0,0 +1,130 @@
=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

98
doc/man-pages/pod/fs_messages.pod Normal file
View File

@ -0,0 +1,98 @@
=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

Some files were not shown because too many files have changed in this diff Show More