Index: openafs/doc/man-pages/.cvsignore diff -c /dev/null openafs/doc/man-pages/.cvsignore:1.2.2.3 *** /dev/null Wed Jan 11 00:01:23 2006 --- openafs/doc/man-pages/.cvsignore Thu Jan 5 13:54:50 2006 *************** *** 0 **** --- 1,5 ---- + Makefile + install-man + man1 + man5 + man8 Index: openafs/doc/man-pages/Makefile.in diff -c openafs/doc/man-pages/Makefile.in:1.1.2.3 openafs/doc/man-pages/Makefile.in:1.1.2.6 *** openafs/doc/man-pages/Makefile.in:1.1.2.3 Wed Nov 9 09:59:39 2005 --- openafs/doc/man-pages/Makefile.in Thu Jan 5 13:54:50 2006 *************** *** 3,199 **** 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 --- 3,36 ---- srcdir=@srcdir@ include @TOP_OBJDIR@/src/config/Makefile.config ! all: ! maintclean: ! rm -rf man1 man5 man8 ! dest: ! chmod +x install-man ! mkdir -p $(DEST)/man/man1 $(DEST)/man/man5 $(DEST)/man/man8 ! set -e; cd man1 && for M in *.1 ; do \ ! ../install-man $$M $(DEST)/man/man1/$$M ; \ ! done ! set -e; cd man5 && for M in *.5 ; do \ ! ../install-man $$M $(DEST)/man/man5/$$M ; \ done ! set -e; cd man8 && for M in *.8 ; do \ ! ../install-man $$M $(DEST)/man/man8/$$M ; \ done install: $(MAN1) $(MAN8) ! chmod +x install-man ! mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man5 \ ! $(DESTDIR)$(mandir)/man8 ! set -e; cd man1 && for M in *.1 ; do \ ! ../install-man $$M $(DESTDIR)$(mandir)/man1/$$M ; \ ! done ! set -e; cd man5 && for M in *.5 ; do \ ! ../install-man $$M $(DESTDIR)$(mandir)/man5/$$M ; \ done ! set -e; cd man8 && for M in *.8 ; do \ ! ../install-man $$M $(DESTDIR)$(mandir)/man8/$$M ; \ done Index: openafs/doc/man-pages/README diff -c /dev/null openafs/doc/man-pages/README:1.4.2.5 *** /dev/null Wed Jan 11 00:01:23 2006 --- openafs/doc/man-pages/README Thu Jan 5 13:55:18 2006 *************** *** 0 **** --- 1,267 ---- + OpenAFS Man Pages + + Overview + + This directory contains the POD source and (in releases) the generated + man pages for OpenAFS commands and files. The man pages are based on + the original IBM AFS Administration Reference manual, released with the + rest of AFS under the IBM Public License 1.0. They were converted from + HTML to POD, editing, and are currently maintained in POD. + + The man pages are very much a work in progress. The original source + material dated from IBM's public release of AFS, and many changes since + made in OpenAFS are not reflected in the man pages. Help and + contributions are actively solicited. Please see "How You Can Help" + below for more information. + + The long-term goal is for every command shipped with OpenAFS and every + configuration or data file written or read by OpenAFS to have its own + man page. Section one is used for commands that don't require special + privileges, section eight for commands for AFS administrators and local + system administrators, and section five for file formats and + configuration files, with the exception that command suites are kept + together (so, for instance, all fs commands are documented in section + one even though some of them are only usable by a local system + administrator). + + The OpenAFS man pages are discussed on the openafs-doc mailing list at + openafs.org. If you plan on contributing to the man page project, + please join that mailing list and send suggestions, patches, and + contributions there. The coordinator of the OpenAFS man page project is + Russ Allbery ; feel free to contact me directly with + questions (although using the mailing list is generally better and will + probably result in a faster response). + + POD and Man Page Generation + + The OpenAFS man pages are maintained in POD (Plain Old Documentation), + the documentation system originally developed for Perl. This is not an + uncontroversial choice, since POD isn't as rich and full-featured as + other possible alternatives such as Docbook RefEntry. On the other + hand, POD is very close to plain text, can be easier to edit and + maintain for those not familiar with the documentation format, and has + more mature tools for conversion to formatted man pages, an output + format that is particularly important on Unix/Linux. There are many + good arguments either way, and fundamentally the decision was made to + use POD because I prefer it and I'm volunteering to write and edit the + pages and maintain them going forward. + + To convert the POD source to formatted man pages, you need the pod2man + utility. This utility has come with Perl for many years, so if you have + Perl installed, you almost certainly have some version of it available. + For the best results, install Pod::Simple 3.03 or later and podlators + 2.00 or later from CPAN and use that pod2man, but the results from the + pod2man that comes with Perl 5.8 or later will be very good. If you are + using earlier versions of Perl, the output should be adequate and + readable but may contain some formatting glitches. + + Preformatted man pages will be included in distribution tarballs, but + those man pages may be generated with older versions of the conversion + utilities. To regenerate the man pages, run regen.sh at the top of the + OpenAFS source tree (this will also regenerate the Autoconf scripts). + + Conversion to HTML can be done via any of the POD to HTML converters + available (there are many of them). Evaluation of the best tool to use + for OpenAFS and exactly how to do the conversion to get the highest + quality results is still underway; when complete, details will be + included here. + + Formatting Standards + + Each command or configuration file should have a separate man page in a + separate POD file. Command suites (fs, pts, vos, etc.) should have an + overview man page that lists the available subcommands by category, + documents common options, and discusses the general use of the suite. + Then, each operation code in the suite should have a separate man page, + named after the command with the space between the command suite and the + operation code replaced with an underscore. + + All man pages must follow the standard layout for man page sections and + formatting. The best general reference is the pod2man man page, + although the sections used for OpenAFS man pages aren't quite the same + (see below). In particular, please use the following markup: + + * B<> for all commands, command/operation code pairs, and options. + * F<> for file names, directory names, partition names, or paths. + * > for user-provided arguments (note the surrounding <>). + * I<> for terms being defined or titles of works. + * C<> for command examples, ACL characters, and example arguments. + + Also see the afs(1) man page for general rules about how OpenAFS man + pages are formatted and for standard terminology to use when talking + about OpenAFS commands. + + Each man page should have the following sections: NAME, SYNOPSIS (for + commands only), DESCRIPTION, CAUTIONS, OPTIONS (for commands only), + OUTPUT (where appropriate), EXAMPLES, PRIVILEGE REQUIRED (for commands + only), SEE ALSO, and COPYRIGHT, generally in that order. Be sure to + include the IBM copyright in all man pages derived from the original IBM + documentation. If you wrote the man page yourself, please include your + own copyright and a statement that the man page is released under the + IBM Public License Version 1.0, or under some other license that is + sufficiently compatible that we can use your work. If you use another + license and that license isn't "public domain," you have to give the + full license text in the man page; please don't use a license so long + that this is annoying. + + The SYNOPSIS section should start with the full command name and the + full names of all options, and then have a second section showing the + most abbreviated form of the command name and its options. If the + command has aliases, it should have additional sections showing those. + Please be sure to follow all of the formatting requirements for + commands, flags, and options. Enclose optional arguments in [] and + choices in () separated by |. Command names and options are marked up + with B<> as mentioned above; all other literal text that should be + entered on the command line gets no markup. + + References to other OpenAFS man pages should be given as L. + Other man pages should be noted like df(1), without the L<> markup. + References to functions should be noted like function() with the + trailing parens. The POD converters know how to format these sorts of + references appropriately. References to other sections in the same page + should be given as L
. + + Command and output examples should be indented three spaces. Commands + entered by the user should be given on a line beginning with %. If the + command doesn't fit in 80 columns, put in a backslash at a logical break + point and continue the line with an additional four spaces of + indentation. Output examples may be wrapped with an additional four + spaces of indentation but probably shouldn't be; not wrapping makes the + man page look somewhat less readable, but is less confusing when + converted to other formats such as HTML. + + POD does not allow markup in verbatim paragraphs (which are indicated by + indenting the first line of the paragraph), so metasyntactic variables + in examples should be shown like with simple angle brackets + surrounding the variable. For consistency in formatting, references to + those variables should be formatted the same in following text. + + How You Can Help + + The OpenAFS man page project is just starting, and a lot of work remains + to be done. Any and all contributions are greatly appreciated. What + follows is a list of the ways that you can help in order of increasing + helpfulness. If you only have time to do something near the top of the + list, please do; every little bit helps. If you have more time and can + do something closer to the bottom of the list, that's even better and + your contribution can be included more rapidly. + + * Point out places OpenAFS behavior has changed since the documentation + was written, or point out missing documentation. Please check the + "Known Problems" list below to make sure that the item is not already + noted. + + * Point out formatting problems, typos, formatting inconsistency, and + other markup or language problems in the man pages. + + * Provide missing documentation in some form (text, HTML, whatever) + that can be incorporated into the man pages, or detailed explanations + of how the existing documentation needs to be changed to match what + the tools actually do. + + * Provide missing man pages in POD format suitable for immediate + inclusion in the documentation. Please try to follow the formatting + standards documented in the "Formatting Standards" section above, and + look at the existing man pages for examples. + + * Provide patches against the POD source that correct formatting + problems, typos, formatting inconsistencies, or other markup or + language problems with the man pages. + + * Provide patches against the POD source that add or correct the + documentation of commands or file formats for changes in OpenAFS. + + Please send contributions either to the openafs-doc list or as bugs + filed via the bug reporting instructions at . + If you do submit a bug, please send me a note at rra@stanford.edu with + the bug number so that I'm aware of it, as I don't always notice new + bugs. + + Known Problems + + The current man pages have the following known deficiencies. Please + don't just report the deficiency again, but any contributions towards + fixing it are greatly appreciated. + + * The following installed commands have no man pages: + + bos_util + copyauth + fs getcalleraccess + fs getcrypt + fs listaliases + fs newalias + fs rxstatpeer + fs rxstatproc + fs setcbaddr + fs setcrypt + kseal + pts interactive + pts quit + pts sleep + pts source + read_tape + restorevol + rmtsysd + vldb_convert + vos changeloc + vos clone + vos convertROtoRW + vos copy + vos shadow + vos size + vsys + + * The following configuration files have no man pages: + + CellAlias + + * klog.krb, pagsh.krb, and tokens.krb need to be listed as alternative + names in the NAME line of the non-.krb man pages, links should be + installed on man page installation, and the behavior of pagsh.krb + should be documented in the pagsh man page. + + * Some of the documentation in fs getserverprefs needs minor updates to + reflect what happens in the dynroot case. + + * fs sysname documentation needs to include the possibility of setting + multiple sysnames and the resulting behavior. + + * The afsd man page is horribly out of date. It doesn't explain + dynroot, many options are missing, and some of the options described + are no longer valid. It also still assumes that -settime is the + default and says that the system must be rebooted after shutdown, + which isn't the case at least on Linux. + + * All of the paths in the man pages are the Transarc paths. I'm not + sure how best to deal with the possibility of installing OpenAFS in + multiple different paths, but it would be good to at least + acknowledge the issue. + + * bos listkeys and the KeyFile man page assume that you're using the + kaserver. + + * I'm fairly sure that the fileserver man page no longer documents all + of the fileserver options. + + * The package man page should probably mention the (pointless) package + apropos and package help commands, or they could be removed. There + used to be separate man pages for them, but that seemed rather + pointless. + + * There are lingering references to AFS Development or AFS Product + Support in descriptions of options that one should generally not + use. Also, all of the manual references refer to the "IBM" manual. + We should decide how to handle this terminology-wise. + + * The salvager actually creates a bunch of SalvageLog files and then + combines them, but the SalvageLog man page doesn't reflect this. + + * The CellServDB documentation hasn't been updated for -dynroot. + + * The aklog man page isn't in POD. (Neither is the mpp man page, but + I don't think we care about it and it's not currently installed.) + + If you notice other problems, please send them to the openafs-doc list + even if you don't have time to fix them. Someone else might, and we + want to track all of the issues. Index: openafs/doc/man-pages/generate-man diff -c /dev/null openafs/doc/man-pages/generate-man:1.1.2.2 *** /dev/null Wed Jan 11 00:01:23 2006 --- openafs/doc/man-pages/generate-man Thu Jan 5 13:53:20 2006 *************** *** 0 **** --- 1,60 ---- + #!/bin/sh + # + # Generate the OpenAFS man pages from POD source. This script is normally + # invoked by regen.sh but may be run at any time to rebuild all of the man + # pages (with a newer version of pod2man than was used for the release, for + # instance). + + # Exit on any error. + set -e + + if [ ! -d pod1 ] ; then + echo 'generate-man must be run from the doc/man-pages directory' >&2 + exit 1 + fi + + if ! pod2man pod1/afs.pod > /dev/null ; then + echo 'pod2man not found, skipping man page generation' >&2 + exit 1 + fi + if ! perl -e 'use Pod::Man 2.04' > /dev/null 2>&1 ; then + echo 'Pod::Man is older than the recommended version of 2.04 or later' >&2 + echo 'Continuing with man page generation anyway' >&2 + fi + + # Create the directories. We generate each section into its own directory + # to make installation rules easier. + [ -d man1 ] || mkdir man1 + [ -d man5 ] || mkdir man5 + [ -d man8 ] || mkdir man8 + + # Generate each set of man pages. For each, allow for the case of the + # directory being empty. In that case, for won't expand the wildcard, and + # we want to avoid running pod2man with a wildcard as an argument. + pod1=`ls pod1` + if [ -n "$pod1" ] ; then + cd pod1 + for f in *.pod ; do + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 1 "$f" \ + > ../man1/`echo "$f" | sed 's/\.pod$//'`.1 + done + cd .. + fi + pod5=`ls pod5` + if [ -n "$pod5" ] ; then + cd pod5 + for f in *.pod ; do + pod2man -c 'AFS File Reference' -r 'OpenAFS' -s 5 "$f" \ + > ../man5/`echo "$f" | sed 's/\.pod$//'`.5 + done + cd .. + fi + pod8=`ls pod8` + if [ -n "$pod8" ] ; then + cd pod8 + for f in *.pod ; do + pod2man -c 'AFS Command Reference' -r 'OpenAFS' -s 8 "$f" \ + > ../man8/`echo "$f" | sed 's/\.pod$//'`.8 + done + cd .. + fi Index: openafs/doc/man-pages/generate-pod diff -c openafs/doc/man-pages/generate-pod:1.1.2.2 openafs/doc/man-pages/generate-pod:removed *** openafs/doc/man-pages/generate-pod:1.1.2.2 Sat Oct 15 11:04:27 2005 --- openafs/doc/man-pages/generate-pod Wed Jan 11 00:01:23 2006 *************** *** 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; - --- 0 ---- Index: openafs/doc/man-pages/install-man.in diff -c /dev/null openafs/doc/man-pages/install-man.in:1.1.2.2 *** /dev/null Wed Jan 11 00:01:23 2006 --- openafs/doc/man-pages/install-man.in Thu Jan 5 13:54:50 2006 *************** *** 0 **** --- 1,50 ---- + #!/bin/sh + # + # Install a man page, but fixing up paths as we go. All of the man pages + # are written to use the Transarc paths, and this script fixes those paths to + # be correct for the chosen configure options as the man pages are installed. + # Takes the source man page file and the destination path as arguments. + + set -e + + manpage="$1" + dest="$2" + + install=@TOP_OBJDIR@/src/pinstall/pinstall + + # We have to include all of the variables here since several of them refer to + # each other and this is the only way we get them all expanded. + prefix=@prefix@ + exec_prefix=@exec_prefix@ + bindir=@bindir@ + includedir=@includedir@ + libdir=@libdir@ + libexecdir=@libexecdir@ + localstatedir=@localstatedir@ + mandir=@mandir@ + sbindir=@sbindir@ + sysconfdir=@sysconfdir@ + afsbackupdir=@afsbackupdir@ + afsbosconfigdir=@afsbosconfigdir@ + afsconfdir=@afsconfdir@ + afsdbdir=@afsdbdir@ + afslocaldir=@afslocaldir@ + afslogsdir=@afslogsdir@ + afssrvbindir=@afssrvbindir@ + afskerneldir=@afskerneldir@ + afssrvlibexecdir=@afssrvlibexecdir@ + afssrvsbindir=@afssrvsbindir@ + viceetcdir=@viceetcdir@ + + # Substitute the paths into a local temporary file and then install it with + # $install. + sed -e "s%/usr/afs/local/BosConfig%${afsbosconfigdir}/BosConfig%g" \ + -e "s%/usr/afs/etc%${afsconfdir}%g" \ + -e "s%/usr/afs/backup%${afsbackupdir}%g" \ + -e "s%/usr/afs/bin%${afssrvlibexecdir}%g" \ + -e "s%/usr/afs/db%${afsdbdir}%g" \ + -e "s%/usr/afs/local%${afslocaldir}%g" \ + -e "s%/usr/afs/logs%${afslogsdir}%g" \ + -e "s%/usr/vice/etc%${viceetcdir}%g" "$manpage" > "$manpage".tmp + $install -c -f -m 0644 "$manpage".tmp "$dest" + rm "$manpage".tmp Index: openafs/doc/man-pages/pod/afs_intro.pod diff -c openafs/doc/man-pages/pod/afs_intro.pod:1.1.2.2 openafs/doc/man-pages/pod/afs_intro.pod:removed *** openafs/doc/man-pages/pod/afs_intro.pod:1.1.2.2 Sat Oct 15 11:04:29 2005 --- openafs/doc/man-pages/pod/afs_intro.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/afsd.pod diff -c openafs/doc/man-pages/pod/afsd.pod:1.1.2.2 openafs/doc/man-pages/pod/afsd.pod:removed *** openafs/doc/man-pages/pod/afsd.pod:1.1.2.2 Sat Oct 15 11:04:29 2005 --- openafs/doc/man-pages/pod/afsd.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/afsmonitor.pod diff -c openafs/doc/man-pages/pod/afsmonitor.pod:1.1.2.2 openafs/doc/man-pages/pod/afsmonitor.pod:removed *** openafs/doc/man-pages/pod/afsmonitor.pod:1.1.2.2 Sat Oct 15 11:04:29 2005 --- openafs/doc/man-pages/pod/afsmonitor.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/backup_addhost.pod diff -c openafs/doc/man-pages/pod/backup_addhost.pod:1.1.2.2 openafs/doc/man-pages/pod/backup_addhost.pod:removed *** openafs/doc/man-pages/pod/backup_addhost.pod:1.1.2.2 Sat Oct 15 11:04:30 2005 --- openafs/doc/man-pages/pod/backup_addhost.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/backup_addvolentry.pod diff -c openafs/doc/man-pages/pod/backup_addvolentry.pod:1.1.2.2 openafs/doc/man-pages/pod/backup_addvolentry.pod:removed *** openafs/doc/man-pages/pod/backup_addvolentry.pod:1.1.2.2 Sat Oct 15 11:04:30 2005 --- openafs/doc/man-pages/pod/backup_addvolentry.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/backup_addvolset.pod diff -c openafs/doc/man-pages/pod/backup_addvolset.pod:1.1.2.2 openafs/doc/man-pages/pod/backup_addvolset.pod:removed *** openafs/doc/man-pages/pod/backup_addvolset.pod:1.1.2.2 Sat Oct 15 11:04:30 2005 --- openafs/doc/man-pages/pod/backup_addvolset.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/backup_apropos.pod diff -c openafs/doc/man-pages/pod/backup_apropos.pod:1.1.2.2 openafs/doc/man-pages/pod/backup_apropos.pod:removed *** openafs/doc/man-pages/pod/backup_apropos.pod:1.1.2.2 Sat Oct 15 11:04:30 2005 --- openafs/doc/man-pages/pod/backup_apropos.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/backup_dbverify.pod diff -c openafs/doc/man-pages/pod/backup_dbverify.pod:1.1.2.2 openafs/doc/man-pages/pod/backup_dbverify.pod:removed *** openafs/doc/man-pages/pod/backup_dbverify.pod:1.1.2.2 Sat Oct 15 11:04:30 2005 --- openafs/doc/man-pages/pod/backup_dbverify.pod Wed Jan 11 00:01:23 2006 *************** *** 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 --- 0 ---- Index: openafs/doc/man-pages/pod/backup_deldump.pod diff -c openafs/doc/man-pages/pod/backup_deldump.pod:1.1.2.2 openafs/doc/man-pages/pod/backup_deldump.pod:removed *** openafs/doc/man-pages/pod/backup_deldump.pod:1.1.2.2 Sat Oct 15 11:04:30 2005 --- openafs/doc/man-pages/pod/backup_deldump.pod Wed Jan 11 00:01:23 2006 *************** *** 1,78 **** - =head1 NAME - - backup deldump - Deletes a dump level from the Backup Dat