Index: openafs/doc/man-pages/Makefile.in diff -c /dev/null openafs/doc/man-pages/Makefile.in:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/Makefile.in Sat Oct 15 11:04:27 2005 *************** *** 0 **** --- 1,199 ---- + # Makefile for AFS man pages + + srcdir=@srcdir@ + include @TOP_OBJDIR@/src/config/Makefile.config + + MAN1 = \ + afs_intro.1 \ + fs.1 \ + fs_apropos.1 \ + fs_checkservers.1 \ + fs_checkvolumes.1 \ + fs_cleanacl.1 \ + fs_copyacl.1 \ + fs_diskfree.1 \ + fs_examine.1 \ + fs_exportafs.1 \ + fs_flush.1 \ + fs_flushmount.1 \ + fs_flushvolume.1 \ + fs_getcacheparms.1 \ + fs_getcellstatus.1 \ + fs_getclientaddrs.1 \ + fs_getserverprefs.1 \ + fs_help.1 \ + fs_listacl.1 \ + fs_listcells.1 \ + fs_listquota.1 \ + fs_lsmount.1 \ + fs_messages.1 \ + fs_mkmount.1 \ + fs_newcell.1 \ + fs_quota.1 \ + fs_rmmount.1 \ + fs_setacl.1 \ + fs_setcachesize.1 \ + fs_setcell.1 \ + fs_setclientaddrs.1 \ + fs_setquota.1 \ + fs_setserverprefs.1 \ + fs_setvol.1 \ + fs_storebehind.1 \ + fs_sysname.1 \ + fs_whereis.1 \ + fs_whichcell.1 \ + fs_wscell.1 \ + klog.1 \ + kpasswd.1 \ + kpwvalid.1 \ + pts.1 \ + pts_adduser.1 \ + pts_apropos.1 \ + pts_chown.1 \ + pts_creategroup.1 \ + pts_createuser.1 \ + pts_delete.1 \ + pts_examine.1 \ + pts_help.1 \ + pts_listentries.1 \ + pts_listmax.1 \ + pts_listowned.1 \ + pts_membership.1 \ + pts_removeuser.1 \ + pts_rename.1 \ + pts_setfields.1 \ + pts_setmax.1 + + MAN8 = \ + afsd.8 \ + afsmonitor.8 \ + backup.8 \ + backup_adddump.8 \ + backup_addhost.8 \ + backup_addvolentry.8 \ + backup_addvolset.8 \ + backup_apropos.8 \ + backup_dbverify.8 \ + backup_deldump.8 \ + backup_deletedump.8 \ + backup_delhost.8 \ + backup_delvolentry.8 \ + backup_delvolset.8 \ + backup_diskrestore.8 \ + backup_dump.8 \ + backup_dumpinfo.8 \ + backup_help.8 \ + backup_interactive.8 \ + backup_jobs.8 \ + backup_kill.8 \ + backup_labeltape.8 \ + backup_listdumps.8 \ + backup_listhosts.8 \ + backup_listvolsets.8 \ + backup_quit.8 \ + backup_readlabel.8 \ + backup_restoredb.8 \ + backup_savedb.8 \ + backup_scantape.8 \ + backup_setexp.8 \ + backup_status.8 \ + backup_volinfo.8 \ + backup_volrestore.8 \ + backup_volsetrestore.8 \ + bos.8 \ + bos_addhost.8 \ + bos_addkey.8 \ + bos_adduser.8 \ + bos_apropos.8 \ + bos_create.8 \ + bos_delete.8 \ + bos_exec.8 \ + bos_getdate.8 \ + bos_getlog.8 \ + bos_getrestart.8 \ + bos_help.8 \ + bos_install.8 \ + bos_listhosts.8 \ + bos_listkeys.8 \ + bos_listusers.8 \ + bos_prune.8 \ + bos_removehost.8 \ + bos_removekey.8 \ + bos_removeuser.8 \ + bos_restart.8 \ + bos_salvage.8 \ + bos_setauth.8 \ + bos_setcellname.8 \ + bos_setrestart.8 \ + bos_shutdown.8 \ + bos_start.8 \ + bos_startup.8 \ + bos_status.8 \ + bos_stop.8 \ + bos_uninstall.8 \ + bosserver.8 \ + buserver.8 \ + butc.8 \ + dlog.8 \ + dpass.8 \ + fileserver.8 \ + fms.8 \ + fstrace.8 \ + fstrace_apropos.8 \ + fstrace_clear.8 \ + fstrace_dump.8 \ + fstrace_help.8 \ + fstrace_lslog.8 \ + fstrace_lsset.8 \ + fstrace_setlog.8 \ + fstrace_setset.8 \ + kadb_check.8 \ + kas.8 \ + kas_apropos.8 \ + kas_create.8 \ + kas_delete.8 \ + kas_examine.8 \ + kas_forgetticket.8 \ + kas_help.8 \ + kas_interactive.8 \ + kas_list.8 \ + kas_listtickets.8 \ + kas_noauthentication.8 \ + kas_quit.8 \ + kas_setfields.8 \ + kas_setpassword.8 \ + kas_statistics.8 \ + kas_stringtokey.8 \ + kas_unlock.8 \ + kaserver.8 \ + kdb.8 \ + knfs.8 + + all: $(MAN1) $(MAN8) + + %.1: $(srcdir)/pod/%.pod + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 $< $@ + + %.8: $(srcdir)/pod/%.pod + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 $< $@ + + clean: + rm -f *.1 *.8 + + dest: $(MAN1) $(MAN8) + mkdir -p $(DEST)/man/man1 $(DEST)/man/man8 + set -e; for M in $(MAN1) ; do \ + $(INSTALL) -c -m 0644 $$M $(DEST)/man/man1/$$M ; \ + done + set -e; for M in $(MAN8) ; do \ + $(INSTALL) -c -m 0644 $$M $(DEST)/man/man8/$$M ; \ + done + + install: $(MAN1) $(MAN8) + mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man8 + set -e; for M in $(MAN1) ; do \ + $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man1/$$M ; \ + done + set -e; for M in $(MAN8) ; do \ + $(INSTALL) -c -m 0644 $$M $(DESTDIR)$(mandir)/man8/$$M ; \ + done Index: openafs/doc/man-pages/generate-pod diff -c /dev/null openafs/doc/man-pages/generate-pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/generate-pod Sat Oct 15 11:04:27 2005 *************** *** 0 **** --- 1,178 ---- + #!/usr/bin/perl -w + # + # Parser for files obtained via + # lynx --dump http://www.openafs.org/pages/doc/AdminReference/auarf174.htm > fstrace_lslog.txt + + use strict; + my $DEBUG = 0; + my $RAW = 0; + + my %hash; + my %options; + + ###################################################################### + ## Input Section: + ###################################################################### + + my $del = $/; + undef $/; + my $text = ; + $/ = $del; + + my $sections = 'Purpose|Synopsis|Description|Cautions|Options|Output|Examples|Privilege\ Required|Related\ Information|References'; + + $text =~ s/^.*\[7\]\s*(.+?)\n//xs; + + $hash{Command} = $1; + my $Cmd_fam = "backup|bos|fs|kas|pts|uss|vos"; + $Cmd_fam .= '|' . (split(" ", $hash{Command}))[0]; + + while ($text !~ /^\s+$/xs) { + $text =~ s/($sections)(.*?)(\n\s*(?:$sections)\n\s*|$)/$3/xs; + $hash{$1} = $2; + } + + $hash{'Related Information'} =~ s/\s*(.+?)\s*___________.*$/$1/xs; + + + + if (! $RAW) { + ###################################################################### + ## Clean-up Section: + ###################################################################### + + # make C 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} = ""; + } + } + + $hash{Options} =~ s/(?:\n|^)B<([^>]*?)>\ \n/\n=item B<$1>$options{$1}\n\n/sxg if ($hash{Options}); + + $hash{Examples} =~ s/\n\s*%(.*?)(?:\n|$)/\n\nB<\ \ \ $1>\n/sxg if ($hash{Examples}); + + $hash{'Related Information'} =~ s/\[\d+\](.*?)\s*\n/L<$1(1)>,\n/msxg if ($hash{'Related Information'}); + $hash{'Related Information'} =~ s/\[\d+\](.*)\s*/L<$1(1)>/msxg if ($hash{'Related Information'}); + $hash{'Related Information'} =~ s/(\w+)\s+(\w+)/$1_$2/msxg if ($hash{'Related Information'}); + + foreach (keys(%hash)) { + $hash{$_} =~ s/((?:\n\n=item\ \*\n(?:\n.+$)+)+)/\n\n=over$1\n\n=back/mxg; + } + + + }; + + + ###################################################################### + ## Output Section: + ###################################################################### + + my $file; + ($file = $hash{Command} . ".pod") =~ s/\s/_/g; + + my $FH; + if ($DEBUG) { + $FH = *STDOUT + } else { + open(FILE, "> $file") || die("Could not open $file\n"); + $FH = *FILE; + } + + print $FH "=head1 NAME\n\n"; + print $FH "$hash{Command} - $hash{Purpose}\n\n"; + + if (exists $hash{Synopsis}) { + print $FH "=head1 SYNOPSIS\n\n"; + print $FH "$hash{Synopsis}\n\n"; + } + + print $FH "=head1 DESCRIPTION\n\n"; + print $FH "$hash{Description}\n\n"; + + if (exists $hash{Options}) { + print $FH "=head1 OPTIONS\n\n"; + print $FH "=over 4\n"; + print $FH "$hash{Options}\n\n"; + print $FH "=back\n\n"; + } + + if (exists $hash{Output}) { + print $FH "=head1 OUTPUT\n\n"; + print $FH "$hash{Output}\n\n"; + } + + if (exists $hash{Examples}) { + print $FH "=head1 EXAMPLES\n\n"; + print $FH "$hash{Examples}\n\n"; + } + + if (exists $hash{'Privilege Required'}) { + print $FH "=head1 PRIVILEGE REQUIRED\n\n"; + print $FH "$hash{'Privilege Required'}\n\n"; + } + + if (exists $hash{Cautions}) { + print $FH "=head1 CAVEATS\n\n"; + print $FH "$hash{Cautions}\n\n"; + } + + print $FH "=head1 COPYRIGHT\n\n"; + print $FH "IBM Corporation 2000. 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"; + + if (exists $hash{'Related Information'}) { + print $FH "=head1 SEE ALSO\n\n"; + print $FH "$hash{'Related Information'}\n\n"; + print $FH "=cut\n"; + } + + close(FILE) unless $DEBUG; + Index: openafs/doc/man-pages/pod/afs_intro.pod diff -c /dev/null openafs/doc/man-pages/pod/afs_intro.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/afs_intro.pod Sat Oct 15 11:04:29 2005 *************** *** 0 **** --- 1,570 ---- + =head1 NAME + + afs_intro - Introduction to AFS commands + + =head1 DESCRIPTION + + AFS provides many commands that enable users and system administrators + to use and customize its features. Many of the commands belong to the + following categories, called command suites. + + =over + + =item B + + 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 Index: openafs/doc/man-pages/pod/afsd.pod diff -c /dev/null openafs/doc/man-pages/pod/afsd.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/afsd.pod Sat Oct 15 11:04:29 2005 *************** *** 0 **** --- 1,597 ---- + =head1 NAME + + afsd - Initializes the Cache Manager and starts related daemons. + + =head1 SYNOPSIS + + afsd [B<-blocks> I<1024 byte blocks in cache>] + [B<-files> I] + [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 Index: openafs/doc/man-pages/pod/afsmonitor.pod diff -c /dev/null openafs/doc/man-pages/pod/afsmonitor.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/afsmonitor.pod Sat Oct 15 11:04:29 2005 *************** *** 0 **** --- 1,432 ---- + =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

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 Index: openafs/doc/man-pages/pod/backup_addhost.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_addhost.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_addhost.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,118 ---- + =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 Index: openafs/doc/man-pages/pod/backup_addvolentry.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_addvolentry.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_addvolentry.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,203 ---- + =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 Index: openafs/doc/man-pages/pod/backup_addvolset.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_addvolset.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_addvolset.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,114 ---- + =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 Index: openafs/doc/man-pages/pod/backup_apropos.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_apropos.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_apropos.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,72 ---- + =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 Index: openafs/doc/man-pages/pod/backup_dbverify.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_dbverify.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_dbverify.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,144 ---- + =head1 NAME + + backup dbverify - Checks the integrity of the Backup Database + + =head1 SYNOPSIS + + backup dbverify [B<-detail>] [B<-localauth>] [B<-cell> I] [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 Index: openafs/doc/man-pages/pod/backup_deldump.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_deldump.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_deldump.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,78 ---- + =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 Index: openafs/doc/man-pages/pod/backup_deletedump.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_deletedump.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_deletedump.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,212 ---- + =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
/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 Index: openafs/doc/man-pages/pod/backup_delhost.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_delhost.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_delhost.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,93 ---- + =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 Index: openafs/doc/man-pages/pod/backup_delvolentry.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_delvolentry.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_delvolentry.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,93 ---- + =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 Index: openafs/doc/man-pages/pod/backup_delvolset.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_delvolset.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_delvolset.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,83 ---- + =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 Index: openafs/doc/man-pages/pod/backup_diskrestore.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_diskrestore.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_diskrestore.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,280 ---- + =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 Index: openafs/doc/man-pages/pod/backup_dump.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_dump.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_dump.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,547 ---- + =head1 NAME + + backup dump - Creates a dump (dumps a volume set at a particular dump level) + + =head1 SYNOPSIS + + backup dump [B<-volumeset> I] [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 Index: openafs/doc/man-pages/pod/backup_dumpinfo.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_dumpinfo.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_dumpinfo.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,427 ---- + =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 Index: openafs/doc/man-pages/pod/backup_help.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_help.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_help.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,95 ---- + =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 Index: openafs/doc/man-pages/pod/backup_interactive.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_interactive.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_interactive.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,121 ---- + =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 Index: openafs/doc/man-pages/pod/backup_jobs.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_jobs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_jobs.pod Sat Oct 15 11:04:30 2005 *************** *** 0 **** --- 1,229 ---- + =head1 NAME + + backup jobs - Lists pending and running operations in interactive mode + + =head1 SYNOPSIS + + jobs [B<-help>] + + j [B<-h>] + + =head1 DESCRIPTION + + The C<(backup) jobs> command lists the job ID number and status of each + B 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 Index: openafs/doc/man-pages/pod/backup_scantape.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_scantape.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_scantape.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,359 ---- + =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 Index: openafs/doc/man-pages/pod/backup_setexp.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_setexp.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_setexp.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,175 ---- + =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 Index: openafs/doc/man-pages/pod/backup_status.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_status.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_status.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,198 ---- + =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 Index: openafs/doc/man-pages/pod/backup_volinfo.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_volinfo.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_volinfo.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,134 ---- + =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 Index: openafs/doc/man-pages/pod/backup_volrestore.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_volrestore.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_volrestore.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,336 ---- + =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 Index: openafs/doc/man-pages/pod/backup_volsetrestore.pod diff -c /dev/null openafs/doc/man-pages/pod/backup_volsetrestore.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/backup_volsetrestore.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,424 ---- + =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 Index: openafs/doc/man-pages/pod/bos.pod diff -c /dev/null openafs/doc/man-pages/pod/bos.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,299 ---- + =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 Index: openafs/doc/man-pages/pod/bos_addhost.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_addhost.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_addhost.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,124 ---- + =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 Index: openafs/doc/man-pages/pod/bos_addkey.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_addkey.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_addkey.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,141 ---- + =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 Index: openafs/doc/man-pages/pod/bos_adduser.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_adduser.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_adduser.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,104 ---- + =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 Index: openafs/doc/man-pages/pod/bos_apropos.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_apropos.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_apropos.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,70 ---- + =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 Index: openafs/doc/man-pages/pod/bos_create.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_create.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_create.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,410 ---- + =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 Index: openafs/doc/man-pages/pod/bos_delete.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_delete.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_delete.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,101 ---- + =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 Index: openafs/doc/man-pages/pod/bos_exec.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_exec.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_exec.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,90 ---- + =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 Index: openafs/doc/man-pages/pod/bos_getdate.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_getdate.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_getdate.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,119 ---- + =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 Index: openafs/doc/man-pages/pod/bos_getlog.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_getlog.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_getlog.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,154 ---- + =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 Index: openafs/doc/man-pages/pod/bos_getrestart.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_getrestart.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_getrestart.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,151 ---- + =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 Index: openafs/doc/man-pages/pod/bos_listhosts.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_listhosts.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_listhosts.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,111 ---- + =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 Index: openafs/doc/man-pages/pod/bos_listkeys.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_listkeys.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_listkeys.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,142 ---- + =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 Index: openafs/doc/man-pages/pod/bos_listusers.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_listusers.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_listusers.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,98 ---- + =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 Index: openafs/doc/man-pages/pod/bos_prune.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_prune.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_prune.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,144 ---- + =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 Index: openafs/doc/man-pages/pod/bos_removehost.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_removehost.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_removehost.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,115 ---- + =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 Index: openafs/doc/man-pages/pod/bos_removekey.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_removekey.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_removekey.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,109 ---- + =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 Index: openafs/doc/man-pages/pod/bos_removeuser.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_removeuser.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_removeuser.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,100 ---- + =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 Index: openafs/doc/man-pages/pod/bos_restart.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_restart.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_restart.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,152 ---- + =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 Index: openafs/doc/man-pages/pod/bos_salvage.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_salvage.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_salvage.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,354 ---- + =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 Index: openafs/doc/man-pages/pod/bos_setauth.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_setauth.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_setauth.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,114 ---- + =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 Index: openafs/doc/man-pages/pod/bos_setcellname.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_setcellname.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_setcellname.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,134 ---- + =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 Index: openafs/doc/man-pages/pod/bos_setrestart.pod diff -c /dev/null openafs/doc/man-pages/pod/bos_setrestart.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/bos_setrestart.pod Sat Oct 15 11:04:31 2005 *************** *** 0 **** --- 1,190 ---- + =head1 NAME + + bos setrestart - Sets the date and time at which the BOS Server restarts processes + + =head1 SYNOPSIS + + bos setrestart B<-server> I 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 Index: openafs/doc/man-pages/pod/dlog.pod diff -c /dev/null openafs/doc/man-pages/pod/dlog.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/dlog.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,230 ---- + =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 Index: openafs/doc/man-pages/pod/dpass.pod diff -c /dev/null openafs/doc/man-pages/pod/dpass.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/dpass.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,113 ---- + =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 Index: openafs/doc/man-pages/pod/fileserver.pod diff -c /dev/null openafs/doc/man-pages/pod/fileserver.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fileserver.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,493 ---- + =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 Index: openafs/doc/man-pages/pod/fms.pod diff -c /dev/null openafs/doc/man-pages/pod/fms.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fms.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,145 ---- + =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 Index: openafs/doc/man-pages/pod/fs.pod diff -c /dev/null openafs/doc/man-pages/pod/fs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,203 ---- + =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 Index: openafs/doc/man-pages/pod/fs_apropos.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_apropos.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_apropos.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,71 ---- + =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 Index: openafs/doc/man-pages/pod/fs_checkservers.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_checkservers.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_checkservers.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,234 ---- + =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 Index: openafs/doc/man-pages/pod/fs_checkvolumes.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_checkvolumes.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_checkvolumes.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,54 ---- + =head1 NAME + + fs checkvolumes - Forces the Cache Manager to update volume-related information + + =head1 SYNOPSIS + + fs checkvolumes [B<-help>] + + fs checkv [B<-h>] + + =head1 DESCRIPTION + + The C 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. + Index: openafs/doc/man-pages/pod/fs_cleanacl.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_cleanacl.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_cleanacl.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,102 ---- + =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 Index: openafs/doc/man-pages/pod/fs_copyacl.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_copyacl.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_copyacl.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,176 ---- + =head1 NAME + + fs copyacl - Copies an ACL from one directory to one or more other directories + + =head1 SYNOPSIS + + fs copyacl B<-fromdir> I + 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 Index: openafs/doc/man-pages/pod/fs_diskfree.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_diskfree.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_diskfree.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,121 ---- + =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 Index: openafs/doc/man-pages/pod/fs_examine.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_examine.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_examine.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,126 ---- + =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 Index: openafs/doc/man-pages/pod/fs_exportafs.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_exportafs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_exportafs.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,215 ---- + =head1 NAME + + fs exportafs - Reports or sets whether the machine can export AFS to clients of other + file systems + + =head1 SYNOPSIS + + fs exportafs B<-type> I + [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 Index: openafs/doc/man-pages/pod/fs_flush.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_flush.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_flush.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,85 ---- + =head1 NAME + + fs flush - Forces the Cache Manager to discard a cached file or directory + + =head1 SYNOPSIS + + fs flush [B<-path> I [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 Index: openafs/doc/man-pages/pod/fs_flushmount.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_flushmount.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_flushmount.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,76 ---- + =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 Index: openafs/doc/man-pages/pod/fs_flushvolume.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_flushvolume.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_flushvolume.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,84 ---- + =head1 NAME + + fs flushvolume - Forces the Cache Manager to discard all cached data from the volume + containing a file or directory + + =head1 SYNOPSIS + + fs flushvolume [B<-path> I [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 Index: openafs/doc/man-pages/pod/fs_getcacheparms.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_getcacheparms.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_getcacheparms.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,66 ---- + =head1 NAME + + fs getcacheparms - Displays the current size of the cache and the amount being used + + =head1 SYNOPSIS + + fs getcacheparms [B<-help>] + + fs getca [B<-h>] + + =head1 DESCRIPTION + + The C 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 Index: openafs/doc/man-pages/pod/fs_getcellstatus.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_getcellstatus.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_getcellstatus.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,70 ---- + =head1 NAME + + fs getcellstatus - Reports whether the machine can run setuid programs from a specified + cell + + =head1 SYNOPSIS + + fs getcellstatus B<-cell> I [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 Index: openafs/doc/man-pages/pod/fs_getclientaddrs.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_getclientaddrs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_getclientaddrs.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,109 ---- + =head1 NAME + + fs getclientaddrs - Displays the client interfaces to register with the File Server + + =head1 SYNOPSIS + + fs getclientaddrs [B<-help>] + + fs gc [B<-h>] + + fs getcl [B<-h>] + + =head1 DESCRIPTION + + The C 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 Index: openafs/doc/man-pages/pod/fs_getserverprefs.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_getserverprefs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_getserverprefs.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,174 ---- + =head1 NAME + + fs getserverprefs - Displays the Cache Manager's preference ranks for file server or VL + Server machines + + =head1 SYNOPSIS + + fs getserverprefs [B<-file> I] + [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 Index: openafs/doc/man-pages/pod/fs_help.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_help.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_help.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,95 ---- + =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 Index: openafs/doc/man-pages/pod/fs_listacl.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_listacl.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_listacl.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,196 ---- + =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 Index: openafs/doc/man-pages/pod/fs_listcells.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_listcells.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_listcells.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,83 ---- + =head1 NAME + + fs listcells - Displays the database server machines in each cell known to the Cache + Manager + + =head1 SYNOPSIS + + fs listcells [B<-numeric>] [B<-help>] + + fs listc [B<-n>] [B<-h>] + + =head1 DESCRIPTION + + The C 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 Index: openafs/doc/man-pages/pod/fs_listquota.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_listquota.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_listquota.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,111 ---- + =head1 NAME + + fs listquota - Displays quota information for the volume containing a file or + directory. + + =head1 SYNOPSIS + + fs listquota [B<-path> I [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 Index: openafs/doc/man-pages/pod/fs_lsmount.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_lsmount.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_lsmount.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,130 ---- + =head1 NAME + + fs lsmount - Reports the volume for which a directory is the mount point. + + =head1 SYNOPSIS + + fs lsmount B<-dir> I [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 Index: openafs/doc/man-pages/pod/fs_messages.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_messages.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_messages.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,98 ---- + =head1 NAME + + fs messages - Sets whether the Cache Manager writes log messages + + =head1 SYNOPSIS + + fs messages [B<-show> I<[user|console|all|none]>] [B<-help>] + + fs me [B<-s> I<[user|console|all|none]>] [B<-h>] + + =head1 DESCRIPTION + + The C 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 Index: openafs/doc/man-pages/pod/fs_mkmount.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_mkmount.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_mkmount.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,274 ---- + =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 Index: openafs/doc/man-pages/pod/fs_newcell.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_newcell.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_newcell.pod Sat Oct 15 11:04:32 2005 *************** *** 0 **** --- 1,112 ---- + =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 Index: openafs/doc/man-pages/pod/fs_quota.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_quota.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_quota.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,85 ---- + =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 Index: openafs/doc/man-pages/pod/fs_rmmount.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_rmmount.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_rmmount.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,68 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setacl.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setacl.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setacl.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,293 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setcachesize.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setcachesize.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setcachesize.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,105 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setcell.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setcell.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setcell.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,104 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setclientaddrs.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setclientaddrs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setclientaddrs.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,122 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setquota.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setquota.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setquota.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,90 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setserverprefs.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setserverprefs.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setserverprefs.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,320 ---- + =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 Index: openafs/doc/man-pages/pod/fs_setvol.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_setvol.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_setvol.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,106 ---- + =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 Index: openafs/doc/man-pages/pod/fs_storebehind.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_storebehind.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_storebehind.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,231 ---- + =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 Index: openafs/doc/man-pages/pod/fs_sysname.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_sysname.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_sysname.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,94 ---- + =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 Index: openafs/doc/man-pages/pod/fs_whereis.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_whereis.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_whereis.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,74 ---- + =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 Index: openafs/doc/man-pages/pod/fs_whichcell.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_whichcell.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_whichcell.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,68 ---- + =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 Index: openafs/doc/man-pages/pod/fs_wscell.pod diff -c /dev/null openafs/doc/man-pages/pod/fs_wscell.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fs_wscell.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,59 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,88 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_apropos.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_apropos.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_apropos.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,71 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_clear.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_clear.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_clear.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,64 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_dump.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_dump.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_dump.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,248 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_help.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_help.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_help.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,94 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_lslog.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_lslog.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_lslog.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,109 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_lsset.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_lsset.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_lsset.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,90 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_setlog.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_setlog.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_setlog.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,74 ---- + =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 Index: openafs/doc/man-pages/pod/fstrace_setset.pod diff -c /dev/null openafs/doc/man-pages/pod/fstrace_setset.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/fstrace_setset.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,79 ---- + =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 Index: openafs/doc/man-pages/pod/kadb_check.pod diff -c /dev/null openafs/doc/man-pages/pod/kadb_check.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/kadb_check.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,102 ---- + =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 Index: openafs/doc/man-pages/pod/kas.pod diff -c /dev/null openafs/doc/man-pages/pod/kas.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/kas.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,214 ---- + =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 Index: openafs/doc/man-pages/pod/kas_apropos.pod diff -c /dev/null openafs/doc/man-pages/pod/kas_apropos.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/kas_apropos.pod Sat Oct 15 11:04:33 2005 *************** *** 0 **** --- 1,69 ---- + =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 Index: openafs/doc/man-pages/pod/kas_create.pod diff -c /dev/null openafs/doc/man-pages/pod/kas_create.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/kas_create.pod Sat Oct 15 11:04:34 2005 *************** *** 0 **** --- 1,125 ---- + =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 Index: openafs/doc/man-pages/pod/kas_delete.pod diff -c /dev/null openafs/doc/man-pages/pod/kas_delete.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/kas_delete.pod Sat Oct 15 11:04:34 2005 *************** *** 0 **** --- 1,102 ---- + =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 Index: openafs/doc/man-pages/pod/kas_examine.pod diff -c /dev/null openafs/doc/man-pages/pod/kas_examine.pod:1.1.2.2 *** /dev/null Sat Oct 22 02:14:42 2005 --- openafs/doc/man-pages/pod/kas_examine.pod Sat Oct 15 11:04:34 2005 *************** *** 0 **** --- 1,308 ---- + =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