diff --git a/doc/man-pages/Makefile.in b/doc/man-pages/Makefile.in index 0bb284de3f..9ec2d9b507 100644 --- a/doc/man-pages/Makefile.in +++ b/doc/man-pages/Makefile.in @@ -3,197 +3,32 @@ srcdir=@srcdir@ include @TOP_OBJDIR@/src/config/Makefile.config -MAN1 = \ - afs_intro.1 \ - fs.1 \ - fs_apropos.1 \ - fs_checkservers.1 \ - fs_checkvolumes.1 \ - fs_cleanacl.1 \ - fs_copyacl.1 \ - fs_diskfree.1 \ - fs_examine.1 \ - fs_exportafs.1 \ - fs_flush.1 \ - fs_flushmount.1 \ - fs_flushvolume.1 \ - fs_getcacheparms.1 \ - fs_getcellstatus.1 \ - fs_getclientaddrs.1 \ - fs_getserverprefs.1 \ - fs_help.1 \ - fs_listacl.1 \ - fs_listcells.1 \ - fs_listquota.1 \ - fs_lsmount.1 \ - fs_messages.1 \ - fs_mkmount.1 \ - fs_newcell.1 \ - fs_quota.1 \ - fs_rmmount.1 \ - fs_setacl.1 \ - fs_setcachesize.1 \ - fs_setcell.1 \ - fs_setclientaddrs.1 \ - fs_setquota.1 \ - fs_setserverprefs.1 \ - fs_setvol.1 \ - fs_storebehind.1 \ - fs_sysname.1 \ - fs_whereis.1 \ - fs_whichcell.1 \ - fs_wscell.1 \ - klog.1 \ - kpasswd.1 \ - kpwvalid.1 \ - pts.1 \ - pts_adduser.1 \ - pts_apropos.1 \ - pts_chown.1 \ - pts_creategroup.1 \ - pts_createuser.1 \ - pts_delete.1 \ - pts_examine.1 \ - pts_help.1 \ - pts_listentries.1 \ - pts_listmax.1 \ - pts_listowned.1 \ - pts_membership.1 \ - pts_removeuser.1 \ - pts_rename.1 \ - pts_setfields.1 \ - pts_setmax.1 +all: -MAN8 = \ - afsd.8 \ - afsmonitor.8 \ - backup.8 \ - backup_adddump.8 \ - backup_addhost.8 \ - backup_addvolentry.8 \ - backup_addvolset.8 \ - backup_apropos.8 \ - backup_dbverify.8 \ - backup_deldump.8 \ - backup_deletedump.8 \ - backup_delhost.8 \ - backup_delvolentry.8 \ - backup_delvolset.8 \ - backup_diskrestore.8 \ - backup_dump.8 \ - backup_dumpinfo.8 \ - backup_help.8 \ - backup_interactive.8 \ - backup_jobs.8 \ - backup_kill.8 \ - backup_labeltape.8 \ - backup_listdumps.8 \ - backup_listhosts.8 \ - backup_listvolsets.8 \ - backup_quit.8 \ - backup_readlabel.8 \ - backup_restoredb.8 \ - backup_savedb.8 \ - backup_scantape.8 \ - backup_setexp.8 \ - backup_status.8 \ - backup_volinfo.8 \ - backup_volrestore.8 \ - backup_volsetrestore.8 \ - bos.8 \ - bos_addhost.8 \ - bos_addkey.8 \ - bos_adduser.8 \ - bos_apropos.8 \ - bos_create.8 \ - bos_delete.8 \ - bos_exec.8 \ - bos_getdate.8 \ - bos_getlog.8 \ - bos_getrestart.8 \ - bos_help.8 \ - bos_install.8 \ - bos_listhosts.8 \ - bos_listkeys.8 \ - bos_listusers.8 \ - bos_prune.8 \ - bos_removehost.8 \ - bos_removekey.8 \ - bos_removeuser.8 \ - bos_restart.8 \ - bos_salvage.8 \ - bos_setauth.8 \ - bos_setcellname.8 \ - bos_setrestart.8 \ - bos_shutdown.8 \ - bos_start.8 \ - bos_startup.8 \ - bos_status.8 \ - bos_stop.8 \ - bos_uninstall.8 \ - bosserver.8 \ - buserver.8 \ - butc.8 \ - dlog.8 \ - dpass.8 \ - fileserver.8 \ - fms.8 \ - fstrace.8 \ - fstrace_apropos.8 \ - fstrace_clear.8 \ - fstrace_dump.8 \ - fstrace_help.8 \ - fstrace_lslog.8 \ - fstrace_lsset.8 \ - fstrace_setlog.8 \ - fstrace_setset.8 \ - kadb_check.8 \ - kas.8 \ - kas_apropos.8 \ - kas_create.8 \ - kas_delete.8 \ - kas_examine.8 \ - kas_forgetticket.8 \ - kas_help.8 \ - kas_interactive.8 \ - kas_list.8 \ - kas_listtickets.8 \ - kas_noauthentication.8 \ - kas_quit.8 \ - kas_setfields.8 \ - kas_setpassword.8 \ - kas_statistics.8 \ - kas_stringtokey.8 \ - kas_unlock.8 \ - kaserver.8 \ - kdb.8 \ - knfs.8 +maintclean: + rm -f *.1 *.5 *.8 -all: $(MAN1) $(MAN8) - -%.1: $(srcdir)/pod/%.pod - -pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 $< $@ - -%.8: $(srcdir)/pod/%.pod - -pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 $< $@ - -clean: - rm -f *.1 *.8 - -dest: $(MAN1) $(MAN8) - mkdir -p $(DEST)/man/man1 $(DEST)/man/man8 - -set -e; for M in $(MAN1) ; do \ +dest: + mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8 + set -e; for M in *.1 ; do \ $(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \ done - -set -e; for M in $(MAN8) ; do \ + set -e; for M in *.5 ; do \ + $(INSTALL) -c -m 0644 $$M $(DEST)/man/man5/$$M ; \ + done + set -e; for M in *.8 ; do \ $(INSTALL) -c -m 0644 $$M $(DEST)/man/man8/$$M ; \ done install: $(MAN1) $(MAN8) - mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man8 - -set -e; for M in $(MAN1) ; do \ + mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man5 \ + $(DESTDIR)$(mandir)/man8 + set -e; for M in *.1 ; do \ $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \ done - -set -e; for M in $(MAN8) ; do \ + set -e; for M in *.5 ; do \ + $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man5/$$M ; \ + done + set -e; for M in *.8 ; do \ $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \ done diff --git a/doc/man-pages/generate-file-map b/doc/man-pages/generate-file-map new file mode 100755 index 0000000000..8428c07fa8 --- /dev/null +++ b/doc/man-pages/generate-file-map @@ -0,0 +1,38 @@ +#!/usr/bin/perl +# +# From an AFS Administrative Reference HTML page, try to figure out what +# command or file it corresponds to and output the appropriate generate-pod +# command. Intended to be run as follows: +# +# generate-file-map *.htm > generate-pods.sh +# +# Each line of the output will be a generate-pod invocation, saving its output +# to the appropriate POD file. + +my %except = map { $_ => 1 } + ('Table of Contents', 'Audience and Purpose', 'Organization', + 'How to Use This Document', 'Related Documents', + 'Typographical Conventions'); + +for my $file (@ARGV) { + my $command; + open (IN, '<', $file) or die "$0: cannot open $file: $!\n"; + while () { + s///g; + s%%%g; + if (/

]+>([^<]+)/) { + $command = $1; + last; + } + } + if ($command) { + next if $except{$command}; + next if $command =~ /\(AFS version\)/; + $command =~ s/,.*//; + $command =~ s/ and.*//; + $command =~ s/\s/_/g; + $command =~ s/([\(\)])/\\$1/g; + print "../../man-pages/generate-pod $file >" + ." ../../man-pages/pod/$command.pod\n"; + } +} diff --git a/doc/man-pages/generate-pod b/doc/man-pages/generate-pod index 706d14dbc2..15456a1c1f 100755 --- a/doc/man-pages/generate-pod +++ b/doc/man-pages/generate-pod @@ -1,178 +1,189 @@ #!/usr/bin/perl -w # -# Parser for files obtained via -# lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt +# Convert the HTML pages of the Administrator's Reference into POD man pages. +# This script was written by Chas Williams and Russ Allbery, based on work by +# Alf Wachsmann and Elizabeth Cassell. It just does a first pass; it's +# expected that the results will require further hand-editing. use strict; -my $DEBUG = 0; -my $RAW = 0; +use HTML::Parser (); -my %hash; -my %options; +my @ignore_tags = qw(meta head comment html body); +my @ignore_elements = qw(script style); -###################################################################### -## Input Section: -###################################################################### +my %INLINES = ('b' => 'B<', + '/b' => '>', + 'i' => 'I<', + '/i' => '>', + 'var' => 'I<', + '/var' => '>', + 'tt' => 'C<', + '/tt' => '>', + 'a' => 'L<', + '/a' => '(1)>', + 'sup' => '', + '/sup' => ''); -my $del = $/; -undef $/; -my $text = ; -$/ = $del; +my %CDATA = ('dd' => 1, + 'dt' => 1, + 'h2' => 1, + 'a' => 1, + 'li' => 1, + 'p' => 1, + 'pre' => 1, + 'strong' => 1); -my $sections = 'Purpose|Synopsis|Description|Cautions|Options|Output|Examples|Privilege\ Required|Related\ Information|References'; +# Global state of the conversion. +my $command = ""; +my $output = 0; +my $emit = 0; +my $pre = 0; +my $buffer = ""; +my $inpara = 0; +my $lasttag = ""; +my $open = ""; +my $cdata = ""; +my $result = ""; -$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; +# Output some data. Accumulate this into $results so that we can do some +# post-filtering at the end. +sub output { + my ($format, @args) = @_; + $result .= sprintf($format, @args); } -$hash{'Related Information'} =~ s/\s*(.+?)\s*___________.*$/$1/xs; +# Handle a single element. +sub element { + if ($output) { + $buffer =~ s/^\s+\n/\n/m; + $buffer =~ s/\n+$/\n/g; - - -if (! $RAW) { - ###################################################################### - ## Clean-up Section: - ###################################################################### - - # make C 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/g; - $hash{$_} =~ s/(unprivileged\s(?:identity|user)\s)anonymous/$1B/g; - $hash{$_} =~ s/system\:administrators/B/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} = ""; + if ($lasttag eq "h2") { + $command = $buffer; + $command =~ s/^L$//; + } elsif ($lasttag eq "strong") { + if ($buffer eq 'Cautions') { + $buffer = 'CAVEATS'; + } elsif ($buffer eq 'Related Information') { + $buffer = 'SEE ALSO'; + } else { + $buffer = uc $buffer; + } + if ($buffer eq 'PURPOSE') { + output "=head1 NAME\n\n%s - ", $command; + } else { + output "=head1 %s\n\n", $buffer; + } + } elsif ($lasttag eq "h5") { + output "=head2 %s\n\n", $buffer; + } elsif ($lasttag eq "h6") { + output "=head3 %s\n\n", $buffer; + } elsif ($lasttag eq "p") { + $buffer =~ s/\n+$//g; + output "%s\n\n", $buffer if $buffer ne ""; + } elsif ($lasttag eq "pre") { + $buffer =~ s/\n+$//; + output "%s\n\n", $buffer if $buffer ne ""; + } elsif ($lasttag eq "ul" || $lasttag eq "dl") { + output "=over 4\n\n"; + } elsif ($lasttag eq "li") { + output "=item *\n\n%s\n\n", $buffer; + } elsif ($lasttag eq "dt") { + output "=item %s\n\n", $buffer; + } elsif ($lasttag eq "dd") { + output "%s\n", $buffer; + } elsif ($lasttag eq "/ul" || $lasttag eq "/dl") { + output "=back\n\n"; + } else { + if ($buffer ne "") { + printf ">>>%s:%s<<<", $lasttag, $buffer; + } + } } - } - - $hash{Options} =~ s/(?:\n|^)B<([^>]*?)>\ \n/\n=item B<$1>$options{$1}\n\n/sxg if ($hash{Options}); - - $hash{Examples} =~ s/\n\s*%(.*?)(?:\n|$)/\n\nB<\ \ \ $1>\n/sxg if ($hash{Examples}); - - $hash{'Related Information'} =~ s/\[\d+\](.*?)\s*\n/L<$1(1)>,\n/msxg if ($hash{'Related Information'}); - $hash{'Related Information'} =~ s/\[\d+\](.*)\s*/L<$1(1)>/msxg if ($hash{'Related Information'}); - $hash{'Related Information'} =~ s/(\w+)\s+(\w+)/$1_$2/msxg if ($hash{'Related Information'}); - - foreach (keys(%hash)) { - $hash{$_} =~ s/((?:\n\n=item\ \*\n(?:\n.+$)+)+)/\n\n=over$1\n\n=back/mxg; - } - - -}; - - -###################################################################### -## 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; + $buffer = ""; } -print $FH "=head1 NAME\n\n"; -print $FH "$hash{Command} - $hash{Purpose}\n\n"; +# Handle a single tag. +sub tag { + my $self = shift; + local $_ = shift; + my $tag = shift; + my $attr = shift; -if (exists $hash{Synopsis}) { - print $FH "=head1 SYNOPSIS\n\n"; - print $FH "$hash{Synopsis}\n\n"; + $output = 1 if ($tag eq "h2"); + $output = 0 if ($tag eq "hr"); + + if (defined $INLINES{$tag}) { + if (defined $open && $open eq $tag) { + printf STDERR "duplicate tag <%s>\n", $tag; + return; + } + if ($tag =~ /^\//) { + undef $open; + } else { + $open = $tag; + } + + &text(sprintf "%s", $INLINES{$tag}); + return; + } + + $cdata = 0; + $cdata = 1 if defined $CDATA{$tag}; + + &element; + $lasttag = $tag; } -print $FH "=head1 DESCRIPTION\n\n"; -print $FH "$hash{Description}\n\n"; +# Do text conversion, mostly undoing SGML escapes. +sub text { + local $_ = shift; -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 ($cdata) { + s/&/&/g; + s/ / /g; + s/>/>/g; + s/<//L<${1}_${2}>/g; + $buffer = $buffer . $_; + } } -if (exists $hash{Output}) { - print $FH "=head1 OUTPUT\n\n"; - print $FH "$hash{Output}\n\n"; -} +my $file = shift @ARGV; -if (exists $hash{Examples}) { - print $FH "=head1 EXAMPLES\n\n"; - print $FH "$hash{Examples}\n\n"; -} +my $p = HTML::Parser->new(api_version => 3, + start_h => [\&tag, "self, text, tag, attr"], + end_h => [\&tag, "self, text, tag, attr"], + process_h => ["", ""], + comment_h => ["", ""], + declaration_h => ["", ""], + default_h => [\&text, "text"], -if (exists $hash{'Privilege Required'}) { - print $FH "=head1 PRIVILEGE REQUIRED\n\n"; - print $FH "$hash{'Privilege Required'}\n\n"; -} + ignore_tags => \@ignore_tags, + ignore_elements => \@ignore_elements, + unbroken_text => 1); -if (exists $hash{Cautions}) { - print $FH "=head1 CAVEATS\n\n"; - print $FH "$hash{Cautions}\n\n"; -} +$p->parse_file($file) || die "Can't open file: $!\n"; -print $FH "=head1 COPYRIGHT\n\n"; -print $FH "IBM Corporation 2000. All Rights Reserved.\n\n"; -print $FH "Converted from html to pod by Alf Wachsmann , 2003,\n"; -print $FH "and Elizabeth Cassell , 2004,\n"; -print $FH "Stanford Linear Accelerator Center, a department of Stanford University.\n\n"; +# Fix up a few last things. +$result =~ s/L<(\S+) (\S+\(1\))>/L<${1}_${2}>/g; +$result =~ s/^(L<\S+>)\n\n(?=L<)/$1,\n/mg; +$result =~ s/^(\S+[^\n]+)\n +/$1\n/mg; +$result =~ s/^(\s+.*)B<([^>]+)>/$1$2/mg; -if (exists $hash{'Related Information'}) { - print $FH "=head1 SEE ALSO\n\n"; - print $FH "$hash{'Related Information'}\n\n"; - print $FH "=cut\n"; -} +# Append a stock copyright statement. +$result .= <<'EOC'; +=head1 COPYRIGHT -close(FILE) unless $DEBUG; +IBM Corporation 2000. All Rights Reserved. +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. +EOC + +# Output the results. +print $result; diff --git a/doc/man-pages/pod/afs_intro.pod b/doc/man-pages/pod/afs_intro.pod deleted file mode 100644 index 43d43c97de..0000000000 --- a/doc/man-pages/pod/afs_intro.pod +++ /dev/null @@ -1,570 +0,0 @@ -=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 - -Interface for configuring and operating the AFS Backup System - -=item B - -Interface to the Basic Overseer (BOS) Server for administering -server processes and configuration files - -=item B - -Interface for administering access control lists (ACLs), the -Cache Manager, and other miscellaneous file system functions - -=item B - -Interface for tracing Cache Manager operations when debugging -problems - -=item B - -Interface to the Authentication Server for administering -security and authentication information - -=item B - -Interface to the Protection Server for administering AFS ID and -group membership information - -=item B - -Interface for automated administration of user accounts - -=item B - -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 B B<-switch> I [I ...] [B<-flag>] - -=head2 Command Names - -Together, the B and B make up the command -name. - -The B 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, B, B, B, B, B, B and B. Some of these suites -have an interactive mode in which the issuer omits the B -portion of the command name. - -The B 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 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. - -=item * - -The I 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. 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>) 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. - -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 is the command suite. The BOS Server executes most of the -commands in this suite. - -=item * - -B is the operation code. It tells the BOS Server on the -specified server machine (in this case B) to report the -modification dates of binary files in the local B -directory. - -=item * - -B<-server> B is one argument, with B<-server> as the switch -and B as the value. This argument specifies the server -machine on which BOS Server is to collect and report binary dates. - -=item * - -B<-file> B B is an argument that takes multiple values. -The switch is B<-file> and the values are B and B. This -argument tells the BOS Server to report the modification dates on -the files B and B. - -=back - -=head2 Rules for Entering AFS Commands - -Enter each AFS command on a single line (press BReturnE> 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. - - 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 command interpreter relies on -the order of arguments. It assumes that the first element following -the operation code, B, is the server machine name, and that -the next argument, B, is a binary file name. Then, because the -command's second (and last) argument accepts multiple values, the -command interpreter correctly interprets B as an additional -value for it. - -On the other hand, the following is not acceptable because it violates -the first two conditions in L: 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 for C - -C for C - -C for C - -C for C - -C for C - -C for C - -C for C - -C for C - -C for C - -In addition to abbreviations, some operation codes have an I, a -short form that is not derived by abbreviating the operation code to -its shortest unambiguous form. For example, the alias for the C command is C, whereas the shortest unambiguous abbreviation -is C. - -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 -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 -has the alias C, its former name. It is acceptable to -abbreviate aliases to their shortest unambiguous form (for -example, C to C). - -=back - -Even if an operation code has an alias, it is still acceptable to use -the shortest unambiguous form. Thus, the C command has three -acceptable forms: C (the full form), C (the shortest -abbreviation), and C (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. - -=head3 Abbreviating Server Machine Names - -AFS server machines must have fully-qualified Internet-style host -names (for example, B), 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 -BI or BI, 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, the second -B, 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 (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 for the State University or B for ABC Corporation). -Some AFS commands accept unambiguous shortened forms, usually with -respect to the local B 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 and C 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, 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 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 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 command: - - fs help setacl - fs setacl: set access control list - aliases: sa - Usage: fs setacl B<-dir> + B<-acl> + - [-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> + B<-acl> + - [-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 -suite, but cannot remember the operation code. She uses C 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/afsd.pod b/doc/man-pages/pod/afsd.pod deleted file mode 100644 index 01c1efe785..0000000000 --- a/doc/man-pages/pod/afsd.pod +++ /dev/null @@ -1,597 +0,0 @@ -=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] -[B<-rootvol> I] -[B<-stat> I] -[B<-memcache>] [B<-cachedir> I] -[B<-mountdir> I] -[B<-daemons> I] -[B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [B<-debug>] -[B<-chunksize> I] -[B<-dcache> I] -[B<-volumes> I] -[B<-biods> I] -[B<-prealloc> I] -[B<-confdir> I] -[B<-logfile> I] -[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 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 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 file -instead.) This information is transferred into the kernel from the -B file and cannot be changed until the C -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 file. After -initialization, use the C 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 file (the default) or the C command's -B<-mountdir> argument. The conventional value is B. - -=item * - -Determines which volume to mount at the root of the AFS file tree. -The default is the volume B; 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) 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 -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 -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 file is the source -for this name, and the standard value is the B -directory. Use the B<-cachedir> argument to override the value in the -B file. - -=item * - -Sets the size of the cache. The default source for the value is -the third field in the B file, which -specifies a number of kilobytes. - -For a memory cache, the following arguments to the C command -override the value in the B 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 -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 -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 program exits without -initializing the Cache Manager and produces the following message -on the standard output stream: - -afsd: memCache allocation failure at I KB - -where I is how many kilobytes were allocated just before the -failure. - -For a disk cache, use the B<-blocks> argument to the C command to -override the value in the B 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 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 command; the setting persists -until the C command runs again or the C command -is reissued. The C command does not work for memory -caches. - -=item * - -Sets the size of each cache I, 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 BI 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 section for details. For a memory -cache, if total cache size divided by chunk size leaves a -remainder, the C 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 (BI 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/I * 1.5) - -=item * - -The result of dividing cachesize by 10 KB (I/10240) - -=back - -=item * - -Sets the number of I allocated in machine memory for -storing information about the chunks in the cache. - -For a disk cache, the B file contains one -entry for each BI 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 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 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 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 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 -program starts the following daemons. (On most system types, these -daemons appear as nameless entries in the output of the UNIX C -command.) - -=over - -=item * - -One I 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 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 daemon, which flushes the cache when free -space is required, by writing cached data and status information -to the File Server. - -=item * - -One I 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 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 daemon, which listens for -incoming RPCs. - -=item * - -On some system types, one I 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 daemons (sometimes called I 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 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 BI files to create in the cache -directory for a disk cache, overriding the default that is -calculated as described in the B section. Each BI -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 directory). -This value overrides the default of the B 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 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 file. If a value -other than the B 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: 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 process). - -=item B<-verbose> - -Generates a detailed trace of the C 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 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 BI 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: 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 directory from -which to fetch the B, B, and B -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. - -=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 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 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. - -=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 command to unmount the AFS root directory (by -convention, B). The machine must then be rebooted to reinitialize -the Cache Manager. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/afsmonitor.pod b/doc/man-pages/pod/afsmonitor.pod deleted file mode 100644 index 19f73cf6da..0000000000 --- a/doc/man-pages/pod/afsmonitor.pod +++ /dev/null @@ -1,432 +0,0 @@ -=head1 NAME - -afsmonitor - Monitors File Servers and Cache Managers - -=head1 SYNOPSIS - -afsmonitor [B] [B<-config> I] -[B<-frequency> I] -[B<-output> I] [B<-detailed>] -[B<-debug> I] -[B<-fshosts> I ...] -[B<-cmhosts> I ...] -[B<-buffers> I] [B<-help>] - -afsmonitor [B] [B<-co> I] -[B<-fr> I] -[B<-o> I] [B<-det>] -[B<-deb> I] -[B<-fs> I ...] -[B<-cm> I ...] -[B<-b> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 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 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 reference page - -=head1 OPTIONS - -=over 4 - -=item B - -Accommodates the command's use of the AFS command parser, and -is optional. - -=item B<-config> I - -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 section, and -the section on the C program in the IBM AFS -Administration Guide. - -=item B<-frequency> I - -Specifies in seconds how often the C 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 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 - -Names the file to which the C program writes all of -the statistics that it collects. By default, no output file is -created. See the section on the C 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 ... - -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 ... - -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 - -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 program displays its data on three screens: - -=over - -=item * - -C: This screen appears automatically when the -C program initializes. It summarizes separately for File -Servers and Cache Managers the number of machines being monitored -and how many of them have I (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: 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: 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 and C 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 field reports how many -times the program has probed File Servers (C), Cache Managers -(C), or both. The counts for File Servers and Cache Managers can -differ. The C 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 - -Switches to the C screen. Available only on the -C and C screens. - -=item B - -Switches to the C screen. Available only on the -C and the C screens. - -=item B - -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 -to scroll horizontally all the way to the left (to display the -first set of data columns). - -=item B - -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 to -scroll to the final page. - -=item B - -Switches to the C screen. Available only on the -C and C screens. - -=item B - -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

to -scroll to the first page. - -=item B - -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 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 screen appears automatically as the C -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 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 (probe failure) appear in square brackets to the -left of the hostname. - -=head1 The File Servers Screen - -The C 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 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 program gathered the indicated statistic from the Cache -Manager (C) or File Server (C) running on the machine called -I. If a probe failed, the error code B<-1> appears in the -I field. - -I

/I [I:I]. The month (I), day -(I
), and year (I) are required. The hour and minutes -(I:I) 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 - -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 ... - -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 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) 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:I) is omitted, it defaults to 59 -seconds after midnight (00:00:59 hours). Similarly, the C -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 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: Specifying the value B 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 command). - -=over - -=item B - -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 file. The C 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 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 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_delhost.pod b/doc/man-pages/pod/backup_delhost.pod deleted file mode 100644 index f842843e64..0000000000 --- a/doc/man-pages/pod/backup_delhost.pod +++ /dev/null @@ -1,93 +0,0 @@ -=head1 NAME - -backup delhost - Deletes a Tape Coordinator entry from the Backup Database - -=head1 SYNOPSIS - -backup delhost B<-tapehost> I [B<-portoffset> I] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup delh B<-t> I [B<-p> I] -[B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 file on the -Tape Coordinator machine. - -To list the Tape Coordinator machines and port offsets defined in the -Backup Database, issue the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-tapehost> I - -Specifies the hostname of the machine housing the Tape -Coordinator to delete. - -=item B<-portoffset> I - -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 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 file. The C 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 reference page. - -=item B<-cell> I - -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 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: - - backup delhost -tapehost backup3.abc.com -portoffset 2 - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_delvolentry.pod b/doc/man-pages/pod/backup_delvolentry.pod deleted file mode 100644 index f1f3826730..0000000000 --- a/doc/man-pages/pod/backup_delvolentry.pod +++ /dev/null @@ -1,93 +0,0 @@ -=head1 NAME - -backup delvolentry - Deletes a volume entry from a volume set - -=head1 SYNOPSIS - -backup delvolentry B<-name> I B<-entry> I -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup delvole B<-n> I B<-e> I -[B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 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 - -Names the volume set from which to delete a volume entry. - -=item B<-entry> I - -Specifies the index number of the volume entry to delete. Use -the C 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 file. The C 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 reference page. - -=item B<-cell> I - -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 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: - - backup delvolentry -name sys -entry 4 - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_delvolset.pod b/doc/man-pages/pod/backup_delvolset.pod deleted file mode 100644 index 025e3ab38f..0000000000 --- a/doc/man-pages/pod/backup_delvolset.pod +++ /dev/null @@ -1,83 +0,0 @@ -=head1 NAME - -backup delvolset - Deletes one or more volume sets from the Backup Database - -=head1 SYNOPSIS - -backup delvolset B<-name> I [I ...] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup delvols B<-n> I [I ...] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C command deletes each volume set named by the -B<-name> argument, and the volume entries each contains, from the Backup -Database. The C command lists the volume sets (and -their volume entries) currently defined in the Backup Database. - -=head1 OPTIONS - -=over 4 - -=item B<-name> I [I ...] - -Names each volume set to delete. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 reference page. - -=item B<-cell> I - -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 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_diskrestore.pod b/doc/man-pages/pod/backup_diskrestore.pod deleted file mode 100644 index 31bbdef993..0000000000 --- a/doc/man-pages/pod/backup_diskrestore.pod +++ /dev/null @@ -1,280 +0,0 @@ -=head1 NAME - -backup diskrestore - Restores the entire contents of a partition - -=head1 SYNOPSIS - -backup diskrestore B<-server> I -B<-partition> I -[B<-portoffset> I [I ...]] -[B<-newserver> I] -[B<-newpartition> I] -[B<-extension> I] -[B<-n>] [B<-localauth>] [B<-cell> I] [B<-help>] - -backup di B<-s> I B<-pa> I -[B<-po> I [I ...]] [B<-news> I] -[B<-newp> I] [B<-e> I] -[B<-n>] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 and C 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 command. To restore -multiple volumes to many different sites, use the C command. - -(If the B instruction appears in the -BI<_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 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 and C 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 command to restore individual volumes, or the -C 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 instruction in the local -BI<_device_name> file, or by prompting the backup operator to insert -the tape if there is no B instruction. However, if the B instruction appears in the BI<_device_name> file, or if the issuer -of the C 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 instruction or prompts the operator. It also invokes the B -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 - -Names the file server machine that the VLDB lists as the site -of the volumes that need to be restored. - -=item B<-partition> I - -Names the partition that the VLDB lists as the site of the -volumes that need to be restored. - -=item B<-portoffset> I [I ...] - -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 - -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 - -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 - -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 file. The C 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 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 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 is the name of the volume that was being restored when the -tape error occurred. Enter the value B to continue the operation -without restoring the indicated volume or the value B 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 partition of the machine B. -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 partition of the machine B to -a new site: the B partition on the machine B. 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 partition of -the machine B: - - 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 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. - -=head1 CAVEATS - -If issuing this command to recover data after a disk crash or other -damage, be sure not to issue the C command first. Doing so -destroys the VLDB record of the volumes that resided on the partition. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_dump.pod b/doc/man-pages/pod/backup_dump.pod deleted file mode 100644 index 3abed19c21..0000000000 --- a/doc/man-pages/pod/backup_dump.pod +++ /dev/null @@ -1,547 +0,0 @@ -=head1 NAME - -backup dump - Creates a dump (dumps a volume set at a particular dump level) - -=head1 SYNOPSIS - -backup dump [B<-volumeset> I] [B<-dump> I] -[B<-portoffset> I] [B<-at> I ...] -[B<-append>] [B<-n>] [B<-file> I] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup dump [B<-v> I] [B<-d> I] -[B<-p> I] [B<-at> I ...] -[B<-ap>] [B<-n>] [B<-f> I] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 instruction appears in the -BI<_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 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 refers to copying a collection of data to tape or a -backup data file, and the resulting collection is termed a I. The -set of tapes that contain one or more dumps is called a I. The -first dump in a dump set is its I, and any dumps -subsequently added to the dump set (by use of the B<-append> argument) -are I. 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, 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, created at -an incremental dump level, contains only data that has changed since -the volume set was dumped at the incremental level's I -(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 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 field of the output from the C -command. As an example, an incremental dump at the -B level includes only files and directories that -have changed since the volume set was dumped at the B 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 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 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 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 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 instruction does not appear -in the BI<_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 instruction appears -in the BI<_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 instruction in the -BI<_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 instruction in the -BI<_device_name> file or prompting the operator. - -=over - -=item 1. - -A name of the form I.I.I, -where I matches the value of the B<-volumeset> -argument, I matches the last element in the pathname -value of the B<-dump> argument, and I 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 has AFS tape name B. 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 CNULLE>, which usually indicates that a backup operator -has used the C 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 CNULLE> 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 CNULLE>, 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 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 file. If the capacity field in the B 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 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 instruction in the -BI<_device_name> file, or by prompting the backup operator to insert -the tape if there is no B instruction. However, if the B instruction appears in the BI<_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 instruction or -prompts the operator. It also invokes the B 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 - -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 -command must be issued within the interactive session in which -the C command was issued with the B<-temporary> -flag. - -=item B<-dump> I - -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 - -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 ... - -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/I
/I [I:I], where the -month (I), day (I
), and year (I) 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:I) 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 - -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 - -Specifies the local disk or AFS pathname of a file containing -C 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 command on its own line in the indicated -file, using the same syntax as for the command line, but -without the word B 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 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 file. The C 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 reference page. - -=item B<-cell> I - -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 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. 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 volume set at the B 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 at the dump level B 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 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. - -=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 and C 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 command must be used to restore one volume at a -time. - -Valid (unexpired) administrative tokens must be available to the -C 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 and C 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_dumpinfo.pod b/doc/man-pages/pod/backup_dumpinfo.pod deleted file mode 100644 index 53420d1ace..0000000000 --- a/doc/man-pages/pod/backup_dumpinfo.pod +++ /dev/null @@ -1,427 +0,0 @@ -=head1 NAME - -backup dumpinfo - Displays a dump record from the Backup Database - -=head1 SYNOPSIS - -backup dumpinfo [B<-ndumps> I] [B<-id> I] -[B<-verbose>] [B<-localauth>] [B<-cell> I] [B<-help> ] - -backup dumpi [B<-n> I] [B<-i> I] -[B<-v>] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 - -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 - -Specifies the dump ID number of a single dump for which to -display the Backup Database record. Precede the I 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 file. The C 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 reference page. - -=item B<-cell> I - -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 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 - -The dump ID number. - -=item B - -The dump ID number of the dump's parent dump. A value of 0 -(zero) identifies a full dump. - -=item B - -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 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 - -The date and time at which the Backup System started the dump -operation that created the dump. - -=item B - -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 command to remove such -entries. - -=item B - -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 - -The dump name in the form - -I.I (I) - -where I is the name of the volume set, and -I is the last element in the dump level pathname -at which the volume set was dumped. - -The I, 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 and reports information for the entire dump in -the following fields: - -=over - -=item B - -The dump ID number. - -=item B - -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 - -The number of volumes for which the dump includes data. - -=item B - -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: Server: I - -where I is the name of the XBSA-compliant program and -I 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, the first two lines of -each entry report information about that tape in the following fields: - -=over - -=item B - -The tape's permanent name if it has one, or its AFS tape name -otherwise, and its tape ID number in parentheses. - -=item B - -The number of volumes for which this tape includes dump data. - -=item B - -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 - -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 - -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 - -The number of bytes of data in the dump of the volume. - -=item B - -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, includes -information about the entire dump. The fields labeled C, C, -C, and C 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 - -The dump's I, which is recorded in the -dump's Backup Database record if the B instruction -appears in the Tape Coordinator's -BI file when the dump is created. - -=item B - -The number of tapes that contain the dump set to which -this dump belongs. - -=item B - -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. The fields labeled -C, C, and C 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 - -The date and time when this tape can be recycled, because -all dumps it contains have expired. - -=item B - -Summed together, these fields represent the total amount -of dumped data actually from volumes (as opposed to -labels, filemarks, and other markers). - -=item B - -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 Data and C 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. The fields labeled C, C, -C, and C 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 - -The volume ID. - -=item B - -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, -C, and C): - - 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_help.pod b/doc/man-pages/pod/backup_help.pod deleted file mode 100644 index 72858bbed2..0000000000 --- a/doc/man-pages/pod/backup_help.pod +++ /dev/null @@ -1,95 +0,0 @@ -=head1 NAME - -backup help - Displays the syntax of specified C commands or lists functional -descriptions of all C commands - -=head1 SYNOPSIS - -backup help [B<-topic> I [I ...]] [B<-help>] - -backup h [B<-t> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. - -To list every C command whose name or short description includes -a specified keyword, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I [I ...] - -Indicates each command for which to display the complete online -help entry. Omit the C part of the command name, providing -only the operation code (for example, specify C, not C). If this argument is omitted, the output briefly -describes every C 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 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, 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 command: - - backup help dump - backup dump: start dump - Usage: backup dump -volumeset -dump - [-portoffset ] [-at +] - [-append] [-n] [-file ] [-help] - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_interactive.pod b/doc/man-pages/pod/backup_interactive.pod deleted file mode 100644 index e6e5b48ee5..0000000000 --- a/doc/man-pages/pod/backup_interactive.pod +++ /dev/null @@ -1,121 +0,0 @@ -=head1 NAME - -backup interactive - Enters interactive mode - -=head1 SYNOPSIS - -backup [interactive] [B<-localauth>] [B<-cell> I] [B<-help>] - -backup [i] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C initiates an interactive session for issuing -C commands. As indicated in the syntax statement, the operation -code (C) is optional. - -Several features of interactive mode distinguish it from regular mode: - -=over - -=item * - -In interactive mode, the C> prompt replaces the system -(shell) prompt. The operator enters only a command's operation -code (omitting the command suite name, C). - -=item * - -If the B<-localauth> flag or the B<-cell> argument is included on the -C 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 subcommand or B<-help> flag on an individual command -issued at the C> 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 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 file. The C 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 reference page. - -=item B<-cell> I - -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 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 subcommand is issued in interactive -mode. - - backup - backup> help dump - dump: start dump - Usage: dump [-volumeset ] [-dump ] - [-portoffset ] [-at +] - [-append ] [-n ] [-file ] [-help ] - -=head1 PRIVILEGE REQUIRED - -None. However, C commands that require privilege in regular mode -still require it in interactive mode. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_jobs.pod b/doc/man-pages/pod/backup_jobs.pod deleted file mode 100644 index 4068393f62..0000000000 --- a/doc/man-pages/pod/backup_jobs.pod +++ /dev/null @@ -1,229 +0,0 @@ -=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 operation running or pending in the current interactive -session. - -This command can be issued in interactive mode only. If the issuer of -the C 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 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 command interpreter is using during the current -interactive session, in the following format: - -I I
/I [I:I]. The month -(I), day (I
), and year (I) 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:I) 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 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 -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 - -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 file. The C 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 -reference page. - -=item B<-cell> I - -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 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_scantape.pod b/doc/man-pages/pod/backup_scantape.pod deleted file mode 100644 index 7d42072ae6..0000000000 --- a/doc/man-pages/pod/backup_scantape.pod +++ /dev/null @@ -1,359 +0,0 @@ -=head1 NAME - -backup scantape - Extracts dump information from a tape - -=head1 SYNOPSIS - -backup scantape [B<-dbadd>] [B<-portoffset> I] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup sc [B<-d>] [B<-p> I] [B<-l>] [B<-c> I] [B<-help>] - -=head1 DESCRIPTION - -The C 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 instruction appears in the -BI file associated with the specified -port offset, then the C command extracts dump -information from the backup data file named in that port offset's -entry in the B 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 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 command, or has -the AFS tape name B). - -The Tape Coordinator's default response to this command is to access -the tape by invoking the B instruction in the BI -file, or by prompting the backup operator to insert the tape if there -is no B instruction. However, if the B instruction -appears in the BI file, or if the issuer of the B -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 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 > 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 - -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 file. The C 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 -reference page. - -=item B<-cell> I - -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 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 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 command: - -=over - -=item B - -The permanent name assigned by using the B<-pname> argument of the -C 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 CNULLE> appears in this field. - -=item B - -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 operation, or the -operator can assign it with the B<-name> argument to the C command. - -=over - -=item * - -I.I.I, if the tape -contains volume data. The I 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 is the -last pathname element of the dump level at which the initial -dump was backed up; and I is the numerical position -of the tape in the dump set. - -=item * - -CNULLE> 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 command was used on this tape, and no data -has been written to it since. - -=back - -=item B - -The date and time at which the Backup System started performing -the dump operation that created the initial dump. - -=item B - -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 - -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 command -or derived from the B file on the Tape -Coordinator machine, not from a measurement of the tape. - -=item B - -The dump level of the initial dump in the dump set. - -=item B - -The dump ID number of the initial dump in the dump set, as -recorded in the Backup Database. - -=item B - -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 - -The volume name, complete with a C<.backup> or C<.readonly> -extension, if appropriate. - -=item B - -The volume's volume ID. - -=item B - -The dump to which the volume belongs. The dump name is of the -form I.I and matches the name -displayed in the dump label. - -=item B - -The dump ID of the dump named in the C field. - -=item B - -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 - -The dump ID number of C's parent dump. It is 0 if the -value in the C field is 0. - -=item B - -Is always 0; it is reserved for internal use. - -=item B - -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 field. - -=back - -The message C 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 > 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 - 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B 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 -instruction in the local BI file, or by -prompting the operator if there is no B 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_setexp.pod b/doc/man-pages/pod/backup_setexp.pod deleted file mode 100644 index 4070345f95..0000000000 --- a/doc/man-pages/pod/backup_setexp.pod +++ /dev/null @@ -1,175 +0,0 @@ -=head1 NAME - -backup setexp - Sets the expiration date for existing dump levels. - -=head1 SYNOPSIS - -backup setexp B<-dump> I [I ...] [B<-expires> I ...] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup se B<-d> I [I ...] [B<-e> I ...] -[B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 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 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 [I ...] - -Specifies the full pathname of each dump level to assign the -expiration date specified by the B<-expires> argument. - -=item B<-expires> I ... - -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] {B | I/I
/I [I:I] } - -where the optional word C is followed either by the string -C, which indicates that dumps created at the dump level -never expire, or by a date value with a required portion (I -for month, I
for day, and I for year) and an optional -portion (I for hours and I for minutes). - -Omit the I:I 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] [IB] [IB] [IB] - -where the optional word C is followed by at least one of a -number of years (maximum B<9999>) followed by the letter C, a -number of months (maximum B<12>) followed by the letter C, or a -number of days (maximum B<31>) followed by the letter C. 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 - -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 file. The C 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 -reference page. - -=item B<-cell> I - -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 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: - - backup setexp -dump B -expires at 12/31/1999 22:00 - -The following example associates a relative expiration date of 7 days -with the two dump levels B and B: - - backup setexp -dump B B -expires 7d - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_status.pod b/doc/man-pages/pod/backup_status.pod deleted file mode 100644 index 3ce84182bc..0000000000 --- a/doc/man-pages/pod/backup_status.pod +++ /dev/null @@ -1,198 +0,0 @@ -=head1 NAME - -backup status - Reports a Tape Coordinator's status - -=head1 SYNOPSIS - -backup status [B<-portoffset> I] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup st [B<-p> I] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C command displays which operation, if any, the -indicated Tape Coordinator is currently executing. - -=head1 OPTIONS - -=over 4 - -=item B<-portoffset> I - -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 file. The C 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 -reference page. - -=item B<-cell> I - -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 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: I: I - -where - -=over - -=item B> - -Is a task identification number assigned by the Tape -Coordinator. It begins with the Tape Coordinator's port offset -number. - -=item B> - -Identifies the operation the Tape Coordinator is performing, -which is initiated by the indicated command: - -=over - -=item * - -Dump (the C command) - -=item * - -Restore (the backup diskrestore, backup volrestore, or C commands) - -=item * - -Labeltape (the C command) - -=item * - -Scantape (the C command) - -=item * - -SaveDb (the C command) - -=item * - -RestoreDb (the C command) - -=back - -=item B> - -Indicates the job's current status in one of the following -messages. - -=over - -=item B Kbytes transferred, volume I> - -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 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 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 Tape coordinator - -where I 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: - - 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_volinfo.pod b/doc/man-pages/pod/backup_volinfo.pod deleted file mode 100644 index 21b0c2ef61..0000000000 --- a/doc/man-pages/pod/backup_volinfo.pod +++ /dev/null @@ -1,134 +0,0 @@ -=head1 NAME - -backup volinfo - Displays a volume's dump history from the Backup Database - -=head1 SYNOPSIS - -backup volinfo B<-volume> I -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup voli B<-v> I [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 - -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 file. The C 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 -reference page. - -=item B<-cell> I - -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 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 - -The dump ID of the dump that includes the volume. - -=item B - -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 - -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 column is also 0. - -=item B - -The date and time at which the Backup System started the dump -operation that created the dump. - -=item B - -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 - -The name of the tape containing the dump: either the permanent -tape name, or an AFS tape name in the format -I.I.I where -I is the name of the volume set associated with -the initial dump in the dump set of which this tape is a part; -I is the name of the dump level at which the -initial dump was backed up; I 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_volrestore.pod b/doc/man-pages/pod/backup_volrestore.pod deleted file mode 100644 index 6c2aa84bae..0000000000 --- a/doc/man-pages/pod/backup_volrestore.pod +++ /dev/null @@ -1,336 +0,0 @@ -=head1 NAME - -backup volrestore - Restores one or more volumes - -=head1 SYNOPSIS - -backup volrestore B<-server> I -B<-partition> I -B<-volume> I [I ...] -[B<-extension> I] -[B<-date> I ...] -[B<-portoffset> I [I ...]] [B<-n>] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup volr B<-s> I B<-pa> I -B<-v> I [I ...] [B<-e> I] -[B<-d> I ...] [B<-po> I [I ...]] -[B<-n>] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 instruction appears in the -BI file associated with the specified -port offset, then the C command restores data from the -backup data file listed for that port offset in the Tape Coordinator's -B 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 command to remove it -and the C 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 and C -commands. - -If restoring all of the volumes that resided on a single partition, it -is usually more efficient to use the C command. If -restoring multiple volumes to many different sites, it can be more -efficient to use the C command. - -By default, the C 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 of the -volume included in the dump is before the indicated date and time (the -clone date timestamp appears in the C field of the output -from the C 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 -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 instruction in the local -BI file, or by prompting the backup -operator to insert the tape if there is no B instruction. However, -if the B instruction appears in the BI file, -or if the issuer of the B 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 instruction or prompts the operator. It also invokes -the B 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 - -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 - -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 [I ...] - -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 - -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 ... - -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/I
/I [I:I], where the -required I/I
/I portion indicates the month (I), day (I
), -and year (I), and the optional I:I 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 - -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 [I ...] - -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 file. The C 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 -reference page. - -=item B<-cell> I - -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 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 to partition -B on machine B: - - backup volrestore -server fs5.abc.com -partition a -volume user.pat - -The following command restores the volumes B and B -to partition B on machine B, adding a B<.rst> extension -to each volume name and preserving the existing B and -B 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 to partition -B on machine B. 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 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. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_volsetrestore.pod b/doc/man-pages/pod/backup_volsetrestore.pod deleted file mode 100644 index 1cdb9bb8f6..0000000000 --- a/doc/man-pages/pod/backup_volsetrestore.pod +++ /dev/null @@ -1,424 +0,0 @@ -=head1 NAME - -backup volsetrestore - Restores all volumes in a volume set - -=head1 SYNOPSIS - -backup volsetrestore [B<-name> I] [B<-file> I] -[B<-portoffset> I [I ...]] -[B<-extension> I] -[B<-n>] [B<-localauth>] [B<-cell> I] [B<-help>] - -backup vols [B<-na> I] [B<-f> I] -[B<-p> I [I ...]] [B<-e> I] -[B<-n>] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 instruction appears in the -BI file associated with the specified -port offset, then the C command restores data from -the backup data file listed for that port offset in the Tape -Coordinator's B 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 command. If restoring all -volumes that resided on a single partition, it is usually more -efficient to use the C 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 -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 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 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 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 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 instruction in the local -BI file, or by prompting the backup -operator to insert the tape if there is no B instruction. However, -if the B instruction appears in the BI file, -or if the issuer of the B 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 instruction or prompts the operator. It also invokes -the B 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 - -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 - -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 - -Names the file server machine to which to restore the -volume. - -=item B - -Names the partition to which to restore the volume. - -=item B - -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 - -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, -I, or I 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 - -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 [I ...] - -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 -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 command. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 -reference page. - -=item B<-cell> I - -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 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 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 - -Names the file server machine that currently houses the volume, -as listed in the VLDB. - -=item B - -Names the partition that currently houses the volume, as listed -in the VLDB. - -=item B - -Specifies the version (read/write or backup) of the volume that -was dumped, as listed in the Backup Database. - -=item B - -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). - -=item B - -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 - -The tape ID of the tape containing the dump of the volume, from -the Backup Database. - -=item B - -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 - -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, 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: - - backup volsetrestore -file B - Starting restore - backup: task ID of restore operation: 113 - backup: Finished doing restore - -The B 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 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. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos.pod b/doc/man-pages/pod/bos.pod deleted file mode 100644 index c34c8a3fe6..0000000000 --- a/doc/man-pages/pod/bos.pod +++ /dev/null @@ -1,299 +0,0 @@ -=head1 NAME - -bos - Introduction to the C command suite - -=head1 DESCRIPTION - -The commands in the C 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 command suite: - -=over - -=item * - -Commands to administer server process binary files: C, -C, C, and C - -=item * - -Commands to maintain system configuration files: C, C, C, C, C, C, -C, C, C, and C - -=item * - -Commands to start and stop processes: C, C, C, C, C, C, and C - -=item * - -Commands to set and verify server process and server machine -status: C, C, C, C, -and C - -=item * - -A command to restore file system consistency: C - -=item * - -Commands to obtain help: C and C - -=back - -The BOS Server and the C commands use and maintain the following -configuration and log files: - -=over - -=item * - -The B 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 file, use the following commands: C, C, C, and C. - -=item * - -The B 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, C, and C. - -=item * - -The B file defines the cell to which the -server machine belongs for the purposes of server-to-server -communication. Administer it with the C command. -There is also a B 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 file lists the user name of each -administrator authorized to issue privileged C and C commands. -To administer the UserList file, use the following commands: C, C, and C. - -=item * - -The B 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, C, C, -C, C, and C. - -=item * - -The B 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 suite. The reference page for each command also lists them, -but they are described here in greater detail. - -=over 4 - -=item B<-cell> I - -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 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 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 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 file. The C 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 -file. The issuer of a command that includes this flag must be -logged on to the server machine as the local superuser B. -The flag is useful for commands invoked by an unattended -application program, such as a process controlled by the UNIX -B utility or by a cron entry in the machine's -B file. It is also useful if an -administrator is unable to authenticate to AFS but is logged in -as the local superuser B. - -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 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. 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 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 - -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), 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, C, -C, C, C, and C -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 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 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 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 command that changes a configuration file or alters -process status, the issuer must be listed in the B -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. - -To issue a C command that only displays information (other than the -C command), no privilege is required. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_addhost.pod b/doc/man-pages/pod/bos_addhost.pod deleted file mode 100644 index 01188738e4..0000000000 --- a/doc/man-pages/pod/bos_addhost.pod +++ /dev/null @@ -1,124 +0,0 @@ -=head1 NAME - -bos addhost - Adds a database server machine to the B file - -=head1 SYNOPSIS - -bos addhost B<-server> I B<-host> I [I ...] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos addh B<-s> I B<-ho> I [I ...] -[B<-c> I] [B<-n>] [B<-l>] [B<-he>] - -=head1 DESCRIPTION - -The C command adds an entry for each database server machine -specified with the B<-host> argument to the B file -on the machine named by the B<-server> argument. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Identifies the server machine on which to change the -B 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 command suite. - -In cells that run the United States edition of AFS and use the -Update Server to distribute the contents of the B -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 command suite. - -=item B<-host> I [I ...] - -Specifies the fully-qualified host name (such as B) -of each database server machine to register in the B -file. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 -and B to the B file on the machine -B (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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -IBM AFS Quick Beginnings - -=cut diff --git a/doc/man-pages/pod/bos_addkey.pod b/doc/man-pages/pod/bos_addkey.pod deleted file mode 100644 index 2787f0962d..0000000000 --- a/doc/man-pages/pod/bos_addkey.pod +++ /dev/null @@ -1,141 +0,0 @@ -=head1 NAME - -bos addkey - Adds a new server encryption key to the B file - -=head1 SYNOPSIS - -bos addkey B<-server> I [B<-key> I] -B<-kvno> I [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos addk B<-s> I [B<-ke> I] B<-kv> I -[B<-ce> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 file on -the machine specified with the B<-server> argument. Be sure to use the -C or C command to add the same key to the B -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 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 command to display -the key version numbers in the B file. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine on which to change the -B 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 command suite. - -In cells that run the United States edition of AFS and use the -Update Server to distribute the contents of the B -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 command suite. - -=item B<-key> I - -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 - -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 command to display key -version numbers. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 and C 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 file kept on the machine B -(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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_adduser.pod b/doc/man-pages/pod/bos_adduser.pod deleted file mode 100644 index 69acd1ea75..0000000000 --- a/doc/man-pages/pod/bos_adduser.pod +++ /dev/null @@ -1,104 +0,0 @@ -=head1 NAME - -bos adduser - Adds a privileged user to the B file - -=head1 SYNOPSIS - -bos adduser B<-server> I B<-user> I [I ...] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos addu B<-s> I B<-u> I [I ...] -[B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command adds each user name specified with the B<-user> -argument to the B 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 - -Indicates the server machine on which to change the -B 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 command suite. - -In cells that run the United States edition of AFS and use the -Update Server to distribute the contents of the B -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 command suite. - -=item B<-user> I [I ...] - -Specifies each user name to insert into the -B file. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 file on the machine B (the system -control machine). - - bos adduser -server fs1.abc.com -user pat smith - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_apropos.pod b/doc/man-pages/pod/bos_apropos.pod deleted file mode 100644 index df4f3c2711..0000000000 --- a/doc/man-pages/pod/bos_apropos.pod +++ /dev/null @@ -1,70 +0,0 @@ -=head1 NAME - -bos apropos - Displays each help entry containing a keyword string - -=head1 SYNOPSIS - -bos apropos B<-topic> I [B<-help>] - -bos ap B<-t> I [B<-h>] - -=head1 DESCRIPTION - -The C command displays the first line of the online help -entry for any C 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 command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I - -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 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 commands that include the word -B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_create.pod b/doc/man-pages/pod/bos_create.pod deleted file mode 100644 index 3107fea3d5..0000000000 --- a/doc/man-pages/pod/bos_create.pod +++ /dev/null @@ -1,410 +0,0 @@ -=head1 NAME - -bos create - Defines a new process in the B file and starts -it running - -=head1 SYNOPSIS - -bos create B<-server> I B<-instance> I -B<-type> I B<-cmd> I [I ...] -[B<-notifier> I] [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos c B<-s> I B<-i> I B<-t> I -B<-cm> I [I ...] [B<-not> I] [B<-ce> I] -[B<-noa>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command creates a server process entry in the -B file on the server machine named by the -B<-server> argument, sets the process's status to B in the B -file and in memory, and starts the process. - -A server process's entry in the B 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 - -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 -command suite. - -=item B<-instance> I - -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 - -The Backup Server process - -=item B - -The process that combines the File Server, Volume Server, -and Salvager processes (B, B, and -B) - -=item B - -The Authentication Server process - -=item B - -The Protection Server process - -=item B - -The controller process for the Network Time Protocol -Daemon - -=item B - -The client portion of the Update Server process that -retrieves binary files from the B directory of -the binary distribution machine for this machine's -CPU/operating system type. (The name of the binary is -B, but the B suffix distinguishes this process -from B.) - -=item B - -The client portion of the Update Server process that -retrieves configuration files from the B -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, but the B -suffix distinguishes this process from B.) - -=item B - -The server portion of the Update Server process - -=item B - -The Volume Location (VL) Server process - -=back - -=item B<-type> I - -Specifies the process's type. The acceptable values are: - -=over - -=item B - -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 command. - -=item B - -Use this value only for the B 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 - -Use this value for all processes listed as acceptable -values to the B<-instance> argument, except for the B -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 [I ...] - -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 for the Protection Server). If including -any of the initialization command's options, surround the -entire command in double quotes (" "). The B process has -a required argument, and the commands for all other processes -take optional arguments. - -For the B process, provide the complete pathname of the local -disk binary file for each of the component processes: -B, B, and B, in that order. The -standard binary directory is B. If including any of -an initialization command's options, surround the entire -command in double quotes (B<" ">). - -For a B 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, 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 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:I), 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 or B. 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 or B, B or B, and so on). For the -time, use the same format as when specifying the time -alone. - -=back - -=back - -=item B<-notifier> I - -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 section. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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: - - 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 on the machine B. It references B as -the source for updates to binary files, checking for changes to the -B 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 on the machine -B. 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 process called B on the -machine B, so that the BOS Server issues the indicated C 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). Note that the issuer provides the complete pathname to the C -command, includes the B<-localauth> flag on it, and types the entire C 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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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 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 and B 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 and one B structure for each exiting process associated -with the notifier program. It brackets each structure with appropriate -C and C statements (C and C, C -and C), 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 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 and B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_delete.pod b/doc/man-pages/pod/bos_delete.pod deleted file mode 100644 index 684287e800..0000000000 --- a/doc/man-pages/pod/bos_delete.pod +++ /dev/null @@ -1,101 +0,0 @@ -=head1 NAME - -bos delete - Deletes a server process from the B file - -=head1 SYNOPSIS - -bos delete B<-server> I B<-instance> I [I ...] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos d B<-s> I B<-i> I [I ...] [B<-c> I] -[B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command removes the B 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 command to stop the -process and set its status flag in the B file to C. The -C command fails with an error message if a process's status -flag is C. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine on which to delete the server -process entry from the B 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 command suite. - -=item B<-instance> I [I ...] - -Names each process to delete. Use the name assigned with the -B<-instance> argument to the C command; process names -appear in the output of the C command. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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, B, B, and -B entries from the B file on B, 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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_exec.pod b/doc/man-pages/pod/bos_exec.pod deleted file mode 100644 index 1f1210d5f2..0000000000 --- a/doc/man-pages/pod/bos_exec.pod +++ /dev/null @@ -1,90 +0,0 @@ -=head1 NAME - -bos exec - Executes a command on a remote server machine - -=head1 SYNOPSIS - -bos exec B<-server> I B<-cmd> I -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos e B<-s> I B<-cm> I [B<-ce> I] -[B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command or equivalent. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -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 command suite. - -=item B<-cmd> I - -Specifies the complete local disk pathname of the command to -execute (for example, B). Surround this argument with -double quotes ("") if the command contains one or more spaces. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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. The issuer has -previously issued the C 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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/bos_getdate.pod b/doc/man-pages/pod/bos_getdate.pod deleted file mode 100644 index ed67b62e28..0000000000 --- a/doc/man-pages/pod/bos_getdate.pod +++ /dev/null @@ -1,119 +0,0 @@ -=head1 NAME - -bos getdate - Displays the time stamps on an AFS binary file - -=head1 SYNOPSIS - -bos getdate B<-server> I B<-file> I [I ...] -[B<-dir> I] [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos getd B<-s> I B<-f> I [I ...] [B<-d> I] -[B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command.) The files must reside in the B -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 -command. To remove obsolete binary files from the B -directory, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -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 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 process. - -=item B<-file> I [I ...] - -Names each binary file to list. - -=item B<-dir> I - -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 -directory. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 on the machine B: - - 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_getlog.pod b/doc/man-pages/pod/bos_getlog.pod deleted file mode 100644 index 6d3a97b954..0000000000 --- a/doc/man-pages/pod/bos_getlog.pod +++ /dev/null @@ -1,154 +0,0 @@ -=head1 NAME - -bos getlog - Prints a server process's log file - -=head1 SYNOPSIS - -bos getlog B<-server> I B<-file> I -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos getl B<-s> I B<-f> I [B<-c> I] -[B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 directory -unless an alternate pathname is provided as part of the B<-file> -argument. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -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 -command suite. - -=item B<-file> I - -Names the log file to display. If a filename only is provided, -the BOS Server fetches the log file from the B -directory; the standard values are: - -=over - -=item B - -The Authentication Server (B) log file - -=item B - -The Backup Server (B) log file - -=item B - -The BOS Server (B) log file - -=item B - -The File Server (B) log file - -=item B - -The Salvager (B) log file - -=item B - -The Volume Location (VL) Server (B) log file - -=item B - -The Volume Server (B) 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 directory. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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'... - -The remainder of the output depends on the particular log file. - -=head1 EXAMPLES - -The following example displays the B file from the machine -B: - - 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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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 command to truncate each log file, or use the C -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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/bos_getrestart.pod b/doc/man-pages/pod/bos_getrestart.pod deleted file mode 100644 index afb810ec55..0000000000 --- a/doc/man-pages/pod/bos_getrestart.pod +++ /dev/null @@ -1,151 +0,0 @@ -=head1 NAME - -bos getrestart - Displays the automatic restart times for server processes - -=head1 SYNOPSIS - -bos getrestart B<-server> I [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos getr B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command displays two restart times from the -B file on the server machine named by the -B<-server> argument: - -=over - -=item * - -The I at which the BOS Server process -automatically restarts itself and all processes marked with status -Run in the B 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 directory is later than the last restart time -for the process. The default is 5:00 a.m. Use the C -command to list a binary file's timestamp, and the B<-long> flag to -the C command to display a process's most recent restart -time. - -=back - -Use the C command to set the restart times. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -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 -command suite. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 restarts at I to the file -B on the machine B, which is the binary -distribution machine for server machines running AIX 4.2 in the -B cell. The current version of the B file is -moved to B. - - 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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_listhosts.pod b/doc/man-pages/pod/bos_listhosts.pod deleted file mode 100644 index 954c0cb2ad..0000000000 --- a/doc/man-pages/pod/bos_listhosts.pod +++ /dev/null @@ -1,111 +0,0 @@ -=head1 NAME - -bos listhosts - Displays the contents of the B file - -=head1 SYNOPSIS - -bos listhosts B<-server> I [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos listh B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -bos getcell B<-server> I [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos getc B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command formats and displays the list of a cell's -database server machines from the B file on the -server machine named by the B<-server> argument. - -To alter the list of machines, use the C and C -commands. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine from which to display the -B 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 command suite. - -For consistent performance in the cell, the output must be the -same on every server machine. The L reference page -explains how to keep the machines synchronized. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 command. - -=head1 EXAMPLES - -The following command displays the database server machines listed in -the B file on the machine B. - - 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_listkeys.pod b/doc/man-pages/pod/bos_listkeys.pod deleted file mode 100644 index f372b00eaf..0000000000 --- a/doc/man-pages/pod/bos_listkeys.pod +++ /dev/null @@ -1,142 +0,0 @@ -=head1 NAME - -bos listkeys - Displays the server encryption keys from the B file - -=head1 SYNOPSIS - -bos listkeys B<-server> I [B<-showkey>] [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos listk B<-se> I [B<-sh>] [B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command formats and displays the list of server -encryption keys from the B file on the server -machine named by the B<-server> argument. - -To edit the list of keys, use the C and C -commands. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine from which to display the B -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 -command suite. - -For consistent performance in the cell, the output must be the -same on every server machine. The L reference page -explains how to keep the machines synchronized. - -=item B<-showkey> - -Displays the octal digits that constitute each key. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 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 -indicates when a key was last added to the B file. The words C indicate the end of the output. - -For mutual authentication to work properly, the output from the -command B 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 file on the machine B. - - 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 file on -the machine B. - - 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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_listusers.pod b/doc/man-pages/pod/bos_listusers.pod deleted file mode 100644 index ca218541ba..0000000000 --- a/doc/man-pages/pod/bos_listusers.pod +++ /dev/null @@ -1,98 +0,0 @@ -=head1 NAME - -bos listusers - Lists the privileged users from the B file - -=head1 SYNOPSIS - -bos listusers B<-server> I [B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos listu B<-s> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command lists the user names from the -B file on the file server machine named by the -B<-server> argument. The users are authorized to issue privileged C and -C commands. - -To edit the list of users, use the C and C -commands. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine from which to display the B -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 -command suite. - -For consistent performance in the cell, the output must be the -same on every server machine. The L reference page -explains how to keep the machines synchronized. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 and C commands. - -=head1 EXAMPLES - -The following example lists the users from B file on the -machine B. - - bos listusers fs4.abc.com - SUsers are: pat smith jones terry - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_prune.pod b/doc/man-pages/pod/bos_prune.pod deleted file mode 100644 index 987db181a9..0000000000 --- a/doc/man-pages/pod/bos_prune.pod +++ /dev/null @@ -1,144 +0,0 @@ -=head1 NAME - -bos prune - Removes obsolete versions of files from the B and -B directories - -=head1 SYNOPSIS - -bos prune B<-server> I [B<-bak>] [B<-old>] [B<-core>] [B<-all>] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos p B<-s> I [B<-b>] [B<-o>] [B<-co>] [B<-a>] -[B<-ce> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 directory -that have a C<.BAK> extension. - -=item * - -The B<-old> flag removes all files from the B directory -that have a C<.OLD> extension. - -=item * - -The B<-core> flag removes all files from the B directory -that have a C 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 command. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -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 command suite. - -=item B<-bak> - -Removes all files from the B 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 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 directory that have a -C 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 - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 -directory on the machine B 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 -directory on the machine B that have a C<.BAK> or C<.OLD> -extension, and all files from the B directory that have a -C prefix. - - bos prune -server db2.abc.com -all - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_removehost.pod b/doc/man-pages/pod/bos_removehost.pod deleted file mode 100644 index 8bf34a2b3e..0000000000 --- a/doc/man-pages/pod/bos_removehost.pod +++ /dev/null @@ -1,115 +0,0 @@ -=head1 NAME - -bos removehost - Removes a database server machine from the B -file - -=head1 SYNOPSIS - -bos removehost B<-server> I B<-host> I [I ...] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos removeh B<-s> I B<-ho> I [I ...] [B<-c> I] -[B<-n>] [B<-l>] [B<-he>] - -=head1 DESCRIPTION - -The C command removes the entry for each database server -machine specified with the B<-host> argument from the -B file on the server machine named by the -B<-server> argument. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine on which to change the -B 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 command suite. - -In cells that run the United States edition of AFS and use the -Update Server to distribute the contents of the B -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 command suite. - -=item B<-host> I [I ...] - -Specifies the fully-qualified host name (such as B) -of each database server machine to remove from the B -file. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 from the B file on the system control machine -B. - - bos removehost -server fs1.abc.com -host db2.abc.com - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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 file. The IBM AFS Quick Beginnings explains in -more detail how to add and remove database server machines. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -IBM_AFS Quick_Beginnings - -=cut diff --git a/doc/man-pages/pod/bos_removekey.pod b/doc/man-pages/pod/bos_removekey.pod deleted file mode 100644 index 261c61e4b7..0000000000 --- a/doc/man-pages/pod/bos_removekey.pod +++ /dev/null @@ -1,109 +0,0 @@ -=head1 NAME - -bos removekey - Removes a server encryption key from the B file - -=head1 SYNOPSIS - -bos removekey B<-server> I B<-kvno> I [I ...] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos removek B<-s> I B<-k> I [I ...] -[B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command removes each specified encryption key from -the B 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 command to display the key -version numbers. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine on which to change the -B 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 command suite. - -In cells that run the United States edition of AFS and use the -Update Server to distribute the contents of the B -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 command suite. - -=item B<-kvno> I [I ...] - -Specifies the key version number of each key to remove. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 file on the system control machine B. - - bos removekey -server fs1.abc.com -kvno 5 6 - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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 and C commands. This ensures that no clients -still possess tickets encrypted with the obsolete key. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_removeuser.pod b/doc/man-pages/pod/bos_removeuser.pod deleted file mode 100644 index 5b846930e3..0000000000 --- a/doc/man-pages/pod/bos_removeuser.pod +++ /dev/null @@ -1,100 +0,0 @@ -=head1 NAME - -bos removeuser - Removes a privileged user from the B file - -=head1 SYNOPSIS - -bos removeuser B<-server> I B<-user> I [I ...] -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos removeu B<-s> I B<-u> I [I ...] [B<-c> I] -[B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C command removes each user name specified with the -B<-user> argument from the B file on the machine -named by the B<-server> argument. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -Indicates the server machine on which to change the -B 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 command suite. - -In cells that run the United States edition of AFS and use the -Update Server to distribute the contents of the B -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 command suite. - -=item B<-user> I [I ...] - -Specifies each user name to remove. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 and B from the -B file on the system control machine B. - - bos removeuser -server fs1.abc.com -user pat jones - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_restart.pod b/doc/man-pages/pod/bos_restart.pod deleted file mode 100644 index beb2848365..0000000000 --- a/doc/man-pages/pod/bos_restart.pod +++ /dev/null @@ -1,152 +0,0 @@ -=head1 NAME - -bos restart - Restarts a server process - -=head1 SYNOPSIS - -bos restart B<-server> I [B<-instance> I [I ...]] [B<-bosserver>] -[B<-all>] [B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos res B<-s> I [B<-i> I [I ...]] [B<-b>] [B<-a>] -[B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 file. Do not include B 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 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 file. - -=back - -This command does not change a process's status flag in the B -file. - -=head1 OPTIONS - -=over 4 - -=item B<-server> I - -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 command suite. - -=item B<-instance> I [I ...] - -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 command. -The output from the C 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 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 status flag in the B file. Provide -this flag or one of the B<-instance> or B<-bosserver> options, but do -not combine them. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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, including the BOS Server. - - bos restart -server fs3.abc.com -bosserver - -The following command stops and restarts all processes running on the -machine B, 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: - - bos restart -server db3.abc.com -instance ptserver vlserver - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_salvage.pod b/doc/man-pages/pod/bos_salvage.pod deleted file mode 100644 index 1e79497c6e..0000000000 --- a/doc/man-pages/pod/bos_salvage.pod +++ /dev/null @@ -1,354 +0,0 @@ -=head1 NAME - -bos salvage - Restores internal consistency to a file system or volume - -=head1 SYNOPSIS - -bos salvage B<-server> I [B<-partition> I] -[B<-volume> I] -[B<-file> I] [B<-all>] [B<-showlog>] -[B<-parallel> I<# of max parallel partition salvaging>] -[B<-tmpdir> I] -[B<-orphans> I] -[B<-cell> I] -[B<-noauth>] [B<-localauth>] [B<-help>] - -bos sa B<-se> I [B<-part> I] -[B<-v> I] -[B<-f> I] [B<-a>] [B<-sh>] -[B<-para> I<# of max parallel partition salvaging>] -[B<-t> I] -[B<-o> I] -[B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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. Issue the C or C -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 or C command. Then issue the C or C 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 or C command. Then create a new copy of -the volume with the C or C command. - -=back - -During the salvage of an entire machine or partition, the C -command reports the fs process's auxiliary status as C. - -The Salvager always writes a trace to the B -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 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 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 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 - -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 command suite. - -=item B<-partition> I - -Specifies a single partition on which to salvage all volumes. -Provide the complete partition name (for example B) or -one of the following abbreviated forms: - - /vicepa = vicepa = a = 0 - /vicepb = vicepb = b = 1 - -After B (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 - -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 - -Specifies the complete pathname of a file into which to write a -trace of the salvage operation, in addition to the -B 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 -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 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 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 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 - -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 - -Controls how the Salvager handles orphaned files and -directories. Choose one of the following three values: - -=over - -=item B - -Leaves the orphaned objects on the disk, but prints a -message to the B 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 - -Removes the orphaned objects, and prints a message to the -B file reporting how many orphans -were removed and the approximate number of kilobytes they -were consuming. - -=item B - -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 for files - -B<_ _ORPHANDIR_ _.>I for directories - -where I 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 -command issued against the volume's root directory. - -=back - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 partition of -the machine B: - - bos salvage -server db3.abc.com -partition /vicepd - -The following command salvages the volume with volume ID number -536870988 on partition B of the machine B: - - bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988 - -The following command salvages all volumes on the machine B. -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 file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -IBM AFS Administration Guide - -=cut diff --git a/doc/man-pages/pod/bos_setauth.pod b/doc/man-pages/pod/bos_setauth.pod deleted file mode 100644 index 81c442ff3a..0000000000 --- a/doc/man-pages/pod/bos_setauth.pod +++ /dev/null @@ -1,114 +0,0 @@ -=head1 NAME - -bos setauth - Sets authorization checking requirements for all server processes - -=head1 SYNOPSIS - -bos setauth B<-server> I -B<-authrequired> I -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos seta B<-s> I -B<-a> I -[B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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; 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 on its local disk. All AFS server processes -constantly monitor for the B 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 - -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 command suite. - -=item B<-authrequired> I - -Enables authorization checking if the value is C, or disables -it if the value is C. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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: - - bos setauth -server fs7.abc.com -authrequired off - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on the -machine named by the B<-server> argument, or must be logged onto a server -machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 CAVEATS - -Do not create the B file directly, except when directed by -instructions for dealing with emergencies (doing so requires being -logged in as the local superuser B). Use this command instead. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/bos_setcellname.pod b/doc/man-pages/pod/bos_setcellname.pod deleted file mode 100644 index bd988ae3a6..0000000000 --- a/doc/man-pages/pod/bos_setcellname.pod +++ /dev/null @@ -1,134 +0,0 @@ -=head1 NAME - -bos setcellname - Sets the cell's name in the B and -B files - -=head1 SYNOPSIS - -bos setcellname B<-server> I B<-name> I -[B<-cell> I] [B<-noauth>] [B<-localauth>] [B<-help>] - -bos setc B<-s> I B<-n> I [B<-c> I] [B<-n>] [B<-l>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 - -=item * - -B. 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 - -Indicates the server machine on which to set the cell name in -the B and B 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 command suite. - -=item B<-name> I - -Defines the cell name, using standard Internet domain name -format (the actual domain name is usually appropriate). -Examples are B for the ABC Corporation and B for -the State University. It must match the value of the B<-cell> -argument, if that is provided. - -=item B<-cell> I - -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 reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. Do -not combine this flag with the B<-localauth> flag. For more -details, see the introductory L reference page. - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 in the B -and B files on the machine B 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 file on the machine -named by the B<-server> argument, or must be logged in as the local -superuser B 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 and B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -IBM AFS Quick Beginnings, -IBM AFS Administration Guide - -=cut diff --git a/doc/man-pages/pod/bos_setrestart.pod b/doc/man-pages/pod/bos_setrestart.pod deleted file mode 100644 index 673433e7ae..0000000000 --- a/doc/man-pages/pod/bos_setrestart.pod +++ /dev/null @@ -1,190 +0,0 @@ -=head1 NAME - -bos setrestart - Sets the date and time at which the BOS Server restarts processes - -=head1 SYNOPSIS - -bos setrestart B<-server> I B<-time> I (for B) and press BReturnE> 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 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 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 file. -Create the Backup Database entry by using the C -command. - -=item * - -The optional BI 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 part of the name is -derived as described previously for the BI and -BI files. - -=back - -=head1 OPTIONS - -=over 4 - -=item B<-port> I - -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 -BI log file. - -=back - -=item B<-cell> I - -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 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 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. The C 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; client machines do not have B 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 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. In addition, the issuer must be able to read and write to the -log and configuration files in the local B directory. - -=head1 CAVEATS - -If the Tape Coordinator machine is an AIX machine, use the B -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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/dlog.pod b/doc/man-pages/pod/dlog.pod deleted file mode 100644 index c99d747db5..0000000000 --- a/doc/man-pages/pod/dlog.pod +++ /dev/null @@ -1,230 +0,0 @@ -=head1 NAME - -dlog - Authenticates to the DCE Security Service - -=head1 SYNOPSIS - -dlog [B<-principal> I] [B<-cell> I] -[B<-password> I] [B<-servers> I [I ...]] -[B<-lifetime> I] -[B<-setpag>] [B<-pipe>] [B<-help>] - -dlog [B<-pr> I] [B<-c> I] [B<-pw> I] -[B<-ser> I [I ...]] -[B<-l> I] [B<-set>] [B<-pi>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 -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 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 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, 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 command displays the ticket obtained by the C -command for the server principal B, 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 - -Specifies the DCE user name for which to obtain DCE -credentials. If this option is omitted, the C command -interpreter uses the name under which the issuer is logged into -the local file system. - -=item B<-cell> I - -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 file on the local client -machine. - -If the issuer does not provide the B<-cell> argument, the C -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 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 - -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 ... - -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 command interpreter randomly selects a -machine from the list of DFS Fileset Location (FL) Servers in -the B 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 - -Requests a ticket lifetime using the format I:I[:I] (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 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 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 in the -B cell. - - dlog -principal cell_admin -cell dce.abc.com - Password: cell_admin's password - -In the following example, the issuer authenticates as B to -the B cell and request a ticket lifetime of 100 hours. The -C command confirms that the user obtained DCE credentials as the -user B: the AFS ID is equivalent to the UNIX ID of B<1> assigned -to B in B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/dpass.pod b/doc/man-pages/pod/dpass.pod deleted file mode 100644 index 74fe47f7f3..0000000000 --- a/doc/man-pages/pod/dpass.pod +++ /dev/null @@ -1,113 +0,0 @@ -=head1 NAME - -dpass - Returns the DCE password for a new DCE account - -=head1 SYNOPSIS - -dpass [B<-cell> I] [B<-help>] - -dpass [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C command returns the DCE password that an administrator -assigned to the issuer when using the C command to migrate AFS -user accounts into a DCE cell. - -The C 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 command. - -=head1 OPTIONS - -=over 4 - -=item B<-cell> I - -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 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 - 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -C reference page in IBM AFS/DFS Migration Toolkit Administration Guide and Reference - -=cut diff --git a/doc/man-pages/pod/fileserver.pod b/doc/man-pages/pod/fileserver.pod deleted file mode 100644 index 88b7939020..0000000000 --- a/doc/man-pages/pod/fileserver.pod +++ /dev/null @@ -1,493 +0,0 @@ -=head1 NAME - -fileserver - Initializes the File Server component of the fs process - -=head1 SYNOPSIS - -fileserver [B<-d> I] [B<-p> I] -[B<-spare> I] -[B<-pctspare> I] [B<-b> I] -[B<-l> I] [B<-s> I] -[B<-vc> I] [B<-w> I] -[B<-cb> I] -[B<-banner> (print banner every 10 minutes)] -[B<-novbc> (whole volume cbs disabled)] -[B<-implicit> I] -[B<-hr> I] -[B<-busyat> I n>] -[B<-rxpck> I] -[B<-rxdbg> (enable rx debugging)] -[B<-rxdbge> (enable rxevent debugging)] -[B<-m> I] -[B<-lock> (keep fileserver from swapping)] -[B<-L> (large server conf)] [B<-S> (small server conf)] -[B<-k> I] [B<-realm> I] -[B<-udpsize> I] -[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 command initializes the File Server component of the B -process. In the conventional configuration, its binary file is located -in the B directory on a file server machine. - -The C command is not normally issued at the command shell -prompt, but rather placed into a database server machine's -B file with the C 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. - -The File Server creates the B 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 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 -section. By default the C 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 command -sets default values, and L 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 packets the File Server uses; corresponds -to the B<-rxpck> argument. Each packet consumes 1544 bytes of memory. - -=back - -=head2 Table 1 - -B - - ------------------------------------------------- - 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 (B) and B -(B) permissions to the B 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 (I) 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 or C 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 - -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 - -Sets the detail level for the debugging trace written to the -B 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 - -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 - -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 - -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 - -Sets the number of directory buffers. Provide a positive -integer. - -=item B<-l> I - -Sets the number of large vnodes available in memory for caching -directory elements. Provide a positive integer. - -=item B<-s> I - -Sets the number of small vnodes available in memory for caching -file elements. Provide a positive integer. - -=item B<-vc> I - -Sets the number of volumes the File Server can cache in memory. -Provide a positive integer. - -=item B<-w> I - -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 - -Sets the number of callbacks the File Server can track. Provide -a positive integer. - -=item B<-banner> - -Prints the following banner to B about every 10 -minutes. - -File Server is running at I permission to the -B group, even if you use the B value. - -=back - -=item B<-hr> I - -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 - -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 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 - -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. - -=item B<-rxdbge> - -Writes a trace of the File Server's operations on Rx events -(such as retransmissions) to the file B. - -=item B<-m> I - -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 - -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 binary from being paged -(swapped) out of memory on a file server machine running the -IRIX operating system. - -=over - -=item B - -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 - -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 - -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 file. - -=item B<-udpsize> I - -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 command creates an B process on the file -server machine B 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 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fms.pod b/doc/man-pages/pod/fms.pod deleted file mode 100644 index 1a7cc9bb40..0000000000 --- a/doc/man-pages/pod/fms.pod +++ /dev/null @@ -1,145 +0,0 @@ -=head1 NAME - -fms - Determine a tape's capacity and a tape device's filemark size - -=head1 SYNOPSIS - -fms B<-tape> I [B<-help>] - -fms B<-t> I [B<-h>] - -=head1 DESCRIPTION - -The C 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 file. For certain types of tape drives, -the Tape Coordinator operates more efficiently when the B -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 - -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; an example is B. - -=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 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 I C: specifies the size, in bytes, of -the tape in the device. - -=item * - -C I C: specifies the device's filemark size -in bytes. - -=back - -The following message indicates that the C command interpreter -cannot access the tape device. The command halts. - -Can't open tape drive I - -The following message indicates that the command interpreter cannot -create the B log file. Again, the command halts. - -Can't open log file - -=head1 EXAMPLES - -The following command illustrates the output for the device called -B: - - 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 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs.pod b/doc/man-pages/pod/fs.pod deleted file mode 100644 index 351888c21a..0000000000 --- a/doc/man-pages/pod/fs.pod +++ /dev/null @@ -1,203 +0,0 @@ -=head1 NAME - -fs - Introduction to the C command suite - -=head1 DESCRIPTION - -The commands in the C 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 command suite: - -=over - -=item * - -Commands to set and report how the Cache Manager interacts with -server machines: C, C, C, C, C, C, -C, C, and C - -=item * - -Commands to administer access control lists (ACLs): C, -C, C, and C - -=item * - -Commands to administer server machines, volumes or partitions that -house a given file or directory: C, C, C, C, C, C, -C, and C - -=item * - -Commands to administer the local client cache and related -information: C, C, C, C, and C - -=item * - -Commands to administer volume mount points: C, C, and C - -=item * - -Commands to control monitoring and tracing: C, and C - -=item * - -A command to administer the Cache Manager's interaction with other -file systems: C - -=item * - -Commands to obtain help: C and C - -=back - -The Cache Manager and the C commands use and maintain the following -configuration files: - -=over - -=item * - -The B 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 volume must also be mounted in the -local cell's AFS file tree. - -=item * - -The B file defines the machine's cell -membership with respect to the AFS command suites and Cache -Manager access to AFS data. - -=item * - -The B 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 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 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 commands vary more than for other -command suites. Pay special attention to the C -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 (B), B (B), and B -(B) permissions on the ACL of the directory in which the -mount point resides. - -=item * - -Being logged onto the machine as the local superuser B. This is -necessary when issuing commands that affect Cache Manager -configuration. - -=item * - -Belonging to the B group in the Protection -Database. - -=item * - -No privilege. Many C commands simply list information. - -=back - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_apropos.pod b/doc/man-pages/pod/fs_apropos.pod deleted file mode 100644 index 2690f2beb4..0000000000 --- a/doc/man-pages/pod/fs_apropos.pod +++ /dev/null @@ -1,71 +0,0 @@ -=head1 NAME - -fs apropos - Displays each help entry containing a keyword string - -=head1 SYNOPSIS - -fs apropos B<-topic> I [B<-help>] - -fs ap B<-t> I [B<-h>] - -=head1 DESCRIPTION - -The C command displays the first line of the online help -entry for any C 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 command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I - -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 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 commands that include the word -B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_checkservers.pod b/doc/man-pages/pod/fs_checkservers.pod deleted file mode 100644 index c83e0ccc00..0000000000 --- a/doc/man-pages/pod/fs_checkservers.pod +++ /dev/null @@ -1,234 +0,0 @@ -=head1 NAME - -fs checkservers - Displays the status of server machines - -=head1 SYNOPSIS - -fs checkservers [B<-cell> I] [B<-all>] [B<-fast>] -[B<-interval> I] [B<-help>] - -fs checks [B<-c> I] [B<-a>] [B<-f>] -[B<-i> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 file, plus any machines added to the -memory list by the C 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 process on a -database server machine or the B 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 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 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 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 command in the machine's -AFS initialization files. - -=head1 OPTIONS - -=over 4 - -=item B<-cell> I - -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 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 - -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. 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 - -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 - -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 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 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. 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 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 commands, the C command does not refer to -the AFSCELL environment variable. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_checkvolumes.pod b/doc/man-pages/pod/fs_checkvolumes.pod deleted file mode 100644 index b55c73ed91..0000000000 --- a/doc/man-pages/pod/fs_checkvolumes.pod +++ /dev/null @@ -1,54 +0,0 @@ -=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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - diff --git a/doc/man-pages/pod/fs_cleanacl.pod b/doc/man-pages/pod/fs_cleanacl.pod deleted file mode 100644 index 48ff64f5b2..0000000000 --- a/doc/man-pages/pod/fs_cleanacl.pod +++ /dev/null @@ -1,102 +0,0 @@ -=head1 NAME - -fs cleanacl - Remove obsolete entries from an ACL - -=head1 SYNOPSIS - -fs cleanacl [B<-path> I [I ...]] [B<-help>] - -fs cl [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 [I ...] - -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). For further discussion of -the concept of read/write and read-only paths through the -filespace, see the L 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 is fine. - -Otherwise, the output reports the resulting state of the ACL, -following the header - -Access list for I is now - -At the same time, the following error message appears for each file in -the cleaned directories: - -fs: 'I': 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 (B) 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 group have the -right implicitly, even if it does not appear on the ACL. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_copyacl.pod b/doc/man-pages/pod/fs_copyacl.pod deleted file mode 100644 index db77fe47df..0000000000 --- a/doc/man-pages/pod/fs_copyacl.pod +++ /dev/null @@ -1,176 +0,0 @@ -=head1 NAME - -fs copyacl - Copies an ACL from one directory to one or more other directories - -=head1 SYNOPSIS - -fs copyacl B<-fromdir> I -B<-todir> I [I ...] -[B<-clear>] [B<-id>] [B<-if>] [B<-help>] - -fs co B<-f> I -B<-t> I [I ...] -[B<-c>] [B<-id>] [B<-if>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 - -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 [I ...] - -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). For -further discussion of the concept of read/write and read-only -paths through the filespace, see the L 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. Note that the source -directory's ACL is unaffected. Entries on the B 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 -(B) permission on the source directory's ACL and the B -(B) 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 and B (B) permissions on the ACL of the file's -directory. - -To copy an ACL between DFS objects, the issuer must have the B -permission on the source directory or file's ACL and the B (B) -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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -IBM AFS/DFS Migration Toolkit Administration Guide and Reference - -=cut diff --git a/doc/man-pages/pod/fs_diskfree.pod b/doc/man-pages/pod/fs_diskfree.pod deleted file mode 100644 index 77876909b7..0000000000 --- a/doc/man-pages/pod/fs_diskfree.pod +++ /dev/null @@ -1,121 +0,0 @@ -=head1 NAME - -fs diskfree - Displays information about the partition housing a directory or file - -=head1 SYNOPSIS - -fs diskfree [B<-path> I [I ...]] [B<-help>] - -fs df [B<-p> I [I ...]] [B<-h>] - -fs di [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 -command. The C and C commands also display information -about a volume. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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 - -The name of the volume - -=item B - -The partition's total size in kilobytes - -=item B - -The number of kilobytes used on the partition - -=item B - -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 CEWARNING> 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 command -to list the volume's locations, and the C command to -display the size of each one. - -=head1 EXAMPLES - -The following example shows the output for the partitions housing the -volumes B and B: - - 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% < (B) 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_examine.pod b/doc/man-pages/pod/fs_examine.pod deleted file mode 100644 index b8ef607d1c..0000000000 --- a/doc/man-pages/pod/fs_examine.pod +++ /dev/null @@ -1,126 +0,0 @@ -=head1 NAME - -fs examine - Displays information about the volume containing a directory or file - -=head1 SYNOPSIS - -fs examine [B<-path> I [I ...]] [B<-help>] - -fs exa [B<-p> I [I ...]] [B<-h>] - -fs listvol [B<-p> I [I ...]] [B<-h>] - -fs listv [B<-p> I [I ...]] [B<-h>] - -fs lv [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command displays similar information in tabular format, and -the C command reports only the percentage of quota used. - -To set volume quota, use the C or C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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 line appears only if an administrator has -included the B<-offlinemsg> argument to the C command. The -remaining lines report, respectively, - -=over - -=item * - -the volume's quota in kilobytes, or the string C 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 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 (B) 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_exportafs.pod b/doc/man-pages/pod/fs_exportafs.pod deleted file mode 100644 index 671bf3f290..0000000000 --- a/doc/man-pages/pod/fs_exportafs.pod +++ /dev/null @@ -1,215 +0,0 @@ -=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 -[B<-start> I] -[B<-convert> I] -[B<-uidcheck> I] -[B<-submounts> I] -[B<-help>] - -fs exp B<-t> I -[B<-st> I] -[B<-c> I] -[B<-u> I] -[B<-su> I] -[B<-help>] - -=head1 DESCRIPTION - -The C 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 and B mode bits on an AFS -file or directory are set to match the B 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 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, use the B<-submounts> -argument. - -=back - -=head1 OPTIONS - -=over 4 - -=item B<-type> I - -Names the alternate file system to which to reexport the AFS -filespace. The only acceptable value is B, in lowercase -letters only. - -=item B<-start> I - -Enables the local machine to reexport the AFS filespace if the -value is B, or disables it if the value is B. Omit this -argument to report the current setting for all of the -configurable parameters. - -=item B<-convert> I - -Controls the setting of the UNIX B and B mode bits on -AFS files and directories exported to the non-AFS file system. -If the value is B, they are set to match the owner mode bits. -If the value is B, the bits are not changed. If this argument -is omitted, the default value is B. - -=item B<-uidcheck> I - -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, the UID that identifies the credential -structure must match the local UID. - -With respect to the C 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 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 and C 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 -command. - -=item * - -If the value is B (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 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.) -This setting allows more than one issuer of the C command -to make tokens available to the same user on the NFS client -machine. Each time a different user issues the C 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 - -Controls whether a user of the non-AFS filesystem can mount any -directory in the AFS filespace other than the top-level B -directory. If the value is B, such submounts are allowed. If -the value is off, only mounts of the B directory are -allowed. If this argument is omitted, the default value is B. - -=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-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' 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' translator is enabled with the following options: - -The following messages indicate that the B<-convert> argument is set to -B or B 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 or B 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 or B 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 and B mode bits on exported AFS -directories and files to match the UNIX B 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. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_flush.pod b/doc/man-pages/pod/fs_flush.pod deleted file mode 100644 index 107a3d2bef..0000000000 --- a/doc/man-pages/pod/fs_flush.pod +++ /dev/null @@ -1,85 +0,0 @@ -=head1 NAME - -fs flush - Forces the Cache Manager to discard a cached file or directory - -=head1 SYNOPSIS - -fs flush [B<-path> I [I ...]] [B<-help>] - -fs flush [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. To -flush a corrupted mount point, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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 in -the current working directory and all data from the subdirectory -B: - - fs flush -path projectnotes ./plans/* - -=head1 PRIVILEGE REQUIRED - -The issuer must have the B (B) 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_flushmount.pod b/doc/man-pages/pod/fs_flushmount.pod deleted file mode 100644 index ba8615c493..0000000000 --- a/doc/man-pages/pod/fs_flushmount.pod +++ /dev/null @@ -1,76 +0,0 @@ -=head1 NAME - -fs flushmount - Forces the Cache Manager to discard a mount point - -=head1 SYNOPSIS - -fs flushmount [B<-path> I [I ...]] [B<-help>] - -fs flushm [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 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 or C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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's home directory: - - fs flushm /afs/abc.com/usr/pat - -=head1 PRIVILEGE REQUIRED - -The issuer must have the B (B) 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_flushvolume.pod b/doc/man-pages/pod/fs_flushvolume.pod deleted file mode 100644 index 6b63d16ea0..0000000000 --- a/doc/man-pages/pod/fs_flushvolume.pod +++ /dev/null @@ -1,84 +0,0 @@ -=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 [I ...]] [B<-help>] - -fs flushv [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. To flush a corrupted -mount point, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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 (B) 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_getcacheparms.pod b/doc/man-pages/pod/fs_getcacheparms.pod deleted file mode 100644 index 9813e7abec..0000000000 --- a/doc/man-pages/pod/fs_getcacheparms.pod +++ /dev/null @@ -1,66 +0,0 @@ -=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 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 -file on a machine using a disk cache, if the C 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 of the cache's available I 1K byte blocks. - -where I is the number of kilobyte blocks currently used to -cache data and status information, and I 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_getcellstatus.pod b/doc/man-pages/pod/fs_getcellstatus.pod deleted file mode 100644 index a935f6af7c..0000000000 --- a/doc/man-pages/pod/fs_getcellstatus.pod +++ /dev/null @@ -1,70 +0,0 @@ -=head1 NAME - -fs getcellstatus - Reports whether the machine can run setuid programs from a specified -cell - -=head1 SYNOPSIS - -fs getcellstatus B<-cell> I [I ...] [B<-help>] - -fs getce B<-c> I [I ...] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command; -its reference page fully describes how AFS treats setuid programs. - -=head1 OPTIONS - -=over 4 - -=item B<-cell> I [I ...] - -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 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 status: setuid allowed - -Cell I status: no setuid allowed - -=head1 EXAMPLES - -The following example indicates that programs from the cell B -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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_getclientaddrs.pod b/doc/man-pages/pod/fs_getclientaddrs.pod deleted file mode 100644 index f7cdb94a1b..0000000000 --- a/doc/man-pages/pod/fs_getclientaddrs.pod +++ /dev/null @@ -1,109 +0,0 @@ -=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 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 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 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 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_getserverprefs.pod b/doc/man-pages/pod/fs_getserverprefs.pod deleted file mode 100644 index 1822a3a600..0000000000 --- a/doc/man-pages/pod/fs_getserverprefs.pod +++ /dev/null @@ -1,174 +0,0 @@ -=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] -[B<-numeric>] [B<-vlservers>] [B<-help>] - -fs gets [B<-f> I] [B<-n>] [B<-v>] [B<-h>] - -fs gp [B<-f> I] [B<-n>] [B<-v>] [B<-h>] - -=head1 DESCRIPTION - -The C command displays preference ranks for file -server machine interfaces (file server machines run the B process) -or, if the B<-vlserver> flag is provided, for Volume Location (VL) Server -machines (which run the B 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 -command is used to change it. The reference page for the C 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 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 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 - -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 command interpreter has the IP -addresses translated to hostnames such as B. - -=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, 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. 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 -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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_help.pod b/doc/man-pages/pod/fs_help.pod deleted file mode 100644 index 21a55484a1..0000000000 --- a/doc/man-pages/pod/fs_help.pod +++ /dev/null @@ -1,95 +0,0 @@ -=head1 NAME - -fs help - Displays the syntax of specified C commands or lists functional -descriptions of all C commands - -=head1 SYNOPSIS - -fs help [B<-topic> I [I ...]] [B<-help>] - -fs h [B<-t> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. - -To display every C command whose name or short description includes a -specified keyword, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I [I ...] - -Indicates each command for which to display the complete online -help entry. Omit the C part of the command name, providing -only the operation code (for example, specify C, not C). If this argument is omitted, the output briefly -describes every C 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 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 -command: - - fs help setacl - fs setacl: set access control list - aliases: sa - Usage: fs setacl -dir + -acl + - [-clear] [-negative] [-help] - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_listacl.pod b/doc/man-pages/pod/fs_listacl.pod deleted file mode 100644 index 147bc7c469..0000000000 --- a/doc/man-pages/pod/fs_listacl.pod +++ /dev/null @@ -1,196 +0,0 @@ -=head1 NAME - -fs listacl - Displays ACLs - -=head1 SYNOPSIS - -fs listacl [B<-path> I [I ...]] [B<-id>] [B<-if>] [B<-help>] - -fs la [B<-p> I [I ...]] [B<-id>] [B<-if>] [B<-h>] - -fs lista [B<-p> I [I ...]] [B<-id>] [B<-if>] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. To copy an ACL from one -directory to another, use the C command. To remove obsolete -entries from an ACL, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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 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 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 -header. The format of negative entries is the same as those on the -C 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 - -(B): change the entries on the ACL - -=item B - -(B): remove files and subdirectories from the directory or -move them to other directories - -=item B - -(B): add files or subdirectories to the directory by -copying, moving or creating - -=item B - -(B): set read locks or write locks on the files in the -directory - -=item B - -(B): list the files and subdirectories in the directory, -stat the directory itself, and issue the C command to -examine the directory's ACL - -=item B - -(B): read the contents of files in the directory; issue the -C command to stat the elements in the directory - -=item B - -(B): modify the contents of files in the directory, and -issue the UNIX C command to change their mode bits - -=item B - -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 (B) permission replaces the AFS B (B) -permission, DFS B (B) replaces AFS B (B), and there is -no DFS equivalent to the AFS B (B) 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 (the current working directory), and on its B -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 (B) 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 -(B) and B (B) 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 (B) 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 section of the ACL does -not guarantee denial of permissions, if the C section -grants the permissions to members of the B group. In that -case, the user needs only to issue the C command to obtain the -permissions granted to the B group. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -IBM AFS/DFS Migration Toolkit Administration Guide and Reference - -=cut diff --git a/doc/man-pages/pod/fs_listcells.pod b/doc/man-pages/pod/fs_listcells.pod deleted file mode 100644 index 9577f861b5..0000000000 --- a/doc/man-pages/pod/fs_listcells.pod +++ /dev/null @@ -1,83 +0,0 @@ -=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 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 into kernel memory. To modify the -list between reboots, use the C 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 on hosts I - -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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_listquota.pod b/doc/man-pages/pod/fs_listquota.pod deleted file mode 100644 index 02c75b5ef7..0000000000 --- a/doc/man-pages/pod/fs_listquota.pod +++ /dev/null @@ -1,111 +0,0 @@ -=head1 NAME - -fs listquota - Displays quota information for the volume containing a file or -directory. - -=head1 SYNOPSIS - -fs listquota [B<-path> I [I ...]] [B<-help>] - -fs listq [B<-p> I [I ...]] [B<-h>] - -fs lq [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. - -To set volume quota, use the fs setquota or C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -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 - -The name of the volume. - -=item B - -The volume's quota in kilobytes, or the string no limit to -indicate an unlimited quota. - -=item B - -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 - -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: - - 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 (B) 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_lsmount.pod b/doc/man-pages/pod/fs_lsmount.pod deleted file mode 100644 index eba6111446..0000000000 --- a/doc/man-pages/pod/fs_lsmount.pod +++ /dev/null @@ -1,130 +0,0 @@ -=head1 NAME - -fs lsmount - Reports the volume for which a directory is the mount point. - -=head1 SYNOPSIS - -fs lsmount B<-dir> I [I ...] [B<-help>] - -fs ls B<-d> I [I ...] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. To remove one, -use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-dir> I [I ...] - -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' is a mount point for volume 'I' - -where - -=over - -=item * - -A number sign (#) precedes the I string for a regular -mount point. - -=item * - -A percent sign (%) precedes the I string for a -read/write mount point. - -=item * - -A cell name and colon (:) follow the number or percent sign and -precede the I string for a cellular mount point. - -=back - -The L 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' is a symbolic link, leading to a mount point for volume 'I' - -If the directory is not a mount point or is not in AFS, the output -reads: - -'I' 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 -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: - - 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 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 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 (B) 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_messages.pod b/doc/man-pages/pod/fs_messages.pod deleted file mode 100644 index f69f653e8b..0000000000 --- a/doc/man-pages/pod/fs_messages.pod +++ /dev/null @@ -1,98 +0,0 @@ -=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 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 - -Send user messages to user screens - -=item B - -Send console messages to the console - -=item B - -Send user messages to user screens and console messages -to the console (the default if the B<-show> argument is -omitted) - -=item B - -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. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_mkmount.pod b/doc/man-pages/pod/fs_mkmount.pod deleted file mode 100644 index 7b1c1625ca..0000000000 --- a/doc/man-pages/pod/fs_mkmount.pod +++ /dev/null @@ -1,274 +0,0 @@ -=head1 NAME - -fs mkmount - Creates a mount point for a volume - -=head1 SYNOPSIS - -fs mkmount B<-dir> I B<-vol> I [B<-cell> I] -[B<-rw>] [B<-fast>] [B<-help>] - -fs mk B<-d> I B<-v> I [B<-c> I] [B<-r>] [B<-f>] [B<-h>] - -=head1 DESCRIPTION - -The C command creates a mount point for the volume named by -the B<-vol> argument at the location in the AFS file space specified by -the B<-dir> argument. The mount point looks like a standard directory -element, and serves as the volume's root directory, but is actually a -special file system object that refers to an AFS volume. When the -Cache Manager first encounters a given mount point during pathname -traversal, it contacts the VL Server to learn which file server -machines house the indicated volume, then fetches a copy of the -volume's root directory from the appropriate file server machine. - -It is possible, although not recommended, to create more than one -mount point to a volume. The Cache Manager can become confused if a -volume is mounted in two places along the same path through the -filespace. - -The Cache Manager observes three basic rules as it traverses the AFS -filespace and encounters mount points: - -=over - -=item * - -B: Access Backup and Read-only Volumes When Specified - -When the Cache Manager encounters a mount point that specifies a -volume with either a B<.readonly> or a B<.backup> extension, it accesses -that type of volume only. If a mount point does not have either a -B<.backup> or B<.readonly> extension, the Cache Manager uses Rules 2 and -3. - -For example, the Cache Manager never accesses the read/write -version of a volume if the mount point names the backup version. -If the specified version is inaccessible, the Cache Manager -reports an error. - -=item * - -B: Follow the Read-only Path When Possible - -If a mount point resides in a read-only volume and the volume that -it references is replicated, the Cache Manager attempts to access -a read-only copy of the volume; if the referenced volume is not -replicated, the Cache Manager accesses the read/write copy. The -Cache Manager is thus said to prefer a I path through the -filespace, accessing read-only volumes when they are available. - -The Cache Manager starts on the read-only path in the first place -because it always accesses a read-only copy of the B volume -if it exists; the volume is mounted at the root of a cell's AFS -filespace (named B by convention). That is, if the B -volume is replicated, the Cache Manager attempts to access a -read-only copy of it rather than the read/write copy. This rule -then keeps the Cache Manager on a read-only path as long as each -successive volume is replicated. The implication is that both the -B and B volumes must be replicated for the Cache -Manager to access replicated volumes mounted below them in the AFS -filespace. The volumes are conventionally mounted at the B and -BI directories, respectively. - -=item * - -B: Once on a Read/write Path, Stay There - -If a mount point resides in a read/write volume and the volume -name does not have a B<.readonly> or a B<.backup> extension, the Cache -Manager attempts to access only the a read/write version of the -volume. The access attempt fails with an error if the read/write -version is inaccessible, even if a read-only version is -accessible. In this situation the Cache Manager is said to be on a -I and cannot switch back to the read-only path -unless mount point explicitly names a volume with a B<.readonly> -extension. (Cellular mount points are an important exception to -this rule, as explained in the following discussion. - -=back - -There are three types of mount points, each appropriate for a -different purpose because of the manner in which the Cache Manager -interprets them. - -=over - -=item * - -When the Cache Manager crosses a I mount point, it obeys all -three of the mount point traversal rules previously described. To -create a regular mount point, include only the required B<-dir> and -B<-vol> arguments to the C command. - -=over - -=item B: - -A regular mount point does not force the Cache Manager always to -access read-only volumes (it is explicitly not a "read-only mount -point"). If a volume is not replicated, the third traversal rule means -that the Cache Manager still accesses the read/write volume when that -is the only type available. However, if the Cache Manager is to access -the read-only version of a replicated volume named by a regular mount -point, all volumes that are mounted above it in the pathname must also -be replicated. - -=back - -=item * - -When the Cache Manager crosses a I mount point, it -attempts to access only the volume version named in the mount -point. If the volume name is the base (read/write) form, without a -B<.readonly> or B<.backup> extension, the Cache Manager accesses the -read/write version of the volume, even if it is replicated. In -other words, the Cache Manager disregards the second mount point -traversal rule when crossing a read/write mount point: it switches -to the read/write path through the filespace. - -To create a read/write mount point, include the B<-rw> flag on the C command. It is conventional to create only one read/write -mount point in a cell's filespace, using it to mount the cell's -B volume just below the AFS filespace root (by convention, -B.I). See the IBM AFS Quick Beginnings for instructions -and the chapter about volume management in the IBM AFS -Administration Guide for further discussion. - -Creating a read/write mount point for a read-only or backup volume -is acceptable, but unnecessary. The first rule of mount point -traversal already specifies that the Cache Manager accesses them -if the volume name in a regular mount point has a B<.readonly> or -B<.backup> extension. - -=item * - -When the Cache Manager crosses a I mount point, it accesses -the indicated volume in the specified cell, which is normally a -foreign cell. (If the mount point does not name a cell along with -the volume, the Cache Manager accesses the volume in the cell -where the mount point resides.) The Cache Manager disregards the -third mount point traversal rule when crossing a regular cellular -mount point: it accesses a read-only version of the volume if it -is replicated, even if the volume that houses the mount point is -read/write. Switching to the read-only path in this way is -designed to avoid imposing undue load on the file server machines -in foreign cells. - -To create a regular cellular mount point, include the B<-cell> -argument on the C command. It is conventional to create -cellular mount points only at the second level in a cell's -filespace, using them to mount foreign cells' B volumes -just below the AFS filespace root (by convention, at -BI). The mount point enables local users to -access the foreign cell's filespace, assuming they have the -necessary permissions on the ACL of the volume's root directory -and that there is an entry for the foreign cell in each local -client machine's B file. In the output of -the C command, the cell name and a colon (:) appear -between the initial number sign and the volume name in a regular -cellular mount point name. - -=back - -=head1 OPTIONS - -=over 4 - -=item B<-dir> I - -Names the directory to create as a mount point. The directory -must not already exist. Relative pathnames are interpreted with -respect to the current working directory. - -Specify the read/write path to the directory, to avoid the -failure that results from attempting to create a new mount -point in a read-only volume. By convention, the read/write path -is indicated by placing a period before the cell name at the -pathname's second level (for example, B). For -further discussion of the concept of read/write and read-only -paths through the filespace, see the L section of -this reference page. - -=item B<-vol> I - -Specifies the name or volume ID number of the volume to mount. -If appropriate, add the C<.readonly> or C<.backup> extension to the -name, or specify the appropriate volume ID number. - -=item B<-cell> I - -Names the cell in which the volume resides (creates a cellular -mount point). Provide the fully qualified domain name, or a -shortened form that disambiguates it from the other cells -listed in the local B file. - -If this argument is omitted, no cell indicator appears in the -mount point. When the Cache Manager interprets it, it assumes -that the volume named in the mount point resides in the same -cell as the volume that houses the mount point. - -=item B<-rw> - -Creates a read/write mount point. Omit this flag to create a -regular mount point. - -=item B<-fast> - -Prevents the Volume Location (VL) Server from checking that the -volume has a VLDB entry and printing a warning message if it -does not. Whether or not this flag is included, the File Server -creates the mount point even when the volume has no VLDB entry. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command creates a regular mount point, mounting the -volume B at B: - - cd /afs/abc.com/usr - - fs mkmount -dir smith -vol user.smith - -The following commands create a read/write mount point and a regular -mount point for the ABC Corporation cell's C volume in that -cell's file tree. The second command follows the convention of putting -a period at the beginning of the read/write mount point's name. - - fs mkmount -dir /afs/abc.com -vol root.cell - - fs mkmount -dir /afs/.abc.com -vol root.cell -rw - -The following command mounts the State University cell's C -volume in the ABC Corporation cell's file tree, creating a regular -cellular mount point called B. When a ABC Corporation -Cache Manager encounters this mount point, it crosses into the State -University cell on a read-only path. - - fs mkmount -dir /afs/stateu.edu -vol root.cell -c stateu.edu - -=head1 PRIVILEGE REQUIRED - -The issuer must have the B (B) and B (B) permissions on -the ACL of the directory that is to house the mount point. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_newcell.pod b/doc/man-pages/pod/fs_newcell.pod deleted file mode 100644 index a84f13d056..0000000000 --- a/doc/man-pages/pod/fs_newcell.pod +++ /dev/null @@ -1,112 +0,0 @@ -=head1 NAME - -fs newcell - Changes the kernel-resident list of a cell's database server machines - -=head1 SYNOPSIS - -fs newcell B<-name> I B<-servers> I [I ...] -[B<-linkedcell> I] [B<-help>] - -fs n B<-n> I B<-s> I [I ...] [B<-l> I] [B<-h>] - -=head1 DESCRIPTION - -The C command removes the Cache Manager's kernel-resident -list of database server machines for the cell specified by the B<-name> -argument and replaces it with the database server machines named by -the B<-servers> argument. - -Each time the machine reboots, the Cache Manager constructs the kernel -list of cells and database server machines by reading the local -B file. This command does not change the -B file, so any changes made with it persist only until the -next reboot, unless the issuer also edits the file. The output of the -C command reflects changes made with this command, because -that command consults the kernel-resident list rather than the -B file. - -This command can introduce a completely new cell into the -kernel-resident list, but cannot make a cell inaccessible (it is not -possible to remove a cell's entry from the kernel-resident list by -providing no values for the B<-server> argument). To make a cell -inaccessible, remove its entry from the B file and reboot the -machine. - -If the B<-name> argument names a DCE cell, then the B<-servers> argument -names DFS Fileset Location (FL) Server machines. The B<-linkedcell> -argument specifies the name of the AFS cell to link to a DCE cell for -the purpose of DFS fileset location. Refer to the IBM AFS/DFS -Migration Toolkit Administration Guide and Reference for more -information on linking AFS clients to DCE cells using this command or -by editing the B file. - -=head1 OPTIONS - -=over 4 - -=item B<-name> I - -Specifies the fully-qualified cell name of the AFS or DCE cell. - -=item B<-servers> I [I ...] - -Specifies the fully-qualified hostnames of all AFS database -server machines or DFS Fileset Location (FL) Server machines -for the cell named by the B<-name> argument. If FL Server machines -are specified, the local machine must be running the AFS/DFS -Migration Toolkit Protocol Translator. - -=item B<-linkedcell> I - -Specifies the name of the AFS cell to link to a DCE cell for -the purpose of DFS fileset location. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following example changes the machine's kernel-resident list of -database server machines for the ABC Corporation cell to include the -machines B and B: - - fs newcell -name abc.com -servers db1.abc.com db2.abc.com - -The following example links the DCE cell B to the AFS cell -B. The AFS client contacts the Fileset Location (FL) servers -B and B for fileset location information -as it interprets a DFS pathname. - - fs newcell -name dce.abc.com -servers db1.dce.abc.com db2.dce.abc.com \ - -linkedcell abc.com - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 CAVEATS - -Some commands, such as the C command, work correctly only when the -information is accurate for a cell in both the B file and the -kernel-resident list. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -IBM AFS/DFS Migration Toolkit Administration Guide and Reference, -IBM AFS/DFS Migration Toolkit Administration Installation and Configuration Guide - -=cut diff --git a/doc/man-pages/pod/fs_quota.pod b/doc/man-pages/pod/fs_quota.pod deleted file mode 100644 index f8a8f842c0..0000000000 --- a/doc/man-pages/pod/fs_quota.pod +++ /dev/null @@ -1,85 +0,0 @@ -=head1 NAME - -fs quota - Displays the percentage of quota used in the volume containing a -directory or file - -=head1 SYNOPSIS - -fs quota [B<-path> I [I ...]] [B<-help>] - -fs q [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C command displays the percent of quota consumed in the -volume that contains each specified directory or file. - -To display more detailed information about the volume and the -partition it resides on, use the C and C commands. - -To set volume quota, use the C or C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -Names each file or directory for which to display the quota -consumed in its parent volume. Partial pathnames are -interpreted relative to the current working directory, which is -also the default value if this argument is omitted. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output reports the percent of volume quota used, in the following -format: - -I% of quota used. - -=head1 EXAMPLES - -The following command lists the percent quota used of the volume -housing the current working directory: - - fs quota - 17% of quota used. - -The following command lists the percent quota used of both the volume -housing the current working directory's parent directory and the -volume housing the directory B: - - fs quota -path .. B.com/usr/smith - 43% of quota used. - 92% of quota used. - -=head1 PRIVILEGE REQUIRED - -The issuer must have the B (B) 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_rmmount.pod b/doc/man-pages/pod/fs_rmmount.pod deleted file mode 100644 index 8749c9660f..0000000000 --- a/doc/man-pages/pod/fs_rmmount.pod +++ /dev/null @@ -1,68 +0,0 @@ -=head1 NAME - -fs rmmount - Removes a mount point - -=head1 SYNOPSIS - -fs rmmount B<-dir> I [I ...] [B<-help>] - -fs rm B<-d> I [I ...] [B<-h>] - -=head1 DESCRIPTION - -The C command removes the mount point named by the B<-dir> -argument from the file system. The corresponding volume remains on its -host partition or partitions, but is inaccessible if there are no -other mount points for it. - -=head1 OPTIONS - -=over 4 - -=item B<-dir> I [I ...] - -Names the mount point to delete from the file system. The last -element in the pathname must be an actual name, not a shorthand -notation such as "dot" (.) or "dot dot" (..). - -Specify the read/write path to the directory, to avoid the -failure that results from attempting to delete a mount point -from a read-only volume. By convention, the read/write path is -indicated by placing a period before the cell name at the -pathname's second level (for example, B). For -further discussion of the concept of read/write and read-only -paths through the filespace, see the L reference page. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command removes the mount points B and B from -the current working directory (the B directory). - - fs rmmount jones terry - -=head1 PRIVILEGE REQUIRED - -The issuer must have the B (B) permission on the ACL of the -directory that houses each mount point. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_setacl.pod b/doc/man-pages/pod/fs_setacl.pod deleted file mode 100644 index 5b68e9c465..0000000000 --- a/doc/man-pages/pod/fs_setacl.pod +++ /dev/null @@ -1,293 +0,0 @@ -=head1 NAME - -fs setacl - Sets the ACL for a directory - -=head1 SYNOPSIS - -fs setacl B<-dir> I [I ...] B<-acl> I [I ...] -[B<-clear>] [B<-negative>] [B<-id>] [B<-if>] [B<-help>] - -fs sa B<-d> I [I ...] B<-a> I [I ...] -[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>] - -fs seta B<-d> I [I ...] B<-a> I [I ...] -[B<-c>] [B<-n>] [B<-id>] [B<-if>] [B<-h>] - -=head1 DESCRIPTION - -The C command adds the access control list (ACL) entries -specified with the B<-acl> argument to the ACL of each directory named by -the B<-dir> argument. - -If the B<-dir> argument designates a pathname in DFS filespace (accessed -via the AFS/DFS Migration Toolkit Protocol Translator), it can be a -file as well as a directory. The ACL must already include an entry for -B, however. For more details, refer to the IBM AFS/DFS -Migration Toolkit Administration Guide and Reference. - -Only user and group entries are acceptable values for the B<-acl> -argument. Do not place machine entries (IP addresses) directly on an -ACL; instead, make the machine entry a group member and place the -group on the ACL. - -To completely erase the existing ACL before adding the new entries, -provide the B<-clear> flag. To add the specified entries to the Negative -rights section of the ACL (deny rights to specified users or groups), -provide the B<-negative> flag. - -To display an ACL, use the C command. To copy an ACL from one -directory to another, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-dir> I [I ...] - -Names each AFS directory, or DFS directory or file, for which -the set the ACL. Partial pathnames are interpreted relative to -the current working directory. - -Specify the read/write path to each directory (or DFS file), to -avoid the failure that results from attempting to change a -read-only volume. By convention, the read/write path is -indicated by placing a period before the cell name at the -pathname's second level (for example, B). For -further discussion of the concept of read/write and read-only -paths through the filespace, see the L reference page. - -=item B<-acl> I [I ...] - -Defines a list of one or more ACL entries, each a pair that -names - -=over - -=item * - -A user name or group name as listed in the Protection -Database - -=item * - -One or more ACL permissions, indicated either by combining -the individual letters or by one of the four acceptable -shorthand words - -=back - -in that order, separated by a space (thus every instance of -this argument has two parts). The accepted AFS abbreviations -and shorthand words, and the meaning of each, are as follows: - -=over - -=item B - -(B): change the entries on the ACL - -=item B - -(B): remove files and subdirectories from the -directory or move them to other directories - -=item B - -(B): add files or subdirectories to the directory by -copying, moving or creating - -=item B - -(B): set read locks or write locks on the files in the -directory - -=item B - -(B): list the files and subdirectories in the -directory, stat the directory itself, and issue the C command to examine the directory's ACL - -=item B - -(B): read the contents of files in the directory; -issue the C command to stat the elements in the -directory - -=item B - -(B): modify the contents of files in the directory, -and issue the UNIX C command to change their mode -bits - -=item B - -Have no default meaning to the AFS server processes, but -are made available for applications to use in controlling -access to the directory's contents in additional ways. -The letters must be uppercase. - -=item B - -Equals all seven permissions (B). - -=item B - -No permissions. Removes the user/group from the ACL, but -does not guarantee they have no permissions if they -belong to groups that remain on the ACL. - -=item B - -Equals the B (B) and B (B) permissions. - -=item B - -Equals all permissions except B (B), that is, -B. - -=back - -It is acceptable to mix entries that combine the individual -letters with entries that use the shorthand words, but not use -both types of notation within an individual pairing of user or -group and permissions. - -To learn the proper format and acceptable values for DFS ACL -entries, see the IBM AFS/DFS Migration Toolkit Administration -Guide and Reference. - -=item B<-clear> - -Removes all existing entries on each ACL before adding the -entries specified with the B<-acl> argument. - -=item B<-negative> - -Places the specified ACL entries in the C section -of each ACL, explicitly denying the rights to the user or -group, even if entries on the accompanying C -section of the ACL grant them permissions. - -This argument is not supported for DFS files or directories, -because DFS does not implement negative ACL permissions. - -=item B<-id> - -Places the ACL entries on the Initial Container ACL of each DFS -directory, which are the only file system objects for which -this flag is supported. - -=item B<-if> - -Places the ACL entries on the Initial Object ACL of each DFS -directory, which are the only file system objects for which -this flag is supported. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following example adds two entries to the C section of -the current working directory's ACL: the first entry grants B (B) -and B (B) permissions to the group B, while the other -(using the B shorthand) gives all permissions except B -(B) to the user B. - - fs setacl -dir . -acl pat:friends rl smith write - - fs listacl -path . - Access list for . is - Normal rights: - pat:friends rl - smith rlidwk - -The following example includes the B<-clear> flag, which removes the -existing permissions (as displayed with the C command) from -the current working directory's B subdirectory and replaces them -with a new set. - - fs listacl -dir reports - Access list for reports is - Normal rights: - system:authuser rl - pat:friends rlid - smith rlidwk - pat rlidwka - Negative rights: - terry rl - - fs setacl -clear -dir reports -acl pat all smith write system:anyuser rl - - fs listacl -dir reports - Access list for reports is - Normal rights: - system:anyuser rl - smith rlidwk - pat rlidwka - -The following example use the B<-dir> and B<-acl> switches because it sets -the ACL for more than one directory (both the current working -directory and its public subdirectory). - - fs setacl -dir . public -acl pat:friends rli - - fs listacl -path . public - Access list for . is - Normal rights: - pat rlidwka - pat:friends rli - Access list for public is - Normal rights: - pat rlidwka - pat:friends rli - -=head1 PRIVILEGE REQUIRED - -The issuer must have the B (B) permission on the directory's -ACL; the directory's owner and the members of the -B group have the right implicitly, even if it does -not appear on the ACL. - -=head1 CAVEATS - -If the ACL already grants certain permissions to a user or group, the -permissions specified with the C command replace the existing -permissions, rather than being added to them. - -Setting negative permissions is generally unnecessary and not -recommended. Simply omitting a user or group from the Normal rights -section of the ACL is normally adequate to prevent access. In -particular, note that it is futile to deny permissions that are -granted to members of the B group on the same ACL; the -user needs only to issue the C command to receive the denied -permissions. - -When including the B<-clear> option, be sure to reinstate an entry for -each directory's owner that includes at least the B (B) -permission. Without that permission, it is impossible to resolve the -"dot" ( . ) and "dot dot" ( .. ) shorthand from within the directory. -(The directory's owner does implicitly have the B [B] -permission even on a cleared ACL, but must know to use it to add other -permissions.) - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -IBM_AFS/DFS_Migration Toolkit_Administration Guide_and Reference - -=cut diff --git a/doc/man-pages/pod/fs_setcachesize.pod b/doc/man-pages/pod/fs_setcachesize.pod deleted file mode 100644 index 86dc511547..0000000000 --- a/doc/man-pages/pod/fs_setcachesize.pod +++ /dev/null @@ -1,105 +0,0 @@ -=head1 NAME - -fs setcachesize - Sets the size of the disk cache - -=head1 SYNOPSIS - -fs setcachesize [B<-blocks> I reset)>] -[B<-reset>] [B<-help>] - -fs setca [B<-b> I reset)>] [B<-r>] [B<-h>] - -fs cachesize [B<-b> I reset)>] [B<-r>] [B<-h>] - -fs ca [B<-b> I reset)>] [B<-r>] [B<-h>] - -=head1 DESCRIPTION - -The C command changes the number of kilobyte blocks of -local disk space available to the Cache Manager for its data cache, on -machines that use a disk cache. The command is not operative on -machines that use a memory cache. - -To return the cache size to the default value specified in the third -field of the local B file, provide a value of B<0> -to the B<-blocks> argument. - -To return the cache size to the value set when the machine was last -rebooted, use the B<-reset> flag instead of the B<-blocks> argument. This is -normally the amount specified in the B file, unless the -B<-blocks> argument was included on the C command to override the -B value. - -To display the current cache size and amount of cache in use, for both -disk and memory caches, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-blocks> I reset)> - -Specifies the number of one-kilobyte blocks of disk space -available for the Cache Manager to devote to the cache. Provide -a value of B<0> to set cache size to the default specified in the -B file. - -=item B<-reset> - -Returns the cache size to the value set when the machine was -last booted. This agrees with the value in the B file -unless the B<-blocks> argument was used on the C command. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command sets the disk cache size to 25000 kilobyte -blocks. - - fs setcachesize -blocks 25000 - -Both of the following commands reset the disk cache size to the value -in the B file, assuming that the B<-blocks> argument to the C -command was not used. - - fs setcachesize -blocks 0 - - fs setcachesize -reset - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 CAVEATS - -This command is not operative on machines using a memory cache, and -results in an error message. To change memory cache size, edit the -B file and reboot, or reboot and provide the B<-blocks> argument -to the C command. - -On machines using a disk cache, do not set the cache size to exceed -85% to 90% of the actual disk space available for the cache directory. -The cache implementation itself requires a small amount of space on -the partition. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_setcell.pod b/doc/man-pages/pod/fs_setcell.pod deleted file mode 100644 index 16bcccdf6f..0000000000 --- a/doc/man-pages/pod/fs_setcell.pod +++ /dev/null @@ -1,104 +0,0 @@ -=head1 NAME - -fs setcell - Allows or disallows running of setuid programs from specified cells - -=head1 SYNOPSIS - -fs setcell B<-cell> I [I ...] [B<-suid>] [B<-nosuid>] [B<-help>] - -fs setce B<-c> I [I ...] [B<-s>] [B<-n>] [B<-h>] - -=head1 DESCRIPTION - -The C command sets whether the Cache Manager allows programs -(and other executable files) from each cell named by the B<-cell> -argument to run with setuid permission. By default, the Cache Manager -allows programs from its home cell to run with setuid permission, but -not programs from any foreign cells. A program belongs to the same -cell as the file server machine that houses the volume in which the -program's binary file resides, as specified in the file server -machine's B file. The Cache Manager determines its -own home cell by reading the B file at -initialization. - -To enable programs from each specified cell to run with setuid -permission, include the B<-suid> flag. To prohibit programs from running -with setuid permission, include the B<-nosuid> flag, or omit both flags. - -The C command directly alters a cell's setuid status as -recorded in kernel memory, so rebooting the machine is unnecessary. -However, non-default settings do not persist across reboots of the -machine unless the appropriate C command appears in the -machine's AFS initialization file. - -To display a cell's setuid status, issue the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-cell> I [I ...] - -Names each cell for which to set setuid status. Provide the -fully qualified domain name, or a shortened form that -disambiguates it from the other cells listed in the local -B file. - -=item B<-suid> - -Allows programs from each specified cell to run with setuid -privilege. Provide it or the B<-nosuid> flag, or omit both flags -to disallow programs from running with setuid privilege. - -=item B<-nosuid> - -Prevents programs from each specified cell from running with -setuid privilege. Provide it or the B<-suid> flag, or omit both -flags to disallow programs form running with setuid privilege. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command enables executable files from the State -University cell to run with setuid privilege on the local machine: - - fs setcell -cell stateu.edu -suid - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 CAVEATS - -AFS does not recognize effective UID: if a setuid program accesses AFS -files and directories, it does so using the current AFS identity of -the AFS user who initialized the program, not of the program's owner. -Only the local file system recognizes effective UID. - -Only members of the B group can turn on the setuid -mode bit on an AFS file or directory. - -When the setuid mode bit is turned on, the UNIX C command displays -the third user mode bit as an s instead of an x. However, the s does -not appear on an AFS file or directory unless setuid permission is -enabled for the cell in which the file resides. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_setclientaddrs.pod b/doc/man-pages/pod/fs_setclientaddrs.pod deleted file mode 100644 index 597870fb0b..0000000000 --- a/doc/man-pages/pod/fs_setclientaddrs.pod +++ /dev/null @@ -1,122 +0,0 @@ -=head1 NAME - -fs setclientaddrs - Sets the client interfaces to register with the File Server - -=head1 SYNOPSIS - -fs setclientaddrs [B<-address> I [I ...]] [B<-help>] - -fs setcl [B<-a> I [I ...]] [B<-h>] - -fs sc [B<-a> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C command defines the IP addresses of the -interfaces that the local Cache Manager registers with a File Server -when first establishing a connection to it. - -The File Server uses the addresses when it initiates a remote -procedure call (RPC) to the Cache Manager (as opposed to responding to -an RPC sent by the Cache Manager). There are two common circumstances -in which the File Server initiates RPCs: when it breaks callbacks and -when it pings the client machine to verify that the Cache Manager is -still accessible. - -The list of interfaces specified with this command replaces the list -that the Cache Manager constructs and records in kernel memory as it -initializes. At that time, if the file B exists on -the client machine's local disk, the Cache Manager uses its contents -as the basis for the list of interfaces addresses. If the file does -not exist, the Cache Manager instead uses the network interfaces -configured with the operating system. It then removes from the list -any address included in the local B file. It -records the final list in kernel memory. (An administrator must create -the B and B files; there are no default versions of -them.) - -If an RPC to that interface fails, the File Server simultaneously -sends RPCs to all of the other interfaces in the list, to learn which -of them are still available. Whichever interface replies first is the -one to which the File Server then sends pings and RPCs to break -callbacks. - -To list the interfaces that the Cache Manager is currently registering -with File Servers, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-address> I [I ...] - -Specifies each IP address to place in the list of interfaces, -in dotted decimal format. Hostnames are not acceptable. -Separate each address with one or more spaces. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The message: - -Adding I - -confirms that each new interface was added to the Cache Manager's -list. The address appears in hexadecimal format to match the notation -used in the File Server log, B. - -=head1 EXAMPLES - -The following example sets the two interfaces that the Cache Manager -registers with File Servers. - - fs setclientaddrs 191.255.105.68 191.255.108.84 - Adding 0xbfff6944 - Adding 0xbfff6c54 - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 CAVEATS - -The list specified with this command persists in kernel memory only -until the client machine reboots. To preserve it across reboots, -either list the interfaces in the local B file, or -place the appropriate C command in the machine's AFS -initialization script. - -Changes made with this command do not propagate automatically to File -Servers to which the Cache Manager has already established a -connection. To force such File Servers to use the revised list, either -reboot each file server machine, or change the B file and reboot -the client machine. - -The C command interpreter verifies that each of the addresses -specified as a value for the B<-address> argument is actually configured -with the operating system on the client machine. If it is not, the -command fails with an error message that marks the address as a -Nonexistent interface. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_setquota.pod b/doc/man-pages/pod/fs_setquota.pod deleted file mode 100644 index 09c0447120..0000000000 --- a/doc/man-pages/pod/fs_setquota.pod +++ /dev/null @@ -1,90 +0,0 @@ -=head1 NAME - -fs setquota - Sets the maximum quota for the volume containing a file or directory - -=head1 SYNOPSIS - -fs setquota [B<-path> I] B<-max> I [B<-help>] - -fs setq [B<-p> I] B<-m> I [B<-h>] - -fs sq [B<-p> I] B<-m> I [B<-h>] - -=head1 DESCRIPTION - -The C command sets the quota (maximum possible size) of the -read/write volume that contains the directory or file named by the -B<-path> argument. - -To set the quota on multiple volumes at the same time, use the C command. - -To display a volume's quota, use the C, C or C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I - -Names the directory or file for which to set the host volume's -quota. Partial pathnames are interpreted relative to the -current working directory, which is also the default value if -this argument is omitted. - -Specify the read/write path to the file or directory, to avoid -the failure that results from attempting to change a read-only -volume. By convention, the read/write path is indicated by -placing a period before the cell name at the pathname's second -level (for example, B). For further discussion of -the concept of read/write and read-only paths through the -filespace, see the L reference page. - -=item B<-max> I - -Sets the maximum amount of file server disk space the volume -can occupy. Specify the number of one-kilobyte blocks as a -positive integer (B<1024> is one megabyte). A value of B<0> sets an -unlimited quota, but the size of the disk partition that houses -the volume places an absolute limit on the volume's size. - -If the B<-path> argument is omitted (to set the quota of the -volume housing the current working directory), the B<-max> switch -must be included with this argument. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command imposes a maximum quota of 3000 kilobytes on the -volume that houses the B directory: - - fs setquota -path /afs/abc.com/usr/smith -max 3000 - -=head1 PRIVILEGE REQUIRED - -The issuer must belong to the B group. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_setserverprefs.pod b/doc/man-pages/pod/fs_setserverprefs.pod deleted file mode 100644 index 115208fad4..0000000000 --- a/doc/man-pages/pod/fs_setserverprefs.pod +++ /dev/null @@ -1,320 +0,0 @@ -=head1 NAME - -fs setserverprefs - Sets the Cache Manager's preference ranks for file server or VL Server -machines - -=head1 SYNOPSIS - -fs setserverprefs [B<-servers> I [I ...]] -[B<-vlservers> I [I ...]] -[B<-file> I] [B<-stdin>] [B<-help>] - -fs sets [B<-se> I [I ...]] [B<-vl> I^ -+] -[B<-f> I] [B<-st>] [B<-h>] - -fs sp [B<-se> I [I ...]] [B<-vl> I [I ...]] - -[B<-f> I] [B<-st>] [B<-h>] - -=head1 DESCRIPTION - -The C command sets the local Cache Manager's -preference ranks for one or more file server machine interfaces or, if -the B<-vlserver> argument is provided, for Volume Location (VL) Server -machines. For file server machines, the numerical ranks determine the -order in which the Cache Manager attempts to contact the interfaces of -machines that are housing a volume. For VL Server machines, the ranks -determine the order in which the Cache Manager attempts to contact a -cell's VL Servers when requesting VLDB information. - -The L reference page explains how the Cache Manager -uses preference ranks when contacting file server machines or VL -Server machines. The following paragraphs explain how the Cache -Manager calculates default ranks, and how to use this command to -change the defaults. - -=head2 Calculation of Default Preference Ranks - -The Cache Manager stores a preference rank in kernel memory as a -paired IP address and numerical rank. If a file server machine is -multihomed, the Cache Manager assigns a distinct rank to each of the -machine's addresses (up to the number of addresses that the VLDB can -store per machine, which is specified in the IBM AFS Release Notes). -Once calculated, a rank persists until the machine reboots, or until -this command is used to change it. - -The Cache Manager sets default VL Server preference ranks as it -initializes, randomly assigning a rank from the range 10,000 to 10,126 -to each of the machines listed in the local B -file. Machines from different cells can have the same rank, but this -does not present a problem because the Cache Manager consults only one -cell's ranks at a time. - -The Cache Manager sets default preference ranks for file server -machine as it fetches volume location information from the VLDB. Each -time it learns about file server machine interfaces for which it has -not already set ranks, it assigns a rank to each interface. If the -local client machine has only one IP address, the Cache Manager -compares it to the server interface's IP address and sets a rank -according to the following algorithm. If the client machine is -multihomed, the Cache Manager applies the algorithm to each of the -client machine's addresses and assigns to the file server machine -interface the lowest rank that results. - -=over - -=item * - -If the local machine is a file server machine, the base rank for -each of its interfaces is 5,000. - -=item * - -If the file server machine interface is on the same subnetwork as -the client interface, its base rank is 20,000. - -=item * - -If the file server machine interface is on the same network as the -client interface, or is at the distant end of a point-to-point -link with the client interface, its base rank is 30,000. - -=item * - -If the file server machine interface is on a different network -than the client interface, or the Cache Manager cannot obtain -network information about it, its base rank is 40,000. - -=back - -After assigning a base rank to a file server machine interface, the -Cache Manager adds to it a number randomly chosen from the range 0 -(zero) to 14. As an example, a file server machine interface in the -same subnetwork as the local machine receives a base rank of 20,000, -but the Cache Manager records the actual rank as an integer between -20,000 and 20,014. This process reduces the number of interfaces that -have exactly the same rank. As with VL Server machine ranks, it is -possible for file server machine interfaces from foreign cells to have -the same rank as interfaces in the local cell, but this does not -present a problem. Only the relative ranks of the interfaces that -house a given volume are relevant, and AFS only supports storage of a -volume in one cell at a time. - -=head2 Setting Non-default Preference Ranks - -Use the C command to reset an existing preference -rank, or to set the initial rank of a file server machine interface or -VL Server machine for which the Cache Manager has no rank. To make a -rank persist across a reboot of the local machine, place the -appropriate C command in the machine's AFS -initialization file. - -Specify each preference rank as a pair of values separated by one or -more spaces: - -=over - -=item * - -The first member of the pair is the fully-qualified hostname (for -example, B), or the IP address in dotted decimal format, -of a file server machine interface or VL Server machine - -=item * - -The second member of the pair is an integer. The possible ranks -range from B<1> through B<65535>. - -=back - -As with default ranks, the Cache Manager adds a randomly chosen -integer to a rank specified by this command. For file server machine -interfaces, the integer is from the range 0 (zero) to 14; for VL -Server machines, it is from the range 0 (zero) to 126. For example, if -the administrator assigns a rank of 15,000 to a file server machine -interface, the Cache Manager stores an integer between 15,000 to -15,014. - -There are several ways to provide ranks for file server machine -interfaces (but not for VL Server machines): - -=over - -=item * - -On the command line, following the B<-servers> argument. - -=item * - -In a file named by the B<-file> argument. Place each pair on its own -line in the file. Directing the output from the C -command to a file automatically generates a file with the proper -format. - -=item * - -Via the standard input stream, by providing the B<-stdin> flag. This -method enables the issuer to feed in values directly from a -program or script that generates preference ranks by using an -algorithm appropriate to the local cell. The AFS distribution does -not include such programs or scripts. - -=back - -When setting file server machine preference ranks, it is legal to -combine the B<-servers>, B<-file>, and B<-stdin> options on a single command -line. If different options specify a different rank for the same -interface, the Cache Manager stores and uses the rank assigned with -the B<-servers> argument. - -The B<-vlservers> argument is the only way to assign VL Server machine -ranks. It can be combined with one or more of the B<-servers>, B<-file>, and -B<-stdin> options, but the Cache Manager applies the values provided for -those options to file server machine ranks only. - -The C command interpreter does not verify hostnames or IP addresses, -and so assigns preference ranks to invalid machine names or addresses. -The Cache Manager never uses such ranks unless the same incorrect -information is in the VLDB. - -=head1 OPTIONS - -=over 4 - -=item B<-servers> I [I ...] - -Specifies one or more file server machine preference ranks. -Each rank pairs the fully-qualified hostname or IP address (in -dotted decimal format) of a file server machine's interface -with an integer rank, separated by one or more spaces; also -separate each pair with one or more spaces. Acceptable values -for the rank range from B<1> through B<65521>; a lower value -indicates a greater preference. Providing ranks outside this -range can have unpredictable results. Providing a value no -larger than B<65521> guarantees that the rank does not exceed the -maximum possible value of 65,535 even if the largest random -factor (14) is added. - -This argument can be combined with the B<-file> argument, B<-stdin> -flag, or both. If more than one of the arguments sets a rank -for the same interface, the rank set by this argument takes -precedence. It can also be combined with the B<-vlservers> -argument, but does not interact with it. - -=item B<-vlservers> I [I ...] - -Specifies one or more VL Server preference ranks. Each rank -pairs the fully-qualified hostname or IP address (in dotted -decimal format) of a VL Server machine with an integer rank, -separated by one or more spaces; also separate each pair with -one or more spaces. Acceptable values for the rank range from B<1> -through B<65521>; a lower value indicates a greater preference. -Providing ranks outside this range can have unpredictable -results. Providing a value no larger than B<65521> guarantees that -the rank does not exceed the maximum possible value of 65,535 -even if the largest random factor (14) is added. - -This argument can be combined with the B<-servers> argument, B<-file> -argument, B<-stdin> flag, or any combination of the three, but -does not interact with any of them. They apply only to file -server machine ranks. - -=item B<-file> I - -Specifies the full pathname of a file from which to read pairs -of file server machine interfaces and their ranks, using the -same notation and range of values as for the B<-servers> argument. -In the file, place each pair on its own line and separate the -two parts of each pair with one or more spaces. - -This argument can be combined with the B<-servers> argument, -B<-stdin> flag, or both. If more than one of the arguments sets a -rank for the same interface, the rank set by the B<-server> -argument takes precedence. It can also be combined with the -B<-vlservers> argument, but does not interact with it. - -=item B<-stdin> - -Reads pairs of file server machine interface and integer rank -from the standard input stream. The intended use is to accept -input piped in from a user-defined program or script that -generates ranks in the appropriate format, but it also accepts -input typed to the shell. Format the interface and rank pairs -as for the B<-file> argument. If typing at the shell, type -BCtrl-dE> after the final newline to complete the input. - -This argument can be combined with the B<-servers> argument, the -B<-file> argument, or both. If more than one of the arguments sets -a rank for the same interface, the rank set by the B<-server> -argument takes precedence. It can also be combined with the -B<-vlservers> argument, but does not interact with it. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command sets the Cache Manager's preference ranks for -the file server machines named B and B, the latter -of which is specified by its IP address, 192.12.105.100. The machines -reside in another subnetwork of the local machine's network, so their -default base rank is 30,000. To increase the Cache Manager's -preference for these machines, the issuer assigns a rank of B<25000>, to -which the Cache Manager adds an integer in the range from 0 to 15. - - fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 - -The following command uses the B<-servers> argument to set the Cache -Manager's preference ranks for the same two file server machines, but -it also uses the B<-file> argument to read a collection of preference -ranks from a file that resides in the local file B: - - fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \ - -file /etc/fs.prefs - -The B file has the following contents and format: - - 192.12.108.214 7500 - 192.12.108.212 7500 - 138.255.33.41 39000 - 138.255.33.34 39000 - 128.0.45.36 41000 - 128.0.45.37 41000 - -The following command uses the B<-stdin> flag to read preference ranks -from the standard input stream. The ranks are piped to the command -from a program, B, which was written by the issuer to -calculate preferences based on values significant to the local cell. - - calc_prefs | fs setserverprefs -stdin - -The following command uses the B<-vlservers> argument to set the Cache -Manager's preferences for the VL server machines named B, -B, and B to base ranks of 1, 11000, and 65521, -respectively: - - fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \ - fs4.abc.com 65521 - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_setvol.pod b/doc/man-pages/pod/fs_setvol.pod deleted file mode 100644 index be53f75ac0..0000000000 --- a/doc/man-pages/pod/fs_setvol.pod +++ /dev/null @@ -1,106 +0,0 @@ -=head1 NAME - -fs setvol - Set maximum quota and messages for the volume containing a file or -directory - -=head1 SYNOPSIS - -fs setvol [B<-path> I [I ...]] [B<-max> I] -[B<-offlinemsg> I] [B<-help>] - -fs setv [B<-p> I [I ...]] [B<-ma> I] -[B<-o> I] [B<-h>] - -fs sv [B<-p> I [I ...]] [B<-ma> I] -[B<-o> I] [B<-h>] - -=head1 DESCRIPTION - -The C command sets the quota (maximum possible size) of the -read/write volume that contains each directory or file named by the -B<-path> argument. To associate a message with the volume which then -appears in the output of the C command, include the -B<-offlinemsg> argument. - -To display all of the settings made with this command, use the C command. The C command reports a fileset's quota, -and the C command the percent of quota used. - -To set quota on one volume at a time, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -Names each file or directory for which to set the host volume's -quota and offline message. Partial pathnames are interpreted -relative to the current working directory, which is also the -default value if this argument is omitted. - -Specify the read/write path to the file or directory, to avoid -the failure that results from attempting to change a read-only -volume. By convention, the read/write path is indicated by -placing a period before the cell name at the pathname's second -level (for example, B). For further discussion of -the concept of read/write and read-only paths through the -filespace, see the L reference page. - -=item B<-max> I - -Sets the maximum amount of file server disk space the volume -can occupy. Provide a positive integer to indicate the number -of one-kilobyte blocks (B<1024> is one megabyte). A value of B<0> -sets an unlimited quota, but the size of the disk partition -that houses the volume places an absolute limit on the volume's -size. - -If the B<-path> argument is omitted (so that the command sets the -quota of the volume housing the current working directory), the -B<-max> switch must be provided. - -=item B<-offlinemsg> I - -Associates a message with the volume which then appears in the -output of the C command. Its intended use is to -explain why the volume is currently offline. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command imposes a 6500 kilobyte quota on the volumes -mounted at the home directories B and -B: - - cd /afs/abc.com/usr - - fs setvol -path smith pat -max 6500 - -=head1 PRIVILEGE REQUIRED - -The issuer must belong to the B group. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_storebehind.pod b/doc/man-pages/pod/fs_storebehind.pod deleted file mode 100644 index bada1cc37d..0000000000 --- a/doc/man-pages/pod/fs_storebehind.pod +++ /dev/null @@ -1,231 +0,0 @@ -=head1 NAME - -fs storebehind - Enables asynchronous writes to the file server - -=head1 SYNOPSIS - -fs storebehind [B<-kbytes> I] -[B<-files> I [I ...]] -[B<-allfiles> I] [B<-verbose>] [B<-help>] - -fs st [B<-k> I] [B<-f> I [I ...]] -[B<-a> I] [B<-v>] [B<-h>] - -=head1 DESCRIPTION - -The C command enables the Cache Manager to perform a -delayed asynchronous write to the File Server when an application -closes a file. By default, the Cache Manager writes all data to the -File Server immediately and synchronously when an application program -closes a file--that is, the B system call does not return until -the Cache Manager has actually transferred the final chunk of the file -to the File Server. This command specifies the number of kilobytes of -a file that can still remain to be written to the File Server when the -Cache Manager returns control to the application. It is useful if -users working on the machine commonly work with very large files, but -also introduces the complications discussed in the L section. - -Set either or both of the following in a single command: - -=over - -=item * - -To set a value that applies to all AFS files manipulated by -applications running on the machine, use the B<-allfiles> argument. -This value is termed the I for the machine, -and persists until the machine reboots. If it is not set, the -default value is zero, indicating that the Cache Manager performs -synchronous writes. - -As an example, the following setting means that when an -application closes a file, the Cache Manager can return control to -the application as soon as no more than 10 kilobytes of the file -remain to be written to the File Server. - - -allfiles 10 - -=item * - -To set a value that applies to one or more individual files, and -overrides the value of the B<-allfiles> argument for them, combine -the B<-kbytes> and B<-files> arguments. The setting persists as long as -there is an entry for the file in the kernel table that the Cache -Manager uses to track certain information about files. In general, -such an entry persists at least until an application closes the -file or exits, but the Cache Manager is free to recycle the entry -if the file is inactive and it needs to free up slots in the -table. To increase the certainty that there is an entry for the -file in the table, issue the C command shortly before -closing the file. - -As an example, the following setting means that when an -application closes either of the files B and B, the -Cache Manager can return control to the application as soon as no -more than a megabyte of the file remains to be written to the File -Server. - - -kbytes 1024 -files bigfile biggerfile - -Note that once an explicit value has been set for a file, the only -way to make it subject to the default store asynchrony once again -is to set B<-kbytes> to that value. In other words, there is no -combination of arguments that automatically makes a file subject -to the default store asynchrony once another value has been set -for the file. - -=back - -To display the settings that currently apply to individual files or to -all files, provide the command's arguments in certain combinations as -specified in the L section of this reference page. - -=head1 OPTIONS - -=over 4 - -=item B<-kbytes> I - -Specifies the number of kilobytes of data from each file named -by the B<-files> argument that can remain to be written to the -file server when the Cache Manager returns control to an -application program that closed the file. The B<-files> argument -is required along with this argument. Provide an integer from -the range B<0> (which reinstates the Cache Manager's default -behavior or writing synchronously) to the maximum AFS file -size. - -=item B<-files> I [I ...] - -Names each file to which the value set with the B<-kbytes> -argument applies. The setting persists as long as there is an -entry for the file in the kernel table that the Cache Manager -uses to track certain information about files. Because closing -a file generally erases the entry, when reopening a file the -only way to guarantee that the setting still applies is to -reissue the command. If this argument is provided without the -B<-kbytes> argument, the command reports the current setting for -the specified files, and the default store asynchrony. - -=item B<-allfiles> I - -Sets the default store asynchrony for the local machine, which -is the number of kilobytes of data that can remain to be -written to the file server when the Cache Manager returns -control to the application program that closed a file. The -value applies to all AFS files manipulated by applications -running on the machine, except those for which settings have -been made with the B<-kbytes> and B<-files> arguments. Provide an -integer from the range B<0> (which indicates the default of -synchronous writes) to the maximum AFS file size. - -=item B<-verbose> - -Produces output confirming the settings made with the -accompanying B<-kbytes> and B<-files> arguments, the B<-allfiles> -argument, or all three. If provided by itself, reports the -current default store asynchrony. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -If none of the command's options are included, or if only the B<-verbose> -flag is included, the following message reports the default store -asynchrony (the setting that applies to all files manipulated by -applications running on the local machine and for which not more -specific asynchrony is set). - - Default store asynchrony is x kbytes. - -A value of C<0> (zero) indicates synchronous writes and is the default if -no one has included the B<-allfiles> argument on this command since the -machine last rebooted. - -If the B<-files> argument is provided without the B<-kbytes> argument, the -output reports the value that applies to each specified file along -with the default store asynchrony. If a particular value has -previously been set for a file, the following message reports it: - - Will store up to y kbytes of file asynchronously. - Default store asynchrony is x kbytes. - -If the default store asynchrony applies to a file because no explicit -B<-kbytes> value has been set for it, the message is instead as follows: - - Will store file according to default. - Default store asynchrony is x kbytes. - -If the B<-verbose> flag is combined with arguments that set values -(B<-files> and B<-kbytes>, or B<-allfiles>, or all three), there is a message -that confirms immediately that the setting has taken effect. When -included without other arguments or flags, the B<-verbose> flag reports -the default store asynchrony only. - -=head1 EXAMPLES - -The following command enables the Cache Manager to return control to -the application program that closed the file B when 100 -kilobytes still remain to be written to the File Server. The B<-verbose> -flag produces output that confirms the new setting, and that the -default store asynchrony is zero. - - fs storebehind -kbytes 100 -files test.data -verbose - Will store up to 100 kbytes of test.data asynchronously. - Default store asynchrony is 0 kbytes. - -=head1 PRIVILEGE REQUIRED - -To include the B<-allfiles> argument, the issuer must be logged in as the -local superuser B. - -To include the B<-kbytes> and B<-files> arguments, the issuer must either be -logged in as the local superuser B or have the B (B) permission -on the ACL of each file's directory. - -To view the current settings (by including no arguments, the B<-file> -argument alone, or the B<-verbose> argument alone), no privilege is -required. - -=head1 CAVEATS - -For the following reasons, use of this command is not recommended in -most cases. - -In normal circumstances, an asynchronous setting results in the Cache -Manager returning control to applications earlier than it otherwise -does, but this is not guaranteed. - -If a delayed write fails, there is no way to notify the application, -since the B system call has already returned with a code -indicating success. - -Writing asynchronously increases the possibility that the user will -not notice if a write operation makes the volume that houses the file -exceed its quota. As always, the portion of the file that exceeds the -volume's quota is lost, which prompts a message such as the following: - -C - -To avoid losing data, it is advisable to verify that the volume -housing the file has space available for the amount of data -anticipated to be written. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L - -=cut diff --git a/doc/man-pages/pod/fs_sysname.pod b/doc/man-pages/pod/fs_sysname.pod deleted file mode 100644 index d14f529929..0000000000 --- a/doc/man-pages/pod/fs_sysname.pod +++ /dev/null @@ -1,94 +0,0 @@ -=head1 NAME - -fs sysname - Reports or sets the CPU/operating system type - -=head1 SYNOPSIS - -fs sysname [B<-newsys> I] [B<-help>] - -fs sy [B<-n> I] [B<-h>] - -=head1 DESCRIPTION - -The C command sets or displays the local machine's -CPU/operating system type as recorded in kernel memory. The Cache -Manager substitutes the string for the I<@sys> variable which can occur -in AFS pathnames; the IBM AFS Quick Beginnings and IBM AFS -Administration Guide explain how using I<@sys> can simplify cell -configuration. It is best to use it sparingly, however, because it can -make the effect of changing directories unpredictable. - -The command always applies to the local machine only. If issued on an -NFS client machine accessing AFS via the NFS/AFS Translator, the -string is set or reported for the NFS client machine. The Cache -Manager on the AFS client machine serving as the NFS client's NFS/AFS -translator machine stores the value in its kernel memory, and so can -provide the NFS client with the proper version of program binaries -when the user issues commands for which the pathname to the binaries -includes I<@sys>. There is a separate record for each user logged into -the NFS client, which implies that if a user adopts a new identity -(UNIX UID) during a login session on the NFS client--perhaps by using -the UNIX C command--he or she must verify that the correct string is -set for the new identity also. - -=head1 OPTIONS - -=over 4 - -=item B<-newsys> I - -Sets the CPU/operating system indicator string for the local -machine. If this argument is omitted, the output displays the -current setting instead. AFS uses a standardized set of -strings; consult the IBM AFS Quick Beginnings or AFS Release -Notes. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -When the B<-newsys> argument is omitted, the output reports the machine's -system type in the following format: - -Current sysname is 'I' - -=head1 EXAMPLES - -The following example shows the output produced on a Sun SPARCStation -running Solaris 5.7: - - fs sysname - Current sysname is 'sun4x_57' - -The following command defines a machine to be a IBM RS/6000 running -AIX 4.2: - - fs sysname -newsys rs_aix42 - -=head1 PRIVILEGE REQUIRED - -To display the current setting, no privilege is required. To include -the B<-newsys> argument on an AFS client machine, the issuer must be -logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -IBM AFS Quick Beginnings, -IBM AFS Administration Guide - -=cut diff --git a/doc/man-pages/pod/fs_whereis.pod b/doc/man-pages/pod/fs_whereis.pod deleted file mode 100644 index 9bd5750c01..0000000000 --- a/doc/man-pages/pod/fs_whereis.pod +++ /dev/null @@ -1,74 +0,0 @@ -=head1 NAME - -fs whereis - Reports the name of each file server machine housing a file or -directory - -=head1 SYNOPSIS - -fs whereis [B<-path> I [I ...]] [B<-help>] - -fs whe [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C command returns the name of each file server machine -that houses the volume containing each directory or file named by the -B<-path> argument. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -Names each AFS file or directory for which to return the host -file server machine. Partial pathnames are interpreted relative -to the current working directory, which is also the default -value if this argument is omitted. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output includes a line for each specified directory or file. It -names the file server machine on which the volume that houses the -specified directory or file resides. A list of multiple machines -indicates that the directory or file is in a replicated volume. - -Machine names usually have a suffix indicating their cell membership. -If the cell is not clear, use the C command to display the -cell in which the directory or file resides. To display the cell -membership of the local machine, use the C command. - -=head1 EXAMPLES - -The following example indicates that volume housing the directory -B resides is replicated on both B and -B: - - fs whereis -path /afs/abc.com - File /afs/abc.com is on hosts fs1.abc.com fs3.abc.com - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_whichcell.pod b/doc/man-pages/pod/fs_whichcell.pod deleted file mode 100644 index 05bf4b3987..0000000000 --- a/doc/man-pages/pod/fs_whichcell.pod +++ /dev/null @@ -1,68 +0,0 @@ -=head1 NAME - -fs whichcell - Returns the name of the cell to which a file or directory belongs - -=head1 SYNOPSIS - -fs whichcell [B<-path> I [I ...]] [B<-help>] - -fs whi [B<-p> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C command returns the name of the cell in which the -volume that houses each indicated directory or file resides. - -To display the file server machine on which the volume housing a -directory or file resides, use the C command. To display -the cell membership of the local machine, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-path> I [I ...] - -Names each AFS file or directory for which to return the cell -membership. Partial pathnames are interpreted relative to the -current working directory, which is also the default value if -this argument is omitted. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output includes a line for each directory or file, naming the cell -to which the volume that houses the directory or file resides. - -=head1 EXAMPLES - -The following example shows that the current working directory resides -in a volume in the ABC Corporation cell: - - fs whichcell - File . lives in cell 'abc.com' - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fs_wscell.pod b/doc/man-pages/pod/fs_wscell.pod deleted file mode 100644 index 1857951b66..0000000000 --- a/doc/man-pages/pod/fs_wscell.pod +++ /dev/null @@ -1,59 +0,0 @@ -=head1 NAME - -fs wscell - Returns the name of the cell to which a machine belongs - -=head1 SYNOPSIS - -fs wscell [B<-help>] - -fs ws [B<-h>] - -=head1 DESCRIPTION - -The C command returns the name of the local machine's home -cell. - -=head1 OPTIONS - -=over 4 - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output displays the contents of the local B -file, in the format - -This workstation belongs to cell 'I' - -=head1 EXAMPLES - -The following example results when the C is issued on a -machine in the State University cell: - - fs wscell - This workstation belongs to cell 'stateu.edu' - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace.pod b/doc/man-pages/pod/fstrace.pod deleted file mode 100644 index a77b028269..0000000000 --- a/doc/man-pages/pod/fstrace.pod +++ /dev/null @@ -1,88 +0,0 @@ -=head1 NAME - -fstrace - Introduction to the C command suite - -=head1 DESCRIPTION - -The commands in the C command suite are the interface that -system administrators employ to trace Cache Manager operations for -debugging purposes. Examples of Cache Manager operations are fetching -file data or the status information used to produce output for the -UNIX B command. - -The C command interpreter defines an extensive set of Cache -Manager operations as the B I. When the event set is -activated, the Cache Manager writes a message to the B I in -kernel memory each time it performs one of the defined operations. The -log expands only to a defined size (by default, 60 KB), after which it -is overwritten in a circular fashion (new trace messages overwrite the -oldest ones). If an operation of particular interest occurs, the -administrator can afterward display the log on the standard output -stream or write it to a file for later study. For more specific -procedural instructions, see the IBM AFS Administration Guide. - -There are several categories of commands in the C command suite: - -=over - -=item * - -Commands to administer or display information about the trace log: -C, C, C - -=item * - -Commands to set or display the status of the event set: -C and C - -=item * - -A command to display the contents of the trace log: C - -=item * - -Commands to obtain help: C and C - -=back - -=head1 OPTIONS - -All C commands accept the following optional flag. It is listed -in the command descriptions and described in detail here: - -=over 4 - -=item B<-help> - -Prints a command's online help message on the standard output -stream. Do not combine this flag with any of the command's -other options; when it is provided, the command interpreter -ignores all other options, and only prints the help message. - -=back - -=head1 PRIVILEGE REQUIRED - -To issue most C commands, the issuer must be logged on as the -local superuser B on the machine that is generating the trace log. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_apropos.pod b/doc/man-pages/pod/fstrace_apropos.pod deleted file mode 100644 index 85bcc04862..0000000000 --- a/doc/man-pages/pod/fstrace_apropos.pod +++ /dev/null @@ -1,71 +0,0 @@ -=head1 NAME - -fstrace apropos - Displays each help entry containing a keyword string - -=head1 SYNOPSIS - -fstrace apropos B<-topic> I [B<-help>] - -fstrace ap B<-t> I [B<-h>] - -=head1 DESCRIPTION - -The C command displays the first line of the online help -entry for any C command that contains in its name or short -description the string specified with the B<-topic> argument. - -To display a command's complete syntax, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I - -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 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 commands that include the word -B in their names or short descriptions: - - fstrace apropos set - clear: clear logs by logname or by event set - lsset: list available event sets - setlog: set the size of a log - setset: set state of event sets - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_clear.pod b/doc/man-pages/pod/fstrace_clear.pod deleted file mode 100644 index 50ef2d006b..0000000000 --- a/doc/man-pages/pod/fstrace_clear.pod +++ /dev/null @@ -1,64 +0,0 @@ -=head1 NAME - -fstrace clear - Clears the trace log - -=head1 SYNOPSIS - -fstrace clear [B<-set> I [I ...]] [B<-log> I [I ...]] [B<-help>] - -fstrace c [B<-s> I [I ...]] [B<-l> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C command erases the contents of the trace log from -kernel memory, but leaves kernel memory allocated for the log. - -=head1 OPTIONS - -=over 4 - -=item B<-set> I [I ...] - -Names the event set for which to clear the associated trace -log. The only acceptable value is B (for which the associated -trace log is B). Provide either this argument or the B<-log> -argument, or omit both to clear the B log by default. - -=item B<-log> I [I ...] - -Names the trace log to clear. The only acceptable value is -B. Provide either this argument or the B<-set> argument, or -omit both to clear the B log by default. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command clears the B trace log on the local machine: - - fstrace clear - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_dump.pod b/doc/man-pages/pod/fstrace_dump.pod deleted file mode 100644 index ade52c3020..0000000000 --- a/doc/man-pages/pod/fstrace_dump.pod +++ /dev/null @@ -1,248 +0,0 @@ -=head1 NAME - -fstrace dump - Dumps a trace log - -=head1 SYNOPSIS - -fstrace dump [B<-set> I [I ...]] [B<-follow> I] -[B<-file> I] -[B<-sleep> I] [B<-help>] - -fstrace d [B<-se> I [I ...]] [B<-fo> I] [B<-fi> I] -[B<-sl> I] [B<-h>] - -=head1 DESCRIPTION - -The C command displays the current contents of the B -trace log on the standard output stream or writes it to the file named -by the B<-file> argument. - -To write the log continuously to the standard output stream or to a -file, use the B<-follow> argument. By default, the log's contents are -written out every ten seconds and then automatically cleared. To -change the interval between writes, use the B<-sleep> argument. - -=head1 OPTIONS - -=over 4 - -=item B<-set> I [I ...] - -Names the event set for which to write out the associated trace -log. The only acceptable value is B (for which the associated -trace log is B). Provide either this argument or the B<-follow> -argument, or omit both to write out the B log by default. - -=item B<-follow> I - -Names the trace log to write out continuously at a specified -interval (by default, every ten seconds; use the B<-sleep> -argument to change the interval). The log is cleared after each -write operation. - -The only acceptable value is B. Provide either this argument -or the B<-set> argument, or omit both to write out the B log by -default. - -=item B<-file> I - -Specifies the pathname of the file to which to write the trace -log's contents. It can be in AFS or on the local disk. Partial -pathnames are interpreted relative to the current working -directory. If this argument is omitted, the trace log appears -on the standard output stream. - -=item B<-sleep> I - -Sets the number of seconds between writes of the trace log's -contents when it is dumped continuously. Provide the B<-follow> -argument along with this one. If this argument is omitted, the -default interval is ten seconds. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output begins with a header specifying the date and time at which -the write operation began. If the B<-follow> argument is not included, -the header also reports the number of logs being dumped; it is always -1, since there is only the B trace log. The format of the header is -as follows: - - AFS Trace Dump - - Date: starting_timestamp - Found 1 logs. - Contents of log cmfx: - -Each subsequent message describes a Cache Manager operation in the -following format: - -time I, pid I:I - -where - -=over - -=item B - -Specifies the time at which the Cache Manager performed the -operation, as the number of seconds since the dump began - -=item B - -Specifies the process ID of the process or thread associated -with the message - -=item B - -Is the message itself. They are generally meaningful only to -someone familiar with the AFS source code. - -=back - -In addition, every 1024 seconds the C command interpreter writes -a message that records the current clock time, in the following -format: - -time I, pid I: Current time: I - -where - -=over - -=item B - -Is the number of seconds from the start of trace logging - -=item B - -Is the process ID number - -=item B - -Is the machine's clock time, represent in the standard UNIX -time format as the number of seconds since midnight on January -1, 1970. - -=back - -Use this message to determine the actual clock time associated with -each log message. Determine the actual time as follows: - -=over - -=item 1. - -Locate the message of interest. - -=item 2. - -Search backward through the trace file for the closest current -time message. - -=item 3. - -If the current time message's I is smaller than the log -message's I, subtract former from the latter. If the -current time message's I is larger than the log message's -I, add 1024 to the latter and subtract the former from the -result. - -=item 4. - -Add the resulting number to the current time message's I -to determine the log message's actual time. - -=back - -If any of the data in the kernel trace buffer has been overwritten -since tracing was activated, the following message appears at the -appropriate place in the output: - - Log wrapped; data missing. - -To reduce the likelihood of overwriting, use the C -command to increase the kernel buffer's size. To display the current -defined buffer size, use the C command with the B<-long> -argument. - -The following message at the end of the log dump indicates that it is -completed: - - AFS Trace Dump - Completed - -=head1 EXAMPLES - -The following command dumps the log associated with the cm event set -to the standard output stream. - - fstrace dump -set cm - AFS Trace Dump - - Date: Tue Apr 7 10:54:57 1998 - Found 1 logs. - time 32.965783, pid 0: Tue Apr 7 10:45:52 1998 - time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20 - time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns 0x0) - time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024 (volume 0) - time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024 (volume 0) - . - . - . - time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs \ - fid (756 4fb7e:588d240.2ff978a8.6) - time 71.440569, pid 33658: Returning code 2 from 19 - time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns 0x2) - time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x0) - AFS Trace Dump - Completed - -The following command dumps the trace log associated with the B event -set on the local machine to the file B, using the -default interval of 10 seconds between successive dumps: - - fstrace dump -follow cmfx -file cmfx.dump.file.1 - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 CAVEATS - -This command produces output only if the B event set is active. To -display or set the event set's state, use the C or C command respectively. - -To make the output from this command maximally readable, the message -catalog file called B must reside in the local -B directory. If necessary, copy the file to that -directory from the AFS Binary Distribution before activating tracing. - -When the B event set is active, a defined amount of kernel memory (by -default, 60 KB) is allocated for the B trace log. As described on -the introductory L reference page, when the buffer is full, -messages are overwritten in a circular fashion (new messages overwrite -the oldest ones). To allocate more kernel memory for the log, use the -C command; to display the log buffer's current size, use -the C command with the B<-long> argument. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_help.pod b/doc/man-pages/pod/fstrace_help.pod deleted file mode 100644 index cb1477f757..0000000000 --- a/doc/man-pages/pod/fstrace_help.pod +++ /dev/null @@ -1,94 +0,0 @@ -=head1 NAME - -fstrace help - Displays the syntax of specified C commands or lists functional -descriptions of all C commands - -=head1 SYNOPSIS - -fstrace help [B<-topic> I [I ...]] [B<-help>] - -fstrace h [B<-t> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C 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 command. - -To list every C command whose name or short description includes -a specified keyword, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I [I ...] - -Indicates each command for which to display the complete online -help entry. Omit the C part of the command name, -providing only the operation code (for example, specify C, -not C). If this argument is omitted, the output -briefly describes every C 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 command consists of two or -three lines: - -=over - -=item * - -The first line names the command and briefly describes its -function. - -=item * - -The second line lists aliases for the command, if any. - -=item * - -The final line, which begins with the string C, 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 command: - - fstrace help -topic setset - fstrace setset: set state of event sets - Usage: fstrace setset [-set +] [-active] [-inactive] - [-dormant] [-help] - -=head1 PRIVILEGE REQUIRED - -None - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_lslog.pod b/doc/man-pages/pod/fstrace_lslog.pod deleted file mode 100644 index 07053f87d0..0000000000 --- a/doc/man-pages/pod/fstrace_lslog.pod +++ /dev/null @@ -1,109 +0,0 @@ -=head1 NAME - -fstrace lslog - Displays information about a log - -=head1 SYNOPSIS - -fstrace lslog [B<-set> I [I ...]] [B<-log> I] [B<-long>] [B<-help>] - -fstrace lsl [B<-s> I [I ...]] [B<-log> I] [B<-lon>] [B<-h>] - -=head1 DESCRIPTION - -The C command reports whether the B log is available -for use. If the B<-long> argument is included, the output reports the -log's defined size, and whether that amount of space is currently -allocated in kernel memory or not. - -To change the B trace log's size, use the C command. -To display or set whether space is allocated for it in kernel memory, -use the C or C command to display or set the -state of the corresponding B event set, respectively. - -=head1 OPTIONS - -=over 4 - -=item B<-set> I [I ...] - -Names the event set for which to display information about the -corresponding trace log. The only acceptable value is B (for -which the associated trace log is B). Provide either this -argument or the B<-log> argument, or omit both to display -information about the B log by default. - -=item B<-log> I - -Names the trace log about which to report. The only acceptable -value is B. Provide either this argument or the B<-set> -argument, or omit both to report on the B log by default. - -=item B<-long> - -Reports the defined size of the log in kilobyte units and -whether that amount of space is currently allocated in kernel -memory. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -By default, the C command displays only the name of the -available log, B, in the following format: - - Available logs: - cmfx - -When the B<-long> flag is included, the output also reports the defined -size of the log in kilobytes, and whether or not that amount of space -is currently allocated in kernel memory, in the following format: - - Available logs: - cmfx : log_size kbytes (allocated | unallocated) - -The C state indicates that the indicated number of kilobytes -is reserved for the B trace log in kernel memory. The B event -set's state is either active or inactive, as reported by the C command, and set by the C command's B<-active> or -B<-inactive> flags respectively. - -The C state indicates that no kernel memory is currently -reserved for the B trace log. The B event set's state is dormant, -as reported by the C command and set by the C -command's B<-dormant> flag. If the event set's state is later changed to -active or inactive, the number of kilobytes indicated as I are -again allocated in kernel memory. - -=head1 EXAMPLES - -The following example uses the -long flag to display information about -the B log: - - fstrace lslog -log cmfx -long - Available logs: - cmfx : 60 kbytes (allocated) - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_lsset.pod b/doc/man-pages/pod/fstrace_lsset.pod deleted file mode 100644 index 18dc096bc6..0000000000 --- a/doc/man-pages/pod/fstrace_lsset.pod +++ /dev/null @@ -1,90 +0,0 @@ -=head1 NAME - -fstrace lsset - Reports the status of an event set - -=head1 SYNOPSIS - -fstrace lsset [B<-set> I [I ...]] [B<-help>] - -fstrace lss [B<-s> I [I ...]] [B<-h>] - -=head1 DESCRIPTION - -The C command displays a list of the available event sets -and reports their current status (active, inactive, or dormant). - -To change an event set's status, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-set> I [I ...] - -Names the event set for which to display the status. The only -acceptable value is B, which is also the default if this -argument is omitted. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output lists the available event sets and the status of each, in -the following format: - - Available sets: - cm {active | inactive | dormant} - -where - -=over - -=item B - -Indicates that tracing is enabled for the event set, and kernel -memory allocated for the corresponding trace log. - -=item B - -Indicates that tracing is temporarily disabled for the event -set, but kernel memory still allocated for the corresponding -trace log. - -=item B - -Indicates that tracing is disabled for the event set, and no -kernel memory allocated for the corresponding trace log. - -=back - -=head1 EXAMPLES - -The following example displays the available event set and its status: - - fstrace lsset - Available sets: - cm active - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_setlog.pod b/doc/man-pages/pod/fstrace_setlog.pod deleted file mode 100644 index a44d94eacf..0000000000 --- a/doc/man-pages/pod/fstrace_setlog.pod +++ /dev/null @@ -1,74 +0,0 @@ -=head1 NAME - -fstrace setlog - Sets the size of a trace log - -=head1 SYNOPSIS - -fstrace setlog [B<-log> I [I ...]] B<-buffersize> I<1-kilobyte_units> [B<-help>] - -fstrace setl [B<-l> I [I ...]] B<-b> I<1-kilobyte_units> [B<-h>] - -fstrace sl [B<-l> I [I ...]] B<-b> I<1-kilobyte_units> [B<-h>] - -=head1 DESCRIPTION - -The C command defines the number of kilobytes of kernel -memory allocated for the B trace log. If kernel memory is currently -allocated, the command clears the current log and creates a new log -buffer of the specified size. - -To display the current defined size of the log buffer, issue the -C command with the B<-long> argument. To control whether the -indicated amount of space is actually allocated, use the C command to set the status of the cm event set; to display the -event set's status, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-log> I [I ...] - -Names trace log for which to set the size. The only acceptable -value is B, which is also the default if this argument is -omitted. - -=item B<-buffersize> I<1-kilobyte_units> - -Specifies the number of 1-kilobyte blocks of kernel memory to -allocate for the trace log. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following command allocated 80 KB of kernel memory for the B -trace log: - - fstrace setlog -log cmfx -buffersize 80 - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/fstrace_setset.pod b/doc/man-pages/pod/fstrace_setset.pod deleted file mode 100644 index db392cf389..0000000000 --- a/doc/man-pages/pod/fstrace_setset.pod +++ /dev/null @@ -1,79 +0,0 @@ -=head1 NAME - -fstrace setset - Sets the status of an event set - -=head1 SYNOPSIS - -fstrace setset [B<-set> I [I ...]] [B<-active>] [B<-inactive>] [B<-dormant>] [B<-help>] - - -fs set [B<-s> I [I ...]] [B<-a>] [B<-i>] [B<-d>] [B<-h>] - -=head1 DESCRIPTION - -The C command sets the status of the B kernel event set -on the local machine, which determines whether trace messages are -recorded in the log buffer in kernel memory. - -=head1 OPTIONS - -=over 4 - -=item B<-set> I [I ...] - -Names the event set for which to set the status. The only -acceptable value is B, which is also the default if this argument -is omitted. - -=item B<-active> - -Enables tracing for the event set and allocates kernel memory -for the associated trace log buffer. Provide one of this flag, -the B<-inactive> flag, or the B<-dormant> flag. - -=item B<-inactive> - -Temporarily disables tracing for the event set, but does not -change the allocation of kernel memory for the associated trace -log buffer. Provide one of this flag, the B<-active> flag, or the -B<-dormant> flag. - -=item B<-dormant> - -Disables tracing for the event set and frees the kernel memory -previously allocated for the associated trace log buffer. -Provide one of this flag, the B<-active> flag, or the B<-inactive> -flag. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following example sets the B event set's status to B: - - fstrace setset -set cm -inactive - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/kadb_check.pod b/doc/man-pages/pod/kadb_check.pod deleted file mode 100644 index f4c9b8f797..0000000000 --- a/doc/man-pages/pod/kadb_check.pod +++ /dev/null @@ -1,102 +0,0 @@ -=head1 NAME - -kadb_check - Checks the integrity of the Authentication Database - -=head1 SYNOPSIS - -kadb_check B<-database> I [B<-uheader>] [B<-kheader>] [B<-entries>] -[B<-verbose>] [B<-rebuild> I] [B<-help>] - -kadb_check B<-d> I [B<-u>] [B<-k>] [B<-e>] [B<-v>] [B<-r> I] [B<-h>] - -=head1 DESCRIPTION - -The C command checks the integrity of the Protection -Database, reporting any errors or corruption it finds. If there are -problems, do not issue any C commands until the database is -repaired. - -=head1 OPTIONS - -=over 4 - -=item B<-database> I - -Names the Authentication Database (copy of the B -file) to check. If the current working directory is not the -location of the file, provide a pathname, either full or -relative to the current working directory. - -=item B<-uheader> - -Displays information which Ubik maintains in the database's -header. - -=item B<-kheader> - -Displays information which the Authentication Server maintains -in the database's header. - -=item B<-entries> - -Outputs every entry in the database, providing information -similar to that returned by the C command. - -=item B<-verbose> - -Reports additional information about the database, including -the number of free (allocated but unused) entries in the -database. - -=item B<-rebuild> I - -Names the file in which to record a list of C commands which, -if issued in the command shell, recreate the current state of -the database being verified. Partial pathnames are interpreted -relative to the current working directory. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -If there are errors in the database, the output always reports them on -the standard error stream. If any options other than B<-database> or -B<-help> are provided, the output written to the standard output stream -includes additional information as described for each option in the -preceding L section of this reference page. The output is -intended for debugging purposes and is meaningful to someone familiar -with the internal structure of the Authentication Database. - -=head1 PRIVILEGE REQUIRED - -The issuer must be logged in as the local superuser B. - -=head1 CAVEATS - -The results can be unpredictable if the Authentication Server makes -changes to the Authentication Database while this command is running. -Use the C command to shutdown the local B process -before running this command, or before creating a second copy of the -B file (with a different name) on which to run the command. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -kaserver.DB0 and kaserver.DBSYS1, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/kas.pod b/doc/man-pages/pod/kas.pod deleted file mode 100644 index bddd681771..0000000000 --- a/doc/man-pages/pod/kas.pod +++ /dev/null @@ -1,214 +0,0 @@ -=head1 NAME - -kas - Introduction to the C command suite - -=head1 DESCRIPTION - -The commands in the C command suite are the administrative interface -to the Authentication Server, which runs on each database server -machine in a cell, maintains the Authentication Database, and provides -the authentication tickets that client applications must present to -AFS servers in order to obtain access to AFS data and other services. - -There are several categories of commands in the C command suite: - -=over - -=item * - -Commands to create, modify, examine and delete entries in the -Authentication Database, including passwords: C, C, C, C, C, C, C, and C - -=item * - -Commands to create, delete, and examine tokens and server tickets: -C, C, C, and C - -=item * - -A command to enter interactive mode: C - -=item * - -A command to trace Authentication Server operations: C - -=item * - -Commands to obtain help: C and C - -=back - -Because of the sensitivity of information in the Authentication -Database, the Authentication Server authenticates issuers of C -commands directly, rather than accepting the standard token generated -by the Ticket Granting Service. Any C command that requires -administrative privilege prompts the issuer for a password. The -resulting ticket is valid for six hours unless the maximum ticket -lifetime for the issuer or the Authentication Server's Ticket Granting -Service is shorter. - -To avoid having to provide a password repeatedly when issuing a -sequence of C commands, enter I by issuing the C command, typing C without any operation code, or typing -C followed by a user and cell name, separated by an at-sign (@; an -example is C). After prompting once for a -password, the Authentication Server accepts the resulting token for -every command issued during the interactive session. See the reference -page for the C command for a discussion of when to use -each method for entering interactive mode and of the effects of -entering a session. - -The Authentication Server maintains two databases on the local disk of -the machine where it runs: - -=over - -=item * - -The Authentication Database (B) stores the -information used to provide AFS authentication services to users -and servers, including the password scrambled as an encryption -key. The reference page for the C command describes the -information in a database entry. - -=item * - -An auxiliary file (B by default) that tracks -how often the user has provided an incorrect password to the local -Authentication Server. The reference page for the C -command describes how the Authentication Server uses this file to -enforce the limit on consecutive authentication failures. To -designate an alternate directory for the file, use the C -command's B<-localfiles> argument. - -=back - -=head1 OPTIONS - -The following arguments and flags are available on many commands in -the C suite. (Some of them are unavailable on commands entered in -interactive mode, because the information they specify is established -when entering interactive mode and cannot be changed except by leaving -interactive mode.) The reference page for each command also lists -them, but they are described here in greater detail. - -=over 4 - -=item B<-admin_username> - -Specifies the user identity under which to authenticate with -the Authentication Server for execution of the command. If this -argument is omitted, the C command interpreter requests -authentication for the identity under which the issuer is -logged onto the local machine. Do not combine this argument -with the B<-noauth> flag. - -=item B<-cell> I - -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 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 file - -=back - -The B<-cell> argument is not available on commands issued in -interactive mode. The cell defined when the C command -interpreter enters interactive mode applies to all commands -issued during the interactive session. - -=item B<-help> - -Prints a command's online help message on the standard output -stream. Do not combine this flag with any of the command's -other options; when it is provided, the command interpreter -ignores all other options, and only prints the help message. - -=item B<-noauth> - -Establishes an unauthenticated connection to the Authentication -Server, in which the Authentication Server treats the issuer as -the unprivileged user B. It is useful only when -authorization checking is disabled on the server machine -(during the installation of a server machine or when the C command has been used during other unusual -circumstances). In normal circumstances, the Authentication -Server allows only privileged users to issue most C commands, -and refuses to perform such an action even if the B<-noauth> flag -is provided. Do not combine this flag with the B<-admin_username> -and B<-password_for_admin> arguments. - -=item B<-password_for_admin> - -Specifies the password of the command's issuer. It is best to -omit this argument, which echoes the password visibly in the -command shell, instead enter the password at the prompt. Do not -combine this argument with the B<-noauth> flag. - -=item B<-servers> - -Establishes a connection with the Authentication Server running -on each specified database server machine, instead of on each -machine listed in the local B file. In -either case, the C command interpreter then chooses one of -the machines at random to contact for execution of each -subsequent command. The issuer can abbreviate the machine name -to the shortest form that allows the local name service to -identify it uniquely. - -=back - -=head1 PRIVILEGE REQUIRED - -To issue most C commands, the issuer must have the C flag set in -his or her Authentication Database entry (use the C -command to turn the flag on). - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L and L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/kas_apropos.pod b/doc/man-pages/pod/kas_apropos.pod deleted file mode 100644 index f3406a6102..0000000000 --- a/doc/man-pages/pod/kas_apropos.pod +++ /dev/null @@ -1,69 +0,0 @@ -=head1 NAME - -kas apropos - Displays each help entry containing a keyword string - -=head1 SYNOPSIS - -kas apropos B<-topic> I [B<-help>] - -kas a B<-t> I [B<-h>] - -=head1 DESCRIPTION - -The C command displays the first line of the online help -entry for any C command that has the string specified by the B<-topic> -argument in its name or short description. - -To display the syntax for a command, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-topic> I - -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 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 commands that include the word B -in their names or short descriptions: - - kas apropos key - setkey: set a user's key - stringtokey: convert a string to a key - -=head1 PRIVILEGE REQUIRED - -None, and no password is required. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/kas_create.pod b/doc/man-pages/pod/kas_create.pod deleted file mode 100644 index 1da1b5b9f9..0000000000 --- a/doc/man-pages/pod/kas_create.pod +++ /dev/null @@ -1,125 +0,0 @@ -=head1 NAME - -kas create - Creates an entry in the Authentication Database - -=head1 SYNOPSIS - -kas create S I> -S<[B<-initial_password> I]> -S<[B<-admin_username> I]> -S<[B<-password_for_admin> I]> -S<[B<-cell> I]> -S<[B<-servers> I ...]> -[B<-noauth>] [B<-help>] - -kas c B<-na> I S<[B<-i> I]> -S<[B<-a> I]> -S<[B<-p> I]> S<[B<-c> I]> -S<[B<-s> I ...]> [B<-no>] [B<-h>] - -=head1 DESCRIPTION - -The C command creates an entry in the Authentication Database -for the user named by the B<-name> argument. - -To avoid having the account's initial password echo visibly at the -shell prompt, omit the B<-initial_password> argument; the command -interpreter prompts for the password and does not echo it visibly. -Whether or not B<-initial_password> is omitted, the Authentication Server -converts the password into a form suitable for use as an encryption -key, and records it in the entry's key field. - -To alter settings in an Authentication Database entry, use the C command. To examine an entry, use the C command. -To list every entry in the database, use the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-name> I - -Names the new Authentication Database entry. Because it is the -name under which the user logs in, it must obey the -restrictions that many operating systems impose on user names -(usually, to contain no more than eight lowercase letters). - -=item B<-initial_password> I - -Sets the user's password; provide a character string that can -include uppercase and lowercase letters, numerals and -punctuation. The Authentication Server scrambles the string -into an octal string suitable for use as an encryption key -before placing it in the entry's key field. If this argument is -omitted, the command interpreter prompts for the string and -does not echo it visibly. - -=item B<-admin_username> I - -Specifies the user identity under which to authenticate with -the Authentication Server for execution of the command. For -more details, see the introductory L reference page. - -=item B<-password_for_admin> I - -Specifies the password of the command's issuer. If it is -omitted (as recommended), the C command interpreter prompts -for it and does not echo it visibly. For more details, see the -introductory L reference page. - -=item B<-cell> I - -Names the cell in which to run the command. For more details, -see the introductory L reference page. - -=item B<-servers> I ... - -Names each machine running an Authentication Server with which -to establish a connection. For more details, see the -introductory L reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. For -more details, see the introductory L reference page. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following example shows the prompts that appear when an -administrator logged in as B creates an Authentication Database -entry for the user B, and does not include either the -B<-initial_password> or B<-password_for_admin arguments>. - - kas create smith - Password for admin: - initial_password: - Verifying, please re-enter initial_password: - -=head1 PRIVILEGE REQUIRED - -The issuer must have the C flag set on his or her Authentication -Database entry. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/kas_delete.pod b/doc/man-pages/pod/kas_delete.pod deleted file mode 100644 index 05195e4655..0000000000 --- a/doc/man-pages/pod/kas_delete.pod +++ /dev/null @@ -1,102 +0,0 @@ -=head1 NAME - -kas delete - Deletes an entry from the Authentication Database - -=head1 SYNOPSIS - -kas delete B<-name> I -S<[B<-admin_username> I]> -S<[B<-password_for_admin> I]> S<[B<-cell> I]> -S<[B<-servers> I ...]> -[B<-noauth>] [B<-help>] - -kas d B<-na> I [B<-a> I] -[B<-p> I] [B<-c> I] -[B<-s> I ...] [B<-no>] [B<-h>] - -kas rm B<-na> I [B<-a> I] -[B<-p> I] [B<-c> I] -[B<-s> I ...] [B<-no>] [B<-h>] - -=head1 DESCRIPTION - -The C command removes from the Authentication Database the -user entry named by the B<-name> argument. The indicated user becomes -unable to log in, or the indicated server becomes unreachable (because -the Authentication Server's Ticket Granting Service module no longer -has a key with which to seal tickets for the server). - -=head1 OPTIONS - -=over 4 - -=item B<-name> I - -Names the Authentication Database entry to delete. - -=item B<-admin_username> I - -Specifies the user identity under which to authenticate with -the Authentication Server for execution of the command. For -more details, see the introductory L reference page. - -=item B<-password_for_admin> I - -Specifies the password of the command's issuer. If it is -omitted (as recommended), the C command interpreter prompts -for it and does not echo it visibly. For more details, see the -introductory L reference page. - -=item B<-cell> I - -Names the cell in which to run the command. For more details, -see the introductory L reference page. - -=item B<-servers> I ... - -Names each machine running an Authentication Server with which -to establish a connection. For more details, see the -introductory L reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. For -more details, see the introductory L reference page. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 EXAMPLES - -The following example shows the administrative user B entering -interactive mode to delete three accounts. - - kas - Password for admin: - ka> delete smith - ka> delete pat - ka> delete terry - -=head1 PRIVILEGE REQUIRED - -The issuer must have the C flag set on his or her Authentication -Database entry. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -and Elizabeth Cassell , 2004, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/kas_examine.pod b/doc/man-pages/pod/kas_examine.pod deleted file mode 100644 index 254256fc80..0000000000 --- a/doc/man-pages/pod/kas_examine.pod +++ /dev/null @@ -1,308 +0,0 @@ -=head1 NAME - -kas examine - Displays information from an Authentication Database entry - -=head1 SYNOPSIS - -kas examine B<-name> I [B<-showkey>] -[B<-admin_username> I] -[B<-password_for_admin> I] [B<-cell> I] -[B<-servers> I ...] -[B<-noauth>] [B<-help>] - -kas e B<-na> I [B<-sh>] -[B<-a> I] -[B<-p> I] [B<-c> I] -[B<-se> I ...] [B<-no>] [B<-h>] - -=head1 DESCRIPTION - -The C command formats and displays information from the -Authentication Database entry of the user named by the B<-name> argument. - -To alter the settings displayed with this command, issue the C command. - -=head1 OPTIONS - -=over 4 - -=item B<-name> I - -Names the Authentication Database entry from which to display -information. - -=item B<-showkey> - -Displays the octal digits that constitute the key. The issuer -must have the C flag on his or her Authentication Database -entry. - -=item B<-admin_username> I - -Specifies the user identity under which to authenticate with -the Authentication Server for execution of the command. For -more details, see the introductory L reference page. - -=item B<-password_for_admin> I - -Specifies the password of the command's issuer. If it is -omitted (as recommended), the C command interpreter prompts -for it and does not echo it visibly. For more details, see the -introductory L reference page. - -=item B<-cell> I - -Names the cell in which to run the command. For more details, -see the introductory L reference page. - -=item B<-servers> I ... - -Names each machine running an Authentication Server with which -to establish a connection. For more details, see the -introductory L reference page. - -=item B<-noauth> - -Assigns the unprivileged identity B to the issuer. For -more details, see the introductory L reference page. - -=item B<-help> - -Prints the online help for this command. All other valid -options are ignored. - -=back - -=head1 OUTPUT - -The output includes: - -=over - -=item * - -The entry name, following the string C. - -=item * - -One or more status flags in parentheses; they appear only if an -administrator has used the C command to change them -from their default values. A plus sign (+) separates the flags if -there is more than one. The nondefault values that can appear, and -their meanings, are as follows: - -=over - -=item B - -Enables the user to issue privileged C commands -(default is C) - -=item B - -Prevents the user from obtaining tickets from the -Authentication Server's Ticket Granting Service (default -is C) - -=item B - -Prevents the Ticket Granting Service from using the -entry's key field as an encryption key (default is C) - -=item B - -Prevents the user from changing his or her password -(default is C) - -=back - -=item * - -The key version number, in parentheses, following the word C, -then one of the following. - -=over - -=item * - -A checksum equivalent of the key, following the string C, if the B<-showkey> flag is not included. The checksum is a -decimal number derived by encrypting a constant with the key. -In the case of the B entry, this number must match the -checksum with the corresponding key version number in the -output of the C command; if not, follow the -instructions in the IBM AFS Administration Guide for creating -a new server encryption key. - -=item * - -The actual key, following a colon, if the B<-showkey> flag is -included. The key consists of eight octal numbers, each -represented as a backslash followed by three decimal digits. - -=back - -=item * - -The date the user last changed his or her own password, following -the string C (which stands for "last change of password"). - -=item * - -The string C indicates that the -associated password never expires; the string C -is followed by the password's expiration date. After the indicated -date, the user cannot authenticate, but has 30 days after it in -which to use the C or C command to set a new -password. After 30 days, only an administrator (one whose account -is marked with the C flag) can change the password by using -the C command. To set the password expiration date, -use the C command's B<-pwexpires> argument. - -=item * - -The number of times the user can fail to provide the correct -password before the account locks, followed by the string -C, or the -string C to indicate that there is no limit. To set the limit, -use the C command's B<-attempts> argument. To unlock a -locked account, use the C command. The L -reference page discusses how the implementation of the lockout -feature interacts with this setting. - -=item * - -The number of minutes for which the Authentication Server refuses -the user's login attempts after the limit on consecutive -unsuccessful authentication attempts is exceeded, following the -string C. Use the C command's -B<-locktime> argument to set the lockout time. This line appears only -if a limit on the number of unsuccessful authentication attempts -has been set with the the C command's B<-attempts> -argument. - -=item * - -An indication of whether the Authentication Server is currently -refusing the user's login attempts. The string C -indicates that authentication can succeed, whereas the string C I
for day, and I for year) and an optional -portion (I for hours and I for minutes). - -Omit the I:I 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] [IB] [IB] [IB] - -where the optional word B is followed by at least one of a -number of years (maximum B<9999>) followed by the letter B, a -number of months (maximum B<12>) followed by the letter B, or a -number of days (maximum B<31>) followed by the letter B. 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: - -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 file. The C 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 -reference page. - - -=item B<-cell> I - -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 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 with a relative -expiration date of one year: - - backup adddump -dump /1999 -expires in 1y - -The following command defines an incremental dump called -B 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 and B. Their parent, the full dump level -B, 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_addhost.pod b/doc/man-pages/pod/backup_addhost.pod deleted file mode 100644 index 108d96a3f2..0000000000 --- a/doc/man-pages/pod/backup_addhost.pod +++ /dev/null @@ -1,118 +0,0 @@ -=head1 NAME - -backup addhost - Adds a Tape Coordinator entry to the Backup Database - -=head1 SYNOPSIS - -backup addhost B<-tapehost> I [B<-portoffset> I] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup addh B<-t> I [B<-p> I] -[B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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) 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 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 command. - -=head1 OPTIONS - -=over 4 - -=item B<-tapehost> I - -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 -or equivalent) on the machine where the command is issued. - -=item B<-portoffset> I - -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 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. The C 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 reference page. - -=item B<-cell> I - -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 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: - - 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: - - backup addhost backup3.abc.com - -=head1 PRIVILEGE REQUIRED - -The issuer must be listed in the B file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_addvolentry.pod b/doc/man-pages/pod/backup_addvolentry.pod deleted file mode 100644 index 5839881d76..0000000000 --- a/doc/man-pages/pod/backup_addvolentry.pod +++ /dev/null @@ -1,203 +0,0 @@ -=head1 NAME - -backup addvolentry - Defines a volume entry in a volume set - -=head1 SYNOPSIS - -backup addvolentry B<-name> I B<-server> I -B<-partition> I -B<-volumes> I -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup addvole B<-n> I B<-s> I B<-p> I -B<-v> I -[B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 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 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) 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) 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 or B or -B, but not B or B. 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 the characters that follow it; for -example, B<[^a]> matches any single character except -lowercase B. 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 and ends with B: - -B - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 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 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. The entry matches all volumes on any machine or partition whose -names begin with the string B 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_addvolset.pod b/doc/man-pages/pod/backup_addvolset.pod deleted file mode 100644 index 7c86bc68d0..0000000000 --- a/doc/man-pages/pod/backup_addvolset.pod +++ /dev/null @@ -1,114 +0,0 @@ -=head1 NAME - -backup addvolset - Creates a new (empty) volume set - -=head1 SYNOPSIS - -backup addvolset B<-name> I [B<-temporary>] -[B<-localauth>] [B<-cell> I] [B<-help>] - -backup addvols B<-n> I [B<-t>] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 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 command to restore a group of volumes that were -not necessarily backed up together. To create a I 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 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 command to delete it before -that. - -One advantage of temporary volume sets is that the C -command, and any C 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 - -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 file. The C 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 reference page. - - -=item B<-cell> I - -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 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_apropos.pod b/doc/man-pages/pod/backup_apropos.pod deleted file mode 100644 index ac694967e9..0000000000 --- a/doc/man-pages/pod/backup_apropos.pod +++ /dev/null @@ -1,72 +0,0 @@ -=head1 NAME - -backup apropos - Displays each help entry containing a keyword string - -=head1 SYNOPSIS - -backup apropos B<-topic> I [B<-help>] - -backup ap B<-t> I [B<-h>] - -=head1 DESCRIPTION - -The C command displays the first line of the online help -entry for any C 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 command. - -=head1 OPTIONS - -=over 4 - - -=item B<-topic> I - -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 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 commands that include the word -B 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. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_dbverify.pod b/doc/man-pages/pod/backup_dbverify.pod deleted file mode 100644 index e089b76efa..0000000000 --- a/doc/man-pages/pod/backup_dbverify.pod +++ /dev/null @@ -1,144 +0,0 @@ -=head1 NAME - -backup dbverify - Checks the integrity of the Backup Database - -=head1 SYNOPSIS - -backup dbverify [B<-detail>] [B<-localauth>] [B<-cell> I] [B<-help>] - -backup db [B<-d>] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 file. The C 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 reference page. - -=item B<-cell> I - -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 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 - -The database is undamaged and can be used. - -=item B - -The database is damaged. You can use the C 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 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 command, and then restore it by using -the C 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 file on the indicated machine. You can use -the C 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 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B 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 command repairs some types of -corruption. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_deldump.pod b/doc/man-pages/pod/backup_deldump.pod deleted file mode 100644 index bbd8c065f9..0000000000 --- a/doc/man-pages/pod/backup_deldump.pod +++ /dev/null @@ -1,78 +0,0 @@ -=head1 NAME - -backup deldump - Deletes a dump level from the Backup Database - -=head1 SYNOPSIS - -backup deldump B<-dump> I [B<-localauth>] -[B<-cell> I] [B<-help>] - -backup deld B<-d> I [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C command deletes the indicated dump level and all of -its child dump levels from the dump hierarchy in the Backup Database. -Use the C command to display the dump hierarchy. - -=head1 OPTIONS - -=over 4 - - -=item B<-dump> I - -Specifies the complete pathname of the dump level to delete. - - -=item B<-localauth> - -Constructs a server ticket using a key from the local -B file. The C 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 reference page. - - -=item B<-cell> I - -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 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 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 file on every -machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the B<-localauth> flag is -included. - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -Converted from html to pod by Alf Wachsmann , 2003, -Stanford Linear Accelerator Center, a department of Stanford University. - -=head1 SEE ALSO - -L, -L, -L - -=cut diff --git a/doc/man-pages/pod/backup_deletedump.pod b/doc/man-pages/pod/backup_deletedump.pod deleted file mode 100644 index ad3fff33db..0000000000 --- a/doc/man-pages/pod/backup_deletedump.pod +++ /dev/null @@ -1,212 +0,0 @@ -=head1 NAME - -backup deletedump - Deletes one or more dump records from the Backup Database - -=head1 SYNOPSIS - -backup deletedump [B<-dumpid> I [I ...]] [B<-from> I ...] -[B<-to> I ...] [B<-localauth>] [B<-cell> I] [B<-help>] - -backup dele [B<-d> I [I ...]] [B<-f> I [I ...]] -[B<-t> I [I ...]] [B<-l>] [B<-c> I] [B<-h>] - -=head1 DESCRIPTION - -The C 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 [I ...] - -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 command). - -Provide either this argument or the B<-to> (and optionally B<-from>) -argument. - -=item B<-from> I ... - -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/I