From: Russ Allbery Date: Thu, 22 Dec 2005 07:34:49 +0000 (+0000) Subject: man-page-misc-improvements-20051221 X-Git-Tag: openafs-devel-1_5_0~137 X-Git-Url: http://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=90bc5c0092652b047c4eabffb5577e05859c80f4;hp=5fde2994348d1c7f6239f98aac355011125b06ad man-page-misc-improvements-20051221 Add new man pages for livesys and voldump. Fix the man page for sys to say what it actually does, rather than implying that it works like livesys, and to recommend livesys instead. Fix a path error in the NetInfo documentation. Update the README for the current status, including listing all installed commands that don't have man pages. (There may still be some subcommands that don't have man pages but aren't listed.) --- diff --git a/doc/man-pages/README b/doc/man-pages/README index 682993b..799e42e 100644 --- a/doc/man-pages/README +++ b/doc/man-pages/README @@ -183,16 +183,10 @@ Known Problems don't just report the deficiency again, but any contributions towards fixing it are greatly appreciated. - * The section five and section eight man pages have not yet had an - initial editing pass and many of the section five man pages are - missing because the original reference page names didn't easily - convert to man page names. This is currently being fixed. Please do - not start working on the section five or section eight man pages yet - or bother reporting problems with them; they will be changing - significantly in the near future. - - * The following commands have no man pages: + * The following installed commands have no man pages: + bos_util + copyauth fs getcalleraccess fs getcrypt fs listaliases @@ -201,16 +195,26 @@ Known Problems 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 @@ -255,6 +259,9 @@ Known Problems * 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. diff --git a/doc/man-pages/pod1/livesys.pod b/doc/man-pages/pod1/livesys.pod new file mode 100644 index 0000000..9db531b --- /dev/null +++ b/doc/man-pages/pod1/livesys.pod @@ -0,0 +1,68 @@ +=head1 NAME + +livesys - Reports the configured CPU/operating system type + +=head1 SYNOPSIS + +B + +=head1 DESCRIPTION + +The B command displays the string stored in kernel memory that +indicates the local machine's CPU/operating system (OS) type, +conventionally called the I. The Cache Manager substitutes this +string for the I<@sys> variable which can occur in AFS pathnames; the +I and I explain +how using I<@sys> can simplify cell configuration. + +To set a new value in kernel memory, use the B command, which +can also be used to view the current value. If a sysname list was set +using B, only the first value in the list will be reported by +B. + +=head1 CAUTIONS + +To see the full sysname list, use B rather than this command. +B is mostly useful for scripts that need to know the primary +sysname for the local system (to create directories that will later be +addressed using I<@sys>, for example). + +B first appeared in OpenAFS 1.2.2. Scripts that need to support +older versions of AFS should parse the output of B or use +B. + +=head1 OUTPUT + +The machine's system type appears as a text string: + + I + +=head1 EXAMPLES + +The following example shows the output produced on a Linux system with a +2.6 kernel: + + % livesys + i386_linux26 + +=head1 PRIVILEGE REQUIRED + +None + +=head1 SEE ALSO + +L, +L + +I + +I + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +Copyright 2005 Russ Allbery + +This documentation is covered by the IBM Public License Version 1.0. It +was written by Russ Allbery based on the B man page. diff --git a/doc/man-pages/pod1/sys.pod b/doc/man-pages/pod1/sys.pod index 909836c..d345007 100644 --- a/doc/man-pages/pod1/sys.pod +++ b/doc/man-pages/pod1/sys.pod @@ -1,23 +1,35 @@ =head1 NAME -sys - Reports the CPU/operating system type +sys - Reports the compile-time CPU/operating system type =head1 SYNOPSIS -sys +B =head1 DESCRIPTION -The B command displays the string stored in kernel memory that -indicates the local machine's CPU/operating system (OS) type. The Cache -Manager substitutes the string for the I<@sys> variable which can occur in -AFS pathnames; the I and I explain how using I<@sys> can simplify cell -configuration. - -The command always reports the value for the local machine only. To set a -new value in kernel memory, use the B command, which like this -command can also be used to display the current value. +The B command displays the string set at compile time that indicates +the local machine's CPU/operating system (OS) type, conventionally called +the I. This string is the default for the value stored in kernel +memory. The Cache Manager substitutes this string for the I<@sys> +variable which can occur in AFS pathnames; the I +and I explain how using I<@sys> can simplify +cell configuration. + +To set a new value in kernel memory, use the B command. To +view the current value set in the kernel, use either B or +B. + +=head1 CAUTIONS + +You almost always want to use B rather than this command. The +B command displays a single value hard-coded at compile time. It +does not query the Cache Manager for the current value and it does not +report sysname lists. If you have changed the local system type with B, or if you run a version of B compiled differently than the +Cache Manager running on the system, the value retured will not match the +behavior of the Cache Manager. The only reason to use B is that +B wasn't available in older versions of AFS. =head1 OUTPUT @@ -39,7 +51,8 @@ None =head1 SEE ALSO -L +L, +L I diff --git a/doc/man-pages/pod5/NetInfo.pod b/doc/man-pages/pod5/NetInfo.pod index 1e940eb..95054c8 100644 --- a/doc/man-pages/pod5/NetInfo.pod +++ b/doc/man-pages/pod5/NetInfo.pod @@ -69,7 +69,7 @@ If the F file exists when the File Server initializes, the File Server uses its contents as the basis for a list of interfaces to register in the VLDB. Otherwise, it uses the list of network interfaces configured with the operating system. It then removes from the list any addresses -that appear in the F file, if it exists. The +that appear in the F file, if it exists. The File Server records the resulting list in the F file and registers the interfaces in the VLDB. The database server processes use a similar procedure when initializing, to determine which interfaces diff --git a/doc/man-pages/pod8/voldump.pod b/doc/man-pages/pod8/voldump.pod new file mode 100644 index 0000000..c25a083 --- /dev/null +++ b/doc/man-pages/pod8/voldump.pod @@ -0,0 +1,92 @@ +=head1 NAME + +voldump - Dump an AFS volume without using the Volume Server + +=head1 SYNOPSIS + +B B<-part> > B<-volumeid> > + [B<-file> >] [B<-verbose>] [B<-help>] + +B B<-p> > B<-vo> > + [B<-f> >] [B<-ve>] [B<-h>] + +=head1 DESCRIPTION + +B dumps an AFS volume in the format used by B without +using the Volume Server. It must be run on the file server machine and +usually must be run as the superuser C to have permissions to read +the file server data. It's primary use is to recover data from a file +server machine where the Volume Server cannot be started for some reason. + +The dump output will go to standard output, or to a file if B<-file> is +specified. B can be used to load the resulting dump into a +new AFS volume. B always does a full dump. + +=head1 CAUTIONS + +Normally, use B instead of this command. B is a tool +of last resort to try to extract data from the raw data structures stored +on the file server machine and is not as regularly tested or used as the +normal B implementation. + +If the AFS volume being dumped changes while B is running, the +results may be inconsistent. If the File Server and Volume Server are +running, stop them with B or a similar method before running +this command. + +=head1 OPTIONS + +=over 4 + +=item B<-part> > + +Names the partition on which the volume to be dumped is located. +B does not take the normal full range of ways of specifying a +partition. Instead, I must be either a single letter between +C and C, corresponding to F through F, or the full +path to the file server partition. C is not recognized; use +F instead. + +=item B<-volumeid> > + +Specifies the ID of the volume to dump. The volume must be specified by +numeric ID, not by name. + +=item B<-file> > + +Specifies the output file for the dump. If this option is not given, the +volume will be dumped to standard output. + +=item B<-verbose> + +Asks for a verbose trace of the dump process. This trace information will +be sent to standard error. + +=back + +=head1 EXAMPLES + +The following command dumps the volume 1936964939 on the F +partition to the file F: + + % voldump -part /vicepb -volumeid 1936964939 -file /tmp/volume.dump + +=head1 PRIVILEGE REQUIRED + +The issuer must have read access to the file server data stored in the +specified partition. Usually, this means that the issuer must be the +local superuser C on the file server machine. + +=head1 SEE ALSO + +L, +L, +L, +L + +=head1 COPYRIGHT + +Copyright 2005 Russ Allbery + +This documentation is covered by the IBM Public License Version 1.0. This +man page was written by Russ Allbery for OpenAFS.