From e2a90e6769c7828de7a0ec8211b406731984f7d1 Mon Sep 17 00:00:00 2001 From: Russ Allbery Date: Thu, 5 Jan 2006 18:35:30 +0000 Subject: [PATCH] STABLE14-man8-editing-pass-20051213 This completes the initial editing pass of the section eight man pages. Only small amounts of content editing has been done. Some known problems have been noted in README, but there will doubtless be others, as well as some lingering formatting problems. However, the quality should now be good enough for general public review. Some of the section eight man pages were really supposed to be section one, the package apropros and package help commands are too useless to document, and a few of the difficult-to-name section five man pages have now acquired names. RCS file: /cvs/openafs/doc/man-pages/pod8/Attic/package_apropos.pod,v Working file: doc/man-pages/pod8/package_apropos.pod head: 1.2 branch: locks: strict access list: keyword substitution: kv total revisions: 4; selected revisions: 0 description: RCS file: /cvs/openafs/doc/man-pages/pod8/Attic/package_help.pod,v Working file: doc/man-pages/pod8/package_help.pod head: 1.2 branch: locks: strict access list: keyword substitution: kv total revisions: 4; selected revisions: 0 description: RCS file: /cvs/openafs/doc/man-pages/pod8/Attic/package_test.pod,v Working file: doc/man-pages/pod8/package_test.pod head: 1.2 branch: locks: strict access list: keyword substitution: kv total revisions: 4; selected revisions: 0 description: RCS file: /cvs/openafs/doc/man-pages/pod8/Attic/tapeconfig.pod,v Working file: doc/man-pages/pod8/tapeconfig.pod head: 1.2 branch: locks: strict access list: keyword substitution: kv total revisions: 4; selected revisions: 0 description: RCS file: /cvs/openafs/doc/man-pages/pod8/Attic/xstat_cm_test.pod,v Working file: doc/man-pages/pod8/xstat_cm_test.pod head: 1.2 branch: locks: strict access list: keyword substitution: kv total revisions: 4; selected revisions: 0 description: RCS file: /cvs/openafs/doc/man-pages/pod8/Attic/xstat_fs_test.pod,v Working file: doc/man-pages/pod8/xstat_fs_test.pod head: 1.2 branch: locks: strict access list: keyword substitution: kv total revisions: 4; selected revisions: 0 description: (cherry picked from commit ab4abf15fef60308b982c73b6d1a17fa60577120) --- doc/man-pages/README | 26 + .../{pod8 => pod1}/xstat_cm_test.pod | 74 +- doc/man-pages/pod1/xstat_fs_test.pod | 107 ++ doc/man-pages/pod5/package.pod | 878 ++++++++++++++++ doc/man-pages/{pod8 => pod5}/tapeconfig.pod | 40 +- doc/man-pages/pod5/uss.pod | 952 ++++++++++++++++++ doc/man-pages/pod5/uss_bulk.pod | 407 ++++++++ doc/man-pages/pod8/afsd.pod | 586 +++++------ doc/man-pages/pod8/backup.pod | 383 ++++--- doc/man-pages/pod8/backup_adddump.pod | 198 ++-- doc/man-pages/pod8/backup_addhost.pod | 98 +- doc/man-pages/pod8/backup_addvolentry.pod | 183 ++-- doc/man-pages/pod8/backup_addvolset.pod | 107 +- doc/man-pages/pod8/backup_apropos.pod | 39 +- doc/man-pages/pod8/backup_dbverify.pod | 109 +- doc/man-pages/pod8/backup_deldump.pod | 58 +- doc/man-pages/pod8/backup_deletedump.pod | 182 ++-- doc/man-pages/pod8/backup_delhost.pod | 77 +- doc/man-pages/pod8/backup_delvolentry.pod | 80 +- doc/man-pages/pod8/backup_delvolset.pod | 64 +- doc/man-pages/pod8/backup_diskrestore.pod | 297 +++--- doc/man-pages/pod8/backup_dump.pod | 595 ++++++----- doc/man-pages/pod8/backup_dumpinfo.pod | 329 +++--- doc/man-pages/pod8/backup_help.pod | 62 +- doc/man-pages/pod8/backup_interactive.pod | 103 +- doc/man-pages/pod8/backup_jobs.pod | 176 ++-- doc/man-pages/pod8/backup_kill.pod | 140 ++- doc/man-pages/pod8/backup_labeltape.pod | 292 +++--- doc/man-pages/pod8/backup_listdumps.pod | 60 +- doc/man-pages/pod8/backup_listhosts.pod | 69 +- doc/man-pages/pod8/backup_listvolsets.pod | 84 +- doc/man-pages/pod8/backup_quit.pod | 52 +- doc/man-pages/pod8/backup_readlabel.pod | 214 ++-- doc/man-pages/pod8/backup_restoredb.pod | 117 ++- doc/man-pages/pod8/backup_savedb.pod | 178 ++-- doc/man-pages/pod8/backup_scantape.pod | 354 +++---- doc/man-pages/pod8/backup_setexp.pod | 149 ++- doc/man-pages/pod8/backup_status.pod | 161 ++- doc/man-pages/pod8/backup_volinfo.pod | 117 +-- doc/man-pages/pod8/backup_volrestore.pod | 392 ++++---- doc/man-pages/pod8/backup_volsetrestore.pod | 460 ++++----- doc/man-pages/pod8/bos.pod | 370 +++---- doc/man-pages/pod8/bos_addhost.pod | 134 ++- doc/man-pages/pod8/bos_addkey.pod | 175 ++-- doc/man-pages/pod8/bos_adduser.pod | 107 +- doc/man-pages/pod8/bos_apropos.pod | 38 +- doc/man-pages/pod8/bos_create.pod | 408 ++++---- doc/man-pages/pod8/bos_delete.pod | 110 +- doc/man-pages/pod8/bos_exec.pod | 84 +- doc/man-pages/pod8/bos_getdate.pod | 120 +-- doc/man-pages/pod8/bos_getlog.pod | 131 ++- doc/man-pages/pod8/bos_getrestart.pod | 118 +-- doc/man-pages/pod8/bos_help.pod | 63 +- doc/man-pages/pod8/bos_install.pod | 155 ++- doc/man-pages/pod8/bos_listhosts.pod | 99 +- doc/man-pages/pod8/bos_listkeys.pod | 119 +-- doc/man-pages/pod8/bos_listusers.pod | 81 +- doc/man-pages/pod8/bos_prune.pod | 150 ++- doc/man-pages/pod8/bos_removehost.pod | 115 +-- doc/man-pages/pod8/bos_removekey.pod | 112 +-- doc/man-pages/pod8/bos_removeuser.pod | 104 +- doc/man-pages/pod8/bos_restart.pod | 151 ++- doc/man-pages/pod8/bos_salvage.pod | 379 ++++--- doc/man-pages/pod8/bos_setauth.pod | 112 +-- doc/man-pages/pod8/bos_setcellname.pod | 139 ++- doc/man-pages/pod8/bos_setrestart.pod | 183 ++-- doc/man-pages/pod8/bos_shutdown.pod | 130 ++- doc/man-pages/pod8/bos_start.pod | 112 +-- doc/man-pages/pod8/bos_startup.pod | 120 +-- doc/man-pages/pod8/bos_status.pod | 66 +- doc/man-pages/pod8/bos_stop.pod | 108 +- doc/man-pages/pod8/bos_uninstall.pod | 133 ++- doc/man-pages/pod8/bosserver.pod | 133 ++- doc/man-pages/pod8/buserver.pod | 157 ++- doc/man-pages/pod8/butc.pod | 248 ++--- doc/man-pages/pod8/fileserver.pod | 462 ++++----- doc/man-pages/pod8/fms.pod | 105 +- doc/man-pages/pod8/fstrace.pod | 94 +- doc/man-pages/pod8/fstrace_apropos.pod | 38 +- doc/man-pages/pod8/fstrace_clear.pod | 43 +- doc/man-pages/pod8/fstrace_dump.pod | 203 ++-- doc/man-pages/pod8/fstrace_help.pod | 64 +- doc/man-pages/pod8/fstrace_lslog.pod | 100 +- doc/man-pages/pod8/fstrace_lsset.pod | 44 +- doc/man-pages/pod8/fstrace_setlog.pod | 52 +- doc/man-pages/pod8/fstrace_setset.pod | 54 +- doc/man-pages/pod8/kadb_check.pod | 84 +- doc/man-pages/pod8/kas.pod | 260 +++-- doc/man-pages/pod8/kas_apropos.pod | 35 +- doc/man-pages/pod8/kas_create.pod | 116 ++- doc/man-pages/pod8/kas_delete.pod | 87 +- doc/man-pages/pod8/kas_examine.pod | 283 +++--- doc/man-pages/pod8/kas_forgetticket.pod | 29 +- doc/man-pages/pod8/kas_help.pod | 62 +- doc/man-pages/pod8/kas_interactive.pod | 147 ++- doc/man-pages/pod8/kas_list.pod | 120 ++- doc/man-pages/pod8/kas_listtickets.pod | 76 +- doc/man-pages/pod8/kas_noauthentication.pod | 39 +- doc/man-pages/pod8/kas_quit.pod | 24 +- doc/man-pages/pod8/kas_setfields.pod | 476 ++++----- doc/man-pages/pod8/kas_setpassword.pod | 169 ++-- doc/man-pages/pod8/kas_statistics.pod | 88 +- doc/man-pages/pod8/kas_stringtokey.pod | 50 +- doc/man-pages/pod8/kas_unlock.pod | 92 +- doc/man-pages/pod8/kaserver.pod | 166 ++- doc/man-pages/pod8/kdb.pod | 106 +- doc/man-pages/pod8/kpwvalid.pod | 44 +- doc/man-pages/pod8/package.pod | 170 ++-- doc/man-pages/pod8/package_apropos.pod | 69 -- doc/man-pages/pod8/package_help.pod | 99 -- doc/man-pages/pod8/package_test.pod | 53 - doc/man-pages/pod8/prdb_check.pod | 74 +- doc/man-pages/pod8/ptserver.pod | 102 +- doc/man-pages/pod8/salvager.pod | 350 +++---- doc/man-pages/pod8/upclient.pod | 208 ++-- doc/man-pages/pod8/upserver.pod | 158 ++- doc/man-pages/pod8/uss.pod | 113 +-- doc/man-pages/pod8/uss_add.pod | 384 ++++--- doc/man-pages/pod8/uss_apropos.pod | 38 +- doc/man-pages/pod8/uss_bulk.pod | 152 ++- doc/man-pages/pod8/uss_delete.pod | 131 ++- doc/man-pages/pod8/uss_help.pod | 61 +- doc/man-pages/pod8/vldb_check.pod | 77 +- doc/man-pages/pod8/vlserver.pod | 116 ++- doc/man-pages/pod8/volinfo.pod | 121 ++- doc/man-pages/pod8/volserver.pod | 103 +- doc/man-pages/pod8/xfs_size_check.pod | 25 +- doc/man-pages/pod8/xstat_fs_test.pod | 109 -- 128 files changed, 10536 insertions(+), 10002 deletions(-) rename doc/man-pages/{pod8 => pod1}/xstat_cm_test.pod (50%) create mode 100644 doc/man-pages/pod1/xstat_fs_test.pod create mode 100644 doc/man-pages/pod5/package.pod rename doc/man-pages/{pod8 => pod5}/tapeconfig.pod (89%) create mode 100644 doc/man-pages/pod5/uss.pod create mode 100644 doc/man-pages/pod5/uss_bulk.pod delete mode 100644 doc/man-pages/pod8/package_apropos.pod delete mode 100644 doc/man-pages/pod8/package_help.pod delete mode 100644 doc/man-pages/pod8/package_test.pod delete mode 100644 doc/man-pages/pod8/xstat_fs_test.pod diff --git a/doc/man-pages/README b/doc/man-pages/README index 15074a952..4bcfaef0a 100644 --- a/doc/man-pages/README +++ b/doc/man-pages/README @@ -223,6 +223,32 @@ Known Problems * 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 assumes 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. + 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/pod8/xstat_cm_test.pod b/doc/man-pages/pod1/xstat_cm_test.pod similarity index 50% rename from doc/man-pages/pod8/xstat_cm_test.pod rename to doc/man-pages/pod1/xstat_cm_test.pod index ce3981681..dea9ac995 100644 --- a/doc/man-pages/pod8/xstat_cm_test.pod +++ b/doc/man-pages/pod1/xstat_cm_test.pod @@ -4,22 +4,23 @@ xstat_cm_test - Displays data collections from the Cache Manager =head1 SYNOPSIS -B [B] -cmname >+ -B<-collID> >+ [B<-onceonly>] - [-frequency >] - [B<-period> >] [B<-debug>] [-help] - -B [B] -cm >+ -B<-co> >+ [B<-o>] - [-f >] - [B<-p> >] [B<-d>] [-h] +B [I] + B<-cmname> >+ + B<-collID> >+ [B<-onceonly>] + [B<-frequency> >] + [B<-period> >] [B<-debug>] + [B<-help>] + +B [I] B<-cm> >+ + B<-co> >+ [B<-o>] + [B<-f> >] + [B<-p> >] [B<-d>] [B<-h>] =head1 DESCRIPTION -The xstat_cm_test command tests the routines in the -B library and displays the data collections -associated with the Cache Manager. The command executes in the -foreground. +The B command tests the routines in the F +library and displays the data collections associated with the Cache +Manager. The command executes in the foreground. The command produces a large volume of output; to save it for later analysis, direct it to a file. @@ -28,17 +29,16 @@ analysis, direct it to a file. =over 4 -=item initcmd +=item I -Accommodates the command's use of the AFS command parser, and is -optional. +Accommodates the command's use of the AFS command parser, and is optional. -=item -cmname +=item B<-cmname> >+ Specifies the fully qualified hostname of each client machine for which to monitor the Cache Manager. -=item -collID +=item B<-collID> >+ Specifies each data collection to return, which defines the type and amount of data the command interpreter gathers about the Cache Manager. @@ -57,44 +57,44 @@ started. =item 1 Reports various internal performance statistics related to the Cache -Manager (for example, statistics about how effectively the cache is being used -and the quantity of intracell and intercell data access). +Manager (for example, statistics about how effectively the cache is being +used and the quantity of intracell and intercell data access). =item 2 -Reports all of the internal performance statistics provided by the -B<1> setting, plus some additional, detailed performance figures (for -example, statistics about the number of RPCs sent by the Cache Manager and how -long they take to complete, and statistics regarding authentication, access, +Reports all of the internal performance statistics provided by the C<1> +setting, plus some additional, detailed performance figures (for example, +statistics about the number of RPCs sent by the Cache Manager and how long +they take to complete, and statistics regarding authentication, access, and PAG information associated with data access). =back -=item -onceonly +=item B<-onceonly> -Gathers statistics just one time. Omit this flag to have the -command continue to probe the Cache Manager for statistics at the frequency -specified by the B<-frequency> argument; in this case press -> to stop the probes. +Gathers statistics just one time. Omit this flag to have the command +continue to probe the Cache Manager for statistics at the frequency +specified by the B<-frequency> argument; in this case press Ctrl-C to stop +the probes. -=item -frequency +=item B<-frequency> > Sets the frequency in seconds at which the program initiates probes to the Cache Manager. The default is 30 seconds. -=item -period +=item B<-period> > -Sets the number of minutes the program runs; at the end of this -period of time, the program exits. The default is 10 minutes. +Sets the number of minutes the program runs; at the end of this period of +time, the program exits. The default is 10 minutes. -=item -debug +=item B<-debug> Displays a trace on the standard output stream as the command runs. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back diff --git a/doc/man-pages/pod1/xstat_fs_test.pod b/doc/man-pages/pod1/xstat_fs_test.pod new file mode 100644 index 000000000..81c1555e1 --- /dev/null +++ b/doc/man-pages/pod1/xstat_fs_test.pod @@ -0,0 +1,107 @@ +=head1 NAME + +xstat_fs_test - Displays data collections from the File Server process + +=head1 SYNOPSIS + +B [I] B<-fsname> >+ + B<-collID> >+ [B<-onceonly>] + [B<-frequency> >] + [B<-period> >] [B<-debug>] [B<-help>] + +B [B] B<-fs> >+ + B<-c> >+ [B<-o>] + [B<-fr> >] + [B<-p> >] [B<-d>] [B<-h>] + +=head1 DESCRIPTION + +The B command tests the routines in the F +library and displays the data collections associated with the File Server +(the C process). The command executes in the foreground. + +The command produces a large volume of output; to save it for later +analysis, direct it to a file. + +=head1 OPTIONS + +=over 4 + +=item I + +Accommodates the command's use of the AFS command parser, and is optional. + +=item B<-fsname> >+ + +Specifies the fully qualified hostname of each file server machine for +which to monitor the File Server process. + +=item B<-collID> >+ + +Specifies each data collection to return, which defines the type and +amount of data the command interpreter gathers about the File Server. +Data is returned in a predefined data structure. + +There are three acceptable values: + +=over 4 + +=item 0 + +Provides profiling information about the numbers of times different +internal File Server routines were called since the File Server +started. This value is not currently implemented; it returns no data. + +=item 1 + +Reports various internal performance statistics related to the File Server +(for example, vnode cache entries and Rx protocol activity). + +=item 2 + +Reports all of the internal performance statistics provided by the C<1> +setting, plus some additional, detailed performance figures about the File +Server (for example, minimum, maximum, and cumulative statistics regarding +File Server RPCs, how long they take to complete, and how many succeed). + +=back + +=item B<-onceonly> + +Gathers statistics just one time. Omit this flag to have the command +continue to probe the Cache Manager for statistics at the frequency +specified by the B<-frequency> argument; in this case press Ctrl-C to stop +the probes. + +=item B<-frequency> > + +Sets the frequency in seconds at which the program initiates probes to the +Cache Manager. The default is 30 seconds. + +=item B<-period> > + +Sets the number of minutes the program runs; at the end of this period of +time, the program exits. The default is 10 minutes. + +=item B<-debug> + +Displays a trace on the standard output stream as the command runs. + +=item B<-help> + +Prints the online help for this command. All other valid options are +ignored. + +=back + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod5/package.pod b/doc/man-pages/pod5/package.pod new file mode 100644 index 000000000..6833d4dfa --- /dev/null +++ b/doc/man-pages/pod5/package.pod @@ -0,0 +1,878 @@ +=head1 NAME + +package Configuration File - Provides instructions for the package command + +=head1 DESCRIPTION + +The package configuration file defines the file system elements +that the B command creates or alters on the local disk of an +AFS client machine it is configuring. Use the B<-config> or +B<-fullconfig> argument to the B command to identify +the configuration file to use. + +Summary of Configuration File Instructions + +The configuration file can include one or more instances of each of the +following instructions, each on its own line. A more detailed +description of each instruction's syntax follows this list. + +=over 4 + +=item B + +Defines a block special device, such as a disk, which deals with input in +units of multi-byte command blocks + +=item C + +Defines a character special device, such as a terminal or tty, which deals +with input in single character units + +=item D + +Creates a directory + +=item F + +Creates or alters a file to match the contents of a specified source file + +=item L + +Creates a symbolic link + +=item S + +Defines a socket, which is a communications device for UDP and TCP/IP +connections + +=item %define + +Defines a variable or declares a string as defined + +=item %ifdef + +Specifies an action to perform if a certain string is declared or defined + +=item %ifndef + +Specifies an action to perform if a certain string is not declared or +defined + +=item %include + +Includes a library file + +=item %undef + +Declares a string not to be defined, or a variable no longer to have a +value + +=back + +The B and C Instructions for Defining Block and Character Special +Devices +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a package configuration file +defines a block special device, such as a disk, that deals with input in units +of multi-byte command blocks. The B instruction defines a +character special device, such as a terminal or tty, that deals with input in +single character units. They share a common syntax: + + {B| C} I I I I I I + +where + +=over 4 + +=item B + +Indicates the definition of a block special device. It must be a +capital letter. + +=item C + +Indicates the definition of character special device. It must be a +capital letter. + +=item I + +Names the special device to define. To learn the name format +appropriate to the machine's system type, consult the hardware or +operating system documentation. + +=item I + +Specifies the device's major device number in decimal format. +To learn the correct value for the machine's system type, consult the +hardware or operating system documentation. + +=item I + +Specifies the device's minor device number in one of hexadecimal, +octal, or decimal format. Precede a hexadecimal number with the string +B<0x> (zero and the letter B) or an octal number with a +B<0> (zero). A number without either prefix is interpreted as a +decimal. To learn the correct value for the machine's system type, +consult the hardware or operating system documentation. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the device's owner in the output from the UNIX B +command. + +=item I + +Specifies the group name or UNIX group ID (GID) of the group to be +designated the device's group in the output from the UNIX B command. + +=item I + +Defines the device's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +=back + +The D Instruction for Creating a Directory +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a package configuration file +creates a directory on the local disk. If a symbolic link, file, or +other element on the local disk has the same name, it is replaced with a +directory. If the directory already exists, its owner, group, and mode +bits are changed if necessary to conform with the instruction. The +instruction has the following syntax: + + D[I] I I I I + +where + +=over 4 + +=item D + +Indicates the creation of a directory. It must be a capital +letter. + +=item I + +Modulates the directory creation instruction. It is optional and +follows the letter B directly, without an intervening space. +Choose one of the two acceptable values: + +=over 4 + +=item X + +Indicates that the directory is a lost+found directory (used by +the B program). + +=item R + +Removes any subdirectory (along its contents) or file that exists in the +existing directory on the local disk but for which an instruction does not +appear in the configuration file. + +=back + +=item I + +Specifies the full pathname of the directory to create. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the directory's owner in the output from the UNIX B +command. + +=item I + +Specifies the name or UNIX group ID (GID) of the group to be designated +the directory's group in the output from the UNIX B +command. + +=item I + +Defines the directory's UNIX mode bits. Acceptable values are +the standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +=back + +The F Instruction for Creating or Updating a File +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a package configuration file +creates or updates a file on the local disk by copying in the contents of the +indicated source file, which can reside in AFS or on the local disk. If +the B command interpreter cannot access the source file, it +exits without executing any instruction in the configuration file. + +If a file with the same name already exists on disk, the package +command overwrites it with the contents of the source file, unless the +B update code is used to prevent that. To add a +B<.old> extension to the current version of the file, include +the B update code. To have the machine reboot automatically +after the B program completes, include the B +update code. + +If a symbolic link, directory, or other element on the local disk has the +same name, it is replaced with the file (a directory's contents are first +removed as necessary). + +The instruction has the following syntax: + + F[I] I I [I] + +where + +=over 4 + +=item F + +Indicates the creation or update of a file. It must be a capital +letter. + +=item I + +Modulates the file creation instruction. It is optional and follows +the letter B directly, without an intervening space. Choose +one or more of the four acceptable values, and list them in any order: + +=over 4 + +=item A + +Indicates that the pathname in the I field is the +complete pathname of the source file, including the filename. If this +argument is omitted, the B command appends the pathname in +the I< file> field to the pathname in the I field to +derive the source file's full name. This code allows the source +and target filenames to differ. + +=item I + +Preserves the existing file called I, rather than overwriting +it. + +=item O + +Saves the existing version of the file by appending a +B<.old> extension to it. + +=item Q + +Causes the package command to exit with status code +B<4> if it overwrites the file. If the standard +B-related changes have been made to the machine's AFS +initialization file, then status code B<4> causes the machine to +reboot automatically. Use this code when the machine must reboot if +updates to the file are to have any effect (for example, if the operating +system file--B or equivalent--has changed). + +=back + +=item I + +Specifies the complete pathname on the local disk of the file to create or +update, including the filename as the final element. + +=item I + +Specifies the pathname (local or AFS) of the file to copy to the local +disk. + +If the A update code is included, specify the source file's +complete pathname. Otherwise, the B command derives +the source file's full name by appending the I pathname to +this pathname. For example, if the B update code is not +included and the file B is the +source file for the B binary, the proper value in this +field is B. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the file's owner in the output from the UNIX B +command. + +To copy the source file's owner to the target file, leave this field +empty. In this case, the I and I fields +must also be empty. + +=item I + +Specifies the name or UNIX group ID (GID) of the group to be designated +the file's group in the output from the UNIX B +command. + +To copy the source file's group to the target file, leave this field +empty. In this case, the I< owner> and I fields +must also be empty. + +=item I + +Defines the file's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +To copy the source file's mode bits to the target file, leave this +field empty. In this case, the I and I fields +must also be empty. + +=back + +The L Instruction for Creating a Symbolic Link +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a package configuration file +creates a symbolic link on the local disk to a directory or file that exists +either in AFS or elsewhere on the local disk. As with the standard UNIX +B command, the link is created even if the actual file or +directory does not exist. + +If a file or directory on the local disk already has the same name, the +B command replaces it with a symbolic link. + +The instruction has the following syntax: + + L[I] I I [I] + +where + +=over 4 + +=item L + +Indicates the creation of a symbolic link. It must be a capital +letter. + +=item I + +Modulates the link creation instruction. It is optional and follows +the letter B directly, without an intervening space. Choose +one or both of the acceptable values, and list them in any order: + +=over 4 + +=item A + +Indicates that the pathname in the I field is the +complete pathname of the actual directory or file (including the filename for +a file). If this argument is omitted, the B command +appends the value in the I field to the pathname in the +I field to derive the actual directory or file's full +name. This code allows the name of the symbolic link and actual +directory or file to differ. + +=item I + +Preserves the existing symbolic link called I, rather than +overwriting it. + +=back + +=item I + +Specifies the complete local disk pathname of the symbolic link to +create. + +=item I + +Specifies the pathname (local or AFS) of the directory or file to which +the link refers. If the B update code is included, specify +the directory or file's complete pathname. Otherwise, the +B command derives the actual directory or file's full +name by appending the value in the I field to this +pathname. For example, if the B update code is not included +and B is a symbolic link to the file +B, the proper value in this +field is B. + +The package command interpreter correctly handles pathnames that +begin with the B<./> (period, slash) or +B<../> (two periods, slash) notation, interpreting them +relative to the current working directory from which the B +command is invoked. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the symbolic link's owner in the output from the UNIX B +command. + +To designate the issuer of the package command (usually, the +local superuser B) as the symbolic link's owner, leave this +field empty. In this case, the I and I +fields must also be empty. + +=item I + +Specifies the name or UNIX group ID (GID) of the group to be designated +the link's group in the output from the UNIX B +command. + +To have the symbolic link's group match the default group associated +with the B command's issuer, leave this field +empty. The issuer is usually the local superuser B and +the default group is designated in the issuer's entry in the local +B file or equivalent. If this field is left empty, +the I and I fields must also be empty. + +=item I + +Defines the symbolic link's UNIX mode bits. Acceptable values +are the standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +Leaving this field empty sets the symbolic link's mode bits to +B<777> (B). In this case, the I +and I fields must also be empty. + +=back + +The S Instruction for Creating a Socket +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a package configuration file +creates a socket (a communications device for UDP or TCP/IP connections) on +the local disk. The instruction has the following syntax: + + S I [I] + +where + +=over 4 + +=item S + +Indicates the creation of a socket. It must be a capital +letter. + +=item I + +Names the socket. The proper format depends on the local +machine's operating system. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the socket's owner in the output from the UNIX B +command. + +To designate the issuer of the package command (usually, the +local superuser B) as the socket's owner, leave this field +empty. In this case, the I and I fields +must also be empty. + +=item I + +Specifies the name or UNIX group ID (GID) of the group to be designated +the socket's group in the output from the UNIX B +command. + +To have the symbolic link's group match the default group associated +with the B command's issuer, leave this field +empty. The issuer is usually the local superuser B and +the default group is designated in the issuer's entry in the local +B file or equivalent. If this field is left empty, +the I and I fields must also be empty. + +=item I + +Defines the socket's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +Leaving this field empty sets the symbolic link's mode bits to +B<777> (B), modulated by the cell's +umask. In this case, the I and I fields must +also be empty. + +=back + +The %define or %undef Instructions Declaring or Undeclaring a +Definition +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B<%define> instruction in a package configuration +file declares or defines a variable, depending on its number of +arguments: + +=over 4 + +=item * + +If followed by a single argument, it declares that argument to be +defined. The argument is then available as a controller when mentioned +in B<%ifdef> and B<%ifndef> statements, which evaluate to +B and B respectively. + + +=item * + +If followed by two arguments, it defines the second argument as the value +of the first. When the first argument appears later in this prototype +or other prototype or library files as a variable--surrounded by curly +braces and preceded by a dollar sign, as in the example +C<${variable}>--the B command interpreter +substitutes the second argument for it. + + +=back + +The %undef statement negates the effect of a previous +B<%define> statement, declaring its argument to be defined no longer, +or to have a value no longer if it is a variable. + +The syntax for the two types of instruction are as follows: + + %define I + %define I I + %undef I + %undef I + +where + +=over 4 + +=item %define + +Indicates a definition statement. + +=item %undef + +Indicates a statement that negates a definition. + +=item I + +Names the string being declared by a %define statement, or +negated by an B<%undef> statement. + +=item I + +Specifies the name of the variable that a %define statement is +defining, or an B<%undef> statement is negating. + +=item I + +Specifies the value to substitute for the string in the I +field when it appears in the appropriate format (surrounded by curly braces +and preceded by a dollar sign, as in the example C<${variable}>), in +this or other prototype and library files. It can include one or more +words. + +=back + +The %ifdef and %ifndef Instructions for Specifying a Conditional +Action to Perform +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B<%ifdef> instruction in a package configuration +file specifies one or more actions to perform if the indicated string has been +declared by a single-argument B<%define> statement, or is a variable +for which a value has been defined by a two-argument B<%define> +statement. + +Similarly, the %ifndef instruction specifies one or more actions +to perform if the indicated string has not been declared or is a variable +without a value, either because no B<%define> statement has defined it +or an B<%undef> statement has undefined it. + +In both cases, the optional %else statement specifies one or +more alternate actions to perform if the first statement evaluates to +B. (For an B<%ifdef> statement, the +B<%else> statement is executed if the indicated string has never been +declared or is a variable without a value, or if an B<%undef> +statement has undefined either one; for an B<%ifndef> statement, +it is executed if the string has been declared or is a variable with a +value.) + +It is possible to nest any number of %ifdef and +B<%ifndef> statements. + +The two types of statement share a common syntax: + + %ifdef | ifndef I + I+ + [%else [I] + I+] + %endif I + +where + +=over 4 + +=item ifdef + +Indicates that the statement evaluates as true if the string in +the I field is declared or is a variable with a defined +value. + +=item ifndef + +Indicates that the statement evaluates as true if the string in +the I field is not declared or is a variable without a +defined value. + +=item I + +Specifies the string that must be declared or the variable name that must +have a defined value for an B<%ifdef> statement to evaluate as +B, which results in the specified action being performed. +For an B<%ifndef> statement, the string must not be declared or the +variable must have no defined value for the statement to evaluate as +B. The first and third occurrences of +I (the latter following the string B<%endif>) are +required. The second occurrence (following the string B<%else>) +is optional, serving only to clarify to which B<%ifdef> or +B<%ifndef> statement the B<%else> statement belongs. + +=item I + +Specifies each action to perform if the %ifdef or +B<%ifndef> statement evaluates as B. Each action +must appear on a separate line. Acceptable types of actions are other +statements beginning with a percent sign and definition instructions. + +=item I + +Specifies each action to perform if the %ifdef or +B<%ifndef> statement evaluates to B. Each action +must appear on a separate line. Acceptable types of actions are other +statements beginning with a percent sign and definition instructions. + +=back + +The %include Instruction for Including a Library File +L<(1)> +L<(1)> +L<(1)> + +The B<%include> instruction in a package configuration +file includes the contents of the indicated library file in a configuration +file that results from the compilation of the prototype file in which the +B<%include> instruction appears. It has the following +syntax: + + %include I + +where + +=over 4 + +=item %include + +Indicates a library file include statement. + +=item I + +Specifies the complete pathname of the library file to include. It +can be in AFS or on the local disk, and can include one or more +variables. + +=back + +=head1 CAUTIONS + +The configuration file must be completely correct. If there are any +syntax errors or incorrect values, the B command interpreter +exits without executing any instruction. + +=head1 EXAMPLES + +The following example B and C instructions define a +disk B with major and minor device numbers B<1> and +B<0> and mode bits of B<-rw-r--r-->, and a tty +B with major and minor device numbers B<6> and +B<5> and mode bits of B<-rw-rw-rw>. In both cases, the +owner is B and the owning group B. + + B /dev/hd0a 1 0 root wheel 644 + C /dev/ttyp5 6 5 root wheel 666 + +The following example D instruction creates the local +B directory with owner B and group +B and mode bits of B. The +B update code removes any files and subdirectories that reside in +the B directory (if it already exists) but do not appear in the +configuration file. + + DR /usr root wheel 755 + +The following example F instruction, appropriate for a machine +running AIX 4.2 in the ABC Corporation cell, creates or updates the +local disk file B, using +B as the source. + + F /bin/grep /afs/abc.com/rs_aix42 root wheel 755 + +The next example F instruction creates the +B file and specifies an absolute pathname for +the source file, as indicated by the B update code. The +B code makes the B command return status code 4 as +it exits, prompting a reboot of the machine if the standard +B-related changes have been made to the machine's AFS +initialization file. No values are provided for the owner, group and +mode bits, so the file inherits them from the source file. + + FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell + +The following example L instruction, appropriate for a machine +running AIX 4.2 in the ABC Corporation cell, creates a symbolic link +from B on the local disk to the file +B. + + L /etc/ftpd /afs/abc.com/rs_aix42 root wheel 644 + +The following example S instruction defines the socket +B. + + + S /dev/printer root wheel 777 + + +The following example %define instruction defines the value for +the variable C<${diskmode}>. This variable is used elsewhere in +the template to fill the I, I, and +I fields in a B, B, or B +instruction. + + %define diskmode root wheel 644 + +The following example %undef instruction declares the string +B not to be defined. + + %undef afsd + +The following example %ifdef instruction specifies that if the +string C is currently declared, then when the prototype file +containing the instruction is compiled the three indicated library files are +included. There is no alternate action defined. There must be +B<%define> statements earlier in the prototype file to declare +B and to assign a value to the C<${wsadmin}> +variable. + + %ifdef rs_aix42 + %include ${wsadmin}/lib/rs_aix42.readonly + %include ${wsadmin}/lib/rs_aix42.generic + %include ${wsadmin}/lib/rs_aix42.generic.dev + %endif rs_aix42 + +The following example %ifndef instruction, appropriate for the +State University cell, defines C as the value of +the C<${cell}> variable if it does not already have a value. + + %ifndef cell + %define cell stateu.edu + %endif cell + +The following example %include instruction includes the library +file B from the B subdirectory of +the directory in which B-related files reside. The +C<${wsadmin}> variable resolves to an actual pathname (such as +B) during compilation. + + %include ${wsadmin}/lib/base.generic + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/tapeconfig.pod b/doc/man-pages/pod5/tapeconfig.pod similarity index 89% rename from doc/man-pages/pod8/tapeconfig.pod rename to doc/man-pages/pod5/tapeconfig.pod index 49e657e56..b7d09019d 100644 --- a/doc/man-pages/pod8/tapeconfig.pod +++ b/doc/man-pages/pod5/tapeconfig.pod @@ -8,7 +8,7 @@ on a Tape Coordinator machine The tapeconfig file defines basic configuration parameters for all of the tape devices or backup data files available for backup operations on a Tape Coordinator machine. The file is in ASCII format and must -reside in the local B directory. The +reside in the local F directory. The instruction for each tape device or backup data file appears on its own line and each has the following format: @@ -19,7 +19,6 @@ where =over 4 =item I Specifies the capacity of the tapes used with a tape device, or the amount of data to write into a backup data file. The Tape Coordinator refers @@ -36,7 +35,6 @@ can write to the tape or file during a B or B operation. If there is already a capacity value on the label, the Tape Coordinator uses it instead. - =item * When the -size argument is omitted the first time the @@ -44,7 +42,6 @@ B command is used on a given tape or file. The Tape Coordinator copies this value into the label's capacity field. - =back The Tape Coordinator uses this capacity value or the one on the Backup @@ -75,22 +72,18 @@ default is kilobytes. Bor K for kilobytes (KB) - =item * B or M for megabytes (MB) - =item * B or G for gigabytes (GB) - =item * B or T for terabytes (TB) - =back If this field is omitted, the Tape Coordinator uses the maximum acceptable @@ -98,7 +91,6 @@ value (2048 GB or 2 TB). Either leave both this field and the I field empty, or provide a value in both of them. =item I Specifies the size of a tape device's filemarks (also called end-of-file or EOF marks), which is set by the device's @@ -126,27 +118,25 @@ If this field is empty, the Tape Coordinator uses the value 0 empty, or provide a value in both of them. =item I Specifies the complete pathname of the tape device or backup data file. The format of tape device names depends on the operating system, but on UNIX systems device names generally begin with the string -B. For a backup data file, this field defines the +F. For a backup data file, this field defines the complete pathname; for a discussion of suggested naming conventions see the description of the B instruction in L(1)>. =item I Specifies the port offset number associated with this combination of Tape Coordinator and tape device or backup data file. -Acceptable values are the integers B<0> through 58510 +Acceptable values are the integers C<0> through 58510 (the Backup System can track a maximum of 58,511 port offset numbers). Each value must be unique among the cell's Tape Coordinators, but any number of them can be associated with a single machine. Port offset numbers need not be assigned sequentially, and can appear in any order in the -B file. Assign port offset B<0> to the Tape +B file. Assign port offset C<0> to the Tape Coordinator for the tape device or backup data file used most often for backup operations; doing so will allow the operator to omit the B<-portoffset> argument from the largest possible number of @@ -158,21 +148,21 @@ B commands. Creating the file requires UNIX B (write) and B (B) permissions on the -B directory. Editing the file requires UNIX +F directory. Editing the file requires UNIX B (B) permission on the file. =head1 EXAMPLES The following example tapeconfig file configures three tape devices and a backup data file. The first device has device name -B, and is assigned port offset B<0> because it +F, and is assigned port offset C<0> because it will be the most frequently used device for all backup operations in the cell. Its default tape capacity is 2 GB and filemark size is 1 -MB. The B drive has half the capacity but a much -smaller filemark size; its port offset is B<3>. The third -device listed, B, has the same capacity and filemark size -as the first device and is assigned port offset B<2>. Port -offset B<4> is assigned to the backup data file B, +MB. The F drive has half the capacity but a much +smaller filemark size; its port offset is C<3>. The third +device listed, F, has the same capacity and filemark size +as the first device and is assigned port offset C<2>. Port +offset C<4> is assigned to the backup data file F, which is actually a symbolic link to the actual file located elsewhere on the local disk. The Tape Coordinator writes up to 1.5 GB into the file; as recommended, the filemark size is set to zero. @@ -184,10 +174,10 @@ file; as recommended, the filemark size is set to zero. =head1 SEE ALSO -L, -L, -L, -L, +L, +L, +L, +L, L, L diff --git a/doc/man-pages/pod5/uss.pod b/doc/man-pages/pod5/uss.pod new file mode 100644 index 000000000..bec37e534 --- /dev/null +++ b/doc/man-pages/pod5/uss.pod @@ -0,0 +1,952 @@ +=head1 NAME + +uss Template File - Provides instructions for the uss add command + +=head1 DESCRIPTION + +The uss template file defines the components of an AFS user +account that the B command (or B instruction in +a B bulk input file) creates. Use the B<-template> +argument to the B or B command to identify +the template file. + +Summary of Template File Instructions + +The template file can include the following instructions, each on its own +line. A more detailed description of each instruction's syntax +follows this list. + +=over 4 + +=item A + +Imposes restrictions on user passwords and authentication attempts + +=item D + +Creates a directory + +=item E + +Creates a single-line file + +=item F + +Creates a file by copying a prototype + +=item G + +Defines a directory that is one of a set of parent directories into which +the B command interpreter evenly distributes newly created home +directories + +=item L + +Creates a hard link + +=item S + +Creates a symbolic link + +=item V + +Creates a volume, mounts it in the file space and sets the ACL on the +mount point + +=item X + +Executes a command + +=back + +If the template file is empty (zero-length), the uss add command +or B instruction in a bulk input file only creates an entry in +the Protection and Authentication Databases, naming them according to the name +specified with the B command's B<-user> +argument, or in the bulk input file B instruction's +I field. + +The A Instruction for Setting the Default Treatment of Volumes +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file enhances +cell security by imposing the following restrictions on users' password +choice and authentication attempts. For further information on these +limits, see the I and the B reference page. + +=over 4 + +=item * + +Limiting the user's password lifetime. When the lifetime +expires, the user can no longer authenticate using that password, and must +change it. + + +=item * + +Prohibiting the reuse of the user's 20 most recently used +passwords. + + +=item * + +Limiting the number of consecutive times that a user can provide an +incorrect password during authentication, and for how long the Authentication +Server refuses further authentication attempts after the limit is exceeded +(referred to as an I). For regular user +accounts in most cells, the recommended limit is nine and lockout time is 25 +minutes. + + +=back + +The instruction has the following syntax: + + A I I I I I + +where + +=over 4 + +=item A + +Indicates a security-enhancing instruction. It must be a capital +letter. + +=item I + +Names the Authentication Database entry on which to impose security +restrictions. Specify the value B<$USER> to read in the +username from the B command's B<-user> argument, +or from the I field of an B instruction in a bulk +input file. + +=item I + +Sets the number of days after the user's password is changed that it +remains valid. When the password becomes invalid (expires), the user is +unable to authenticate, but has 30 more days in which to issue the +B command to change the password (after that, only an +administrator can change it). + +Specify an integer from the range B<1> through 254 to +specify the number of days until expiration, the value B<0> to +indicate that the password never expires, or the value B<$PWEXPIRES> +to read in the number of days from the B or B command's B<-pwexpires> argument. If the +B instruction does not appear in the template file, the default is +for the user's password never to expire. + +=item I + +Determines whether or not the user can change his or her password (using +the B or B command) to one that is +similar to any of the last twenty passwords. The acceptable values are +B to allow reuse and B to prohibit it. +If the B instruction does not appear in the template file, the +default is to allow password reuse. + +=item I + +Sets the number of consecutive times the user can provide an incorrect +password during authentication (using the B command or a login +utility that grants AFS tokens). When the user exceeds the limit, the +Authentication Server rejects further authentication attempts for the amount +of time specified in the I field. + +Specify an integer from the range B<1> through 254 to +specify the number of failures permitted, or the value B<0> to +indicate that there is no limit to the number of unsuccessful attempts. +If the B instruction does not appear in the template file, the +default is to allow an unlimited number of failures. + +=item I + +Specifies how long the Authentication Server refuses authentication +attempts from a user who has exceeded the failure limit set in the +I field. + +Specify a number of hours and minutes (I) or minutes +only (I), from the range B<01> (one minute) through +B<36:00> (36 hours). The Authentication Server +automatically reduces any larger value to B<36:00> and also +rounds up any non-zero value to the next higher multiple of 8.5 +minutes. A value of B<0> (zero) sets an infinite lockout +time; an administrator must always issue the B +command to unlock the account. + +=back + +The D Instruction for Creating a Directory +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file creates a +directory. Its intended use is to create a subdirectory in the user +home directory created by the B instruction in the template +file. + +Any number of D instructions can appear in the template +file. If any variables in the instruction take their values from the +B instruction (notably, the $MTPT variable), the instruction must +follow the B instruction in the file. + +Although it is possible to use the D instruction to create a +directory on the local disk of the machine where the B command is +issued, it is not recommended. The preferred method for automated +creation of directories on a local disk is the B +program. Two complications arise if the I field refers +to a local disk directory: + +=over 4 + +=item * + +The uss command prints a warning message because it cannot +associate an access control list (ACL) with a local disk directory. It +creates the directory nonetheless, and some syntactically correct value must +appear in the instruction's I field. + + +=item * + +To designate any user other than the issuer as the new directory's +owner, the issuer must log onto the machine as the local superuser +B. For local disk directories, only the local superuser +B is allowed to issue the UNIX B command that the +B command interpreter invokes to change the owner from the +default value (the directory's creator, which in this case is the issuer +of the B command). The issuer must then also use the +B<-admin> argument to the B or B +command to authenticate as a privileged AFS administrator, which is required +for creating the Authentication Database and Protection Database entries that +the B command interpreter always creates for a new +account. + + +=back + +The instruction has the following syntax: + + D I I I I + +where + +=over 4 + +=item D + +Indicates a directory creation instruction. It must be a capital +letter. + +=item I + +Specifies the directory's full pathname. It can include +variables. + +Specify the read/write path to the directory, to avoid the failure that +results from attempting to create a new directory in a read-only +volume. By convention, the read/write path is indicated by placing a +period before the cell name at the pathname's second level (for example, +B). For further discussion of the +concept of read/write and read-only paths through the filespace, see the +reference page for the B command. + +=item I + +Sets the directory's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. The +first (owner) B bit must be turned on to enable access to a +directory. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the directory's owner in the output from the UNIX B +command. If the directory resides in AFS, place the $UID variable in +this field. If the directory resides on the local disk, this field must +be the username or UID of the B command's issuer, unless the +issuer is logged in as the local superuser B. + +=item I + +Sets the ACL on the new directory. It must appear even if the new +directory resides on the local disk rather than in AFS, but is ignored in that +case. Provide one or more paired values, each pair consisting of an AFS +username or group name and the desired permissions, in that order. +Separate the two parts of the pair, and each pair, with a space. The +B reference page describes the available +permissions. + +For an AFS directory, grant all permissions to the directory's owner +at least. Usually that is the new user, in which case the appropriate +value is B<$USER all>. + +It is not possible to grant any permissions to the issuer of the +B command. As the last step in account creation, the +B command interpreter automatically deletes that person from any +ACLs set during the creation process. + +=back + +The E Instruction for Creating a Single-line File +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file creates a +file by echoing a specified character string into it. Its intended use +is to create files in the user home directory created by the B +instruction in the template file, or in a subdirectory created by a +B instruction. + +Any number of E instructions can appear in the template +file. If the file resides in a directory created by a B +instruction, the B instruction must follow the B +instruction in the file. + +The B and F instructions have complementary +advantages. The character string echoed into the file by an +B instruction can be customized for each user, because it can +include the standard variables for which the B command +interpreter substitutes the values specified by arguments to the B command or fields in a bulk input file B +instruction. In contrast, a file created using the B +instruction cannot include variables and so has the same content for all +users. However, a file created by an B instruction can be a +single line only, because no carriage returns (newline characters) are allowed +in the character string. + +Although it is possible to use the E instruction to create a +file on the local disk of the machine where the B command is +issued, it is not recommended. The preferred method for automated +creation of files on a local disk is the B program. +The main complication is that designating any user other than the issuer as +the new file's owner requires logging onto the machine as the local +superuser B. For local disk files, only the local +superuser B is allowed to issue the UNIX B +command that the B command interpreter invokes to change the +owner from the default value (the file's creator, which in this case is +the issuer of the B command). The issuer must then also +use the B<-admin> argument to the B or B command to authenticate as a privileged AFS administrator, which is +required for creating the Authentication Database and Protection Database +entries that the B command interpreter always creates for a new +account. + +The instruction has the following syntax: + + E I I I "I" + +where + +=over 4 + +=item E + +Indicates a file creation instruction. It must be a capital +letter. + +=item I + +Specifies the file's full pathname. It can include +variables. + +Specify the read/write path to the file, to avoid the failure that results +from attempting to create a new file in a read-only volume. By +convention, the read/write path is indicated by placing a period before the +cell name at the pathname's second level (for example, +B). For further discussion of the +concept of read/write and read-only paths through the filespace, see the +reference page for the B command. + +=item I + +Sets the file's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the file's owner in the output from the UNIX B +command. If the file resides in AFS, place the $UID variable in this +field. If the file resides on the local disk, specify the username or +UID of the B command's issuer; otherwise, the account +creation operation halts immediately. + +=item I + +Specifies the one-line character string to write into the new file. +Surround it with double quotes if it contains one or more spaces. It +cannot contain the newline character, but can contain any of the standard +variables, which the command interpreter resolves as it creates the +file. + +=back + +L<(1)>The F Instruction for Creating a File +from a Prototype +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file creates a +file by copying the contents of an existing file (the I) +into it. Its intended use is to create files in the user home directory +created by the B instruction in the template file, or in a +subdirectory created by a B instruction. + +Any number of F instructions can appear in the template +file. If the file resides in a directory created by a B +instruction, the B instruction must follow the B +instruction in the file. + +The B and F instructions have complementary +advantages. A file created using the B instruction has the +same content for all users, whereas a file created by an B +instruction can be customized for each user if it includes variables. +However, a file created by an B instruction can be a single line +only, whereas the prototype file copied by an B instruction can be +any length. + +Although it is possible to use the F instruction to create a +file on the local disk of the machine where the B command is +issued, it is not recommended. The preferred method for automated +creation of files on a local disk is the B program. +The main complication is that designating any user other than the issuer as +the new file's owner requires logging onto the machine as the local +superuser B. For local disk files, only the local +superuser B is allowed to issue the UNIX B +command that the B command interpreter invokes to change the +owner from the default value (the file's creator, which in this case is +the issuer of the B command). The issuer must then also +use the B<-admin> argument to the B or B command to authenticate as a privileged AFS administrator, which is +required for creating the Authentication Database and Protection Database +entries that the B command interpreter always creates for a new +account. + +The instruction has the following syntax: + + F I I I I + +where + +=over 4 + +=item F + +Indicates a file creation instruction. It must be a capital +letter. + +=item I + +Specifies the full pathname of the file to create, including the +filename. It can include variables. + +Specify the read/write path to the file, to avoid the failure that results +from attempting to create a new file in a read-only volume. By +convention, the read/write path is indicated by placing a period before the +cell name at the pathname's second level (for example, +B). For further discussion of the +concept of read/write and read-only paths through the filespace, see the +reference page for the B command. + +=item I + +Sets the file's UNIX mode bits. Acceptable values are the +standard three- or four-digit numbers corresponding to combinations of +permissions. Examples: B<755> corresponds to +B, and B<644> to B. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the file's owner in the output from the UNIX B +command. If the file resides in AFS, place the $UID variable in this +field. If the file resides on the local disk, specify the username or +UID of the B command's issuer; otherwise, the account +creation operation halts immediately. + +=item I + +Names the AFS or local disk directory that houses the prototype file to +copy. The prototype file's name must match the final element in +the I field. + +=back + +L<(1)>The G Instruction for Facilitating Even +Distribution of Home Directories +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file creates a +directory as one of the set of directories from which the B +command interpreter selects when choosing a new user home directory's +parent directory. More specifically, when the $AUTO variable appears in +the I field of a B instruction, the command +interpreter substitutes for it the directory defined by a B +instruction that currently has the fewest entries. + +The instruction's intended use is to distribute user accounts evenly +among several directories, rather than using directories that reflect +divisions such as departmental affiliation. Distributing home +directories in this fashion is useful mainly in very large cells where storing +all user home directories under a single parent directory potentially slows +directory lookup, or where a workplace-based division results in unevenly +sized directories such that some users consistently experience slower +directory lookup than others. See the chapter on B in the +I for more information. + +Any number of G instructions can appear in the template +file. If the B instruction includes the $AUTO variable, it +must appear after all of the B instructions in the file. + +The instruction has the following syntax: + + G I + +where + +=over 4 + +=item G + +Indicates an instruction that creates a directory to be considered as a +value for the $AUTO variable. It must be a capital letter. + +=item I + +Specifies the directory's name as either a complete pathname or only +the directory name. The choice determines the appropriate format for +the I field of a B instruction, as discussed in +the following example. + +Specify the read/write path to the directory, to avoid the failure that +results from attempting to create a new mount point in a read-only volume when +the $AUTO variable is used in a B instruction's +I field. By convention, the read/write path is +indicated by placing a period before the cell name at the pathname's +second level (for example, B). For +further discussion of the concept of read/write and read-only paths through +the filespace, see the reference page for the B +command. + +=back + +The L and S Instructions for Creating a Link +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file creates a +hard link between two files, as achieved by the standard UNIX B +command. The B instruction creates a symbolic link between +two files, as achieved by the standard UNIX B command. A +full explanation of links is beyond the scope of this document, but the basic +effect is to create a second name for an existing file, enabling access via +either name. Creating a link does not create a second copy of the +file. + +AFS allows hard links only if the linked files reside in the same +directory, because it becomes difficult to determine which access control list +(ACL) applies to the file if the two copies reside in directories with +different ACLs. AFS allows symbolic links between two files that reside +in different directories, or even different volumes. The File Server +uses the ACL associated with the actual file rather than the link. + +Any number of B and S instructions can appear in the +template file. If the existing file or link is to reside in a directory +created by a B instruction, or if the existing file was created by +an B or B instruction, the B or B +instruction must follow the B, B, or B +instruction. + +The instructions share the following syntax: + + L I I + S I I + +where + +=over 4 + +=item L + +Indicates a hard link creation instruction. It must be a capital +letter. + +=item S + +Indicates a symbolic link creation instruction. It must be a +capital letter. + +=item I + +Specifies the complete pathname of the existing file. + +=item I + +Specifies the complete pathname of the second name for the file. + +Specify the read/write path to the link, to avoid the failure that results +from attempting to create a new link in a read-only volume. By +convention, the read/write path is indicated by placing a period before the +cell name at the pathname's second level (for example, +B). For further discussion of the +concept of read/write and read-only paths through the filespace, see the +reference page for the B command. + +=back + +L<(1)>The V Instruction for Creating and +Mounting a Volume +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file creates a +volume on a specified file server machine and partition and creates an entry +for it in the Volume Location Database (VLDB). It mounts the volume at +a location in the AFS file space that becomes the user's home directory, +then designates the directory's owner and sets its access control list +(ACL). + +Only one V instruction can appear in the template file, and one +must appear if the template file contains any instructions at all (is not +empty). All other instructions are optional, except that the template +must include B instructions if the $AUTO variable appears in +it. (The B instruction is not necessarily the first line in +the template. If the template includes the $AUTO variable, then the +B instructions which provide values for the variable must precede +it in the file.) + +The instruction has the following syntax: + + V I I I I I I I + +where + +=over 4 + +=item V + +Indicates a volume creation instruction. It must be a capital +letter. + +=item I + +Specifies the volume's name. To follow the convention for AFS +user volume names, specify the value B. +Provide a value for the $USER variable via the B +command's B<-user> argument or the I field in the +bulk input file B instruction. + +=item I + +Names the file server machine on which to create the new user's +volume. It is best to provide the fully-qualified hostname (for +example, B), but an abbreviated form is +acceptable provided that the cell's naming service is available to +resolve it at the time the volume is created. To read in the value from +the B command's B<-server> argument, specify the +value B<$SERVER>. + +=item I + +Specifies the partition on which to create the user's volume; it +must be on the file server machine named in the I field. +Identify the partition by its complete name (for example, B) +or use or use one of the following abbreviations. + + B = B = B = 0 + B = B = B = 1 + +After /vicepz (for which the index is 25) comes + + B = B = B = 26 + B = B = B = 27 + +and so on through + + B = B = B = 255 + +To read in the value from the uss add command's +B<-partition> argument, specify the value B<$PART>. + +=item I + +Sets the maximum number of kilobyte blocks the volume can occupy on the +file server machine's disk. Specify an integer constant if all +volumes have the same quota (B<1024> equals a megabyte), or use one of +the number variables ($1 through $9) to assign different values to different +volumes. + +=item I + +Creates a mount point for the volume, which serves as the volume's +root directory. Include the $USER variable as part of the pathname to +follow the convention that user home directory names include the +username. + +Specify the read/write path to the mount point, to avoid the failure that +results from attempting to create a new mount point in a read-only +volume. By convention, the read/write path is indicated by placing a +period before the cell name at the pathname's second level (for example, +B). If the $AUTO variable appears +in this field, the directories named by each B instruction possibly +already indicate the read/write path. For further discussion of the +concept of read/write and read-only paths through the filespace, see the +reference page for the B command.. + +=item I + +Specifies the username or UNIX user ID (UID) of the user to be designated +the mount point's owner in the output from the UNIX B +command. To follow the convention for home directory ownership, place +the value B<$UID> in this field. + +=item I + +Sets the ACL on the new directory. Provide one or more paired +values, each pair consisting of an AFS username or group name and the desired +permissions, in that order. Separate the two parts of the pair, and +each pair, with a space. The B reference page +describes the available permissions. + +Grant all permissions to the new user at least. The appropriate +value is B<$USER all>. + +AFS automatically grants the system:administrators group +all permissions as well. It is not possible to grant any permissions to +the issuer of the B command. As the last step in account +creation, the B command interpreter automatically deletes that +user from any ACLs set during the creation process. + +=back + +L<(1)>The X Instruction for Running a +Command +L<(1)> +L<(1)> +L<(1)> + +The B instruction in a uss template file runs the +indicated command, which can be a standard UNIX or AFS command. It can +include any variables from the template file, which the B command +interpreter resolves before passing the command on to the appropriate other +command interpreter. It must be a single line only, however (cannot +contain carriage returns or newline characters). + +Any number of X instructions can appear in the template +file. If an instruction manipulates an element created by another +instruction, it must follow that instruction in the file. + +The instruction has the following syntax: + + BI" + +where + +=over 4 + +=item X + +Indicates a command execution instruction. It must be a capital +letter. + +=item I + +Specifies the command to run. Surround it with double quotes as +shown if it contains one or more spaces. It can contain any variables +from the template file, but not newline characters. + +=back + +=head1 EXAMPLES + +The following example A instruction sets a password lifetime of +254 days, prohibits password reuse, limits the number of consecutive failed +authentication attempts to nine and sets the corresponding locktime to +25:30 minutes (which is a multiple of 8.5 minutes). The +username is read in from the B<-user> argument to the B command or from the I field in each B +instruction in a bulk input file. + + A $USER 254 noreuse 9 25:30 + +The following example D instruction creates a directory called +I in a new user's home directory, designates the user as +the directory's owner, and grants him or her all ACL permissions. + + D $MTPT/public 0755 $UID $USER all + +The following example E instruction creates a file in the +current working directory called +I.B. The contents are an entry +suitable for incorporating into the cell's global +B file. + + E $USER.etcp 0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh" + +The following example F instruction, appropriate for the ABC +Corporation cell, copies a prototype B<.login> file into the +user's home directory. + + F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login + +In the following example, the State University cell's administrators +have decided to distribute user home directories evenly into three +directories. They define three B instructions: + + G usr1 + G usr2 + G usr3 + +and then put the following value in the I field of the +B instruction: + + /afs/stateu.edu/$AUTO/$USER + +Alternatively, if they include the entire directory pathname in the +B instruction: + + G /afs/stateu.edu/usr1 + G /afs/stateu.edu/usr2 + G /afs/stateu.edu/usr3 + +then the I field of the V instruction +specifies only the following: + + $AUTO/$USER + +The following example L instruction creates a hard link between +the files B and B in the user's home +directory. + + L $MTPT/mbox $MTPT/mail + +The following example S instruction, appropriate for the ABC +Corporation cell, links the file B in the user's +home directory to the file +B. + + S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing + +The following example V instruction creates a volume called +BI on the B partition +of the specified file server machine, assigning it a quota of 3000 kilobyte +blocks. The mount point is under B and +matches the username (the value of the $USER variable). The user owns +the home directory and has all access rights to it. The instruction +appears on two lines only for legibility; it must appear on a single line +in the template file. + + V user.$USER $SERVER.abc.com /vicepa 3000 \ + /afs/abc.com/usr/$USER $UID $USER all + +The following example X instruction mounts the backup version of +the user's volume at the B subdirectory. + + X "fs mkm /afs/abc.com/usr/$USER/OldFiles user.$USER.backup" + +=head1 SEE ALSO + +L + +L, +L + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod5/uss_bulk.pod b/doc/man-pages/pod5/uss_bulk.pod new file mode 100644 index 000000000..213f502ce --- /dev/null +++ b/doc/man-pages/pod5/uss_bulk.pod @@ -0,0 +1,407 @@ +=head1 NAME + +uss Bulk Input File - Provides instructions for the uss bulk command + +=head1 DESCRIPTION + +The uss bulk input file lists instructions for the +B command interpreter to execute when running the B command. If the file includes B instructions +that reference a B template file, then the template file must +also exist. + +Summary of Bulk Input File Instructions + +The bulk input file can include the following instructions, each on its own +line. A more detailed description of each instruction's syntax +follows this list. + +=over 4 + +=item add + +Creates a user account. Equivalent to the uss add +command. + +=item delete + +Deletes a user account. Equivalent to the uss delete +command. + +=item delvolume + +Removes the volume and VLDB entry for each account referenced by a +B instruction that follows this instruction in the bulk input +file. + +=item exec + +Executes a command. + +=item savevolume + +Preserves the volume and VLDB entry for each account referenced by a +B instruction that follows this instruction in the bulk input +file. + +=back + +The add Instruction for Creating an Account +L<(1)> +L<(1)> + +The add instruction creates a user account. Each instance +in the bulk input file is equivalent in effect to a B command +issued on the command line. The order of the instruction's fields +matches the order of arguments to the B command, although +some arguments do not have a corresponding field. Like the B command's arguments, many of the fields correspond to (provide +a value for) a variable in the B template file, as indicated in +the following description of each field. + +The instruction's syntax is as follows. It appears on multiple +lines here only for the sake of legibility--each B +instruction must appear on a single line in the bulk input file. + + add I[:I][:I][:I] + [:I][:I][:I][:I][:I][:I] + [:I][:I][:I][:I][:I][:I][:I][:] + +To omit a value for a field (presumably because it is optional or the +template specifies a constant value for it), type nothing between the two +colons that surround it. After the last argument provided, end the line +with either a colon and carriage return, or a carriage return alone. + +The meaning of, and acceptable values for, each field are as +follows. + +=over 4 + +=item I + +Names the user's Authentication Database and Protection Database +entries. It can include up to eight alphanumeric characters, but not +the B<:> (colon), B<.> (period), or B<@> +(at-sign) characters. Because it becomes the username (the name under +which a user logs in), it is best not to include shell metacharacters and to +obey the restrictions that many operating systems impose on usernames +(usually, to contain no more than eight lowercase letters). + +Corresponding argument to the uss add command: +B<-user>. Corresponding variable in the template file: +$USER. + +=item I + +Specifies the user's full name. Do not surround it with double +quotes (""), even if it contains spaces. If not provided, it defaults +to the username in the I field. + +Corresponding argument to the uss add command: +B<-realname>. Corresponding variable in the template +file: $NAME. Many operating systems include a field for the full +name in a user's entry in the local password file (B +or equivalent), and this variable can be used to pass a value to be used in +that field. + +=item I + +Specifies the user's initial password. Although the AFS +commands that handle passwords accept strings of virtually unlimited length, +it is best to use a password of eight characters or less, which is the maximum +length that many applications and utilities accept. If not provided, +this argument defaults to the string B. + +Corresponding argument to the uss add command: +B<-pass>. Corresponding variable in the template file: +none. + +=item I + +Sets the number of days after a user's password is changed that it +remains valid. Provide an integer from the range B<1> through +B<254> to specify the number of days until expiration, or the value +B<0> to indicate that the password never expires (the default). + +When the password becomes invalid (expires), the user is unable to +authenticate, but has 30 more days in which to issue the B +command to change the password (after that, only an administrator can change +it). + +Corresponding argument to the uss add command: +B<-pwexpires>. Corresponding variable in the template +file: $PWEXPIRES. + +=item I + +Names the file server machine on which to create the new user's +volume. It is best to provide a fully-qualified hostname (for example, +B), but an abbreviated form is acceptable +provided that the cell's naming service is available to resolve it at the +time the volume is created. + +Corresponding argument to the uss add command: +B<-server>. Corresponding variable in the template file: +$SERVER. + +=item I + +Specifies the partition on which to create the user's volume; it +must reside on the file server machine named in the I +field. Identify the partition by its complete name (for example, +B, or use one of the following abbreviations: + + B = B = B = 0 + B = B = B = 1 + +After /vicepz (for which the index is 25) comes + + B = B = B = 26 + B = B = B = 27 + +and so on through + + B = B = B = 255 + +Corresponding argument to the uss add command: +B<-partition>. Corresponding variable in template: +$PART. + +=item I + +Specifies the complete pathname for the user's home directory. + +Corresponding argument to the uss add command: +B<-mount>. + +Corresponding variable in template: $MTPT, but in the template +file's B instruction only. Occurrences of the $MTPT +variable in template instructions that follow the B instruction +take their value from the B instruction's I +field. Thus the value of this command line argument becomes the value +for the $MTPT variable in instructions that follow the B +instruction only if the string $MTPT appears alone in the B +instruction's I field. + +=item I + +Specifies a positive integer other than 0 (zero) to assign as +the user's AFS UID. If this argument is omitted, the Protection +Server assigns an AFS UID that is one greater than the current value of the +C C C counter (use the B command to display the counter). If including this +argument, first use the B command to verify that no +existing account already has the desired AFS UID; if one does, the +account-creation process terminates with an error. + +Corresponding argument to the uss add command: +B<-uid>. Corresponding variable in template: $UID. + +=item I +> + +Specifies values for each of the number variables $1 through $9 that can +appear in the template file. The number variables allow the +administrator to provide values for variables other than the set defined by +the B command suite. + +Corresponding argument to the uss add command: +B<-var>. Corresponding variables in template: $1 through +$9. + +If providing a value in any of the fields, then in every field that +precedes it either provide an actual value or indicate an empty field by +putting nothing between two colons. It is acceptable, but not +necessary, to indicate empty fields by putting colons after the last field +that contains an actual value. + +=back + +The delete Instruction for Deleting an Account +L<(1)> +L<(1)> + +The delete instruction deletes a user account from the +system. Each instance in the bulk input file is equivalent in effect to +a B command issued on the command line. The order +of the instruction's fields matches the order of arguments to the +B command: + + delete I:I[:{ savevolume | delvolume }][:] + +where + +=over 4 + +=item I + +Names the entry to delete from the Protection and Authentication +Databases. + +=item I + +Specifies the complete pathname to the user's home directory, which +is deleted from the filespace. By default, the volume mounted there is +also deleted from the file server machine where it resides, as is its record +from the Volume Location Database (VLDB). To prevent deletion, include +the B string in the instruction's third field, or +precede this B instruction with a B +instruction. Partial pathnames are interpreted relative to the current +working directory. + +=item savevolume + +Retains the volume on its file server machine, and the corresponding entry +in the VLDB. Provide this value or B in the third +field, or omit both values to treat the volume according to the prevailing +default, which is set by a preceding B or +B instruction in the bulk input file. + +=item delvolume + +Removes the volume from its file server machine, and the corresponding +entry from the VLDB. Provide this value or B in the +third field, or omit both values to treat the volume according to the +prevailing default, which is set by a preceding B or +B instruction in the bulk input file. + +=back + +After the last argument provided, end the line with either a colon and +carriage return or a carriage return alone. + +The exec Instruction for Executing a Command + +The exec instruction executes the specified command, which can +be a UNIX shell script or command, a program, or an AFS command. The +B command interpreter must have the necessary privileges in AFS +and the local file system; it assumes the AFS and local identities of the +issuer of the B command. + +The instruction's syntax is as follows: + + exec I + +The delvolume and savevolume Instructions for Setting the Default +Treatment of Volumes +L<(1)> +L<(1)> +L<(1)> +L<(1)> + +The B and delvolume instructions determine +the default treatment of volumes referenced by the B +instructions that follow them in the bulk input file. Their syntax is +as follows: + + savevolume + delvolume + +The savevolume instruction prevents the removal of the volume +and VLDB entry for all B instruction that follow it in the +bulk input file, and the B instruction removes the volume +and VLDB entry for all subsequent B instructions. +Either setting persists until its opposite appears in the file, or until the +end of the bulk file. + +If neither line appears in the bulk input file, the default is to remove +the volume and the VLDB entry; B instructions that appear +before the first B instruction are also subject to this +default. If a B instruction's third field +specifies either B or B, that setting +overrides the default. + +=head1 EXAMPLES + +The following example add instruction creates an +authentication-only account. The user's initial password is +B (the default). + + add anderson + +The following example add instructions refer to the indicated +B instruction in a template file (which must appear on a single +line in the template file). + + add smith:John Smith:::fs1:a:::::marketing + add jones:Pat Jones:::fs3:c:::::finance + V user.$USER $SERVER.abc.com /vicep$PART 2000 \ + /afs/abc.com/usr/$3/$USER $UID $USER all + +The first add instruction creates an account called +B in the Protection and Authentication Databases, with an +initial password B and a value for $UID provided by the +Protection Server. The volume B resides on +partition B of file server machine +B and is mounted at +B. He owns his home +directory and has all access permissions on its root directory's access +control list (ACL). The account for B is similar, except +that the volume resides on partition B of file server machine +B and is mounted at +B. + +Notice that the fields corresponding to the volume mount point, UID, $1 +variable, and $2 variable are empty (between C and +C on the first example line), because their corresponding +variables do not appear in the template file. The initial password +field is also empty. + +The following add instructions are equivalent in effect to the +preceding example, but explicitly indicate empty fields for all of the number +variables that don't have a value: + + add smith:John Smith:::fs1:a:::::marketing:::::: + add jones:Pat Jones:::fs3:c:::::finance:::::: + +The following example shows a complete bulk file containing a set of +B instructions combined with a B +instruction. Because the B instruction for users +B, B, and B appear before the +B instruction and the third field is blank in each, the +corresponding home volumes are removed. The volume for user +B is retained because the default established by the +B instruction applies to it, but user +B's volume is removed because the third field of her +B instruction overrides the current default. + + delete smith:/afs/abc.com/usr/smith + delete pat:/afs/abc.com/usr/pat + delete rogers:/afs/abc.com/usr/rogers + savevolume + delete terry:/afs/abc.com/usr/terry + delete johnson:/afs/abc.com/usr/johnson:delvolume + +The following example exec instruction appears between sets of +B and B instructions in a bulk input file. +A message appears in the command shell where the B command +is issued, to indicate when the additions are finished and the deletions +beginning. + + exec echo "Additions completed; beginning deletions..." + +=head1 SEE ALSO + +L + +L, +L, +L + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0. It was +converted from HTML to POD by software written by Chas Williams and Russ +Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/afsd.pod b/doc/man-pages/pod8/afsd.pod index c852b6c8d..449192147 100644 --- a/doc/man-pages/pod8/afsd.pod +++ b/doc/man-pages/pod8/afsd.pod @@ -1,36 +1,33 @@ =head1 NAME -afsd - Initializes the Cache Manager and starts related daemons. +afsd - Initializes the Cache Manager and starts related daemons =head1 SYNOPSIS -B [-blocks >] -[B<-files> >] - [-rootvol >] - [-stat >] - [B<-memcache>] [-cachedir >] - [-mountdir >] - [-daemons >] - [B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [-debug] - [-chunksize >] - [-dcache >] - [-volumes >] - [-biods >] - [-prealloc >] - [-confdir >] - [-logfile >] - [B<-waitclose>] [B<-shutdown>] [-enable_peer_stats] - [B<-enable_process_stats>] [-help] - -This command does not use the syntax conventions of the AFS command -suites. Provide the command name and all option names in full. +B [B<-blocks> >] + [B<-files> >] + [B<-rootvol> >] + [B<-stat> >] + [B<-memcache>] [B<-cachedir> >] + [B<-mountdir> >] + [B<-daemons> >] + [B<-nosettime>] [B<-verbose>] [B<-rmtsys>] [B<-debug>] + [B<-chunksize> >] + [B<-dcache> >] + [B<-volumes> >] + [B<-biods> >] + [B<-prealloc> >] + [B<-confdir> >] + [B<-logfile> >] + [B<-waitclose>] [B<-shutdown>] [B<-enable_peer_stats>] + [B<-enable_process_stats>] [B<-help>] =head1 DESCRIPTION -The afsd command initializes the Cache Manager on an AFS client -machine by transferring AFS-related configuration information into kernel -memory and starting several daemons. More specifically, the -B command performs the following actions: +The B 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 B command +performs the following actions: =over 4 @@ -39,166 +36,144 @@ B command performs the following actions: 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 -B program runs again. - +interpreters refer to the F file instead.) This +information is transferred into the kernel from the +F file and cannot be changed until the B +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 +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 B command to change the kernel-resident list without -having to reboot. +the F file. After initialization, use the B 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 B -command's B<-mountdir> argument. The conventional value is -B. - +Mounts the root of the AFS filespace on a directory on the machine's local +disk, according to either the first field in the +F file (the default) or the B command's +B<-mountdir> argument. The conventional value is F. =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. - +Determines which volume to mount at the root of the AFS file tree. The +default is the volume C; 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, C) 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 -B 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. - +B<-memcache> argument is provided. In the latter case, the B 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 -B program creates the directory (its parent directory must -already exist). It does not remove the directory that formerly served -this function, if one exists. - +B<-memcache> argument is not used. If necessary, the B 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 /usr/vice/etc/cacheinfo 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. +The second field in the F file is the source for +this name, and the standard value is the F 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. +Sets the size of the cache. The default source for the value is the third +field in the F file, which specifies a number of +kilobytes. - -For a memory cache, the following arguments to the afsd command -override the value in the B file: +For a memory cache, the following arguments to the afsd command override +the value in the B file: =over 4 =item * -The -blocks argument, to specify a different number of kilobyte -blocks. - +The B<-blocks> argument, to specify a different number of kilobyte blocks. =item * -The B<-dcache> and -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 B -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. - +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 B 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 -dcache argument by itself. In this case, the -B 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. - +The B<-dcache> argument by itself. In this case, the B 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 +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 B program exits without initializing the Cache -Manager and produces the following message on the standard output -stream: +Manager and produces the following message on the standard output stream: - afsd: memCache allocation failure at I KB + afsd: memCache allocation failure at KB -where I is how many kilobytes were allocated just before the +where is how many kilobytes were allocated just before the failure. -For a disk cache, use the -blocks argument to the -B 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 B program rejects any setting larger than 95% -of the partition size, and exits after generating an error message on the +For a disk cache, use the B<-blocks> argument to the B 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 B 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. +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 B command; the setting persists until -the B command runs again or the B -command is reissued. The B command does not -work for memory caches. +use the B command; the setting persists until the B +command runs again or the B command is reissued. The B 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 +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 VI 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. +For a disk cache, a chunk is a F<< VIZ<> >> 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 B program rounds down the number of dcache entries, -resulting in a slightly smaller cache. +B<-chunksize> argument to provide an integer to be used as an exponent of +two; see L for details. For a memory cache, if total cache size +divided by chunk size leaves a remainder, the B 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: - +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 (F<< VIZ<> >> files) is set to the largest +of the following unless the B<-files> argument is used to set the value +explicitly: =over 4 @@ -206,18 +181,15 @@ to set the value explicitly: 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 * @@ -225,33 +197,29 @@ The result of dividing cachesize by 10 KB (I/10240) Sets the number of I allocated in machine memory for storing information about the chunks in the cache. +For a disk cache, the F file contains one +entry for each F<< VIZ<> >> 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 disk cache, the /usr/vice/cache/CacheItems 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 F 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 B +program derives it by dividing the cache size by the chunk size. -For a memory cache, there is no CacheItems file so all -information about cache chunks must be in memory as dcache entries. -Thus, there is no default number of dcache entries for a memory cache; -instead, the B program derives it by dividing the cache size by -the chunk size. - -To set the number of dcache entries, use the -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. +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. - +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 * @@ -259,86 +227,73 @@ 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 afsd command -from selecting a time standard. This is recommended only on file server -machines that are also acting as clients. File server machines maintain -the correct time using the Network Time Protocol Daemon instead. +Use the B<-nosettime> flag to prevent the afsd command from selecting a +time standard. This is recommended only on file server machines that are +also acting as clients. File server machines maintain the correct time +using the Network Time Protocol Daemon instead. =back -In addition to setting cache configuration parameters, the afsd -program starts the following daemons. (On most system types, these -daemons appear as nameless entries in the output of the UNIX B -command.) +In addition to setting cache configuration parameters, the B program +starts the following daemons. (On most system types, these daemons appear +as nameless entries in the output of the UNIX B command.) =over 4 =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. - +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: - +One I daemon, which performs the following tasks: =over 4 =item * Garbage collects obsolete data (for example, expired tokens) from kernel -memory - +memory. =item * -Synchronizes files - +Synchronizes files. =item * -Refreshes information from read-only volumes once per hour - +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 - +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 +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 +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. - +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. +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 +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 * @@ -346,122 +301,116 @@ necessary. 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. - +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: - +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 4 =item * -If the -biods argument is used, it sets the number of VM -daemons. - +If the B<-biods> argument is used, it sets the number of VM daemons. =item * -If only the -daemons argument is used, the number of VM daemons -is twice the number of background daemons. - +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 +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + =head1 CAUTIONS -Do not use the -shutdown parameter. It does not shutdown -the Cache Manager effectively. Instead, halt Cache Manager activity by -using the standard UNIX B command to unmount the AFS root -directory (by convention, B). The machine must then be -rebooted to reinitialize the Cache Manager. +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 B command to unmount the AFS root directory (by +convention, F). The machine must then be rebooted to reinitialize +the Cache Manager. =head1 OPTIONS =over 4 -=item -blocks +=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. +F 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 -files +=item B<-files> > -Specifies the number of VI 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. +Specifies the number of F<< VIZ<> >> files to create in the cache +directory for a disk cache, overriding the default that is calculated as +described in L. Each F<< VIZ<> >> 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 -rootvol +=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. +AFS file tree (which is usually the F directory). This value +overrides the default of the C volume. -=item -stat +=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. +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 C<300>. -=item -memcache +=item B<-memcache> -Initializes a memory cache rather than a disk cache. Do not combine -this flag with the B<-files> argument. +Initializes a memory cache rather than a disk cache. Do not combine this +flag with the B<-files> argument. -=item -cachedir +=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. +F file. -=item -mountdir +=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. +filespace. This value overrides the default defined in the first field of +the F file. If a value other than the F +directory is used, the machine cannot access the filespace of cells that +do use that value. -=item -daemons +=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>. +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 C<2>, which is adequate +for a machine serving up to five users. Values greater than C<6> are not +generally more effective than C<6>. -Note: On AIX machines with integrated virtual memory (VM), -the number of VM daemons is set to twice the value of this argument, if it is -provided and the B<-biods> argument is not. If both arguments -are omitted, there are five VM daemons. +Note: On AIX machines with integrated virtual memory (VM), the number of +VM daemons is set to twice the value of this argument, if it is provided +and the B<-biods> argument is not. If both arguments are omitted, there +are five VM daemons. -=item -nosettime +=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 @@ -469,104 +418,100 @@ 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 -verbose +=item B<-verbose> -Generates a detailed trace of the afsd program's actions -on the standard output stream. +Generates a detailed trace of the B program's actions on the +standard output stream. -=item -rmtsys +=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. -L<(1)> +NFS/AFS translator machine serving users of NFS client machines who +execute AFS commands. -=item -debug +=item B<-debug> -Generates a highly detailed trace of the afsd program's -actions on the standard output stream. The information is useful mostly -for debugging purposes. +Generates a highly detailed trace of the B program's actions on the +standard output stream. The information is useful mostly for debugging +purposes. -=item -chunksize +=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 -(216 is 64 KB) and 13 for a memory cache (213 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. +Sets the size of each cache chunk. The integer provided, which must be +from the range C<0> to C<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 C<0> or less, or greater than +C<30>, sets chunk size to the appropriate default. Values less than C<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 -dcache +=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 +default, which is 50% of the number of F<< VIZ<> >> 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. +B<-blocks> argument, since doing so can possibly result in a chunk size +that is not an exponent of 2. -=item -volumes +=item B<-volumes> > Specifies the number of memory structures to allocate for storing volume -location information. The default value is 50. +location information. The default value is C<50>. -=item -biods +=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. +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. -=item -prealloc +=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. +Manager's internal use. The default initial value is C<400>, but the Cache +Manager dynamically allocates more memory as it needs it. -=item -confdir +=item B<-confdir> > -Names a directory other than the /usr/vice/etc directory from -which to fetch the B, B, and -B configuration files. +Names a directory other than the F directory from which to +fetch the F, F, and F configuration +files. -=item -logfile +=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. +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 F. -=item -waitclose +=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 +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 B -command. +asynchronous writes in certain cases, use the B command. -=item -shutdown +=item B<-shutdown> Shuts down the Cache Manager, but not in the most effective possible way. Do not use this flag. -=item -enable_peer_stats +=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. +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 -enable_process_stats +=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, @@ -574,16 +519,16 @@ 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 -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The afsd command is normally included in the machine's AFS +The B 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 @@ -595,7 +540,7 @@ 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 (214). +KB (2^14). /usr/vice/etc/afsd -memcache -chunksize 14 @@ -605,18 +550,9 @@ The issuer must be logged in as the local superuser root. =head1 SEE ALSO -L, -L - -L - -L(1)>, -L -L<(1)> -L<(1)> -L<(1)> -L<(1)> -L<(1)> +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup.pod b/doc/man-pages/pod8/backup.pod index ceadf8f1c..f5ad974da 100644 --- a/doc/man-pages/pod8/backup.pod +++ b/doc/man-pages/pod8/backup.pod @@ -4,7 +4,7 @@ backup - Introduction to the backup command suite =head1 DESCRIPTION -The commands in the backup command suite are the administrative +The commands in the B command suite are the administrative interface to the AFS Backup System. There are several categories of commands in the suite: @@ -13,220 +13,190 @@ commands in the suite: =item * Commands to copy data from AFS volumes to tape or a backup data file, and -to restore it to the file system: B, -B, B, and B - +to restore it to the file system: B, B, +B, and B. =item * -Commands to administer the records in the Backup Database: -B, B, B, B, B, -B, B, B, B, B, -B, B, B, B, B, and -B - +Commands to administer the records in the Backup Database: B, B, B, B, +B, B, B, B, B, B, B, B, B, B, B, and B. =item * -Commands to write and read tape labels: backup labeltape -and B - +Commands to write and read tape labels: B and B. =item * Commands to list and change the status of backup operations and the -machines performing them: B<(backup) jobs>, B<(backup) -kill>, and B - +machines performing them: B, B, and B. =item * -Commands to enter and leave interactive mode: backup -(interactive) and B<(backup) quit> - +Commands to enter and leave interactive mode: B and +B. =item * Commands to check for and repair corruption in the Backup Database: -B, B, and B - +B, B, and B. =item * -Commands to obtain help: B and backup -help - +Commands to obtain help: B and B. =back -The backup command interpreter interacts with two other -processes: -L<(1)> -L<(1)> +The backup command interpreter interacts with two other processes: =over 4 =item * -The Backup Server (buserver) process. It maintains the -Backup Database, which stores most of the administrative information used by -the Backup System. In the standard configuration, the Backup Server -runs on each database server machine in the cell, and uses AFS's -distributed database technology, Ubik, to synchronize its copy of the database -with the copies on the other database server machines. - +The Backup Server (B) process. It maintains the Backup Database, +which stores most of the administrative information used by the Backup +System. In the standard configuration, the Backup Server runs on each +database server machine in the cell, and uses AFS's distributed database +technology, Ubik, to synchronize its copy of the database with the copies +on the other database server machines. =item * -The Backup Tape Coordinator (butc) process. A separate -instance of the process controls each tape device or backup data file used to -dump or restore data. The Tape Coordinator runs on a Tape Coordinator -machine, which is an AFS server or client machine that has one or more tape -devices attached, or has sufficient disk space to accommodate one or more -backup data files on its local disk. - +The Backup Tape Coordinator (B) process. A separate instance of the +process controls each tape device or backup data file used to dump or +restore data. The Tape Coordinator runs on a Tape Coordinator machine, +which is an AFS server or client machine that has one or more tape devices +attached, or has sufficient disk space to accommodate one or more backup +data files on its local disk. Each Tape Coordinator must be registered in the Backup Database and in the -B configuration file on the Tape -Coordinator machine's local disk, and information in the two places must -be consistent for proper Backup System performance. The optional -BI for each Tape Coordinator -records information used to automate its operation. +F configuration file on the Tape Coordinator +machine's local disk, and information in the two places must be consistent +for proper Backup System performance. The optional +F> for each Tape Coordinator records +information used to automate its operation. =back -In addition to the standard command line interface, the backup -command suite provides an I interface, which has several -useful features described on the B reference -page. Three of the commands in the suite are available only in -interactive mode: B<(backup) jobs>, B<(backup) kill>, -and B<(backup) quit>. +In addition to the standard command line interface, the B command +suite provides an I interface, which has several useful +features described in L. Three of the commands in +the suite are available only in interactive mode: B, B, and B. =head1 OPTIONS -The following options are available on many commands in the -B suite. The reference page for each command also lists -them, but they are described here in greater detail. -L<(1)> -L<(1)> -L<(1)> +The following options are available on many commands in the B +suite. The reference page for each command also lists them, but they are +described here in greater detail. =over 4 -=item -cell -> +=item B<-cell> > -Names the cell in which to run the command. It is acceptable to -abbreviate the cell name to the shortest form that distinguishes it from the -other entries in the B file on the local -machine. If the B<-cell> argument is omitted, the command -interpreter determines the name of the local cell by reading the following in -order: +Names the cell in which to run the command. It is acceptable to abbreviate +the cell name to the shortest form that distinguishes it from the other +entries in the F file on the local machine. If +the B<-cell> argument is omitted, the command interpreter determines the +name of the local cell by reading the following in order: -=item * +=over 4 -The value of the AFSCELL environment variable +=item * +The value of the AFSCELL environment variable. =item * -The local /usr/vice/etc/ThisCell file +The local F file. +=back -Do not combine the B<-cell> and -localauth -options. A command on which the B<-localauth> flag is included -always runs in the local cell (as defined in the server machine's local -B file), whereas a command on which the -B<-cell> argument is included runs in the specified foreign -cell. +Do not combine the B<-cell> and B<-localauth> options. A command on which +the B<-localauth> flag is included always runs in the local cell (as +defined in the server machine's local F file), +whereas a command on which the B<-cell> argument is included runs in the +specified foreign cell. -The -cell argument is not available on commands issued in -interactive mode. The cell defined when the B command -interpreter enters interactive mode applies to all commands issued during the -interactive session. -L<(1)> +The B<-cell> argument is not available on commands issued in interactive +mode. The cell defined when the B command interpreter enters +interactive mode applies to all commands issued during the interactive +session. -=item -help +=item B<-help> -Prints a command's online help message on the standard output -stream. Do not combine this flag with any of the command's other -options; when it is provided, the command interpreter ignores all other -options, and only prints the help message. +Prints a command's online help message on the standard output stream. Do +not combine this flag with any of the command's other options; when it is +provided, the command interpreter ignores all other options, and only +prints the help message. -=item L<(1) --localauth -> +=item B<-localauth> Constructs a server ticket using the server encryption key with the -highest key version number in the local B -file. The B command interpreter presents the ticket, -which never expires, to the Backup Server, Volume Server and Volume Location -(VL) Server during mutual authentication. +highest key version number in the local F file. The +B command interpreter presents the ticket, which never expires, to +the Backup Server, Volume Server and Volume Location (VL) Server during +mutual authentication. Use this flag only when issuing a command on a server machine; client -machines do not usually have a B file. -The issuer of a command that includes this flag must be logged on to the -server machine as the local superuser B. The flag is -useful for commands invoked by an unattended application program, such as a -process controlled by the UNIX B utility or by a cron entry in -the machine's B file. It is also -useful if an administrator is unable to authenticate to AFS but is logged in -as the local superuser B. - -Do not combine the B<-cell> and -localauth -options. A command on which the B<-localauth> flag is included -always runs in the local cell (as defined in the server machine's local -B file), whereas a command on which the -B<-cell> argument is included runs in the specified foreign -cell. - -The -localauth argument is not available on commands issued in +machines do not usually have a F file. The issuer +of a command that includes this flag must be logged on to the server +machine as the local superuser C. The flag is useful for commands +invoked by an unattended application program, such as a process controlled +by the UNIX B utility or by a cron entry in the machine's +F file. It is also useful if an administrator is +unable to authenticate to AFS but is logged in as the local superuser +C. + +Do not combine the B<-cell> and B<-localauth> options. A command on which +the B<-localauth> flag is included always runs in the local cell (as +defined in the server machine's local F file), +whereas a command on which the B<-cell> argument is included runs in the +specified foreign cell. + +The B<-localauth> argument is not available on commands issued in interactive mode. The local identity and AFS tokens with which the B command interpreter enters interactive mode apply to all commands issued during the interactive session. -=item L<(1) --portoffset > -> +=item B<-portoffset> > Specifies the port offset number of the Tape Coordinator that is to -execute the B command. The port offset number uniquely -identifies a pairing of a Tape Coordinator (B) process and tape -device or backup data file. - -The backup command interpreter and Tape Coordinator process -communicate via a UDP socket, or port. Before issuing a -B command that involves reading or writing a tape, the backup -operator must start a B process that controls the appropriate -tape device and listens for requests sent to its port number. If a -Backup System machine has multiple tape devices attached, they can perform -backup operations simultaneously because each device has its own associated -B process and port offset number. +execute the B command. The port offset number uniquely identifies +a pairing of a Tape Coordinator (B) process and tape device or +backup data file. + +The backup command interpreter and Tape Coordinator process communicate +via a UDP socket, or port. Before issuing a B command that +involves reading or writing a tape, the backup operator must start a +B process that controls the appropriate tape device and listens for +requests sent to its port number. If a Backup System machine has multiple +tape devices attached, they can perform backup operations simultaneously +because each device has its own associated B process and port offset +number. The Backup System associates a tape capacity and file mark size with each -port offset (as defined in the B file). For a -compressing tape device, the capacity and file mark values differ for -compression and non-compression modes, so the two modes have distinct port -offset numbers. +port offset (as defined in the F file). For a compressing tape +device, the capacity and file mark values differ for compression and +non-compression modes, so the two modes have distinct port offset numbers. The Backup Database can store up to 58,511 port offsets, so the legal -values for this argument are the integers B<0> through -B<58510>. If the issuer omits the argument, it defaults to -B<0>. (The limit of 58,511 port offsets results from the fact -that UDP socket numbers are identified by a 16-bit integer, and the lowest -socket number used by the Backup System is 7025. The largest number -that a 16-bit integer can represent is 65,535. Subtracting 7,025 yields -58,510. The addition of port offset 0 (zero) increases the maximum to -58,511.) +values for this argument are the integers C<0> through C<58510>. If the +issuer omits the argument, it defaults to C<0>. (The limit of 58,511 port +offsets results from the fact that UDP socket numbers are identified by a +16-bit integer, and the lowest socket number used by the Backup System is +7025. The largest number that a 16-bit integer can represent is +65,535. Subtracting 7,025 yields 58,510. The addition of port offset 0 +(zero) increases the maximum to 58,511.) Although it is possible to define up to 58,511 port offset numbers for a -cell, it is not possible to run 58,511 tape devices simultaneously, due to the -following limits: +cell, it is not possible to run 58,511 tape devices simultaneously, due to +the following limits: =over 4 @@ -235,22 +205,19 @@ following limits: The maximum number of dump or restore operations that can run simultaneously is 64. - =item * The maximum number of tape devices that can work together on a restore -operation is 128 (that is the maximum number of values that can be provided -for the B<-portoffset> argument to the B, -B, or B -command). - +operation is 128 (that is the maximum number of values that can be +provided for the B<-portoffset> argument to the B, +B, or B command). =back -The Backup System does not reserve UDP sockets. If another -application is already using the Tape Coordinator's socket when it tries -to start, the B process fails and the following error message -appears at the shell prompt: +The Backup System does not reserve UDP sockets. If another application is +already using the Tape Coordinator's socket when it tries to start, the +B process fails and the following error message appears at the shell +prompt: bind: Address already in use rxi_GetUDPSocket: bind failed @@ -259,68 +226,62 @@ appears at the shell prompt: =head1 PRIVILEGE REQUIRED -To issue any backup command that accesses the Backup Database -only, the issuer must be listed in the B file -on every machine where the Backup Server is running. To issue any -B command that accesses volume data, the issuer must appear in -the B file on every Backup Server machine, every Volume -Location (VL) Server machine, and every file server machine that houses -affected volumes. By convention, a common B file is -distributed to all database server and file server machines in the -cell. See the chapter on privileged users in the I for more information on this type of +To issue any backup command that accesses the Backup Database only, the +issuer must be listed in the F file on every +machine where the Backup Server is running. To issue any B command +that accesses volume data, the issuer must appear in the F file +on every Backup Server machine, every Volume Location (VL) Server machine, +and every file server machine that houses affected volumes. By convention, +a common F file is distributed to all database server and file +server machines in the cell. See the chapter on privileged users in the +I for more information on this type of privilege. -If the -localauth flag is included, the user must instead be -logged on as the local superuser B on the server machine where -the B command is issued. +If the B<-localauth> flag is included, the user must instead be logged on +as the local superuser C on the server machine where the B +command is issued. =head1 SEE ALSO -L, -L(1)>, -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, +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 =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_adddump.pod b/doc/man-pages/pod8/backup_adddump.pod index 07b14f291..9b26f4126 100644 --- a/doc/man-pages/pod8/backup_adddump.pod +++ b/doc/man-pages/pod8/backup_adddump.pod @@ -4,31 +4,32 @@ backup adddump - Defines a dump level in the dump hierarchy =head1 SYNOPSIS -B >+ [-expires >+] -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-dump> >+ + [B<-expires> >+] + [B<-localauth>] [B<-cell> >] [B<-help>] -B >+ [B<-e> >+] [-l] -[B<-c> >] [B<-h>] +B B<-d> >+ [B<-e> >+] + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup adddump command creates one or more dump levels in -the dump hierarchy stored in the Backup Database, and optionally assigns an -expiration date to each one. All of the dump levels in the Backup -Database collectively constitute the dump hierarchy. - -Use the -expires argument to associate an expiration date with -each dump level. When the Backup System subsequently creates a dump at -the dump level, it uses the specified value to derive the dump's -expiration date, which it records on the label of the tape (or backup data -file). The Backup System refuses to overwrite a tape until after the -latest expiration date of any dump that the tape contains, unless the -B command is used to relabel the tape. If a -dump level does not have an expiration date, the Backup System treats dumps -created at the level as expired as soon as it creates them. - -(Note that the Backup System does not automatically remove a dump's -record from the Backup Database when the dump reaches its expiration date, but +The B command creates one or more dump levels in the dump +hierarchy stored in the Backup Database, and optionally assigns an +expiration date to each one. All of the dump levels in the Backup Database +collectively constitute the dump hierarchy. + +Use the B<-expires> argument to associate an expiration date with each +dump level. When the Backup System subsequently creates a dump at the dump +level, it uses the specified value to derive the dump's expiration date, +which it records on the label of the tape (or backup data file). The +Backup System refuses to overwrite a tape until after the latest +expiration date of any dump that the tape contains, unless the B command is used to relabel the tape. If a dump level does not +have an expiration date, the Backup System treats dumps created at the +level as expired as soon as it creates them. + +(Note that the Backup System does not automatically remove a dump's record +from the Backup Database when the dump reaches its expiration date, but only if the tape that contains the dump is recycled or relabeled. To remove expired and other obsolete dump records, use the B command.) @@ -40,19 +41,17 @@ Define either an absolute or relative expiration date: =item * An absolute expiration date defines the month/day/year (and, optionally, -hour and minutes) at which a dump expires. If the expiration date -predates the dump creation time, the Backup System immediately treats the dump -as expired. - +hour and minutes) at which a dump expires. If the expiration date predates +the dump creation time, the Backup System immediately treats the dump as +expired. =item * A relative date defines the number of years, months, or days (or a -combination of the three) after the dump's creation that it -expires. When the Backup System creates a dump at the dump level, it -calculates an actual expiration date by adding the relative date to the start -time of the dump operation. - +combination of the three) after the dump's creation that it expires. When +the Backup System creates a dump at the dump level, it calculates an +actual expiration date by adding the relative date to the start time of +the dump operation. =back @@ -60,122 +59,115 @@ time of the dump operation. =over 4 -=item -dump +=item B<-dump> >+ -Names each dump level to add to the dump hierarchy. Precede full -dump level names with a slash (for example, B). Indicate -an incremental dump level by preceding it with an ordered list of the dump -levels directly above it in the hierarchy (its parent dump levels); use -the slash as a separator. The parent dump levels must already -exist. For example, the dump levels B and -B must exist when the incremental dump level -B is created. +Names each dump level to add to the dump hierarchy. Precede full dump +level names with a slash (for example, C). Indicate an incremental +dump level by preceding it with an ordered list of the dump levels +directly above it in the hierarchy (its parent dump levels); use the slash +as a separator. The parent dump levels must already exist. For example, +the dump levels C and C must exist when the +incremental dump level C is created. Dump level names can have any number of levels, but cannot exceed 256 characters in length, including the slashes. The maximum length for any -single level (the text between slashes) is 28 characters, not including the -preceding slash. +single level (the text between slashes) is 28 characters, not including +the preceding slash. -All alphanumeric characters are allowed in dump level names. Do not -use the period (B<.>), however, because it is the separator -between the volume set name and dump level name in the dump name assigned -automatically by the B command. It is best not to -include other metacharacters either; if using them, enclose them in -double quotes (B<" ">) when issuing the B -command outside interactive mode. +All alphanumeric characters are allowed in dump level names. Do not use +the period (C<.>), however, because it is the separator between the volume +set name and dump level name in the dump name assigned automatically by +the B command. It is best not to include other metacharacters +either; if using them, enclose them in double quotes (C<" ">) when issuing +the B command outside interactive mode. -=item -expires +=item B<-expires> >+ Defines the absolute or relative expiration date to associate with each -dump level named by the B<-dump> argument. Absolute expiration -dates have the following format: +dump level named by the B<-dump> argument. Absolute expiration dates have +the following format: - [B] {B | IBI
BI [I:I] } + [at] {NEVER | /
/ [:] } -where the optional word at is followed either by the string -B, which indicates that dumps created at the dump level never -expire, or by a date value with a required portion (I for month, -I
for day, and I for year) and an optional portion -(I for hours and I for minutes). +where the optional word at is followed either by the string C, +which indicates that dumps created at the dump level never expire, or by a +date value with a required portion ( for month,
), and year (I) are required. The hour and -minutes (I:I) are optional, but if provided must be -in 24-hour format (for example, the value B<14:36> represents -2:36 p.m.). If omitted, the time defaults to -midnight (00:00 hours). +Omit this argument to indicate the default of midnight (00:00 hours) on 1 +January 1970 (UNIX time zero), or provide a date value in the format +I [I]. The month (I), day (I
), and year +(I) are required. The hour and minutes (I) are optional, but +if provided must be in 24-hour format (for example, the value C<14:36> +represents 2:36 p.m.). If omitted, the time defaults to midnight (00:00 +hours). -The -to argument must be provided along with this one. +The B<-to> argument must be provided along with this one. -=item -to +=item B<-to> >+ Specifies the end of a range of dates; the record of any dump created during the range is deleted from the Backup Database. -Provide either the value NOW to indicate the current date and -time, or a date value in the same format as for the B<-from> -argument. Valid values for the year (I) range from -B<1970> to B<2037>; higher values are not valid because -the latest possible date in the standard UNIX representation is in February -2038. The command interpreter automatically reduces any later date to -the maximum value. - -If the time portion (I) is omitted, it defaults to 59 -seconds after midnight (00:00:59 hours). Similarly, the -B command interpreter automatically adds 59 seconds to any -time value provided. In both cases, adding 59 seconds compensates for -how the Backup Database and B command represent dump -creation times in hours and minutes only. For example, the Database -records a creation timestamp of C<20:55> for any dump operation -that begins between 20:55:00 and 20:55:59. -Automatically adding 59 seconds to a time thus includes the records for all -dumps created during that minute. - -Provide either this argument, or the -dumpid argument. -This argument is required if the B<-from> argument is provided. - -B Specifying the value NOW for this -argument when the B<-from> argument is omitted deletes all dump -records from the Backup Database (except for Backup Database dump records -created with the B command). - -=item -localauth +Provide either the value C to indicate the current date and time, or +a date value in the same format as for the B<-from> argument. Valid values +for the year (I) range from C<1970> to C<2037>; higher values are +not valid because the latest possible date in the standard UNIX +representation is in February 2038. The command interpreter automatically +reduces any later date to the maximum value. + +If the time portion (I) is omitted, it defaults to 59 seconds after +midnight (00:00:59 hours). Similarly, the B command interpreter +automatically adds 59 seconds to any time value provided. In both cases, +adding 59 seconds compensates for how the Backup Database and B command represent dump creation times in hours and minutes +only. For example, the Database records a creation timestamp of C<20:55> +for any dump operation that begins between 20:55:00 and 20:55:59. +Automatically adding 59 seconds to a time thus includes the records for +all dumps created during that minute. + +Provide either this argument, or the B<-dumpid> argument. This argument +is required if the B<-from> argument is provided. + +B Specifying the value C for this argument when the +B<-from> argument is omitted deletes all dump records from the Backup +Database (except for Backup Database dump records created with the +B command). + +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -139,9 +133,9 @@ At the conclusion of processing, the output lists the dump IDs of all dump records deleted in the following format: The following dumps were deleted: - I - I - I + dump ID 1 + dump ID 2 + etc. =head1 EXAMPLES @@ -153,8 +147,8 @@ for any appended dumps associated with it: 653777462 The following command deletes the Backup Database record of all dumps -created between midnight on 1 January 1997 and 23:59:59 hours on -31 December 1997: +created between midnight on 1 January 1997 and 23:59:59 hours on 31 +December 1997: % backup deletedump -from 01/01/1997 -to 12/31/1997 The following dumps were deleted: @@ -167,16 +161,16 @@ created between midnight on 1 January 1997 and 23:59:59 hours on =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_delhost.pod b/doc/man-pages/pod8/backup_delhost.pod index 4aaa854ee..35a569a93 100644 --- a/doc/man-pages/pod8/backup_delhost.pod +++ b/doc/man-pages/pod8/backup_delhost.pod @@ -4,20 +4,21 @@ backup delhost - Deletes a Tape Coordinator entry from the Backup Database =head1 SYNOPSIS -B > [-portoffset >] -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-tapehost> > + [B<-portoffset> >] [B<-localauth>] + [B<-cell> >] [B<-help>] -B > [-p >] -[B<-l>] [B<-c> >] [B<-h>] +B B<-t> > [B<-p> >] + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup delhost command deletes the indicated Tape -Coordinator entry from the Backup Database. It is then impossible to -submit backup operations to that Tape Coordinator, even if it is still -running. To keep configuration information consistent, also remove the -corresponding entry from the B file on the -Tape Coordinator machine. +The B command deletes the indicated Tape Coordinator entry +from the Backup Database. It is then impossible to submit backup +operations to that Tape Coordinator, even if it is still running. To keep +configuration information consistent, also remove the corresponding entry +from the F file on the Tape Coordinator +machine. To list the Tape Coordinator machines and port offsets defined in the Backup Database, issue the B command. @@ -26,39 +27,37 @@ Backup Database, issue the B command. =over 4 -=item -tapehost +=item B<-tapehost> > Specifies the hostname of the machine housing the Tape Coordinator to delete. -=item -portoffset +=item B<-portoffset> > -Specifies the port offset number of the Tape Coordinator to delete. -If omitted, it defaults to B<0>. If provided, it is an integer -between B<0> (zero) and B<58510>, and must match the port -offset number assigned to the same combination of Tape Coordinator and tape -device or file in the B file on the Tape -Coordinator machine indicated by the B<-tapehost> argument. +Specifies the port offset number of the Tape Coordinator to delete. If +omitted, it defaults to C<0>. If provided, it is an integer between C<0> +(zero) and C<58510>, and must match the port offset number assigned to the +same combination of Tape Coordinator and tape device or file in the +F file on the Tape Coordinator machine +indicated by the B<-tapehost> argument. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -66,22 +65,22 @@ are ignored. The following command deletes the Backup Database entry for the Tape Coordinator with port offset 2 on the Tape Coordinator machine -B: +C: % backup delhost -tapehost backup3.abc.com -portoffset 2 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_delvolentry.pod b/doc/man-pages/pod8/backup_delvolentry.pod index d7ad0036c..bdc344cf7 100644 --- a/doc/man-pages/pod8/backup_delvolentry.pod +++ b/doc/man-pages/pod8/backup_delvolentry.pod @@ -4,86 +4,84 @@ backup delvolentry - Deletes a volume entry from a volume set =head1 SYNOPSIS -B > -entry > -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-name> > + B<-entry> > [B<-localauth>] + [B<-cell> >] [B<-help>] -B > -e > -[B<-l>] [B<-c> >] [B<-h>] +B B<-n> > B<-e> > + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup delvolentry command deletes the indicated volume -entry from the volume set specified with the B<-name> argument. -Use the B<-entry> argument to identify the volume entry by its index -number. To display the index numbers, use the B command. +The B command deletes the indicated volume entry from +the volume set specified with the B<-name> argument. Use the B<-entry> +argument to identify the volume entry by its index number. To display the +index numbers, use the B command. If there are any remaining volume entries with index numbers higher than -the deleted entry, their indexes are automatically decremented to eliminate -any gaps in the indexing sequence. +the deleted entry, their indexes are automatically decremented to +eliminate any gaps in the indexing sequence. =head1 CAUTIONS -Deleting volume entries from a temporary volume set is possible only within -the interactive session in which the volume set was created. +Deleting volume entries from a temporary volume set is possible only +within the interactive session in which the volume set was created. =head1 OPTIONS =over 4 -=item -name +=item B<-name> > Names the volume set from which to delete a volume entry. -=item -entry +=item B<-entry> > -Specifies the index number of the volume entry to delete. Use the -B command to display the index numbers for a -volume set's volume entries. +Specifies the index number of the volume entry to delete. Use the B command to display the index numbers for a volume set's +volume entries. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command deletes the fourth volume entry from the volume set -called B: +called C: % backup delvolentry -name sys -entry 4 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_delvolset.pod b/doc/man-pages/pod8/backup_delvolset.pod index 9cc0625af..77a5c7fa4 100644 --- a/doc/man-pages/pod8/backup_delvolset.pod +++ b/doc/man-pages/pod8/backup_delvolset.pod @@ -4,18 +4,18 @@ backup delvolset - Deletes one or more volume sets from the Backup Database =head1 SYNOPSIS -backup delvolset -name >+ -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-name> >+ [B<-localauth>] + [B<-cell> >] [B<-help>] -B >+ [B<-l>] [B<-c> >] [-h] +B B<-n> >+ [B<-l>] + [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup delvolset command deletes each volume set named by -the B<-name> argument, and the volume entries each contains, from the -Backup Database. The B command lists the -volume sets (and their volume entries) currently defined in the Backup -Database. +The B command deletes each volume set named by the +B<-name> argument, and the volume entries each contains, from the Backup +Database. The B command lists the volume sets (and +their volume entries) currently defined in the Backup Database. =head1 CAUTIONS @@ -27,53 +27,51 @@ destroys the temporary volume set automatically. =over 4 -=item -name +=item B<-name> >+ Names each volume set to delete. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command deletes the volume set called user and all -volume entries in it: +The following command deletes the volume set called user and all volume +entries in it: % backup delvolset user =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_diskrestore.pod b/doc/man-pages/pod8/backup_diskrestore.pod index 1e14adafe..e59e6e88e 100644 --- a/doc/man-pages/pod8/backup_diskrestore.pod +++ b/doc/man-pages/pod8/backup_diskrestore.pod @@ -4,70 +4,67 @@ backup diskrestore - Restores the entire contents of a partition =head1 SYNOPSIS -backup diskrestore -server > -B<-partition> > - [-portoffset >+] - [-newserver >] - [-newpartition >] - [-extension >] - [B<-n>] [B<-localauth>] [B<-cell> >] [-help] - -B > -pa > -[B<-po> >+] [B<-news> >] - [B<-newp> >] [-e >] - [B<-n>] [B<-l>] [B<-c> >] [-h] +B B<-server> > + B<-partition> > + [B<-portoffset> >+] + [B<-newserver> >] + [B<-newpartition> >] + [B<-extension> >] + [B<-n>] [B<-localauth>] [B<-cell> >] [B<-help>] + +B B<-s> > B<-pa> > + [B<-po> >+] [B<-news> >] + [B<-newp> >] + [B<-e> >] [B<-n>] [B<-l>] + [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup diskrestore command restores all of the volumes for -which the Volume Location Database (VLDB) lists a read/write site on the -partition specified with the B<-server> and B<-partition> -arguments. It is useful if a disk or machine failure corrupts or -destroys the data on an entire partition. (To restore any read-only or -backup volumes that resided on the partition, use the B -and B commands, respectively, after restoring the -read/write version.) +The B command restores all of the volumes for which +the Volume Location Database (VLDB) lists a read/write site on the +partition specified with the B<-server> and B<-partition> arguments. It is +useful if a disk or machine failure corrupts or destroys the data on an +entire partition. (To restore any read-only or backup volumes that resided +on the partition, use the B and B commands, +respectively, after restoring the read/write version.) If restoring only selected volumes to a single site, it is usually more -efficient to use the B command. To restore -multiple volumes to many different sites, use the B command. - -(If the FILE YES instruction appears in the -BI file on the Tape -Coordinator machine associated with the specified port offset, then the Backup -System restores data from the backup data file listed for that port offset in -the Tape Coordinator's B file, -instead of from tape. For the sake of clarity, the following text -refers to tapes only, but the Backup System handles backup data files in much -the same way.) +efficient to use the B command. To restore multiple +volumes to many different sites, use the B command. + +(If the C instruction appears in the +F> file on the Tape Coordinator machine +associated with the specified port offset, then the Backup System restores +data from the backup data file listed for that port offset in the Tape +Coordinator's F file, instead of from +tape. For the sake of clarity, the following text refers to tapes only, +but the Backup System handles backup data files in much the same way.) The Backup System determines whether the read/write or backup version of -each volume was dumped more recently, and restores the dumps of that version, -starting with the most recent full dump. It resets the creation +each volume was dumped more recently, and restores the dumps of that +version, starting with the most recent full dump. It resets the creation timestamp of each restored volume to the date and time at which it begins -restoring the volume (the creation timestamp appears in the -C field of the output from the B and -B commands). +restoring the volume (the creation timestamp appears in the C +field of the output from the B and B commands). If all of the full and incremental dumps of all relevant volumes were not written on compatible tape devices, use the B<-portoffset> argument to -list multiple port offset numbers in the order in which the tapes are needed -(first list the port offset for the full dump, second the port offset for the -level 1 incremental dump, and so on). This implies that the full dumps -of all relevant volumes must have been written to a type of tape that the -first Tape Coordinator can read, the level 1 incremental dumps to a type of -tape the second Tape Coordinator can read, and so on. If dumps are on -multiple incompatible tape types, use the B command -to restore individual volumes, or the B command -after defining groups of volumes that were dumped to compatible tape -types. For further discussion, see the I. +list multiple port offset numbers in the order in which the tapes are +needed (first list the port offset for the full dump, second the port +offset for the level 1 incremental dump, and so on). This implies that the +full dumps of all relevant volumes must have been written to a type of +tape that the first Tape Coordinator can read, the level 1 incremental +dumps to a type of tape the second Tape Coordinator can read, and so +on. If dumps are on multiple incompatible tape types, use the B command to restore individual volumes, or the B command after defining groups of volumes that were dumped +to compatible tape types. For further discussion, see the I. By default, the Backup System restores the contents of the specified -partition to that same partition. To restore the contents to an -alternate site, combine the following options as indicated. The Backup -System removes each volume from the original site, if it still exists, and +partition to that same partition. To restore the contents to an alternate +site, combine the following options as indicated. The Backup System +removes each volume from the original site, if it still exists, and records the change of site in the VLDB. =over 4 @@ -77,134 +74,125 @@ records the change of site in the VLDB. To restore to a different partition on the same file server machine, provide the B<-newpartition> argument. - =item * To restore to the partition with the same name on a different file server machine, provide the B<-newserver> argument. - =item * -To restore to a completely different site, combine the -B<-newserver> and B<-newpartition> arguments. - +To restore to a completely different site, combine the B<-newserver> and +B<-newpartition> arguments. =back By default, the Backup System overwrites the contents of existing volumes -with the restored data. To create a new volume to house the restored -data instead, use the B<-extension> argument. The Backup System -creates the new volume at the site designated by the B<-newserver> and -B<-newpartition> arguments if they are used or the B<-server> -and B<-partition> arguments otherwise. It derives the volume -name by adding the extension to the read/write base name listed in the VLDB, -and creates a new VLDB entry. The command does not affect the existing -volume in any way. However, if a volume with the specified extension -also already exists, the command overwrites it. +with the restored data. To create a new volume to house the restored data +instead, use the B<-extension> argument. The Backup System creates the new +volume at the site designated by the B<-newserver> and B<-newpartition> +arguments if they are used or the B<-server> and B<-partition> arguments +otherwise. It derives the volume name by adding the extension to the +read/write base name listed in the VLDB, and creates a new VLDB entry. The +command does not affect the existing volume in any way. However, if a +volume with the specified extension also already exists, the command +overwrites it. To print out a list of the tapes containing the needed dumps, without -actually performing the restore operation, include the B<-n> flag -along with the other options to be used on the actual command. - -The Tape Coordinator's default response to this command is to access -the first tape it needs by invoking the B instruction in the -local BI file, or by prompting the backup -operator to insert the tape if there is no B -instruction. However, if the B instruction -appears in the BI file, or if the issuer of -the B command included the B<-noautoquery> flag, the -Tape Coordinator instead expects the tape to be in the device already. -If it is not, or is the wrong tape, the Tape Coordinator invokes the -B instruction or prompts the operator. It also invokes -the B instruction or prompts for any additional tapes needed to -complete the restore operation; the backup operator must arrange to -provide them. +actually performing the restore operation, include the B<-n> flag along +with the other options to be used on the actual command. + +The Tape Coordinator's default response to this command is to access the +first tape it needs by invoking the C instruction in the local +F> file, or by prompting the backup operator to insert +the tape if there is no C instruction. However, if the C instruction appears in the F> file, or if the +issuer of the B command included the B<-noautoquery> flag, the Tape +Coordinator instead expects the tape to be in the device already. If it +is not, or is the wrong tape, the Tape Coordinator invokes the C +instruction or prompts the operator. It also invokes the C +instruction or prompts for any additional tapes needed to complete the +restore operation; the backup operator must arrange to provide them. =head1 CAUTIONS -If issuing this command to recover data after a disk crash or other damage, -be sure not to issue the B command first. Doing -so destroys the VLDB record of the volumes that resided on the -partition. +If issuing this command to recover data after a disk crash or other +damage, be sure not to issue the B command first. Doing so +destroys the VLDB record of the volumes that resided on the partition. =head1 OPTIONS =over 4 -=item -server +=item B<-server> > Names the file server machine that the VLDB lists as the site of the volumes that need to be restored. -=item -partition +=item B<-partition> > Names the partition that the VLDB lists as the site of the volumes that need to be restored. -=item -portoffset +=item B<-portoffset> >+ Specifies one or more port offset numbers (up to a maximum of 128), each -corresponding to a Tape Coordinator to use in the operation. If there -is more than one value, the Backup System uses the first one when restoring +corresponding to a Tape Coordinator to use in the operation. If there is +more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 -incremental dump of each volume, and so on. It uses the final value in -the list when restoring dumps at the corresponding depth in the dump hierarchy +incremental dump of each volume, and so on. It uses the final value in the +list when restoring dumps at the corresponding depth in the dump hierarchy and at all lower levels. Provide this argument unless the default value of 0 (zero) is appropriate -for all dumps. If B<0> is just one of the values in the list, -provide it explicitly in the appropriate order. +for all dumps. If C<0> is just one of the values in the list, provide it +explicitly in the appropriate order. -=item -newserver +=item B<-newserver> > -Names an alternate file server machine to which to restore the -volumes. If this argument is omitted, the volumes are restored to the -file server machine named by the B<-server> argument. +Names an alternate file server machine to which to restore the volumes. If +this argument is omitted, the volumes are restored to the file server +machine named by the B<-server> argument. -=item -newpartition +=item B<-newpartition> > Names an alternate partition to which to restore the data. If this -argument is omitted, the volumes are restored to the partition named by the -B<-partition> argument. +argument is omitted, the volumes are restored to the partition named by +the B<-partition> argument. -=item -extension +=item B<-extension> > Creates a new volume for each volume being restored, to house the restored -data. The Backup System derives the new volume's name by appending -the specified string to the read/write base name listed in the VLDB, and -creates a new VLDB volume entry. The Backup System preserves the -contents of the volumes on the partition, if any still exist. Any -string other than B<.readonly> or B<.backup> is -acceptable, but the combination of the base name and extension cannot exceed -22 characters in length. To use a period to separate the extension from -the name, specify it as the first character of the string (as in -B<.rst>, for example). - -=item -n +data. The Backup System derives the new volume's name by appending the +specified string to the read/write base name listed in the VLDB, and +creates a new VLDB volume entry. The Backup System preserves the contents +of the volumes on the partition, if any still exist. Any string other than +C<.readonly> or C<.backup> is acceptable, but the combination of the base +name and extension cannot exceed 22 characters in length. To use a period +to separate the extension from the name, specify it as the first character +of the string (as in C<.rst>, for example). + +=item B<-n> Displays a list of the tapes necessary to perform the requested restore, without actually performing the operation. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -216,41 +204,39 @@ displays the following messages: Restore operation on volume I failed due to tape error Do you want to continue (y/n)? -where I is the name of the volume that was being restored when -the tape error occurred. Enter the value B to continue the -operation without restoring the indicated volume or the value B to -terminate the operation. In the latter case, the operator can then -attempt to determine the cause of the tape error. +where I is the name of the volume that was being restored when the +tape error occurred. Enter the value B to continue the operation +without restoring the indicated volume or the value C to terminate the +operation. In the latter case, the operator can then attempt to determine +the cause of the tape error. -If the issuer includes the -n flag with the command, the -following string appears at the head of the list of the tapes necessary to -perform the restore operation: +If the issuer includes the B<-n> flag with the command, the following +string appears at the head of the list of the tapes necessary to perform +the restore operation: Tapes needed: =head1 EXAMPLES The following command restores the volumes for which the VLDB lists a -read/write site on the B partition of the machine -B. The Tape Coordinator associated -with port offset 3 performs the operation. +read/write site on the F partition of the machine +C. The Tape Coordinator associated with port offset 3 +performs the operation. % backup diskrestore -server fs5.abc.com -partition /vicepd -portoffset 3 The following command restores the volumes for which the VLDB lists a -read/write site on the B partition of the machine -B to a new site: the -B partition on the machine -B. The Tape Coordinator associated -with port offset 0 performs the operation. (The command appears here on -two lines only for legibility.) +read/write site on the F partition of the machine C +to a new site: the F partition on the machine C. The +Tape Coordinator associated with port offset 0 performs the +operation. (The command appears here on two lines only for legibility.) % backup diskrestore -server fs1.abc.com -partition /vicepb \ -newserver fs3.abc.com -newpartition /vicepa The following command lists the tapes required to restore the volumes for -which the VLDB lists a read/write site on the B partition of -the machine B: +which the VLDB lists a read/write site on the F partition of the +machine C: % backup diskrestore -server fs4.abc.com -partition /vicepm -n Tapes needed: @@ -262,20 +248,19 @@ the machine B: =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server or Volume Location (VL) Server is -running, and on every file server machine that houses an affected -volume. If the B<-localauth> flag is included, the issuer must -instead be logged on to a server machine as the local superuser -B. +The issuer must be listed in the F file on every +machine where the Backup Server or Volume Location (VL) Server is running, +and on every file server machine that houses an affected volume. If the +B<-localauth> flag is included, the issuer must instead be logged on to a +server machine as the local superuser C. =head1 SEE ALSO -L, -L, -L, -L, -L, +L, +L, +L, +L, +L, L, L, L, diff --git a/doc/man-pages/pod8/backup_dump.pod b/doc/man-pages/pod8/backup_dump.pod index 7ba8c6280..617f516f4 100644 --- a/doc/man-pages/pod8/backup_dump.pod +++ b/doc/man-pages/pod8/backup_dump.pod @@ -4,250 +4,238 @@ backup dump - Creates a dump (dumps a volume set at a particular dump level) =head1 SYNOPSIS -B [B<-volumeset> >] [-dump >] -[B<-portoffset> >] [B<-at> >+] - [B<-append>] [B<-n>] [-file >] - [B<-localauth>] [-B >] [-help] +B [B<-volumeset> >] + [B<-dump> >] [B<-portoffset> >] + [B<-at> >+] [B<-append>] [B<-n>] + [B<-file> >] [B<-localauth>] [-B >] + [B<-help>] -B [B<-v> >] [-d >] -[B<-p> >] [B<-at> >+] - [B<-ap>] [B<-n>] [B<-f> >] [B<-l>] [B<-c> >] [-h] +B [B<-v> >] [B<-d> >] + [B<-p> >] [B<-at> >+] + [B<-ap>] [B<-n>] [B<-f> >] [B<-l>] [B<-c> >] + [B<-h>] =head1 DESCRIPTION -The backup dump command either dumps the volume set specified by -the B<-volumeset> argument at the dump level specified by the -B<-dump> argument and creates a Backup Database dump record about it, -or executes the dump instructions listed in the file named by the -B<-file> argument. The Tape Coordinator indicated by the -B<-portoffset> argument (or on each command in the file) executes the -operation. - -(If the FILE YES instruction appears in the -BI file on the Tape -Coordinator machine associated with the specified port offset, then the Backup -System dumps data to the backup data file listed for that port offset in the -Tape Coordinator's B file, rather -than to tape. For the sake of clarity, the following text refers to -tapes only, but the Backup System handles backup data files in much the same -way.) - -The term I refers to copying a collection of data to tape -or a backup data file, and the resulting collection is termed a -I. The set of tapes that contain one or more dumps is -called a I. The first dump in a dump set is its -I, and any dumps subsequently added to the dump set (by -use of the B<-append> argument) are I. -Creating appended dumps is optional, and appended dumps can be of different -volume sets, and at different dump levels, than the initial dump. +The B command either dumps the volume set specified by the +B<-volumeset> argument at the dump level specified by the B<-dump> +argument and creates a Backup Database dump record about it, or executes +the dump instructions listed in the file named by the B<-file> +argument. The Tape Coordinator indicated by the B<-portoffset> argument +(or on each command in the file) executes the operation. + +(If the C instruction appears in the +F> file on the Tape Coordinator machine +associated with the specified port offset, then the Backup System dumps +data to the backup data file listed for that port offset in the Tape +Coordinator's F file, rather than to tape. For +the sake of clarity, the following text refers to tapes only, but the +Backup System handles backup data files in much the same way.) + +The term I refers to copying a collection of data to tape or a +backup data file, and the resulting collection is termed a I. The +set of tapes that contain one or more dumps is called a I. The +first dump in a dump set is its I, and any dumps +subsequently added to the dump set (by use of the B<-append> argument) are +I. Creating appended dumps is optional, and appended +dumps can be of different volume sets, and at different dump levels, than +the initial dump. A I, created at a full dump level in the dump hierarchy, -contains all of the data that existed at the time of the dump in the volumes -belonging to the volume set. An I, created at -an incremental dump level, contains only data that has changed since the -volume set was dumped at the incremental level's I (the dump level immediately above the incremental level in the -hierarchy), which can be a full or incremental level. More -specifically, an incremental dump includes only the files and directories that -have modification timestamps later than the I of the -volume included at the parent dump level. For backup and read-only -volumes, the clone date is the time at which the volume was cloned from its -read/write source before being included in the parent dump; for -read/write volumes, it represents the time at which the volume was locked for -inclusion in the parent dump. The clone date appears in the I field of the output from the B -command. As an example, an incremental dump at the -B level includes only files and directories that -have changed since the volume set was dumped at the B -level. - -Initiating different types of dump operations +contains all of the data that existed at the time of the dump in the +volumes belonging to the volume set. An I, created at an +incremental dump level, contains only data that has changed since the +volume set was dumped at the incremental level's I (the +dump level immediately above the incremental level in the hierarchy), +which can be a full or incremental level. More specifically, an +incremental dump includes only the files and directories that have +modification timestamps later than the I of the volume +included at the parent dump level. For backup and read-only volumes, the +clone date is the time at which the volume was cloned from its read/write +source before being included in the parent dump; for read/write volumes, +it represents the time at which the volume was locked for inclusion in the +parent dump. The clone date appears in the I field of the +output from the B command. As an example, an incremental +dump at the C level includes only files and +directories that have changed since the volume set was dumped at the +C level. + +=head2 Initiating different types of dump operations To initiate a dump operation that is to start as soon as the relevant Tape -Coordinator is available, provide only the B<-volumeset>, -B<-dump>, B<-portoffset>, and optionally B<-append> -options. To schedule a single B command to execute -in the future, also include the B<-at> argument to specify the start -time. +Coordinator is available, provide only the B<-volumeset>, B<-dump>, +B<-portoffset>, and optionally B<-append> options. To schedule a single +B command to execute in the future, also include the B<-at> +argument to specify the start time. -To append a dump to an existing dump set, include the -append -flag. The Backup System imposes the following conditions on appended -dumps: +To append a dump to an existing dump set, include the B<-append> flag. The +Backup System imposes the following conditions on appended dumps: =over 4 =item * If writing to tape, the Tape Coordinator checks that it is the final one -in a dump set for which there are complete and valid tape and dump records in -the Backup Database. If not, it rejects the tape and requests an -acceptable one. The operator can use the B<-dbadd> argument to -the B command to insert the necessary records into -the database. - +in a dump set for which there are complete and valid tape and dump records +in the Backup Database. If not, it rejects the tape and requests an +acceptable one. The operator can use the B<-dbadd> argument to the +B command to insert the necessary records into the +database. =item * The most recent dump on the tape or in the backup data file must have completed successfully. - =item * The dump set must begin with an initial dump that is recorded in the -Backup Database. If there are no dumps on the tape, then the Backup -System treats the dump operation as an initial dump and imposes the relevant +Backup Database. If there are no dumps on the tape, then the Backup System +treats the dump operation as an initial dump and imposes the relevant requirements (for example, checks the AFS tape name if appropriate). - =back -To schedule multiple dump operations, list the operations in the file named -by the B<-file> argument. Optionally include the B<-at> -argument to specify when the B command interpreter reads the -file; otherwise it reads it immediately. Do not combine the -B<-file> argument with the command's first three arguments or the -B<-append> or B<-n> flags. The commands in the file can -include any of the B command's arguments, including -the B<-at> argument to schedule them to run even later in the -future. +To schedule multiple dump operations, list the operations in the file +named by the B<-file> argument. Optionally include the B<-at> argument to +specify when the B command interpreter reads the file; otherwise +it reads it immediately. Do not combine the B<-file> argument with the +command's first three arguments or the B<-append> or B<-n> flags. The +commands in the file can include any of the B command's +arguments, including the B<-at> argument to schedule them to run even +later in the future. To generate a list of the volumes included in a dump, without actually -dumping them, combine the B<-n> flag with the options to be used on -the actual command. +dumping them, combine the B<-n> flag with the options to be used on the +actual command. -How the Backup System executes a dump operation +=head2 How the Backup System executes a dump operation -Before beginning a dump operation, the Backup System verifies that there is -a Backup Database entry for the volume set, dump level, and port -offset. If the command is correctly formed and issued in interactive -mode, it is assigned a job number and added to the jobs list. List jobs -in interactive mode by using the B<(backup) jobs> command; -terminate them with the B<(backup) kill> command. +Before beginning a dump operation, the Backup System verifies that there +is a Backup Database entry for the volume set, dump level, and port +offset. If the command is correctly formed and issued in interactive mode, +it is assigned a job number and added to the jobs list. List jobs in +interactive mode by using the B command; terminate them with +the B command. After obtaining the list of volumes to dump from the Volume Location (VL) Server, the Backup System sorts the list by site (server and -partition). It groups volumes from the same site together in the dump -to minimize the number of times the operator must change tapes during restore +partition). It groups volumes from the same site together in the dump to +minimize the number of times the operator must change tapes during restore operations. The dependence of an incremental dump on its parent means that a valid parent dump must already exist for the Backup System to create its child incremental dump. If the Backup System does not find a record of a dump -created at the immediate parent dump level, it looks in the Backup Database -for a dump created at one level higher in the hierarchy, and so on, up to the -full dump level if necessary. It creates an incremental dump at the -level one below the lowest valid parent dump set that it finds. If it -fails to find even a full dump, it dumps the volume set at the full dump -level. +created at the immediate parent dump level, it looks in the Backup +Database for a dump created at one level higher in the hierarchy, and so +on, up to the full dump level if necessary. It creates an incremental dump +at the level one below the lowest valid parent dump set that it finds. If +it fails to find even a full dump, it dumps the volume set at the full +dump level. If the Backup System is unable to access a volume during a dump operation, it skips the volume and dumps the remaining volumes from the volume -set. Possible reasons a volume is inaccessible include server machine -or process outages, or that the volume was moved between the time the Volume -Location (VL) Server generated the list of sites for the volume in the volume -set and the time the Backup System actually attempts to dump the data in -it. After the first dumping pass, the Backup System attempts to dump -each volume it skipped. If it still cannot dump a volume and the -B instruction does not appear in the -BI file, it queries the operator as to -whether it needs to attempt to dump the volume again, omit the volume from the -dump, or halt the dump operation altogether. When prompted, the -operator can attempt to solve whatever problem prevented the Backup System -from accessing the volumes. If the B instruction -appears in the BI file, the Backup System -omits the volume from the dump. +set. Possible reasons a volume is inaccessible include server machine or +process outages, or that the volume was moved between the time the Volume +Location (VL) Server generated the list of sites for the volume in the +volume set and the time the Backup System actually attempts to dump the +data in it. After the first dumping pass, the Backup System attempts to +dump each volume it skipped. If it still cannot dump a volume and the +C instruction does not appear in the F> file, +it queries the operator as to whether it needs to attempt to dump the +volume again, omit the volume from the dump, or halt the dump operation +altogether. When prompted, the operator can attempt to solve whatever +problem prevented the Backup System from accessing the volumes. If the +C instruction appears in the F> file, the +Backup System omits the volume from the dump. Before scheduling a dump operation, the Backup System verifies that the date specified by the B<-at> argument is in the future, and checks the -validity of the volume set, dump level and port offset as for a regular dump -operation. It checks the validity of the parameters again just before +validity of the volume set, dump level and port offset as for a regular +dump operation. It checks the validity of the parameters again just before actually running the scheduled operation. Before writing an initial dump to a tape that does not have a permanent name on the label, the Backup System checks that the AFS tape name on the label is acceptable. If desired, disable name checking by including the -B instruction in the -BI file. +C instruction in the F> file. If AFS tape name checking is enabled, the Backup System accepts the -following three types of values for the AFS tape name. If the name on -the label does not conform, the Backup System obtains a tape with an -acceptable label by invoking the B instruction in the -BI file or prompting the operator. +following three types of values for the AFS tape name. If the name on the +label does not conform, the Backup System obtains a tape with an +acceptable label by invoking the C instruction in the +F> file or prompting the operator. -=item * +=over 4 -A name of the form -I, where -I matches the value of the B<-volumeset> -argument, I matches the last element in the pathname -value of the B<-dump> argument, and I reflects the -tape's place in a multitape dump set. As an example, the first -tape in a dump set for which the initial dump is of volume set B -at the dump level B has AFS tape name -B. If the label records this type -of AFS tape name, the Backup System retains the AFS tape name and writes the -dump to the tape. +=item * +A name of the form I, where +I matches the value of the B<-volumeset> argument, +I matches the last element in the pathname value of the +B<-dump> argument, and I reflects the tape's place in a +multitape dump set. As an example, the first tape in a dump set for which +the initial dump is of volume set C at the dump level +C has AFS tape name C. If the label +records this type of AFS tape name, the Backup System retains the AFS tape +name and writes the dump to the tape. =item * -The string C<>, which usually indicates that a backup -operator has used the B command to write a label on -the tape, but did not include the B<-name> argument to assign an AFS -tape name. Presumably, the operator did include the B<-pname> -argument to assign a permanent name. If the label records a -C<> value, the Backup System constructs and records on the -label the appropriate AFS tape name, and writes the dump on the tape. - +The string C<< >>, which usually indicates that a backup operator +has used the B command to write a label on the tape, but +did not include the B<-name> argument to assign an AFS tape +name. Presumably, the operator did include the B<-pname> argument to +assign a permanent name. If the label records a C<< >> value, the +Backup System constructs and records on the label the appropriate AFS tape +name, and writes the dump on the tape. =item * No value at all, because the tape has never been labeled or used in the -Backup System. As when the AFS tape name is C<>, the -Backup System constructs and records on the label the appropriate AFS tape -name, and writes the dump on the tape. +Backup System. As when the AFS tape name is C<< >>, the Backup +System constructs and records on the label the appropriate AFS tape name, +and writes the dump on the tape. +=back To determine how much data it can write to a tape, the Tape Coordinator -reads the capacity recorded on the tape's label (placed there by -including the B<-size> argument to the B -command). If the label's capacity field is empty, the Tape -Coordinator uses the capacity recorded for the specified port offset in the -local B file. If the capacity field in the -B file is also empty, the Tape Coordinator uses the -maximum capacity of 2 TB. +reads the capacity recorded on the tape's label (placed there by including +the B<-size> argument to the B command). If the label's +capacity field is empty, the Tape Coordinator uses the capacity recorded +for the specified port offset in the local F file. If the +capacity field in the F file is also empty, the Tape +Coordinator uses the maximum capacity of 2 TB. During a dump operation, the Tape Coordinator tracks how much data it has -written and stops shortly before it reaches what it believes is the -tape's capacity. If it is in the middle of writing the data for a -volume when it reaches that point, it writes a special marker that indicates -an interrupted volume and continues writing the volume on the next -tape. It can split a volume this way during both an initial and an -appended dump, and the fact that the volume resides on multiple tapes is -automatically recorded in the Backup Database. +written and stops shortly before it reaches what it believes is the tape's +capacity. If it is in the middle of writing the data for a volume when it +reaches that point, it writes a special marker that indicates an +interrupted volume and continues writing the volume on the next tape. It +can split a volume this way during both an initial and an appended dump, +and the fact that the volume resides on multiple tapes is automatically +recorded in the Backup Database. If the tape is actually larger than the expected capacity, then the Tape Coordinator simply does not use the excess tape. If the tape is smaller than the expected capacity, the Tape Coordinator can reach the end-of-tape -(EOT) unexpectedly while it is writing data. If the Tape Coordinator is -in the middle of the writing data from a volume, it obtains a new tape and +(EOT) unexpectedly while it is writing data. If the Tape Coordinator is in +the middle of the writing data from a volume, it obtains a new tape and rewrites the entire contents of the interrupted volume to it. The data -from the volume that was written to the previous tape remains there, but is -never used. +from the volume that was written to the previous tape remains there, but +is never used. -The Backup System allows recycling of tapes (writing a new dump set over an -old dump set that is no longer needed), but imposes the following +The Backup System allows recycling of tapes (writing a new dump set over +an old dump set that is no longer needed), but imposes the following conditions: =over 4 =item * -All dumps in the old dump set must be expired. The Backup System -always checks expiration dates, even when name checking is disabled. - +All dumps in the old dump set must be expired. The Backup System always +checks expiration dates, even when name checking is disabled. =item * @@ -256,85 +244,80 @@ checking is enabled, then the AFS tape name derived from the new initial dump's volume set name and dump level name must match the AFS tape name already recorded on the label. - =item * The tape cannot already have data on it that belongs to the dump currently being performed, because that implies that the operator or automated tape device has not removed the previous tape from the drive, or has mistakenly reinserted it. The Tape Coordinator generates the following message and -attempts to obtain another tape: - +attempts to obtain another tape: Can't overwrite tape containing the dump in progress =item * The tape cannot contain data from a parent dump of the current -(incremental) dump, because overwriting a parent dump makes it impossible to -restore data from the current dump. The Tape Coordinator generates the -following message and attempts to obtain another tape: - +(incremental) dump, because overwriting a parent dump makes it impossible +to restore data from the current dump. The Tape Coordinator generates the +following message and attempts to obtain another tape: Can't overwrite the parent dump I (I) =back To recycle a tape before all dumps on it have expired or if the AFS tape -name is wrong, use the B command to overwrite the -tape's label and remove all associated tape and dump records from the -Backup Database. - -The Tape Coordinator's default response to this command is to access -the first tape by invoking the B instruction in the -BI file, or by prompting the backup operator -to insert the tape if there is no B instruction. -However, if the B instruction appears in the -BI file, or if the issuer of the -B command included the B<-noautoquery> flag, the Tape -Coordinator instead expects the tape to be in the device already. If it -is not, the Tape Coordinator invokes the B instruction or -prompts the operator. It also invokes the B instruction -or prompts for any additional tapes needed to complete the dump -operation; the issuer must arrange to provide them. +name is wrong, use the B command to overwrite the tape's +label and remove all associated tape and dump records from the Backup +Database. + +The Tape Coordinator's default response to this command is to access the +first tape by invoking the C instruction in the +F> file, or by prompting the backup operator to insert +the tape if there is no C instruction. However, if the C instruction appears in the F> file, or if the +issuer of the B command included the B<-noautoquery> flag, the Tape +Coordinator instead expects the tape to be in the device already. If it is +not, the Tape Coordinator invokes the C instruction or prompts the +operator. It also invokes the C instruction or prompts for any +additional tapes needed to complete the dump operation; the issuer must +arrange to provide them. =head1 CAUTIONS If a dump operation is interrupted or fails for any reason, data from all volumes written to tape before the interrupt are valid can be used in a restore operation. The Backup Database includes an entry for the failed -dump and for each volume that was successfully dumped. See the I for information on dealing with interrupted -dumps. +dump and for each volume that was successfully dumped. See the I for information on dealing with interrupted dumps. If dumping to tape rather than a backup data file, it is best to use only -compatible tape devices (ones that can read the same type of tape). -Using compatible devices greatly simplifies restore operations. The -B<-portoffset> argument to the B and -B commands accepts multiple port offset numbers, -but the Backup System uses the first listed port offset when restoring all -full dumps, the second port offset when restoring all level 1 dumps, and so +compatible tape devices (ones that can read the same type of tape). Using +compatible devices greatly simplifies restore operations. The +B<-portoffset> argument to the B and B commands accepts multiple port offset numbers, but the +Backup System uses the first listed port offset when restoring all full +dumps, the second port offset when restoring all level 1 dumps, and so on. At the very least, use compatible tape devices to perform dumps at each level. If compatible tape devices are not used, the B command must be used to restore one volume at a time. -Valid (unexpired) administrative tokens must be available to the -B command interpreter both when it reads the file named by the -B<-file> argument and when it runs each operation listed in the -file. Presumably, the issuer is scheduling dumps for times when no -human operator is present, and so must arrange for valid tokens to be -available on the local machine. One option is to issue all commands (or -run all scripts) on file server machines and use the B<-localauth> -flag on the B and B commands. To protect -against improper access to the machine or the tokens, the machine must be -physically secure (perhaps even more protected than a Tape Coordinator machine -monitored by a human operator during operation). Also, if an unattended -dump requires multiple tapes, the operator must properly configure a tape -stacker or jukebox and the device configuration file. +Valid (unexpired) administrative tokens must be available to the B +command interpreter both when it reads the file named by the B<-file> +argument and when it runs each operation listed in the file. Presumably, +the issuer is scheduling dumps for times when no human operator is +present, and so must arrange for valid tokens to be available on the local +machine. One option is to issue all commands (or run all scripts) on file +server machines and use the B<-localauth> flag on the B and B +commands. To protect against improper access to the machine or the tokens, +the machine must be physically secure (perhaps even more protected than a +Tape Coordinator machine monitored by a human operator during +operation). Also, if an unattended dump requires multiple tapes, the +operator must properly configure a tape stacker or jukebox and the device +configuration file. When the command is issued in regular (non-interactive) mode, the command -shell prompt does not return until the dump operation completes. To -avoid having to open additional connections, issue the command in interactive +shell prompt does not return until the dump operation completes. To avoid +having to open additional connections, issue the command in interactive mode, especially when including the B<-at> argument to schedule dump operations. @@ -342,112 +325,100 @@ operations. =over 4 -=item -volumeset +=item B<-volumeset> > -Names the volume set to dump. The -dump argument must be -provided along with this one; do not combine them with the -B<-file> argument. If using a temporary volume set, the -B command must be issued within the interactive session in -which the B command was issued with the -B<-temporary> flag. +Names the volume set to dump. The B<-dump> argument must be provided along +with this one; do not combine them with the B<-file> argument. If using a +temporary volume set, the B command must be issued within the +interactive session in which the B command was issued +with the B<-temporary> flag. -=item -dump +=item B<-dump> > Specifies the complete pathname of the dump level at which to dump the -volume set. The B<-volumeset> argument must be provided along -with this one; do not combine them with the B<-file> -argument. +volume set. The B<-volumeset> argument must be provided along with this +one; do not combine them with the B<-file> argument. -=item -portoffset +=item B<-portoffset> > Specifies the port offset number of the Tape Coordinator handling the -tapes for this operation. It must be provided unless the default value -of 0 (zero) is appropriate; do not combine it with the B<-file> -argument. +tapes for this operation. It must be provided unless the default value of +0 (zero) is appropriate; do not combine it with the B<-file> argument. -=item -at -> +=item B<-at> > Specifies the date and time in the future at which to run the command, or -to read the file named by the B<-file> argument. Provide a -value in the format I [I], where the -month (I), day (I
), and year (I) are -required. Valid values for the year range from B<1970> to -B<2037>; higher values are not valid because the latest possible -date in the standard UNIX representation is in February 2038. The -Backup System automatically reduces any later date to the maximum -value. +to read the file named by the B<-file> argument. Provide a value in the +format I [I], where the month (I), day (I
), and +year (I) are required. Valid values for the year range from C<1970> +to C<2037>; higher values are not valid because the latest possible date +in the standard UNIX representation is in February 2038. The Backup System +automatically reduces any later date to the maximum value. -The hour and minutes (I) are optional, but if provided -must be in 24-hour format (for example, the value B<14:36> -represents 2:36 p.m.). If omitted, the time -defaults to midnight (00:00 hours). +The hour and minutes (I) are optional, but if provided must be in +24-hour format (for example, the value C<14:36> represents 2:36 p.m.). If +omitted, the time defaults to midnight (00:00 hours). -As an example, the value 04/23/1999 20:20 schedules the -command for 8:20 p.m. on 23 April 1999. +As an example, the value 04/23/1999 20:20 schedules the command for 8:20 +p.m. on 23 April 1999. -=item -append +=item B<-append> Appends the dump onto the end of a tape that already contains data from -another dump. However, if the tape is not in fact part of an existing -dump set, the Backup System creates a new dump set using the parameters of -this dump. If the tape is not the last tape in the dump set, the Tape -Coordinator prompts for insertion of the appropriate tape. Do not -combine this argument with the B<-file> argument. +another dump. However, if the tape is not in fact part of an existing dump +set, the Backup System creates a new dump set using the parameters of this +dump. If the tape is not the last tape in the dump set, the Tape +Coordinator prompts for insertion of the appropriate tape. Do not combine +this argument with the B<-file> argument. -=item -n +=item B<-n> Displays the names of volumes to be included in the indicated dump, without actually performing the dump operation. Do not combine this argument with the B<-file> argument. -=item -file - -Specifies the local disk or AFS pathname of a file containing -B commands. The Backup System reads the file -immediately, or at the time specified by the B<-at> argument if it is -provided. A partial pathname is interpreted relative to the current -working directory. - -Place each backup dump command on its own line in the indicated -file, using the same syntax as for the command line, but without the word -B at the start of the line. Each command must include a -value for the B<-volumeset> and B<-dump> arguments, and for -the B<-portoffset> argument unless the default value of 0 is -appropriate. Commands in the file can also include any of the -B command's optional options. In the -following example file, the first command runs as soon as the Backup System -reads the file, whereas the other commands are themselves scheduled; the -specified date and time must be later than the date and time at which the -Backup System reads the file. +=item B<-file> > + +Specifies the local disk or AFS pathname of a file containing B +commands. The Backup System reads the file immediately, or at the time +specified by the B<-at> argument if it is provided. A partial pathname is +interpreted relative to the current working directory. + +Place each B command on its own line in the indicated file, +using the same syntax as for the command line, but without the word +B at the start of the line. Each command must include a value for +the B<-volumeset> and B<-dump> arguments, and for the B<-portoffset> +argument unless the default value of 0 is appropriate. Commands in the +file can also include any of the B command's optional +options. In the following example file, the first command runs as soon as +the Backup System reads the file, whereas the other commands are +themselves scheduled; the specified date and time must be later than the +date and time at which the Backup System reads the file. dump user /sunday1/wednesday -port 1 dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999 dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append -Do not combine this argument with the -volumeset, -B<-dump>, B<-portoffset>, B<-append>, or B<-n> -options. +Do not combine this argument with the B<-volumeset>, B<-dump>, +B<-portoffset>, B<-append>, or B<-n> options. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -455,8 +426,8 @@ are ignored. The command interpreter first generates a list of the volumes to be included in the dump by matching the entries in the volume set against the -volumes listed in the Volume Location Database (VLDB). It prints the -list following the header: +volumes listed in the Volume Location Database (VLDB). It prints the list +following the header: Preparing to dump the following volumes: @@ -466,13 +437,13 @@ processing: Starting dump. -If the issuer includes the -n flag, the output is of the -following form: +If the issuer includes the B<-n> flag, the output is of the following +form: - Starting dump of volume set 'I' (dump set 'I') - Total number of volumes : I + Starting dump of volume set '' (dump set '') + Total number of volumes : Would have dumped the following volumes: - I + where I identifies each volume by name and volume ID number. @@ -482,9 +453,9 @@ message in its window and records the error in its log and error files. =head1 EXAMPLES -The following command dumps the volumes in the volume set called -B at the dump level B. The -issuer places the necessary tapes in the device with port offset 5. +The following command dumps the volumes in the volume set called C +at the dump level C. The issuer places the necessary +tapes in the device with port offset 5. % backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5 Preparing to dump the following volumes: @@ -496,8 +467,7 @@ issuer places the necessary tapes in the device with port offset 5. Starting dump. The following command displays the list of volumes to be dumped when the -user dumps the B volume set at the B dump -level. +user dumps the C volume set at the C dump level. % backup dump -volumeset sys_sun -dump /full -n Starting dump of volume set 'sys_sun' (dump set '/full') @@ -512,31 +482,30 @@ level. . . The following command schedules a dump of the volumes in the volume set -B at the dump level B for 11:00 -p.m. on 14 June 1999. The appropriate Tape Coordinator -has port offset 0 (zero), so that argument is omitted. +C at the dump level C for 11:00 p.m. on 14 June +1999. The appropriate Tape Coordinator has port offset 0 (zero), so that +argument is omitted. % backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server or Volume Location (VL) Server is -running, and on every file server machine that houses an affected -volume. If the B<-localauth> flag is included, the issuer must -instead be logged on to a server machine as the local superuser -B. +The issuer must be listed in the F file on every +machine where the Backup Server or Volume Location (VL) Server is running, +and on every file server machine that houses an affected volume. If the +B<-localauth> flag is included, the issuer must instead be logged on to a +server machine as the local superuser C. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_dumpinfo.pod b/doc/man-pages/pod8/backup_dumpinfo.pod index 02403ff86..1b8a7be62 100644 --- a/doc/man-pages/pod8/backup_dumpinfo.pod +++ b/doc/man-pages/pod8/backup_dumpinfo.pod @@ -4,170 +4,153 @@ backup dumpinfo - Displays a dump record from the Backup Database =head1 SYNOPSIS -B [B<-ndumps> >] [-id >] -[B<-verbose>] [B<-localauth>] [B<-cell> >] [B<-help> ] +B [B<-ndumps> >] [B<-id> >] + [B<-verbose>] [B<-localauth>] [B<-cell> >] [B<-help>] -B [B<-n> >] [-i >] -[B<-v>] [B<-l>] [B<-c> >] [B<-h>] +B [B<-n> >] [-i >] [B<-v>] + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup dumpinfo command formats and displays the Backup -Database record for the specified dumps. To specify how many of the -most recent dumps to display, starting with the newest one and going back in -time, use the B<-ndumps> argument. To display more detailed -information about a single dump, use the B<-id> argument. To -display the records for the 10 most recent dumps, omit both the -B<-ndumps> and B<-id> arguments. +The B command formats and displays the Backup Database +record for the specified dumps. To specify how many of the most recent +dumps to display, starting with the newest one and going back in time, use +the B<-ndumps> argument. To display more detailed information about a +single dump, use the B<-id> argument. To display the records for the 10 +most recent dumps, omit both the B<-ndumps> and B<-id> arguments. -The -verbose flag produces very detailed information that is -useful mostly for debugging purposes. It can be combined only with the -B<-id> argument. +The B<-verbose> flag produces very detailed information that is useful +mostly for debugging purposes. It can be combined only with the B<-id> +argument. =head1 OPTIONS =over 4 -=item -ndumps +=item B<-ndumps> > Displays the Backup Database record for each of the specified number of dumps that were most recently performed. If the database contains fewer dumps than are requested, the output includes the records for all existing -dumps. Do not combine this argument with the B<-id> or -B<-verbose> options; omit all options to display the records for -the last 10 dumps. +dumps. Do not combine this argument with the B<-id> or B<-verbose> +options; omit all options to display the records for the last 10 dumps. -=item -id +=item B<-id> > Specifies the dump ID number of a single dump for which to display the -Backup Database record. Precede the I value with the -B<-id> switch; otherwise, the command interpreter interprets it -as the value of the B<-ndumps> argument. Combine this argument -with the B<-verbose> flag, but not with the B<-ndumps> -argument; omit all options to display the records for the last 10 -dumps. +Backup Database record. Precede the I value with the B<-id> +switch; otherwise, the command interpreter interprets it as the value of +the B<-ndumps> argument. Combine this argument with the B<-verbose> flag, +but not with the B<-ndumps> argument; omit all options to display the +records for the last 10 dumps. -=item -verbose +=item B<-verbose> Provides more detailed information about the dump specified with the -B<-id> argument, which must be provided along with it. Do not -combine this flag with the B<-ndumps> argument. +B<-id> argument, which must be provided along with it. Do not combine this +flag with the B<-ndumps> argument. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -If the -ndumps argument is provided, the output presents the -following information in table form, with a separate line for each dump: +If the B<-ndumps> argument is provided, the output presents the following +information in table form, with a separate line for each dump: =over 4 -=item C +=item dumpid The dump ID number. -=item C +=item parentid -The dump ID number of the dump's parent dump. A value of -C<0> (zero) identifies a full dump. +The dump ID number of the dump's parent dump. A value of C<0> (zero) +identifies a full dump. -=item C +=item lv The depth in the dump hierarchy of the dump level used to create the -dump. A value of C<0> (zero) identifies a full dump, in which -case the value in the C field is also C<0>. A -value of C<1> or greater indicates an incremental dump made at the -corresponding level in the dump hierarchy. +dump. A value of C<0> (zero) identifies a full dump, in which case the +value in the C field is also C<0>. A value of C<1> or greater +indicates an incremental dump made at the corresponding level in the dump +hierarchy. -=item C +=item created The date and time at which the Backup System started the dump operation that created the dump. -=item C +=item nt -The number of tapes that contain the data in the dump. A value of -C<0> (zero) indicates that the dump operation was terminated or -failed. Use the B command to remove such -entries. +The number of tapes that contain the data in the dump. A value of C<0> +(zero) indicates that the dump operation was terminated or failed. Use the +B command to remove such entries. -=item C +=item nvols -The number of volumes from which the dump includes data. If a -volume spans tapes, it is counted twice. A value of C<0> (zero) -indicates that the dump operation was terminated or failed; the value in -the C field is also C<0> in this case. +The number of volumes from which the dump includes data. If a volume spans +tapes, it is counted twice. A value of C<0> (zero) indicates that the dump +operation was terminated or failed; the value in the C field is also +C<0> in this case. -=item C +=item dump name The dump name in the form - I.I (I) + . () -where I is the name of the volume set, and -I is the last element in the dump level pathname at -which the volume set was dumped. +where is the name of the volume set, and + is the last element in the dump level pathname at which +the volume set was dumped. -The I, if displayed, is the dump ID of the initial -dump in the dump set to which this dump belongs. If there is no value -in parentheses, the dump is the initial dump in a dump set that has no +The , if displayed, is the dump ID of the initial dump in +the dump set to which this dump belongs. If there is no value in +parentheses, the dump is the initial dump in a dump set that has no appended dumps. =back -If the -id argument is provided alone, the first line of output -begins with the string C and reports information for the entire -dump in the following fields: +If the B<-id> argument is provided alone, the first line of output begins +with the string C and reports information for the entire dump in the +following fields: =over 4 -=item C +=item id The dump ID number. -=item C +=item level The depth in the dump hierarchy of the dump level used to create the -dump. A value of C<0> (zero) identifies a full dump. A -value of C<1> (one) or greater indicates an incremental dump made at -the specified level in the dump hierarchy. +dump. A value of C<0> (zero) identifies a full dump. A value of C<1> (one) +or greater indicates an incremental dump made at the specified level in +the dump hierarchy. -=item C +=item volumes The number of volumes for which the dump includes data. -=item C +=item created The date and time at which the dump operation began. @@ -176,31 +159,27 @@ The date and time at which the dump operation began. If an XBSA server was the backup medium for the dump (rather than a tape device or backup data file), the following line appears next: - Backup Service: I: Server: I + Backup Service: : Server: -where I is the name of the XBSA-compliant program and -I is the name of the machine on which the program runs. +where is the name of the XBSA-compliant program and + is the name of the machine on which the program runs. Next the output includes an entry for each tape that houses volume data -from the dump. Following the string C, the first two -lines of each entry report information about that tape in the following -fields: +from the dump. Following the string C, the first two lines of each +entry report information about that tape in the following fields: =over 4 -=item C +=item name -The tape's permanent name if it has one, or its AFS tape name -otherwise, and its tape ID number in parentheses. +The tape's permanent name if it has one, or its AFS tape name otherwise, +and its tape ID number in parentheses. -=item C +=item nVolumes The number of volumes for which this tape includes dump data. -=item C +=item created The date and time at which the Tape Coordinator began writing data to this tape. @@ -213,73 +192,64 @@ information appears in columns with the following headings: =over 4 -=item C +=item Pos -The relative position of each volume in this tape or file. On a -tape, the counter begins at position 2 (the tape label occupies position 1), -and increments by one for each volume. For volumes in a backup data -file, the position numbers start with 1 and do not usually increment only by -one, because each is the ordinal of the 16 KB offset in the file at which the +The relative position of each volume in this tape or file. On a tape, the +counter begins at position 2 (the tape label occupies position 1), and +increments by one for each volume. For volumes in a backup data file, the +position numbers start with 1 and do not usually increment only by one, +because each is the ordinal of the 16 KB offset in the file at which the volume's data begins. The difference between the position numbers -therefore indicates how many 16 KB blocks each volume's data -occupies. For example, if the second volume is at position 5 and the -third volume in the list is at position 9, that means that the dump of the -second volume occupies 64 KB (four 16-KB blocks) of space in the file. +therefore indicates how many 16 KB blocks each volume's data occupies. For +example, if the second volume is at position 5 and the third volume in the +list is at position 9, that means that the dump of the second volume +occupies 64 KB (four 16-KB blocks) of space in the file. -=item C +=item Clone time For a backup or read-only volume, the time at which it was cloned from its read/write source. For a Read/Write volume, it is the same as the dump creation date reported on the first line of the output. -=item C +=item Nbytes The number of bytes of data in the dump of the volume. -=item C +=item Volume -The volume name, complete with C<.backup> or -C<.readonly> extension if appropriate. +The volume name, complete with C<.backup> or C<.readonly> extension if +appropriate. =back -If both the B<-id> and -verbose options are provided, -the output is divided into several sections: +If both the B<-id> and B<-verbose> options are provided, the output is +divided into several sections: =over 4 =item * -The first section, headed by the underlined string C, -includes information about the entire dump. The fields labeled -C, C, C, and C -report the same values (though in a different order) as appear on the first -line of output when the B<-id> argument is provided by itself. -Other fields of potential interest to the backup operator are: - +The first section, headed by the underlined string C, includes +information about the entire dump. The fields labeled C, C, +C, and C report the same values (though in a different +order) as appear on the first line of output when the B<-id> argument is +provided by itself. Other fields of potential interest to the backup +operator are: =over 4 -=item C +=item Group id -The dump's I, which is recorded in the -dump's Backup Database record if the B instruction -appears in the Tape Coordinator's B< -/usr/afs/backup/CFG_>I file when the dump is created. +The dump's I, which is recorded in the dump's Backup +Database record if the C instruction appears in the Tape +Coordinator's F> file when the dump is +created. -=item C +=item maxTapes -The number of tapes that contain the dump set to which this dump -belongs. +The number of tapes that contain the dump set to which this dump belongs. -=item C +=item Start Tape Seq The ordinal of the tape on which this dump begins in the set of tapes that contain the dump set. @@ -289,60 +259,52 @@ contain the dump set. =item * For each tape that contains data from this dump, there follows a section -headed by the underlined string C. The fields labeled -C, C, and C report the same -values (though in a different order) as appear on the second and third lines -of output when the B<-id> argument is provided by itself. Other -fields of potential interest to the backup operator are: - +headed by the underlined string C. The fields labeled C, +C, and C report the same values (though in a different +order) as appear on the second and third lines of output when the B<-id> +argument is provided by itself. Other fields of potential interest to the +backup operator are: =over 4 -=item C +=item expires The date and time when this tape can be recycled, because all dumps it contains have expired. -=item C -> +=item nMBytes Data and nBytes Data Summed together, these fields represent the total amount of dumped data actually from volumes (as opposed to labels, filemarks, and other markers). -=item C +=item KBytes Tape Used The number of kilobytes of tape (or disk space, for a backup data file) used to store the dump data. It is generally larger than the sum of the -values in the C and C fields, -because it includes the space required for the label, file marks and other -markers, and because the Backup System writes data at 16 KB offsets, even if -the data in a given block doesn't fill the entire 16 KB. +values in the C and C fields, because it +includes the space required for the label, file marks and other markers, +and because the Backup System writes data at 16 KB offsets, even if the +data in a given block doesn't fill the entire 16 KB. =back =item * For each volume on a given tape, there follows a section headed by the -underlined string C. The fields labeled -C, C, C, and C -report the same values (though in a different order) as appear in the table -that lists the volumes in each tape when the B<-id> argument is -provided by itself. Other fields of potential interest to the backup -operator are: - +underlined string C. The fields labeled C, C, +C, and C report the same values (though in a different +order) as appear in the table that lists the volumes in each tape when the +B<-id> argument is provided by itself. Other fields of potential interest +to the backup operator are: =over 4 -=item C +=item id The volume ID. -=item C +=item tape The name of the tape containing this volume data. @@ -362,8 +324,7 @@ The following example displays information about the last five dumps: 924860000 924424000 1 04/23/1999 05:33 1 58 usr.fri (924424000) 925033000 0 0 04/25/1999 05:36 2 73 sys.week -The following example displays a more detailed record for a single -dump. +The following example displays a more detailed record for a single dump. % backup dumpinfo -id 922097346 Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999 @@ -373,9 +334,9 @@ dump. 1 03/22/1999 04:43 27787914 user.pat.backup The following example displays even more detailed information about the -dump displayed in the previous example (dump ID 922097346). This -example includes only one exemplar of each type of section (C, -C, and C): +dump displayed in the previous example (dump ID 922097346). This example +includes only one exemplar of each type of section (C, C, and +C): % backup dumpinfo -id 922097346 -verbose Dump @@ -433,15 +394,15 @@ C, and C): =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_help.pod b/doc/man-pages/pod8/backup_help.pod index 3a22ae0f6..c29e7b72d 100644 --- a/doc/man-pages/pod8/backup_help.pod +++ b/doc/man-pages/pod8/backup_help.pod @@ -1,77 +1,69 @@ =head1 NAME -backup help - Displays the syntax of specified backup commands or lists -functional descriptions of all B commands +backup help - Displays help for backup commands =head1 SYNOPSIS -B [B<-topic> >+] [-help] +B [B<-topic> >+] [B<-help>] -B [B<-t> >+] [-h] +B [B<-t> >+] [B<-h>] =head1 DESCRIPTION -The backup help command displays the complete online help entry -(short description and syntax statement) for each operation code specified by -the B<-topic> argument. If the B<-topic> argument is -omitted, the output includes the first line (name and short description) of -the online help entry for every B command. +The B command displays the complete online help entry (short +description and syntax statement) for each operation code specified by the +B<-topic> argument. If the B<-topic> argument is omitted, the output +includes the first line (name and short description) of the online help +entry for every B command. -To list every backup command whose name or short description -includes a specified keyword, use the B -command. +To list every backup command whose name or short description includes a +specified keyword, use the B command. =head1 OPTIONS =over 4 -=item -topic +=item B<-topic> >+ Indicates each command for which to display the complete online help -entry. Omit the B part of the command name, providing -only the operation code (for example, specify B, not B). If this argument is omitted, the output briefly describes -every B command. +entry. Omit the B part of the command name, providing only the +operation code (for example, specify B, not B). If this +argument is omitted, the output briefly describes every B command. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -The online help entry for each backup command consists of the -following two or three lines: +The online help entry for each backup command consists of the following +two or three lines: =over 4 =item * -The first line names the command and briefly describes its -function. - +The first line names the command and briefly describes its function. =item * The second line lists aliases for the command, if any. - =item * -The final line, which begins with the string C, lists the -command's options in the prescribed order. Online help entries use -the same symbols (for example, brackets) as the reference pages in this -document. - +The final line, which begins with the string C, lists the command's +options in the prescribed order. Online help entries use the same symbols +(for example, brackets) as the reference pages in this document. =back =head1 EXAMPLES -The following example displays the online help entry for the backup -dump command: +The following example displays the online help entry for the B command: % backup help dump backup dump: start dump @@ -85,8 +77,8 @@ None =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_interactive.pod b/doc/man-pages/pod8/backup_interactive.pod index fa397b98d..aab649fbc 100644 --- a/doc/man-pages/pod8/backup_interactive.pod +++ b/doc/man-pages/pod8/backup_interactive.pod @@ -4,98 +4,89 @@ backup interactive - Enters interactive mode =head1 SYNOPSIS -B [B] [B<-localauth>] [B<-cell> >] [-help] +B [B] [B<-localauth>] [B<-cell> >] + [B<-help>] -B [B] [B<-l>] [B<-c> >] [-h] +B [B] [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup interactive initiates an interactive session for -issuing B commands. As indicated in the syntax -statement, the operation code (B) is optional. +The B initiates an interactive session for issuing +B commands. As indicated in the syntax statement, the operation +code (B) is optional. -Several features of interactive mode distinguish it from regular -mode: +Several features of interactive mode distinguish it from regular mode: =over 4 =item * -In interactive mode, the C> prompt replaces the system -(shell) prompt. The operator enters only a command's operation -code (omitting the command suite name, B). - +In interactive mode, the C> prompt replaces the system (shell) +prompt. The operator enters only a command's operation code (omitting the +command suite name, B). =item * -If the B<-localauth> flag or the -cell argument is -included on the B command, the settings apply to -all commands issued during that interactive session. The issuer does -not need to type them on every command. Another consequence is that the -flag and argument do not appear in the syntax statement generated by the -B subcommand or B<-help> flag on an individual command -issued at the C> prompt. - +If the B<-localauth> flag or the B<-cell> argument is included on the +B command, the settings apply to all commands issued +during that interactive session. The issuer does not need to type them on +every command. Another consequence is that the flag and argument do not +appear in the syntax statement generated by the B subcommand or +B<-help> flag on an individual command issued at the C> prompt. =item * -The B<(backup) jobs> and (backup) kill commands are -available only in interactive mode. It is not possible to track and -terminate backup operations as cleanly in non-interactive mode. - +The B and B commands are available only in +interactive mode. It is not possible to track and terminate backup +operations as cleanly in non-interactive mode. =item * It is not necessary to enclose strings that include metacharacters in double quotes or other delimiters. - =item * -The backup command interpreter establishes a connection to the -Backup Server, Volume Server and Volume Location (VL) Server processes as it -enters interactive mode, and uses the same connection for all commands during -the session. Execution time can therefore be faster than in -non-interactive mode, in which the command interpreter must establish a new -connection for each command. - +The backup command interpreter establishes a connection to the Backup +Server, Volume Server and Volume Location (VL) Server processes as it +enters interactive mode, and uses the same connection for all commands +during the session. Execution time can therefore be faster than in +non-interactive mode, in which the command interpreter must establish a +new connection for each command. =back -To exit an interactive session, issue the (backup) quit -command. +To exit an interactive session, issue the B command. =head1 OPTIONS =over 4 -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example shows how the -localauth flag and -B<-cell> argument do not appear when the B -subcommand is issued in interactive mode. +The following example shows how the B<-localauth> flag and B<-cell> +argument do not appear when the B subcommand is issued in +interactive mode. % backup backup> help dump @@ -106,16 +97,16 @@ subcommand is issued in interactive mode. =head1 PRIVILEGE REQUIRED -None. However, backup commands that require privilege in -regular mode still require it in interactive mode. +None. However, B commands that require privilege in regular mode +still require it in interactive mode. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_jobs.pod b/doc/man-pages/pod8/backup_jobs.pod index dd5a12080..e848bca43 100644 --- a/doc/man-pages/pod8/backup_jobs.pod +++ b/doc/man-pages/pod8/backup_jobs.pod @@ -4,23 +4,21 @@ backup jobs - Lists pending and running operations in interactive mode =head1 SYNOPSIS -B [-help] +B [B<-help>] -B [-h] +B [B<-h>] =head1 DESCRIPTION -The (backup) jobs command lists the job ID number and status of -each B operation running or pending in the current interactive -session. +The B command lists the job ID number and status of each +B operation running or pending in the current interactive session. -This command can be issued in interactive mode only. If the issuer -of the B command included the -B<-localauth> flag, the B<-cell> argument, or both, those -settings apply to this command also. +This command can be issued in interactive mode only. If the issuer of the +B command included the B<-localauth> flag, the +B<-cell> argument, or both, those settings apply to this command also. -To terminate operations that appear in the output, issue the (backup) -kill command and identify the operation to cancel with the job ID number +To terminate operations that appear in the output, issue the B command and identify the operation to cancel with the job ID number from this command's output. To check the status of a Tape Coordinator, rather than of a certain @@ -30,59 +28,53 @@ operation, use the B command. =over 4 -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT The output always includes the expiration date and time of the tokens that -the B command interpreter is using during the current -interactive session, in the following format: +the B command interpreter is using during the current interactive +session, in the following format: - I I
), and -year (I) are required, and valid values for the year range from -B<1970> to B<2037>; higher values are not valid because -the latest possible date in the standard UNIX representation is in February -2038. The Backup System automatically reduces any later date to the -maximum value. - +A date value in the format I [I]. The month (I), +day (I
), and year (I) are required, and valid values for the +year range from C<1970> to C<2037>; higher values are not valid because +the latest possible date in the standard UNIX representation is in +February 2038. The Backup System automatically reduces any later date to +the maximum value. -The hour and minutes (I:I) are optional, but if -provided must be in 24-hour format (for example, the value -B<14:36> represents 2:36 p.m.). If +The hour and minutes (I) are optional, but if provided must be in +24-hour format (for example, the value C<14:36> represents 2:36 p.m.). If omitted, the time defaults to 59 seconds after midnight (00:00:59 -hours). Similarly, the B command interpreter -automatically adds 59 seconds to any time value provided. In both -cases, adding 59 seconds compensates for how the Backup Database and -B command represent dump creation times in hours and -minutes only. That is, the Database records a creation timestamp of -C<20:55> for any dump created between 20:55:00 and -20:55:59. Automatically adding 59 seconds to a time thus -includes the records for all dumps created during that minute. +hours). Similarly, the B command interpreter automatically adds 59 +seconds to any time value provided. In both cases, adding 59 seconds +compensates for how the Backup Database and B command +represent dump creation times in hours and minutes only. That is, the +Database records a creation timestamp of C<20:55> for any dump created +between 20:55:00 and 20:55:59. Automatically adding 59 seconds to a time +thus includes the records for all dumps created during that minute. =back -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -141,17 +133,17 @@ device controlled by the Tape Coordinator with port offset 1: =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_scantape.pod b/doc/man-pages/pod8/backup_scantape.pod index 316515f0c..0d65f8e6d 100644 --- a/doc/man-pages/pod8/backup_scantape.pod +++ b/doc/man-pages/pod8/backup_scantape.pod @@ -4,111 +4,105 @@ backup scantape - Extracts dump information from a tape =head1 SYNOPSIS -B [B<-dbadd>] [-portoffset >] -[B<-localauth>] [B<-cell> >] [B<-help>] +B [B<-dbadd>] [B<-portoffset> >] + [B<-localauth>] [B<-cell> >] [B<-help>] -B [B<-d>] [B<-p> >] [B<-l>] [B<-c> >] [-help] +B [B<-d>] [B<-p> >] [B<-l>] + [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup scantape command extracts information from the dump -labels and volume headers on the tape in the device controlled by the Tape -Coordinator indicated by the B<-portoffset> argument. The Tape -Coordinator displays the information for each volume in its window as soon as -it extracts it (rather than waiting until it has scanned the entire -tape). - -(If the FILE YES instruction appears in the -BI file associated with the -specified port offset, then the B command extracts -dump information from the backup data file named in that port offset's -entry in the B file on the Tape -Coordinator machine, rather than from a tape. For the sake of clarity, -the following text refers to tapes only, but the Backup System handles backup -data files in much the same way.) - -If the B<-dbadd> flag is provided, the backup scantape -command creates new dump and volume records in the Backup Database for the -scanned information. However, if it finds that a record already exists -in the database for the same dump, it terminates the scanning -operation. - -The scanning operation works only on tapes containing volume data. -The command fails with an error message if the tape contains a copy of the -Backup Database (was created with the B command, or has -the AFS tape name B). - -The Tape Coordinator's default response to this command is to access -the tape by invoking the B instruction in the -BI file, or by prompting the backup operator -to insert the tape if there is no B instruction. -However, if the B instruction appears in the -BI file, or if the issuer of the -B command included the B<-noautoquery> flag, the Tape -Coordinator instead expects the tape to be in the device already. If it -is not, the Tape Coordinator invokes the B instruction or -prompts the operator. +The B command extracts information from the dump labels +and volume headers on the tape in the device controlled by the Tape +Coordinator indicated by the B<-portoffset> argument. The Tape Coordinator +displays the information for each volume in its window as soon as it +extracts it (rather than waiting until it has scanned the entire tape). + +(If the C instruction appears in the +F> file associated with the specified +port offset, then the B command extracts dump information +from the backup data file named in that port offset's entry in the +F file on the Tape Coordinator machine, rather +than from a tape. For the sake of clarity, the following text refers to +tapes only, but the Backup System handles backup data files in much the +same way.) + +If the B<-dbadd> flag is provided, the backup scantape command creates new +dump and volume records in the Backup Database for the scanned +information. However, if it finds that a record already exists in the +database for the same dump, it terminates the scanning operation. + +The scanning operation works only on tapes containing volume data. The +command fails with an error message if the tape contains a copy of the +Backup Database (was created with the B command, or has the +AFS tape name C). + +The Tape Coordinator's default response to this command is to access the +tape by invoking the C instruction in the F> +file, or by prompting the backup operator to insert the tape if there is +no C instruction. However, if the C instruction +appears in the F> file, or if the issuer of the B +command included the B<-noautoquery> flag, the Tape Coordinator instead +expects the tape to be in the device already. If it is not, the Tape +Coordinator invokes the C instruction or prompts the operator. To terminate a tape scanning operation in interactive mode, issue the -B<(backup) kill> command. In noninteractive mode, the only -choice is to use a termination signal such as > to halt -the Tape Coordinator completely. +B command. In noninteractive mode, the only choice is to use +a termination signal such as Ctrl-C to halt the Tape Coordinator +completely. =head1 CAUTIONS A scanning operation does not have to begin with the first tape in a dump -set, but the Backup System can process tapes only in sequential order after -the initial tape provided. The Tape Coordinator automatically requests -any subsequent tapes by invoking the B instruction in the local -BI file, or by prompting the -operator if there is no B instruction. +set, but the Backup System can process tapes only in sequential order +after the initial tape provided. The Tape Coordinator automatically +requests any subsequent tapes by invoking the C instruction in the +local F> file, or by prompting the +operator if there is no C instruction. The Tape Coordinator's success in scanning a tape that is corrupted or damaged depends on the extent of the damage and what type of data is -corrupted. It can almost always scan the tape successfully up to the -point of damage. If the damage is minor, the Tape Coordinator can -usually skip over it and scan the rest of the tape, but more major damage can -prevent further scanning. Because a scanning operation can start on any -tape in a dump set, damage on one tape does not prevent scanning of the others -in the dump set. However, it is possible to scan either the tapes that +corrupted. It can almost always scan the tape successfully up to the point +of damage. If the damage is minor, the Tape Coordinator can usually skip +over it and scan the rest of the tape, but more major damage can prevent +further scanning. Because a scanning operation can start on any tape in a +dump set, damage on one tape does not prevent scanning of the others in +the dump set. However, it is possible to scan either the tapes that precede the damaged one or the ones that follow it, but not both. -If a tape is relabeled with the backup labeltape command, it is -not possible to recover data from it for the purposes of rebuilding the Backup +If a tape is relabeled with the backup labeltape command, it is not +possible to recover data from it for the purposes of rebuilding the Backup Database. -If the -dbadd flag is included on the command, it is best not to +If the B<-dbadd> flag is included on the command, it is best not to terminate the tape scanning operation before it completes (for example, by -issuing the B<(backup) kill> command in interactive mode). The -Backup System writes a new record in the Backup Database for each dump as soon -as it scans the relevant information on the tape, and so it possibly has -already written new records. If the operator wants to rerun the -scanning operation, he or she must locate and remove the records created -during the terminated operation: the second operation exits -automatically if it finds that a record that it needs to create already -exists. - -If the -dbadd flag is included and the first tape provided is -not the first tape in the dump set, the following restrictions apply: +issuing the B command in interactive mode). The Backup System +writes a new record in the Backup Database for each dump as soon as it +scans the relevant information on the tape, and so it possibly has already +written new records. If the operator wants to rerun the scanning +operation, he or she must locate and remove the records created during the +terminated operation: the second operation exits automatically if it finds +that a record that it needs to create already exists. + +If the B<-dbadd> flag is included and the first tape provided is not the +first tape in the dump set, the following restrictions apply: =over 4 =item * If the first data on the tape is a continuation of a volume that begins on -the previous (unscanned) tape in the dump set, the Backup System does not add -a record for that volume to the Backup Database. - +the previous (unscanned) tape in the dump set, the Backup System does not +add a record for that volume to the Backup Database. =item * The Backup System must read the marker that indicates the start of an -appended dump to add database records for the volumes in it. If the -first volume on the tape belongs to an appended dump, but is not immediately +appended dump to add database records for the volumes in it. If the first +volume on the tape belongs to an appended dump, but is not immediately preceded by the appended-dump marker, the Backup System does not create a -Backup Database record for it or any subsequent volumes that belong to that -appended dump. - +Backup Database record for it or any subsequent volumes that belong to +that appended dump. =back @@ -116,125 +110,112 @@ appended dump. =over 4 -=item -dbadd +=item B<-dbadd> Adds the information extracted from the tape to the Backup Database (but -only if the database does not already contain an entry with the same dump ID -number). +only if the database does not already contain an entry with the same dump +ID number). -=item -portoffset +=item B<-portoffset> > Specifies the port offset number of the Tape Coordinator handling the tapes for this operation. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -For every dump on a tape, the backup scantape command displays -in the Tape Coordinator window the dump label and the volume header of each -volume in the dump. If a dump spans more than one tape, the dump label -does not repeat at the beginning of subsequent tapes. +For every dump on a tape, the backup scantape command displays in the Tape +Coordinator window the dump label and the volume header of each volume in +the dump. If a dump spans more than one tape, the dump label does not +repeat at the beginning of subsequent tapes. A dump label contains the following fields, which are the same as in the output from the B command: =over 4 -=item C -> +=item tape name -The permanent name assigned by using the -pname argument of the -B command. This name remains on the tape -until that argument is used again, no matter how many times the tape is -recycled or otherwise relabeled. If the tape does not have a permanent -name, the value C<> appears in this field. +The permanent name assigned by using the B<-pname> argument of the +B command. This name remains on the tape until that +argument is used again, no matter how many times the tape is recycled or +otherwise relabeled. If the tape does not have a permanent name, the value +C<< >> appears in this field. -=item C +=item AFS tape name -A tape name in one of the following prescribed formats. The Backup -System automatically writes the appropriate AFS tape name to the label as part -of a B operation, or the operator can assign it with the -B<-name> argument to the B command. +A tape name in one of the following prescribed formats. The Backup System +automatically writes the appropriate AFS tape name to the label as part of +a B operation, or the operator can assign it with the +B<-name> argument to the B command. =over 4 =item * -I.I.I, if the tape contains volume data. The -I is the name of the volume set that was dumped to -create the initial dump in the dump set of which this tape is a part; -I is the last pathname element of the dump level at -which the initial dump was backed up; and I is the -numerical position of the tape in the dump set. - +I.I.I, if the tape contains +volume data. The I is the name of the volume set that was +dumped to create the initial dump in the dump set of which this tape is a +part; I is the last pathname element of the dump level at +which the initial dump was backed up; and I is the numerical +position of the tape in the dump set. =item * -C<> if the tape has no AFS tape name. This is -normally the case if the B<-name> argument was not included the last -time the B command was used on this tape, and no -data has been written to it since. - +C<< >> if the tape has no AFS tape name. This is normally the case +if the B<-name> argument was not included the last time the B command was used on this tape, and no data has been written to +it since. =back -=item C +=item creationTime The date and time at which the Backup System started performing the dump operation that created the initial dump. -=item C +=item cell -The cell in which the dump set was created. This is the cell whose -Backup Database contains a record of the dump set. +The cell in which the dump set was created. This is the cell whose Backup +Database contains a record of the dump set. -=item C +=item size -The tape's capacity (in kilobytes) as recorded on the label, rather -than the amount of data on the tape. The value is assigned by the -B<-size> argument to the B command or -derived from the B file on the Tape -Coordinator machine, not from a measurement of the tape. +The tape's capacity (in kilobytes) as recorded on the label, rather than +the amount of data on the tape. The value is assigned by the B<-size> +argument to the B command or derived from the +F file on the Tape Coordinator machine, not +from a measurement of the tape. -=item C -> +=item dump path The dump level of the initial dump in the dump set. -=item C -> +=item dump id The dump ID number of the initial dump in the dump set, as recorded in the Backup Database. -=item C +=item useCount The number of times a dump has been written to the tape, or it has been relabeled. @@ -245,76 +226,65 @@ The volume header contains the following fields: =over 4 -=item C -> +=item volume name -The volume name, complete with a C<.backup> or -C<.readonly> extension, if appropriate. +The volume name, complete with a C<.backup> or C<.readonly> extension, if +appropriate. -=item C -> +=item volume ID The volume's volume ID. -=item C +=item dumpSetName The dump to which the volume belongs. The dump name is of the form -IB<.>I and -matches the name displayed in the dump label. +I.I and matches the name displayed in +the dump label. -=item C +=item dumpID The dump ID of the dump named in the C field. -=item C +=item level The depth in the dump hierarchy of the dump level used in creating the -dump. A value of C<0> indicates a full dump. A value of -C<1> or greater indicates an incremental dump made at the indicated -depth in the hierarchy. The value reported is for the entire dump, not -necessarily for the volume itself; for example, it is possible for a dump -performed at an incremental level to include a full dump of an individual -volume if the volume was omitted from previous dumps. +dump. A value of C<0> indicates a full dump. A value of C<1> or greater +indicates an incremental dump made at the indicated depth in the +hierarchy. The value reported is for the entire dump, not necessarily for +the volume itself; for example, it is possible for a dump performed at an +incremental level to include a full dump of an individual volume if the +volume was omitted from previous dumps. -=item C +=item parentID -The dump ID number of C's parent dump. It -is C<0> if the value in the C field is -C<0>. +The dump ID number of C's parent dump. It is C<0> if the +value in the C field is C<0>. -=item C +=item endTime Is always C<0>; it is reserved for internal use. -=item C +=item cloneDate The date and time at which the volume was created. For a backup or read-only volume, this represents the time at which it was cloned from its -read/write source. For a read/write volume, it indicates the time at -which the Backup System locked the volume for purposes of including it in the +read/write source. For a read/write volume, it indicates the time at which +the Backup System locked the volume for purposes of including it in the dump named in the C field. =back -The message C indicates the completion of -the output. +The message C indicates the completion of the output. -In normal circumstances, the Backup System writes a marker to indicate that -a volume is the last one on a tape, or that the volume continues on the next -tape. However, if a backup operation terminated abnormally (for -example, because the operator terminated the Tape Coordinator by issuing the -> command during the operation), then there is no such -marker. Some very early versions of the Backup System also did not -write these markers. If a tape does not conclude with one of the -expected markers, the Tape Coordinator cannot determine if there is a -subsequent tape in the dump set and so generates the following message in its -window: +In normal circumstances, the Backup System writes a marker to indicate +that a volume is the last one on a tape, or that the volume continues on +the next tape. However, if a backup operation terminated abnormally (for +example, because the operator terminated the Tape Coordinator by issuing +the Ctrl-C command during the operation), then there is no such +marker. Some very early versions of the Backup System also did not write +these markers. If a tape does not conclude with one of the expected +markers, the Tape Coordinator cannot determine if there is a subsequent +tape in the dump set and so generates the following message in its window: Are there more tapes? (y/n) @@ -356,16 +326,16 @@ in the device with port offset 0: =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, +L, +L, +L, L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_setexp.pod b/doc/man-pages/pod8/backup_setexp.pod index 18903a415..418e54875 100644 --- a/doc/man-pages/pod8/backup_setexp.pod +++ b/doc/man-pages/pod8/backup_setexp.pod @@ -4,30 +4,31 @@ backup setexp - Sets the expiration date for existing dump levels. =head1 SYNOPSIS -B >+ [-expires >+] -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-dump> >+ + [B<-expires> >+] [B<-localauth>] + [B<-cell> >] [B<-help>] -B >+ [-e >+] -[B<-l>] [B<-c> >] [B<-h>] +B B<-d> >+ [B<-e> >+] + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup setexp command sets or changes the expiration date +The B command sets or changes the expiration date associated with each specified dump level, which must already exist in the dump hierarchy. -Use the -expires argument to associate an expiration date with -each dump level. When the Backup System subsequently creates a dump at -the dump level, it uses the specified value to derive the dump's -expiration date, which it records on the label of the tape (or backup data -file). The Backup System refuses to overwrite a tape until after the -latest expiration date of any dump that the tape contains, unless the -B command is used to relabel the tape. If a -dump level does not have an expiration date, the Backup System treats dumps -created at the level as expired as soon as it creates them. - -(Note that the Backup System does not automatically remove a dump's -record from the Backup Database when the dump reaches its expiration date, but +Use the B<-expires> argument to associate an expiration date with each +dump level. When the Backup System subsequently creates a dump at the dump +level, it uses the specified value to derive the dump's expiration date, +which it records on the label of the tape (or backup data file). The +Backup System refuses to overwrite a tape until after the latest +expiration date of any dump that the tape contains, unless the B command is used to relabel the tape. If a dump level does not +have an expiration date, the Backup System treats dumps created at the +level as expired as soon as it creates them. + +(Note that the Backup System does not automatically remove a dump's record +from the Backup Database when the dump reaches its expiration date, but only if the tape that contains the dump is recycled or relabeled. To remove expired and other obsolete dump records, use the B command.) @@ -39,19 +40,17 @@ Define either an absolute or relative expiration date: =item * An absolute expiration date defines the month/day/year (and, optionally, -hour and minutes) at which a dump expires. If the expiration date -predates the dump creation time, the Backup System immediately treats the dump -as expired. - +hour and minutes) at which a dump expires. If the expiration date predates +the dump creation time, the Backup System immediately treats the dump as +expired. =item * A relative date defines the number of years, months, or days (or a -combination of the three) after the dump's creation that it -expires. When the Backup System creates a dump at the dump level, it -calculates an actual expiration date by adding the relative date to the start -time of the dump operation. - +combination of the three) after the dump's creation that it expires. When +the Backup System creates a dump at the dump level, it calculates an +actual expiration date by adding the relative date to the start time of +the dump operation. =back @@ -64,96 +63,90 @@ they were created. =over 4 -=item -dump +=item B<-dump> >+ Specifies the full pathname of each dump level to assign the expiration date specified by the B<-expires> argument. -=item -expires +=item B<-expires> >+ Defines the absolute or relative expiration date to associate with each -dump level named by the B<-dump> argument. Absolute expiration -dates have the following format: +dump level named by the B<-dump> argument. Absolute expiration dates have +the following format: - [B] {B | IBI
BI [I:I] } + [at] {NEVER | /
/ [:] } -where the optional word at is followed either by the string -B, which indicates that dumps created at the dump level never -expire, or by a date value with a required portion (I for month, -I
for day, and I for year) and an optional portion -(I for hours and I for minutes). +where the optional word at is followed either by the string C, +which indicates that dumps created at the dump level never expire, or by a +date value with a required portion ( for month,
for day, and + for year) and an optional portion ( for hours and 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. +Omit the : portion to use the default of midnight (00:00 hours), +or provide a value in 24-hour format (for example, C<20:30> is 8:30 p.m.). +Valid values for the year range from C<1970> to C<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] [Id] + [in] [y] [m] [d] -where the optional word in 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. +where the optional word in is followed by at least one of a number of +years (maximum C<9999>) followed by the letter C, a number of months +(maximum C<12>) followed by the letter C, or a number of days (maximum +C<31>) followed by the letter C. If providing more than one of the +three, list them in the indicated order. If the date that results from +adding the relative expiration value to a dump's creation time is later +than the latest possible date in the UNIX time representation, the Backup +System automatically reduces it to that date. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following example associates an absolute expiration date of 10:00 -p.m. on 31 December 1999 with the dump level -B: +p.m. on 31 December 1999 with the dump level C: % backup setexp -dump /1998/december -expires at 12/31/1999 22:00 The following example associates a relative expiration date of 7 days with -the two dump levels B and -B: +the two dump levels C and C: % backup setexp -dump /monthly/week1 /monthly/week -expires 7d =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_status.pod b/doc/man-pages/pod8/backup_status.pod index 2288bb943..e02a3829b 100644 --- a/doc/man-pages/pod8/backup_status.pod +++ b/doc/man-pages/pod8/backup_status.pod @@ -4,44 +4,43 @@ backup status - Reports a Tape Coordinator's status =head1 SYNOPSIS -B [-portoffset >] -[B<-localauth>] [B<-cell> >] [B<-help>] +B [B<-portoffset> >] [B<-localauth>] + [B<-cell> >] [B<-help>] -B [B<-p> >] [B<-l>] [B<-c> >] [-h] +B [B<-p> >] [B<-l>] [B<-c> >] + [B<-h>] =head1 DESCRIPTION -The backup status command displays which operation, if any, the +The B command displays which operation, if any, the indicated Tape Coordinator is currently executing. =head1 OPTIONS =over 4 -=item -portoffset +=item B<-portoffset> > Specifies the port offset number of the Tape Coordinator for which to report the status. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -55,114 +54,94 @@ performing an operation: Otherwise, the output includes a message of the following format for each running or pending operation: - Task I: I: I + Task : : where =over 4 -=item I +=item -Is a task identification number assigned by the Tape Coordinator. -It begins with the Tape Coordinator's port offset number. +Is a task identification number assigned by the Tape Coordinator. It +begins with the Tape Coordinator's port offset number. -=item I +=item Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command: =over 4 -=item * +=item Dump -C (the backup dump command) +The B command. +=item Restore -=item * +The B, B, or B commands. -C (the B, backup -volrestore, or B commands) +=item Labeltape +The B command. -=item * +=item Scantape -C (the backup labeltape command) +The B command. +=item SaveDb -=item * +The B command. -C (the backup scantape command) - - -=item * - -C (the backup savedb command) - - -=item * - -C (the backup restoredb command) +=item RestoreDb +The B command. =back -=item I +=item -Indicates the job's current status in one of the following -messages. +Indicates the job's current status in one of the following messages. =over 4 -=item I I -> +=item I Kbytes transferred, volume I For a running dump operation, indicates the number of kilobytes copied to -tape or a backup data file so far, and the volume currently being -dumped. +tape or a backup data file so far, and the volume currently being dumped. -=item I -> +=item I Kbytes, restore.volume For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a backup data file so far. -=item C<[abort requested] -> +=item [abort requested] -The (backup) kill command was issued, but the termination -signal has yet to reach the Tape Coordinator. +The B command was issued, but the termination signal has yet +to reach the Tape Coordinator. -=item C<[abort sent] -> +=item [abort sent] -The operation is canceled by the (backup) kill command. -Once the Backup System removes an operation from the queue or stops it from -running, it no longer appears at all in the output from the command. +The operation is canceled by the B command. Once the Backup +System removes an operation from the queue or stops it from running, it no +longer appears at all in the output from the command. -=item C<[butc contact lost] -> +=item [butc contact lost] -The backup command interpreter cannot reach the Tape -Coordinator. The message can mean either that the Tape Coordinator -handling the operation was terminated or failed while the operation was -running, or that the connection to the Tape Coordinator timed out. +The B command interpreter cannot reach the Tape Coordinator. The +message can mean either that the Tape Coordinator handling the operation +was terminated or failed while the operation was running, or that the +connection to the Tape Coordinator timed out. -=item C<[done] -> +=item [done] The Tape Coordinator has finished the operation. -=item C<[drive wait] -> +=item [drive wait] -The operation is waiting for the specified tape drive to become -free. +The operation is waiting for the specified tape drive to become free. -=item C<[operator wait] -> +=item [operator wait] The Tape Coordinator is waiting for the backup operator to insert a tape in the drive. @@ -171,36 +150,34 @@ in the drive. =back -If the Tape Coordinator is communicating with an XBSA server (a third-party -backup utility that implements the Open Group's Backup Service API -[XBSA]), the following message appears last in the output: +If the Tape Coordinator is communicating with an XBSA server (a +third-party backup utility that implements the Open Group's Backup Service +API [XBSA]), the following message appears last in the output: - I Tape coordinator + Tape coordinator -where I is the name of the XBSA-compliant -program. +where is the name of the XBSA-compliant program. =head1 EXAMPLES The following example shows that the Tape Coordinator with port offset 4 -has so far dumped about 1.5 MB of data for the current dump operation, -and is currently dumping the volume named -B: +has so far dumped about 1.5 MB of data for the current dump operation, and +is currently dumping the volume named C: % backup status -portoffset 4 Task 4001: Dump: 1520 Kbytes transferred, volume user.pat.backup =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_volinfo.pod b/doc/man-pages/pod8/backup_volinfo.pod index 77b3ac0c2..34f2abb62 100644 --- a/doc/man-pages/pod8/backup_volinfo.pod +++ b/doc/man-pages/pod8/backup_volinfo.pod @@ -4,112 +4,103 @@ backup volinfo - Displays a volume's dump history from the Backup Database =head1 SYNOPSIS -backup volinfo -volume > -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-volume> > [B<-localauth>] + [B<-cell> >] [B<-help>] -B > [B<-l>] [B<-c> >] [-h] +B B<-v> > [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup volinfo command displays a dump history of the -specified volume, reporting information such as the date on which the volume -was dumped and the tapes that contain it. Include the -B<.backup> extension on the volume name if the backup version -of the volume was dumped. +The B command displays a dump history of the specified +volume, reporting information such as the date on which the volume was +dumped and the tapes that contain it. Include the C<.backup> extension on +the volume name if the backup version of the volume was dumped. =head1 OPTIONS =over 4 -=item -volume +=item B<-volume> > -Names the volume for which to display the dump history. Include -theC< .backup> or C<.readonly> extension if the -backup or read-only version of the volume was dumped. +Names the volume for which to display the dump history. Include the +C<.backup> or C<.readonly> extension if the backup or read-only version of +the volume was dumped. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT The output includes a line for each Backup Database dump record that -mentions the specified volume, order from most to least recent. The -output for each record appears in a table with six columns: +mentions the specified volume, order from most to least recent. The output +for each record appears in a table with six columns: =over 4 -=item C +=item dumpID The dump ID of the dump that includes the volume. -=item C +=item lvl The depth in the dump hierarchy of the dump level at which the volume was -dumped. A value of C<0> indicates a full dump. A value -of C<1> or greater indicates an incremental dump made at the specified -depth in the dump hierarchy. +dumped. A value of C<0> indicates a full dump. A value of C<1> or greater +indicates an incremental dump made at the specified depth in the dump +hierarchy. -=item C +=item parentid -The dump ID of the dump's parent dump. A value of C<0> -indicates a full dump, which has no parent; in this case, the value in -the C column is also C<0>. +The dump ID of the dump's parent dump. A value of C<0> indicates a full +dump, which has no parent; in this case, the value in the C column is +also C<0>. -=item C +=item creation date The date and time at which the Backup System started the dump operation that created the dump. -=item C +=item clone date For a backup or read-only volume, the time at which it was cloned from its -read/write source. For a read/write volume, the same as the value in -the C field. - -=item C - -The name of the tape containing the dump: either the permanent tape -name, or an AFS tape name in the format -I.I.I -where I is the name of the volume set associated with -the initial dump in the dump set of which this tape is a part; -I is the name of the dump level at which the initial -dump was backed up; I is the ordinal of the tape in -the dump set. Either type of name can be followed by a dump ID in -parentheses; if it appears, it is the dump ID of the initial dump in the -dump set to which this appended dump belongs. +read/write source. For a read/write volume, the same as the value in the +C field. + +=item tape name + +The name of the tape containing the dump: either the permanent tape name, +or an AFS tape name in the format +I.I.I where +I is the name of the volume set associated with the +initial dump in the dump set of which this tape is a part; +I is the name of the dump level at which the initial dump +was backed up; I is the ordinal of the tape in the dump +set. Either type of name can be followed by a dump ID in parentheses; if +it appears, it is the dump ID of the initial dump in the dump set to which +this appended dump belongs. =back =head1 EXAMPLES The following example shows part of the dump history of the Backup volume -B: +C: % backup volinfo -volume user.smith.backup DumpID lvl parentID creation date clone date tape name @@ -125,9 +116,9 @@ None =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_volrestore.pod b/doc/man-pages/pod8/backup_volrestore.pod index 6ccda4ae8..a4c537114 100644 --- a/doc/man-pages/pod8/backup_volrestore.pod +++ b/doc/man-pages/pod8/backup_volrestore.pod @@ -4,36 +4,36 @@ backup volrestore - Restores one or more volumes =head1 SYNOPSIS -backup volrestore -server > -B<-partition> > - -volume >+ - [-extension >] - [-date >+] - [B<-portoffset> >+] [-n] - [B<-localauth>] [B<-cell> >] [-help] - -B > -pa > -B<-v> >+ [B<-e> >] - [B<-d> >+] [-po >+] - [B<-n>] [B<-l>] [B<-c> >] [-h] +B B<-server> > + B<-partition> > + B<-volume> >+ + [B<-extension> >] + [B<-date> >+] + [B<-portoffset> >+] [B<-n>] + [B<-localauth>] [B<-cell> >] [B<-help>] + +B B<-s> > + B<-pa> > B<-v> >+ + [B<-e> >] + [B<-d> >+] [B<-po> >+] + [B<-n>] [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup volrestore command restores the contents of one or -more volumes to the site indicated by the B<-server> and -B<-partition> arguments. Use the command either to overwrite -the contents of existing volumes with the restored data or to create new -volumes while retaining the existing ones. The specified site does not -have to be the current site for the volumes. - -(If the FILE YES instruction appears in the -BI file associated with the -specified port offset, then the B command restores -data from the backup data file listed for that port offset in the Tape -Coordinator's B file, rather than -from tape. For the sake of clarity, the following text refers to tapes -only, but the Backup System handles backup data files in much the same -way.) +The B command restores the contents of one or more +volumes to the site indicated by the B<-server> and B<-partition> +arguments. Use the command either to overwrite the contents of existing +volumes with the restored data or to create new volumes while retaining +the existing ones. The specified site does not have to be the current site +for the volumes. + +(If the C instruction appears in the +F> file associated with the specified +port offset, then the B command restores data from the +backup data file listed for that port offset in the Tape Coordinator's +F file, rather than from tape. For the sake of +clarity, the following text refers to tapes only, but the Backup System +handles backup data files in much the same way.) The command's arguments can be combined as indicated: @@ -41,282 +41,260 @@ The command's arguments can be combined as indicated: =item * -To preserve a volume's current contents and also create a new volume -to house the restored version, use the B<-extension> argument. -The Backup System creates the new volume on the server and partition named by -the B<-server> and B<-partition> arguments, assigns it the -same name as the current volume with the addition of the specified extension, -and creates a new Volume Location Database (VLDB) entry for it. -Creating a new volume enables the administrator to compare the two -versions. - +To preserve a volume's current contents and also create a new volume to +house the restored version, use the B<-extension> argument. The Backup +System creates the new volume on the server and partition named by the +B<-server> and B<-partition> arguments, assigns it the same name as the +current volume with the addition of the specified extension, and creates a +new Volume Location Database (VLDB) entry for it. Creating a new volume +enables the administrator to compare the two versions. =item * -To overwrite a volume's existing contents with the restored version, -omit the B<-extension> argument, and specify the site as -indicated: - +To overwrite a volume's existing contents with the restored version, omit +the B<-extension> argument, and specify the site as indicated: =over 4 =item * -To retain the current site, specify it with the -server and +To retain the current site, specify it with the B<-server> and B<-partition> arguments. - =item * To move the volume to a different site while overwriting it, specify the -new site with the B<-server> argument, B<-partition> argument, -or both. The Backup System creates a new volume at that site, removes -the existing volume, and updates the site information in the volume's -VLDB entry. The backup version of the volume is not removed -automatically from the original site, if it exists. Use the B command to remove it and the B command to -create a backup version at the new site. - +new site with the B<-server> argument, B<-partition> argument, or +both. The Backup System creates a new volume at that site, removes the +existing volume, and updates the site information in the volume's VLDB +entry. The backup version of the volume is not removed automatically from +the original site, if it exists. Use the B command to remove +it and the B command to create a backup version at the new +site. =back =item * To restore a volume that no longer exists in the file system, specify its -name with the B<-volume> argument and use the B<-server> and -B<-partition> arguments to place it at the desired site. The -Backup System creates a new volume and new VLDB entry. - +name with the B<-volume> argument and use the B<-server> and B<-partition> +arguments to place it at the desired site. The Backup System creates a new +volume and new VLDB entry. =back -In each case, the command sets each volume's creation date to the date -and time at which it restores it. The creation date appears in the -C field in the output from the B and -B commands. +In each case, the command sets each volume's creation date to the date and +time at which it restores it. The creation date appears in the C +field in the output from the B and B commands. If restoring all of the volumes that resided on a single partition, it is -usually more efficient to use the B -command. If restoring multiple volumes to many different sites, it can -be more efficient to use the B command. - -By default, the backup volrestore command restores the most -recent full dump and all subsequent incremental dumps for each volume, -bringing the restored volumes to the most current possible state. To -restore the volumes to their state at some time in the past, use the -B<-date> argument. The Backup System restores the most recent -full dump and each subsequent incremental dump for which the I of the volume included in the dump is before the indicated date and -time (the clone date timestamp appears in the C field of -the output from the B command). For backup and -read-only volumes, the clone date represents the time at which the volume was -copied from its read/write source; for read/write volumes, it represents -the time at which the volume was locked for inclusion in the dump. The -resemblance of a restored volume to its actual state at the indicated time -depends on the amount of time that elapsed between the volume's clone -date in the last eligible dump and the specified time. - -If the -volume argument specifies the base (read/write) form of -the volume name, the Backup System searches the Backup Database for the newest -dump set that includes a dump of either the read/write or the backup version -of the volume. It restores the dumps of that version of the volume, -starting with the most recent full dump. If, in contrast, the volume -name explicitly includes the B<.backup> or -B<.readonly> extension, the Backup System restores dumps of the -corresponding volume version only. +usually more efficient to use the B command. If +restoring multiple volumes to many different sites, it can be more +efficient to use the B command. + +By default, the backup volrestore command restores the most recent full +dump and all subsequent incremental dumps for each volume, bringing the +restored volumes to the most current possible state. To restore the +volumes to their state at some time in the past, use the B<-date> +argument. The Backup System restores the most recent full dump and each +subsequent incremental dump for which the I of the volume +included in the dump is before the indicated date and time (the clone date +timestamp appears in the C field of the output from the +B command). For backup and read-only volumes, the clone +date represents the time at which the volume was copied from its +read/write source; for read/write volumes, it represents the time at which +the volume was locked for inclusion in the dump. The resemblance of a +restored volume to its actual state at the indicated time depends on the +amount of time that elapsed between the volume's clone date in the last +eligible dump and the specified time. + +If the B<-volume> argument specifies the base (read/write) form of the +volume name, the Backup System searches the Backup Database for the newest +dump set that includes a dump of either the read/write or the backup +version of the volume. It restores the dumps of that version of the +volume, starting with the most recent full dump. If, in contrast, the +volume name explicitly includes the C<.backup> or C<.readonly> extension, +the Backup System restores dumps of the corresponding volume version only. To generate a list of the tapes the Backup System needs to perform the -restore operation, without actually performing it, combine the B<-n> -flag with the options to be used on the actual command. +restore operation, without actually performing it, combine the B<-n> flag +with the options to be used on the actual command. If all of the full and incremental dumps of all relevant volumes were not written to a type of tape that a single Tape Coordinator can read, use the -B<-portoffset> argument to list multiple port offset numbers in the -order in which the tapes are needed (first list the port offset for the full +B<-portoffset> argument to list multiple port offset numbers in the order +in which the tapes are needed (first list the port offset for the full dump, second the port offset for the level 1 incremental dump, and so -on). If restoring multiple volumes, the same ordered list of port -offsets must apply to all of them. If not, either issue this command -separately for each volume, or use the B command -after defining groups of volumes that were dumped to compatible tape -types. For further discussion, see the I. - -The Tape Coordinator's default response to this command is to access -the first tape it needs by invoking the B instruction in the -local BI file, or by -prompting the backup operator to insert the tape if there is no -B instruction. However, if the B -instruction appears in the BI file, or if the -issuer of the B command included the B<-noautoquery> +on). If restoring multiple volumes, the same ordered list of port offsets +must apply to all of them. If not, either issue this command separately +for each volume, or use the B command after defining +groups of volumes that were dumped to compatible tape types. For further +discussion, see the I. + +The Tape Coordinator's default response to this command is to access the +first tape it needs by invoking the B instruction in the local +F> file, or by prompting the backup +operator to insert the tape if there is no C instruction. However, +if the C instruction appears in the F> +file, or if the issuer of the B command included the B<-noautoquery> flag, the Tape Coordinator instead expects the tape to be in the device -already. If it is not, or is the wrong tape, the Tape Coordinator -invokes the B instruction or prompts the operator. It -also invokes the B instruction or prompts for any additional -tapes needed to complete the restore operation; the backup operator must -arrange to provide them. +already. If it is not, or is the wrong tape, the Tape Coordinator invokes +the C instruction or prompts the operator. It also invokes the +C instruction or prompts for any additional tapes needed to +complete the restore operation; the backup operator must arrange to +provide them. =head1 OPTIONS =over 4 -=item -server +=item B<-server> > -Names the file server machine on which to restore each volume. If -this argument and the B<-partition> argument indicate a site other -than the current site for each volume, and the B<-extension> argument -is not also provided, the Backup System removes the existing volumes from -their current sites, places the restored contents at the specified site, and +Names the file server machine on which to restore each volume. If this +argument and the B<-partition> argument indicate a site other than the +current site for each volume, and the B<-extension> argument is not also +provided, the Backup System removes the existing volumes from their +current sites, places the restored contents at the specified site, and changes the site information in the volume's VLDB entry. -=item -partition +=item B<-partition> > -Names the partition to which to restore each volume. If this -argument and the B<-server> argument indicate a site other than the -current site for each volume, and the B<-extension> argument is not -also provided, the Backup System removes the existing volumes from their -current sites, places the restored contents at the specified site, and changes -the site information in the volume's VLDB entry. +Names the partition to which to restore each volume. If this argument and +the B<-server> argument indicate a site other than the current site for +each volume, and the B<-extension> argument is not also provided, the +Backup System removes the existing volumes from their current sites, +places the restored contents at the specified site, and changes the site +information in the volume's VLDB entry. -=item -volume +=item B<-volume> >+ Names one or more volumes to restore, using the volume name as listed in -the Backup Database. Provide the base (read/write) name of each volume -to have the Backup System search the Backup Database for the newest dump set +the Backup Database. Provide the base (read/write) name of each volume to +have the Backup System search the Backup Database for the newest dump set that includes a dump of either the read/write or the backup version of the -volume; it restores the dumps of that version of the volume, starting -with the most recent full dump. If, in contrast, a volume name -explicitly includes the B<.backup> or -B<.readonly> extension, the Backup System restores dumps of the -corresponding volume version only. +volume; it restores the dumps of that version of the volume, starting with +the most recent full dump. If, in contrast, a volume name explicitly +includes the C<.backup> or C<.readonly> extension, the Backup System +restores dumps of the corresponding volume version only. -=item -extension +=item B<-extension> > Creates a new volume to house the restored data, with a name derived by appending the specified string to each volume named by the B<-volume> -argument. The Backup System creates a new VLDB entry for the -volume. Any string other than B<.readonly> or -B<.backup> is acceptable, but the combination of the existing -volume name and extension cannot exceed 22 characters in length. To use -a period to separate the extension from the name, specify it as the first -character of the string (as in B<.rst>, for example). - -=item -date - -Specifies a date and optionally time; the restored volume includes -data from dumps performed before the date only. Provide a value in the -format I/I
/I [I:I], -where the required I portion indicates the month -(I), day (I
), and year (I), and the optional -I portion indicates the hour and minutes in 24-hour format -(for example, the value B<14:36> represents 2:36 -p.m.). If omitted, the time defaults to 59 seconds after -midnight (00:00:59 hours). - -Valid values for the year range from 1970 to -B<2037>; higher values are not valid because the latest possible -date in the standard UNIX representation is in February 2038. The -command interpreter automatically reduces any later date to the maximum -value. +argument. The Backup System creates a new VLDB entry for the volume. Any +string other than C<.readonly> or C<.backup> is acceptable, but the +combination of the existing volume name and extension cannot exceed 22 +characters in length. To use a period to separate the extension from the +name, specify it as the first character of the string (as in C<.rst>, for +example). + +=item B<-date> >+ + +Specifies a date and optionally time; the restored volume includes data +from dumps performed before the date only. Provide a value in the format +I [I:I], where the required I portion +indicates the month (I), day (I
), and year (I), and the +optional I portion indicates the hour and minutes in 24-hour format +(for example, the value C<14:36> represents 2:36 p.m.). If omitted, the +time defaults to 59 seconds after midnight (00:00:59 hours). + +Valid values for the year range from C<1970> to C<2037>; higher values are +not valid because the latest possible date in the standard UNIX +representation is in February 2038. The command interpreter automatically +reduces any later date to the maximum value. If this argument is omitted, the Backup System restores all possible dumps including the most recently created. -=item -portoffset +=item B<-portoffset> >+ Specifies one or more port offset numbers (up to a maximum of 128), each -corresponding to a Tape Coordinator to use in the operation. If there -is more than one value, the Backup System uses the first one when restoring +corresponding to a Tape Coordinator to use in the operation. If there is +more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 -incremental dump of each volume, and so on. It uses the final value in -the list when restoring dumps at the corresponding depth in the dump hierarchy +incremental dump of each volume, and so on. It uses the final value in the +list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower levels. Provide this argument unless the default value of 0 (zero) is appropriate -for all dumps. If B<0> is just one of the values in the list, -provide it explicitly in the appropriate order. +for all dumps. If C<0> is just one of the values in the list, provide it +explicitly in the appropriate order. -=item -n +=item B<-n> Displays the list of tapes that contain the dumps required by the restore operation, without actually performing the operation. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -If the issuer includes the -n flag with the command, the -following string appears at the head of the list of the tapes necessary to -complete the restore operation. +If the issuer includes the B<-n> flag with the command, the following +string appears at the head of the list of the tapes necessary to complete +the restore operation. Tapes needed: =head1 EXAMPLES -The following command restores the volume user.pat to -partition B on machine -B: +The following command restores the volume user.pat to partition F +on machine C: % backup volrestore -server fs5.abc.com -partition a -volume user.pat -The following command restores the volumes user.smith and -B to partition B on machine -B, adding a B<.rst> -extension to each volume name and preserving the existing -B and B volumes. -Only dumps created before 5:00 p.m. on 31 January 1998 are -restored. (The command is shown here on multiple lines only for -legibility reasons.) +The following command restores the volumes C and C +to partition F on machine C, adding a C<.rst> +extension to each volume name and preserving the existing C +and C volumes. Only dumps created before 5:00 p.m. on 31 +January 1998 are restored. (The command is shown here on multiple lines +only for legibility reasons.) % backup volrestore -server fs4.abc.com -partition b \ -volume user.smith user.terry \ -extension .rst -date 1/31/1998 17:00 -The following command restores the volume user.pat to -partition B on machine -B. The Tape Coordinator with port -offset 1 handles the tape containing the full dump; the Tape Coordinator -with port offset 0 handles all tapes containing incremental dumps. (The -command is shown here on two lines only for legibility reasons.) +The following command restores the volume user.pat to partition F +on machine C. The Tape Coordinator with port offset 1 handles +the tape containing the full dump; the Tape Coordinator with port offset 0 +handles all tapes containing incremental dumps. (The command is shown here +on two lines only for legibility reasons.) % backup volrestore -server fs5.abc.com -partition a \ -volume user.pat -portoffset 1 0 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server or Volume Location (VL) Server is -running, and on every file server machine that houses an affected -volume. If the B<-localauth> flag is included, the issuer must -instead be logged on to a server machine as the local superuser -B. +The issuer must be listed in the F file on every +machine where the Backup Server or Volume Location (VL) Server is running, +and on every file server machine that houses an affected volume. If the +B<-localauth> flag is included, the issuer must instead be logged on to a +server machine as the local superuser C. =head1 SEE ALSO -L, -L, -L, -L, -L, +L, +L, +L, +L, +L, L, L diff --git a/doc/man-pages/pod8/backup_volsetrestore.pod b/doc/man-pages/pod8/backup_volsetrestore.pod index f3dc34a9b..031ab792e 100644 --- a/doc/man-pages/pod8/backup_volsetrestore.pod +++ b/doc/man-pages/pod8/backup_volsetrestore.pod @@ -4,383 +4,352 @@ backup volsetrestore - Restores all volumes in a volume set =head1 SYNOPSIS -B [B<-name> >] [-file >] -[B<-portoffset> >+] - [-extension >] - [B<-n>] [B<-localauth>] [B<-cell> >] [-help] +B [B<-name> >] + [B<-file> >] [B<-portoffset> >+] + [B<-extension> >] [B<-n>] + [B<-localauth>] [B<-cell> >] [B<-help>] -B [B<-na> >] [-f >] -[B<-p> >+] [B<-e> >] - [B<-n>] [B<-l>] [B<-c> >] [-h] +B [B<-na> >] [B<-f> >] + [B<-p> >+] [B<-e> >] + [B<-n>] [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup volsetrestore command restores the complete contents -of a group of read/write volumes to the file system, by restoring data from -the last full dump and all subsequent incremental dumps of each volume. -It is most useful for recovering from loss of data on multiple partitions, -since it can restore each of a defined set of volumes to a different -site. - -(If the FILE YES instruction appears in the -BI file associated with the -specified port offset, then the B command -restores data from the backup data file listed for that port offset in the -Tape Coordinator's B file, instead of -from tape. For the sake of clarity, the following text refers to tapes -only, but the Backup System handles backup data files in much the same -way.) +The B command restores the complete contents of a +group of read/write volumes to the file system, by restoring data from the +last full dump and all subsequent incremental dumps of each volume. It is +most useful for recovering from loss of data on multiple partitions, since +it can restore each of a defined set of volumes to a different site. + +(If the C instruction appears in the +F> file associated with the specified +port offset, then the B command restores data from +the backup data file listed for that port offset in the Tape Coordinator's +F file, instead of from tape. For the sake of +clarity, the following text refers to tapes only, but the Backup System +handles backup data files in much the same way.) If restoring one or more volumes to a single site only, it is usually more -efficient to use the B command. If restoring -all volumes that resided on a single partition, it is usually more efficient +efficient to use the B command. If restoring all +volumes that resided on a single partition, it is usually more efficient to use the B command. -Indicate the volumes to restore by providing either the -name -argument or the B<-file> argument: +Indicate the volumes to restore by providing either the B<-name> argument +or the B<-file> argument: =over 4 =item * -The -name argument names a volume set. The Backup System -restores all volumes listed in the Volume Location Database (VLDB) that match -the server, partition, and volume name criteria defined in the volume -set's volume entries, and for which dumps are available. It -restores the volumes to their current site (machine and partition), and by -default overwrites the existing volume contents. - +The B<-name> argument names a volume set. The Backup System restores all +volumes listed in the Volume Location Database (VLDB) that match the +server, partition, and volume name criteria defined in the volume set's +volume entries, and for which dumps are available. It restores the volumes +to their current site (machine and partition), and by default overwrites +the existing volume contents. It is not required that the volume set was previously used to back up -volumes (was used as the B<-volumeset> option to the B command). It can be defined especially to match the volumes -that need to be restored with this command, and that is usually the better -choice. Indeed, a I volume set, created by including -the B<-temporary> flag to the B command, can -be especially useful in this context. A temporary volume set is not -added to the Backup Database and exists only during the current interactive -backup session, which is suitable if the volume set is needed only to complete -the single restore operation initialized by this command. +volumes (was used as the B<-volumeset> option to the B +command). It can be defined especially to match the volumes that need to +be restored with this command, and that is usually the better +choice. Indeed, a I volume set, created by including the +B<-temporary> flag to the B command, can be especially +useful in this context. A temporary volume set is not added to the Backup +Database and exists only during the current interactive backup session, +which is suitable if the volume set is needed only to complete the single +restore operation initialized by this command. The reason that a specially defined volume set is probably better is that -volume sets previously defined for use in dump operations usually match the -backup version of volumes, whereas for a restore operation it is best to -define volume entries that match the base (read/write) name. In that -case, the Backup System searches the Backup Database for the newest dump set -that includes either the read/write or the backup version of the -volume. If, in contrast, a volume entry explicitly matches the -volume's backup or read-only version, the Backup System restores dumps of -that volume version only. +volume sets previously defined for use in dump operations usually match +the backup version of volumes, whereas for a restore operation it is best +to define volume entries that match the base (read/write) name. In that +case, the Backup System searches the Backup Database for the newest dump +set that includes either the read/write or the backup version of the +volume. If, in contrast, a volume entry explicitly matches the volume's +backup or read-only version, the Backup System restores dumps of that +volume version only. =item * -The -file argument names a file that lists specific volumes and -the site to which to restore each. The volume name must match the name -used in Backup Database dump records rather than in the VLDB, if they differ, +The B<-file> argument names a file that lists specific volumes and the +site to which to restore each. The volume name must match the name used in +Backup Database dump records rather than in the VLDB, if they differ, because the Backup System does not look up volumes in the VLDB. The -specified site can be different than the volume's current one; in -that case, the Backup System removes the current version of the volume and +specified site can be different than the volume's current one; in that +case, the Backup System removes the current version of the volume and updates the volume's location information in the VLDB. - =back If all of the full and incremental dumps of all relevant volumes were not written to a type of tape that a single Tape Coordinator can read, use the -B<-portoffset> argument to list multiple port offset numbers in the -order in which the tapes are needed (first list the port offset for the full +B<-portoffset> argument to list multiple port offset numbers in the order +in which the tapes are needed (first list the port offset for the full dump, second the port offset for the level 1 incremental dump, and so on). This implies that the full dumps of all relevant volumes must have -been written to a type of tape that the first Tape Coordinator can read, the -level 1 incremental dumps to a type of tape the second Tape Coordinator can -read, and so on. If dumps are on multiple incompatible tape types, use -the B command to restore individual volumes, or use -this command after defining new volume sets that group together volumes that -were dumped to compatible tape types. For further discussion, see the -I. - -By default, the Backup System overwrites the contents of an existing volume -with the restored data. To create a new volume to house the restored -version instead, use the B<-extension> argument. The Backup +been written to a type of tape that the first Tape Coordinator can read, +the level 1 incremental dumps to a type of tape the second Tape +Coordinator can read, and so on. If dumps are on multiple incompatible +tape types, use the B command to restore individual +volumes, or use this command after defining new volume sets that group +together volumes that were dumped to compatible tape types. For further +discussion, see the I. + +By default, the Backup System overwrites the contents of an existing +volume with the restored data. To create a new volume to house the +restored version instead, use the B<-extension> argument. The Backup System derives the new volume's name by adding the specified extension to -the read/write base name, and creates a new VLDB entry. The command -does not affect the existing volume in any way. However, if a volume -with the specified extension also already exists, the command overwrites -it. - -The -n flag produces a list of the volumes to be restored if the -B<-n> flag were not included, without actually restoring any -volumes. See the B section of this reference page for a -detailed description of the output, and suggestions on how to combine it most -effectively with the B<-file> and B<-name> arguments. - -The execution time for a backup volsetrestore command depends on -the number of volumes to be restored and the amount of data in them, but it -can take hours to restore a large number of volumes. One way to reduce -the time is to run multiple instances of the command simultaneously, either +the read/write base name, and creates a new VLDB entry. The command does +not affect the existing volume in any way. However, if a volume with the +specified extension also already exists, the command overwrites it. + +The B<-n> flag produces a list of the volumes to be restored if the B<-n> +flag were not included, without actually restoring any volumes. See +L for a detailed description of the output, and suggestions on how +to combine it most effectively with the B<-file> and B<-name> arguments. + +The execution time for a B command depends on the +number of volumes to be restored and the amount of data in them, but it +can take hours to restore a large number of volumes. One way to reduce the +time is to run multiple instances of the command simultaneously, either using the B<-name> argument to specify disjoint volume sets for each command, or the B<-file> argument to name files that list different volumes. This is possible if there are multiple available Tape Coordinators that can read the required tapes. Depending on how the -volumes to be restored were dumped to tape, specifying disjoint volume sets -can also reduce the number of tape changes required. - -The Tape Coordinator's default response to this command is to access -the first tape it needs by invoking the B instruction in the -local BI file, or by -prompting the backup operator to insert the tape if there is no -B instruction. However, if the B -instruction appears in the BI file, or if the -issuer of the B command included the B<-noautoquery> +volumes to be restored were dumped to tape, specifying disjoint volume +sets can also reduce the number of tape changes required. + +The Tape Coordinator's default response to this command is to access the +first tape it needs by invoking the C instruction in the local +F> file, or by prompting the backup +operator to insert the tape if there is no C instruction. However, +if the C instruction appears in the F> +file, or if the issuer of the B command included the B<-noautoquery> flag, the Tape Coordinator instead expects the tape to be in the device -already. If it is not, or is the wrong tape, the Tape Coordinator -invokes the B instruction or prompts the operator. It -also invokes the B instruction or prompts for any additional -tapes needed to complete the restore operation; the backup operator must -arrange to provide them. +already. If it is not, or is the wrong tape, the Tape Coordinator invokes +the C instruction or prompts the operator. It also invokes the +C instruction or prompts for any additional tapes needed to +complete the restore operation; the backup operator must arrange to +provide them. =head1 OPTIONS =over 4 -=item -name +=item B<-name> > -Names a volume set to restore. The Backup System restores all of -the volumes listed in the VLDB that match the volume set's volume -entries. Provide this argument or the B<-file> argument, but -not both. +Names a volume set to restore. The Backup System restores all of the +volumes listed in the VLDB that match the volume set's volume +entries. Provide this argument or the B<-file> argument, but not both. -=item -file +=item B<-file> > Specifies the full pathname of a file that lists one or more volumes and the site (file server machine and partition) to which to restore each. -Use either this argument or the B<-name> argument, but not -both. +Use either this argument or the B<-name> argument, but not both. -Each volume's entry must appear on its own (unbroken) line in the -file, and have the following format: +Each volume's entry must appear on its own (unbroken) line in the file, +and have the following format: - I [I] + [ ...] where =over 4 -=item I +=item Names the file server machine to which to restore the volume. -=item I +=item Names the partition to which to restore the volume. -=item I +=item -Names the volume to restore. It is generally best to specify the -base (read/write) name of each volume. In this case, the Backup System -searches the Backup Database for the newest dump set that includes a dump of -either the read/write or the backup version of the volume. It restores -the dumps of that version of the volume, starting with the most recent full -dump. If, in contrast, the name explicitly includes the -B<.backup> or B<.readonly> extension, the Backup -System restores dumps of that volume version only. +Names the volume to restore. It is generally best to specify the base +(read/write) name of each volume. In this case, the Backup System searches +the Backup Database for the newest dump set that includes a dump of either +the read/write or the backup version of the volume. It restores the dumps +of that version of the volume, starting with the most recent full +dump. If, in contrast, the name explicitly includes the C<.backup> or +C<.readonly> extension, the Backup System restores dumps of that volume +version only. -=item I +=item ... -Is any other text. The Backup System ignores any text on each line -that appears after the volume name, so this field can be used for notes -helpful to the backup operator or other administrator. +Is any other text. The Backup System ignores any text on each line that +appears after the volume name, so this field can be used for notes helpful +to the backup operator or other administrator. =back -Do not use wildcards (for example, .*) in the -I, I, or I fields. It is -acceptable for multiple lines in the file to name the same volume, but the -Backup System processes only the first of them. +Do not use wildcards (for example, C<.*>) in the , , +or fields. It is acceptable for multiple lines in the file to +name the same volume, but the Backup System processes only the first of +them. -=item -extension +=item B<-extension> > -Creates a new volume for each volume specified by the -name or -B<-file> argument, to house the restored data from that volume. -The Backup System derives the new volume's name by appending the -specified string to the read/write base name, and creates a new VLDB volume -entry. It preserves the contents of each existing volume. Any -string other than B<.readonly> or B<.backup> is -acceptable, but the combination of the base name and extension cannot exceed -22 characters in length. To use a period to separate the extension from -the name, specify it as the first character of the string (as in -B<.rst>, for example). +Creates a new volume for each volume specified by the B<-name> or B<-file> +argument, to house the restored data from that volume. The Backup System +derives the new volume's name by appending the specified string to the +read/write base name, and creates a new VLDB volume entry. It preserves +the contents of each existing volume. Any string other than C<.readonly> +or C<.backup> is acceptable, but the combination of the base name and +extension cannot exceed 22 characters in length. To use a period to +separate the extension from the name, specify it as the first character of +the string (as in C<.rst>, for example). -=item -portoffset +=item B<-portoffset> >+ Specifies one or more port offset numbers (up to a maximum of 128), each -corresponding to a Tape Coordinator to use in the operation. If there -is more than one value, the Backup System uses the first one when restoring +corresponding to a Tape Coordinator to use in the operation. If there is +more than one value, the Backup System uses the first one when restoring the full dump of each volume, the second one when restoring the level 1 -incremental dump of each volume, and so on. It uses the final value in -the list when restoring dumps at the corresponding depth in the dump hierarchy +incremental dump of each volume, and so on. It uses the final value in the +list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower levels. Provide this argument unless the default value of 0 (zero) is appropriate -for all dumps. If B<0> is just one of the values in the list, -provide it explicitly in the appropriate order. +for all dumps. If C<0> is just one of the values in the list, provide it +explicitly in the appropriate order. -=item -n +=item B<-n> Displays a list of the volumes to be restored if the flag were not -included, without actually restoring them. The B -section of this reference page details the format of the output. When -combined with the B<-name> argument, its output is easily edited for -use as input to the B<-file> argument on a subsequent B details the format of +the output. When combined with the B<-name> argument, its output is easily +edited for use as input to the B<-file> argument on a subsequent B command. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -If the -n flag is not provided, the command displays a unique -task ID number for the operation, in two places: +If the B<-n> flag is not provided, the command displays a unique task ID +number for the operation, in two places: =over 4 =item * -In the shell window, directly following the command line - +In the shell window, directly following the command line. =item * -In the Tape Coordinator window, if the butc process was started -at debug level 1 - +In the Tape Coordinator window, if the butc process was started at debug +level 1. =back The task ID number is not the same as the job ID number displayed by the -B<(backup) jobs> command when the B<(backup) volsetrestore> -command is issued in interactive mode. The Backup System does not -assign either type of ID number until the restoration process actually -begins. - -When the -n flag is included, no task ID or job ID numbers are -reported because none are assigned. Instead, the output begins with a -count of the number of volumes to be restored, followed by a line for each -dump of a volume. For each volume, the line representing the most -recent full dump appears first, and lines for any subsequent incremental dumps -follow, ordered by dump level. The lines for a given volume do not -necessarily appear all together, however. +B command when the B command is issued +in interactive mode. The Backup System does not assign either type of ID +number until the restoration process actually begins. + +When the B<-n> flag is included, no task ID or job ID numbers are reported +because none are assigned. Instead, the output begins with a count of the +number of volumes to be restored, followed by a line for each dump of a +volume. For each volume, the line representing the most recent full dump +appears first, and lines for any subsequent incremental dumps follow, +ordered by dump level. The lines for a given volume do not necessarily +appear all together, however. The format of each line is as follows (the output is shown here on two lines only for legibility reasons): - I # as I; I (I); \ - pos I; I + # as ; \ + (); pos ; where =over 4 -=item I +=item Names the file server machine that currently houses the volume, as listed in the VLDB. -=item I +=item Names the partition that currently houses the volume, as listed in the VLDB. -=item I +=item Specifies the version (read/write or backup) of the volume that was dumped, as listed in the Backup Database. -=item I +=item -Specifies the name under which to restore the volume. The Backup -System only restores data to read/write volumes. If the -B<-extension> argument is included, then the specified extension -appears on the name in this field (for example, -C). +Specifies the name under which to restore the volume. The Backup System +only restores data to read/write volumes. If the B<-extension> argument is +included, then the specified extension appears on the name in this field +(for example, C). -=item I +=item Names the tape containing the dump of the volume, from the Backup -Database. If the tape has a permanent name, it appears here; -otherwise, it is the AFS tape name. +Database. If the tape has a permanent name, it appears here; otherwise, it +is the AFS tape name. -=item I +=item The tape ID of the tape containing the dump of the volume, from the Backup Database. -=item I +=item -Specifies the dump's position on the tape (for example, C<31> -indicates that 30 volume dumps precede the current one on the tape). If -the dump was written to a backup data file, this number is the ordinal of the -16 KB-offset at which the volume's data begins. +Specifies the dump's position on the tape (for example, C<31> indicates +that 30 volume dumps precede the current one on the tape). If the dump was +written to a backup data file, this number is the ordinal of the 16 +KB-offset at which the volume's data begins. -=item I +=item The date and time when the volume was dumped. =back -One way to generate a file for use as input to the -file -argument is to combine the B<-name> and B<-n> options, -directing the output to a file. The I section on using the Backup System to restore data explains how to -edit the file as necessary before using it as input to the B<-file> -argument. +One way to generate a file for use as input to the B<-file> argument is to +combine the B<-name> and B<-n> options, directing the output to a +file. The I section on using the Backup +System to restore data explains how to edit the file as necessary before +using it as input to the B<-file> argument. The output of this command includes only volumes for which the Backup Database includes at least one dump record. The command interpreter generates a message on the standard error stream about volumes that do not -have dump records but either are listed in the file named by the -B<-file> argument, or appear in the VLDB as a match to a volume entry -in the volume set named by the B<-name> argument. +have dump records but either are listed in the file named by the B<-file> +argument, or appear in the VLDB as a match to a volume entry in the volume +set named by the B<-name> argument. =head1 EXAMPLES The following command restores all volumes included in entries in the -volume set named B, which was created expressly -to restore data to a pair of file server machines on which all data was -corrupted due to a software error. All volumes are restored to the -sites recorded in their entries in the VLDB. +volume set named C, which was created expressly to restore +data to a pair of file server machines on which all data was corrupted due +to a software error. All volumes are restored to the sites recorded in +their entries in the VLDB. % backup volsetrestore -name data.restore Starting restore @@ -388,14 +357,14 @@ sites recorded in their entries in the VLDB. backup: Finished doing restore The following command restores all volumes that have entries in the file -named B: +named F: % backup volsetrestore -file /tmp/restore Starting restore backup: task ID of restore operation: 113 backup: Finished doing restore -The /tmp/restore file has the following contents: +The F file has the following contents: fs1.abc.com b user.pat fs1.abc.com b user.terry @@ -406,22 +375,21 @@ The /tmp/restore file has the following contents: =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server or Volume Location (VL) Server is -running, and on every file server machine that houses an affected -volume. If the B<-localauth> flag is included, the issuer must -instead be logged on to a server machine as the local superuser -B. +The issuer must be listed in the F file on every +machine where the Backup Server or Volume Location (VL) Server is running, +and on every file server machine that houses an affected volume. If the +B<-localauth> flag is included, the issuer must instead be logged on to a +server machine as the local superuser C. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos.pod b/doc/man-pages/pod8/bos.pod index 1ccb7d384..ce875a298 100644 --- a/doc/man-pages/pod8/bos.pod +++ b/doc/man-pages/pod8/bos.pod @@ -4,126 +4,105 @@ bos - Introduction to the bos command suite =head1 DESCRIPTION -The commands in the bos command suite are the administrative -interface to the Basic OverSeer (BOS) Server, which runs on every file server -machine to monitor the other server processes on it. If a process -fails, the BOS Server can restart it automatically, taking into account +The commands in the B command suite are the administrative interface +to the Basic OverSeer (BOS) Server, which runs on every file server +machine to monitor the other server processes on it. If a process fails, +the BOS Server can restart it automatically, taking into account interdependencies between it and other processes. The BOS Server frees -system administrators from constantly monitoring the status of server machines -and processes. +system administrators from constantly monitoring the status of server +machines and processes. -There are several categories of commands in the bos command -suite: +There are several categories of commands in the B command suite: =over 4 =item * -Commands to administer server process binary files: bos -getdate, B, B, and B - +Commands to administer server process binary files: B, B, B, and B. =item * -Commands to maintain system configuration files: bos -addhost, B, B, B, B, B, B, B, B, and -B - +Commands to maintain system configuration files: B, B, B, B, B, B, B, B, B, and +B. =item * -Commands to start and stop processes: bos create, -B, B, B, -B, B, and B - +Commands to start and stop processes: B, B, B, B, B, B, and B. =item * -Commands to set and verify server process and server machine status: -B, B, B, -B, and B - +Commands to set and verify server process and server machine status: B, B, B, B, and B. =item * -A command to restore file system consistency: bos salvage - +A command to restore file system consistency: B. =item * -Commands to obtain help: B and bos -help - +Commands to obtain help: B and B. =back -The BOS Server and the bos commands use and maintain the -following configuration and log files: +The BOS Server and the B commands use and maintain the following +configuration and log files: =over 4 =item * -The /usr/afs/etc/CellServDB file lists the local cell's -database server machines. These machines run the Authentication, -Backup, Protection and Volume Location (VL) Server processes, which maintain -databases of administrative information. The database server processes -consult the file to learn about their peers, whereas the other server -processes consult it to learn where to access database information as -needed. To administer the B file, use the following -commands: B, B, B, and B. - +The F file lists the local cell's database server +machines. These machines run the Authentication, Backup, Protection and +Volume Location (VL) Server processes, which maintain databases of +administrative information. The database server processes consult the file +to learn about their peers, whereas the other server processes consult it +to learn where to access database information as needed. To administer the +F file, use the following commands: B, B, B, and B. =item * -The /usr/afs/etc/KeyFile file lists the server encryption keys -that the server processes use to decrypt tickets presented by client processes -and one another. To administer the B file, use the -following commands: B, B, and -B. - +The F file lists the server encryption keys that the +server processes use to decrypt tickets presented by client processes and +one another. To administer the F file, use the following +commands: B, B, and B. =item * -The /usr/afs/etc/ThisCell file defines the cell to which the -server machine belongs for the purposes of server-to-server -communication. Administer it with the B -command. There is also a B file that -defines the machine's cell membership with respect to the AFS command -suites and Cache Manager access to AFS data. - +The F file defines the cell to which the server +machine belongs for the purposes of server-to-server communication. +Administer it with the B command. There is also a +F file that defines the machine's cell membership +with respect to the AFS command suites and Cache Manager access to AFS +data. =item * -The /usr/afs/etc/UserList file lists the user name of each +The F file lists the user name of each administrator authorized to issue privileged B and B -commands. To administer the B file, use the following -commands: B, B, and B. - +commands. To administer the F file, use the following commands: +B, B, and B. =item * -The /usr/afs/local/BosConfig file defines which AFS server -processes run on the server machine, and whether the BOS Server restarts them +The F file defines which AFS server processes +run on the server machine, and whether the BOS Server restarts them automatically if they fail. It also defines when all processes restart automatically (by default once per week), and when the BOS Server restarts processes that have new binary files (by default once per day). To -administer the B file, use the following commands: -B, B, B, -B, B, and B. - +administer the F file, use the following commands: B, B, B, B, B, and B. =item * -The /usr/afs/log/BosLog file records important operations the -BOS Server performs and error conditions it encounters. - +The F file records important operations the BOS +Server performs and error conditions it encounters. =back @@ -132,132 +111,114 @@ For more details, see the reference page for each file. =head1 OPTIONS The following arguments and flags are available on many commands in the -B suite. The reference page for each command also lists -them, but they are described here in greater detail. -L<(1)> -L<(1)> -L<(1)> +B suite. The reference page for each command also lists them, but +they are described here in greater detail. =over 4 -=item -cell -> +=item B<-cell> > -Names the cell in which to run the command. It is acceptable to -abbreviate the cell name to the shortest form that distinguishes it from the -other entries in the B file on the local -machine. If the B<-cell> argument is omitted, the command -interpreter determines the name of the local cell by reading the following in -order: +Names the cell in which to run the command. It is acceptable to abbreviate +the cell name to the shortest form that distinguishes it from the other +entries in the F file on the local machine. If +the B<-cell> argument is omitted, the command interpreter determines the +name of the local cell by reading the following in order: -=item * +=over 4 -The value of the AFSCELL environment variable +=item * +The value of the AFSCELL environment variable. =item * -The local /usr/vice/etc/ThisCell file +The local F file. +=back -Do not combine the B<-cell> and -localauth -options. A command on which the B<-localauth> flag is included -always runs in the local cell (as defined in the server machine's local -B file), whereas a command on which the -B<-cell> argument is included runs in the specified foreign -cell. -L<(1)> +Do not combine the B<-cell> and B<-localauth> options. A command on which +the B<-localauth> flag is included always runs in the local cell (as +defined in the server machine's local F file), +whereas a command on which the B<-cell> argument is included runs in the +specified foreign cell. -=item -help +=item B<-help> -Prints a command's online help message on the standard output -stream. Do not combine this flag with any of the command's other -options; when it is provided, the command interpreter ignores all other -options, and only prints the help message. +Prints a command's online help message on the standard output stream. Do +not combine this flag with any of the command's other options; when it is +provided, the command interpreter ignores all other options, and only +prints the help message. -=item L<(1) -B<-localauth> -> +=item B<-localauth> Constructs a server ticket using the server encryption key with the -highest key version number in the local B -file. The B command interpreter presents the ticket, which -never expires, to the BOS Server during mutual authentication. +highest key version number in the local F file. The +B command interpreter presents the ticket, which never expires, to +the BOS Server during mutual authentication. Use this flag only when issuing a command on a server machine; client -machines do not usually have a B file. -The issuer of a command that includes this flag must be logged on to the -server machine as the local superuser B. The flag is -useful for commands invoked by an unattended application program, such as a -process controlled by the UNIX B utility or by a cron entry in -the machine's B file. It is also -useful if an administrator is unable to authenticate to AFS but is logged in -as the local superuser B. - -Do not combine the B<-cell> and -localauth -options. A command on which the B<-localauth> flag is included -always runs in the local cell (as defined in the server machine's local -B file), whereas a command on which the -B<-cell> argument is included runs in the specified foreign -cell. Also, do not combine the B<-localauth> and +machines do not usually have a F file. The issuer +of a command that includes this flag must be logged on to the server +machine as the local superuser C. The flag is useful for commands +invoked by an unattended application program, such as a process controlled +by the UNIX B utility or by a cron entry in the machine's +F file. It is also useful if an administrator is +unable to authenticate to AFS but is logged in as the local superuser +C. + +Do not combine the B<-cell> and B<-localauth> options. A command on which +the B<-localauth> flag is included always runs in the local cell (as +defined in the server machine's local F file), +whereas a command on which the B<-cell> argument is included runs in the +specified foreign cell. Also, do not combine the B<-localauth> and B<-noauth> flags. -=item L<(1) -B<-noauth> -> +=item B<-noauth> Establishes an unauthenticated connection to the BOS Server, in which the -BOS Server treats the issuer as the unprivileged user -B. It is useful only when authorization checking is -disabled on the server machine (during the installation of a file server -machine or when the B command has been used during other -unusual circumstances). In normal circumstances, the BOS Server allows -only privileged users to issue commands that change the status of a server or -configuration file, and refuses to perform such an action even if the -B<-noauth> flag is provided. Do not combine the -B<-noauth> and B<-localauth> flags. - -=item -server > -L<(1)> -> - -Indicates the AFS server machine on which to run the command. -Identify the machine by its IP address in dotted decimal format, its -fully-qualified host name (for example, B), -or by an abbreviated form of its host name that distinguishes it from other +BOS Server treats the issuer as the unprivileged user C. It is +useful only when authorization checking is disabled on the server machine +(during the installation of a file server machine or when the B command has been used during other unusual circumstances). In +normal circumstances, the BOS Server allows only privileged users to issue +commands that change the status of a server or configuration file, and +refuses to perform such an action even if the B<-noauth> flag is +provided. Do not combine the B<-noauth> and B<-localauth> flags. + +=item B<-server> > + +Indicates the AFS server machine on which to run the command. Identify +the machine by its IP address in dotted decimal format, its +fully-qualified host name (for example, C), or by an +abbreviated form of its host name that distinguishes it from other machines. Successful use of an abbreviated form depends on the availability of a name service (such as the Domain Name Service or a local host table) at the time the command is issued. For the commands that alter the administrative files shared by all server -machines in the cell (the B, B, -B, B, B, -and B commands), the appropriate machine depends on -whether the cell uses the United States or international version of AFS: +machines in the cell (the B, B, B, +B, B, and B commands), the +appropriate machine depends on whether the cell uses the United States or +international version of AFS: =over 4 =item * -If the cell runs the United States edition of AFS and (as recommended) -uses the Update Server to distribute the contents of the -B directory, provide the name of the system control -machine. After issuing the command, allow up to five minutes for the -Update Server to distribute the changed file to the other AFS server machines -in the cell. If the specified machine is not the system control machine -but is running an B process that refers to the system +If the cell (as recommended) uses the Update Server to distribute the +contents of the F directory, provide the name of the system +control machine. After issuing the command, allow up to five minutes for +the Update Server to distribute the changed file to the other AFS server +machines in the cell. If the specified machine is not the system control +machine but is running an B process that refers to the system control machine, then the change will be overwritten when the process next brings over the relevant file from the system control machine. - =item * -If the cell runs the international edition of AFS, do not use the Update -Server to distribute the contents of the B -directory. Instead, repeatedly issue the command, naming each of the -cell's server machines in turn. To avoid possible inconsistency -problems, finish issuing the commands within a fairly short time. - +Otherwise, repeatedly issue the command, naming each of the cell's server +machines in turn. To avoid possible inconsistency problems, finish issuing +the commands within a fairly short time. =back @@ -265,59 +226,52 @@ problems, finish issuing the commands within a fairly short time. =head1 PRIVILEGE REQUIRED -To issue any bos command that changes a configuration file or -alters process status, the issuer must be listed in the -B file on the server machine named by the -B<-server> argument. Alternatively, if the -B<-localauth> flag is included the issuer must be logged on as the -local superuser B. +To issue any bos command that changes a configuration file or alters +process status, the issuer must be listed in the F +file on the server machine named by the B<-server> +argument. Alternatively, if the B<-localauth> flag is included the issuer +must be logged on as the local superuser C. -To issue a bos command that only displays information (other -than the B command), no privilege is required. +To issue a bos command that only displays information (other than the +B command), no privilege is required. =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, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_addhost.pod b/doc/man-pages/pod8/bos_addhost.pod index 847853e52..b394ed470 100644 --- a/doc/man-pages/pod8/bos_addhost.pod +++ b/doc/man-pages/pod8/bos_addhost.pod @@ -1,128 +1,110 @@ =head1 NAME -bos addhost - Adds a database server machine to the /usr/afs/etc/CellServDB -file +bos addhost - Adds a database server machine to the CellServDB file =head1 SYNOPSIS -B > -host >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-host> >+ + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > -ho >+ -[B<-c> >] [B<-n>] [B<-l>] [B<-he>] +B B<-s> > B<-ho> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-he>] =head1 DESCRIPTION -The bos addhost command adds an entry for each database server -machine specified with the B<-host> argument to the -B file on the machine named by the -B<-server> argument. +The B command adds an entry for each database server machine +specified with the B<-host> argument to the F +file on the machine named by the B<-server> argument. =head1 CAUTIONS After executing this command (and waiting for the Update Server to -propagate the changes, if it is used), restart the database server processes -on all database server machines to force election of a quorum that includes -the new set of machines listed in the B -file. The I explains in more detail -how to add and remove database server machines. +propagate the changes, if it is used), restart the database server +processes on all database server machines to force election of a quorum +that includes the new set of machines listed in the +F file. The I explains +in more detail how to add and remove database server machines. It is best to maintain a one-to-one mapping between hostnames and IP addresses on a multihomed database server machine (this is actually the -conventional configuration for any AFS machine). The BOS Server uses -the B routine to obtain the IP address -associated with the hostname specified by the B<-host> -argument. If there is more than one address, the BOS Server records in -the B entry the one that appears first in the list of -addresses returned by the routine. The routine possibly returns -addresses in a different order on different machines, which can create -inconsistency. +conventional configuration for any AFS machine). The BOS Server uses the +gethostbyname() routine to obtain the IP address associated with the +hostname specified by the B<-host> argument. If there is more than one +address, the BOS Server records in the F entry the one that +appears first in the list of addresses returned by the routine. The +routine possibly returns addresses in a different order on different +machines, which can create inconsistency. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Identifies the server machine on which to change the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. -In cells that run the United States edition of AFS and use the Update -Server to distribute the contents of the B directory, it -is conventional to specify only the system control machine as a value for the -B<-server> argument. In cells that run the international -version of AFS, repeat the command for each file server machine. For -further discussion, see the introductory reference page for the B -command suite. +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. Otherwise, repeat +the command for each file server machine. For further discussion, see +L. -=item -host -> +=item B<-host> >+ -Specifies the fully-qualified host name (such as -B) of each database server machine to -register in the B file. +Specifies the fully-qualified host name (such as C) of each +database server machine to register in the F file. -=item -cell -> +=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 B reference page. +argument with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not combine +this flag with the B<-localauth> flag. For more details, see L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command adds the database server machines -B and B -to the B file on the machine -B (the system control machine). +The following command adds the database server machines C and +C to the F file on the machine +C (the system control machine). % bos addhost -server fs1.abc.com -host db2.abc.com db3.abc.com =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L - -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L I diff --git a/doc/man-pages/pod8/bos_addkey.pod b/doc/man-pages/pod8/bos_addkey.pod index 0357be6d0..f3de0260e 100644 --- a/doc/man-pages/pod8/bos_addkey.pod +++ b/doc/man-pages/pod8/bos_addkey.pod @@ -1,127 +1,110 @@ =head1 NAME -bos addkey - Adds a new server encryption key to the /usr/afs/etc/KeyFile -file +bos addkey - Adds a new server encryption key to the KeyFile file =head1 SYNOPSIS -B > [-key >] -B<-kvno> > [B<-cell> >] - [B<-noauth>] [B<-localauth>] [-help] +B B<-server> > [B<-key> >] + B<-kvno> > [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-ke> >] -kv > -[B<-ce> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > [B<-ke> >] + B<-kv> > [B<-ce> >] [B<-n>] + [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos addkey command constructs a server encryption key from -the text string provided, assigns it the key version number specified with the -B<-kvno> argument, and adds it to the B -file on the machine specified with the B<-server> argument. Be -sure to use the B or B command to -add the same key to the B entry in the Authentication -Database. +The B command constructs a server encryption key from the text +string provided, assigns it the key version number specified with the +B<-kvno> argument, and adds it to the F file on the +machine specified with the B<-server> argument. Be sure to use the B or B command to add the same key to the C +entry in the Authentication Database. -Do not use the -key argument, which echoes the password string -visibly on the screen. If the argument is omitted, the BOS Server -prompts for the string and does not echo it visibly: +Do not use the B<-key> argument, which echoes the password string visibly +on the screen. If the argument is omitted, the BOS Server prompts for the +string and does not echo it visibly: Input key: Retype input key: The BOS Server prohibits reuse of any key version number already listed in -the B file. This ensures that users who -still have tickets sealed with the current key are not prevented from -communicating with a server process because the current key is overwritten -with a new key. Use the B command to display the -key version numbers in the B file. +the F file. This ensures that users who still have +tickets sealed with the current key are not prevented from communicating +with a server process because the current key is overwritten with a new +key. Use the B command to display the key version numbers in +the F file. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to change the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. - -In cells that run the United States edition of AFS and use the Update -Server to distribute the contents of the B directory, it -is conventional to specify only the system control machine as a value for the -B<-server> argument. In cells that run the international -version of AFS, repeat the command for each file server machine. For -further discussion, see the introductory reference page for the B -command suite. - -=item -key -> - -Specifies a character string just like a password; the BOS Server -calls a DES conversion function to encode it into a form appropriate for use -as an encryption key. Omit this argument to have the BOS Server prompt -for the string instead. - -=item -kvno -> - -Defines the new key's key version number. It must be an -integer in the range from B<0> (zero) through B<255>. -For the sake of simplicity, use the number one higher than the current highest -key version number; use the B command to display -key version numbers. -L<(1)> - -=item -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 B reference page. - -=item -noauth -> - -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. - -=item -localauth -> +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. + +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. Otherwise, repeat +the command for each file server machine. For further discussion, see +L. + +=item B<-key> > + +Specifies a character string just like a password; the BOS Server calls a +DES conversion function to encode it into a form appropriate for use as an +encryption key. Omit this argument to have the BOS Server prompt for the +string instead. + +=item B<-kvno> > + +Defines the new key's key version number. It must be an integer in the +range from C<0> (zero) through C<255>. For the sake of simplicity, use +the number one higher than the current highest key version number; use the +B command to display key version numbers. + +=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 L. + +=item B<-noauth> + +Assigns the unprivileged identity C to the issuer. Do not combine +this flag with the B<-localauth> flag. For more details, see L. + +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -If the strings typed at the C and C prompts do not match, the following message appears, and the command -exits without adding a new key: +If the strings typed at the C and C prompts +do not match, the following message appears, and the command exits without +adding a new key: Input key mismatch =head1 EXAMPLES The following command adds a new server encryption key with key version -number 14 to the B file kept on the machine -B (the system control machine). The -issuer omits the B<-key> argument, as recommended, and provides the -password at the prompts. +number 14 to the B file kept on the machine C (the +system control machine). The issuer omits the B<-key> argument, as +recommended, and provides the password at the prompts. % bos addkey -server fs1.abc.com -kvno 14 Input key: @@ -129,18 +112,18 @@ password at the prompts. =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_adduser.pod b/doc/man-pages/pod8/bos_adduser.pod index 7be24022c..1573cdbb7 100644 --- a/doc/man-pages/pod8/bos_adduser.pod +++ b/doc/man-pages/pod8/bos_adduser.pod @@ -1,104 +1,91 @@ =head1 NAME -bos adduser - Adds a privileged user to the /usr/afs/etc/UserList file +bos adduser - Adds a privileged user to the UserList file =head1 SYNOPSIS -B > -user >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-user> >+ + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > -u >+ -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-u> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos adduser command adds each user name specified with the -B<-user> argument to the B file on the -machine named by the B<-server> argument. It is the -issuer's responsibility to verify that an entry for the user exists in -the Authentication and Protection Databases. +The bos adduser command adds each user name specified with the B<-user> +argument to the F file on the machine named by the +B<-server> argument. It is the issuer's responsibility to verify that an +entry for the user exists in the Authentication and Protection Databases. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to change the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. -In cells that run the United States edition of AFS and use the Update -Server to distribute the contents of the B directory, it -is conventional to specify only the system control machine as a value for the -B<-server> argument. In cells that run the international -version of AFS, repeat the command for each file server machine. For -further discussion, see the introductory reference page for the B -command suite. +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. Otherwise, repeat +the command for each file server machine. For further discussion, see +L. -=item -user -> +=item B<-user> >+ -Specifies each user name to insert into the -B file. +Specifies each user name to insert into the F file. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command adds the user names pat and -B to the B file on the machine -B (the system control machine). +The following command adds the user names C and C to the +F file on the machine C (the system +control machine). % bos adduser -server fs1.abc.com -user pat smith =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_apropos.pod b/doc/man-pages/pod8/bos_apropos.pod index 200cf4a03..275fc8693 100644 --- a/doc/man-pages/pod8/bos_apropos.pod +++ b/doc/man-pages/pod8/bos_apropos.pod @@ -4,34 +4,32 @@ bos apropos - Displays each help entry containing a keyword string =head1 SYNOPSIS -B > [-help] +B B<-topic> > [B<-help>] -B > [-h] +B B<-t> > [B<-h>] =head1 DESCRIPTION -The bos apropos command displays the first line of the online -help entry for any B command that has in its name or short -description the string specified by the B<-topic> argument. +The B command displays the first line of the online help +entry for any B 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 bos help -command. +To display the syntax for a command, use the B command. =head1 OPTIONS =over 4 -=item -topic -> +=item B<-topic> > -Specifies the keyword string to match, in lowercase letters only. -If the string is more than a single word, surround it with double quotes ("") +Specifies the keyword string to match, in lowercase letters only. If the +string is more than a single word, surround it with double quotes (C<"">) or other delimiters. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -39,13 +37,13 @@ are ignored. 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 -B command where the string specified with the B<-topic> -argument is part of the command name or first line. +B command where the string specified with the B<-topic> argument is +part of the command name or first line. =head1 EXAMPLES -The following command lists all bos commands that include the -word B in their names or short descriptions: +The following command lists all B commands that include the word +C in their names or short descriptions: % bos apropos restart getrestart: get restart times @@ -58,8 +56,8 @@ None =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_create.pod b/doc/man-pages/pod8/bos_create.pod index 7175bd997..d48d17c74 100644 --- a/doc/man-pages/pod8/bos_create.pod +++ b/doc/man-pages/pod8/bos_create.pod @@ -1,188 +1,147 @@ =head1 NAME -bos create - Defines a new process in the /usr/afs/local/BosConfig file and -starts it running +bos create - Defines a new process in the BosConfig file and starts it =head1 SYNOPSIS -B > -instance > -B<-type> > B<-cmd> >+ - [B<-notifier> >] [-cell >] - [B<-noauth>] [B<-localauth>] [-help] +B B<-server> > + B<-instance> > B<-type> > + B<-cmd> >+ [B<-notifier> >] + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-i> > -t > -B<-cm> >+ [B<-not> >] [B<-ce> >] - [B<-noa>] [B<-l>] [-h] +B B<-s> > B<-i> > + B<-t> > B<-cm> >+ + [B<-not> >] [B<-ce> >] [B<-noa>] + [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos create command creates a server process entry in the -B file on the server machine named by the -B<-server> argument, sets the process's status to B -in the B file and in memory, and starts the process. +The B command creates a server process entry in the +F file on the server machine named by the +B<-server> argument, sets the process's status to C in the +F file and in memory, and starts the process. -A server process's entry in the BosConfig file defines its -name, its type, the command that initializes it, and optionally, the name of a +A server process's entry in the F file defines its name, its +type, the command that initializes it, and optionally, the name of a notifier program that runs when the process terminates. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to define and start the new process. Identify the machine by IP address or its host name (either -fully-qualified or abbreviated unambiguously). For details, see the -introductory reference page for the B command suite. +fully-qualified or abbreviated unambiguously). For details, see L. -=item -instance -> +=item B<-instance> > -Names the process to define and start. Any name is acceptable, but -for the sake of simplicity it is best to use the last element of the -process's binary file pathname, and to use the same name on every server -machine. The conventional names, as used in all AFS documentation, -are: +Names the process to define and start. Any name is acceptable, but for the +sake of simplicity it is best to use the last element of the process's +binary file pathname, and to use the same name on every server +machine. The conventional names, as used in all AFS documentation, are: =over 4 =item buserver -> -The Backup Server process -L<(1)> -L<(1)> +The Backup Server process. =item fs -> The process that combines the File Server, Volume Server, and Salvager -processes (B, B, and -B) -L<(1)> -L<(1)> +processes (B, B, and B). =item kaserver -> -The Authentication Server process -L<(1)> -L<(1)> +The Authentication Server process. =item ptserver -> -The Protection Server process -L<(1)> -L<(1)> +The Protection Server process. =item runntp -> -The controller process for the Network Time Protocol Daemon -L<(1)> -L<(1)> +The controller process for the Network Time Protocol Daemon. =item upclientbin -> The client portion of the Update Server process that retrieves binary -files from the B directory of the binary distribution -machine for this machine's CPU/operating system type. (The name of -the binary is B, but the B suffix distinguishes -this process from B.) -L<(1)> -L<(1)> +files from the F directory of the binary distribution +machine for this machine's CPU/operating system type. (The name of the +binary is B, but the C suffix distinguishes this process +from C.) =item upclientetc -> The client portion of the Update Server process that retrieves -configuration files from the B directory of the system -control machine. Do not run this process in cells that use the -international edition of AFS. (The name of the binary is -B, but the B suffix distinguishes this process -from B.) +configuration files from the F directory of the system +control machine. (The name of the binary is B, but the C +suffix distinguishes this process from C.) =item upserver -> -The server portion of the Update Server process -L<(1)> -L<(1)> +The server portion of the Update Server process. =item vlserver -> -The Volume Location (VL) Server process -L<(1)> -L<(1)> +The Volume Location (VL) Server process. =back -=item -type -> +=item B<-type> > Specifies the process's type. The acceptable values are: =over 4 =item cron -> Use this value for cron-type processes that the BOS Server starts only at a defined daily or weekly time, rather than whenever it detects that the -process has terminated. AFS does not define any such processes by -default, but makes this value available for administrator use. Define -the time for command execution as part of the B<-cmd> argument to the -B command. +process has terminated. AFS does not define any such processes by default, +but makes this value available for administrator use. Define the time for +command execution as part of the B<-cmd> argument to the B +command. =item fs -> -Use this value only for the fs process, which combines the File -Server, Volume Server and Salvager processes. If one of the component -processes terminates, the BOS Server shuts down and restarts the processes in -the appropriate order. +Use this value only for the fs process, which combines the File Server, +Volume Server and Salvager processes. If one of the component processes +terminates, the BOS Server shuts down and restarts the processes in the +appropriate order. =item simple -> Use this value for all processes listed as acceptable values to the -B<-instance> argument, except for the B process. -There are no interdependencies between simple processes, so the BOS Server can -stop and start them independently as necessary. +B<-instance> argument, except for the B process. There are no +interdependencies between simple processes, so the BOS Server can stop and +start them independently as necessary. =back -=item -cmd -> +=item B<-cmd> >+ -Specifies each command the BOS Server runs to start the process. -Specify no more than six commands (which can include the command's -options, in which case the entire string is surrounded by double quotes); -any additional commands are ignored. +Specifies each command the BOS Server runs to start the process. Specify +no more than six commands (which can include the command's options, in +which case the entire string is surrounded by double quotes); any +additional commands are ignored. For a simple process, provide the complete pathname of the process's -binary file on the local disk (for example, B -for the Protection Server). If including any of the initialization -command's options, surround the entire command in double quotes (B<" -">). The B process has a required argument, and -the commands for all other processes take optional arguments. -L<(1)> - -For the fs process, provide the complete pathname of the local -disk binary file for each of the component processes: -B, B, and B, in that -order. The standard binary directory is B. -If including any of an initialization command's options, surround the -entire command in double quotes (B<" ">). -L<(1)> +binary file on the local disk (for example, F for +the Protection Server). If including any of the initialization command's +options, surround the entire command in double quotes (C<"">). The +B process has a required argument, and the commands for all +other processes take optional arguments. + +For the fs process, provide the complete pathname of the local disk binary +file for each of the component processes: B, B, and +B, in that order. The standard binary directory is +F. If including any of an initialization command's options, +surround the entire command in double quotes (C<"">). For a cron process, provide two parameters: -L<(1)> =over 4 @@ -190,181 +149,157 @@ L<(1)> The complete local disk pathname of either an executable file or a command from one of the AFS suites (complete with all of the necessary -arguments). Surround this parameter with double quotes (B<" ">) -if it contains spaces. - +arguments). Surround this parameter with double quotes (C<"">) if it +contains spaces. =item * A specification of when the BOS Server executes the file or command -indicated by the first parameter. There are three acceptable -values: - +indicated by the first parameter. There are three acceptable values: =over 4 =item * -The string now, which directs the BOS Server to execute the -file or command immediately and only once. It is usually simpler to -issue the command directly or issue the B command. - +The string C, which directs the BOS Server to execute the file or +command immediately and only once. It is usually simpler to issue the +command directly or issue the B command. =item * -A time of day. The BOS Server executes the file or command daily at -the indicated time. Separate the hours and minutes with a colon -(I:I), and use either 24-hour format, or a value -in the range from B<1:00> through B<12:59> with -the addition of B or B. For example, both -B<14:30> and B<"2:30 pm"> indicate 2:30 in -the afternoon. Surround this parameter with double quotes (B<" -">) if it contains a space. - +A time of day. The BOS Server executes the file or command daily at the +indicated time. Separate the hours and minutes with a colon (I), +and use either 24-hour format, or a value in the range from C<1:00> +through C<12:59> with the addition of C or C. For example, both +C<14:30> and C<"2:30 pm"> indicate 2:30 in the afternoon. Surround this +parameter with double quotes (C<"">) if it contains a space. =item * A day of the week and time of day, separated by a space and surrounded -with double quotes (B<" ">). The BOS Server executes the file -or command weekly at the indicated day and time. For the day, provide -either the whole name or the first three letters, all in lowercase letters -(B or B, B or B, -and so on). For the time, use the same format as when specifying the -time alone. - +with double quotes (C<"">). The BOS Server executes the file or command +weekly at the indicated day and time. For the day, provide either the +whole name or the first three letters, all in lowercase letters (C +or C, C or C, and so on). For the time, use the same +format as when specifying the time alone. =back =back -=item -notifier -> +=item B<-notifier> > Specifies the complete pathname on the local disk of a program that the -BOS Server invokes when the process terminates. The AFS distribution -does not include any notifier programs, but this argument is available for -administrator use. See the B -section. +BOS Server invokes when the process terminates. The AFS distribution does +not include any notifier programs, but this argument is available for +administrator use. See L. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command defines and starts the simple process -B on the machine B: +C on the machine C: - % bos create -server fs3.abc.com -instance kaserver -type simple \ + % bos create -server fs3.abc.com -instance kaserver -type simple \ -cmd /usr/afs/bin/kaserver -The following command defines and starts the simple process -B on the machine -B. It references -B as the source for updates to binary -files, checking for changes to the B directory every 120 -seconds. - - % bos create -server fs4.abc.com -instance upclientbin -type simple \ - -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \ +The following command defines and starts the simple process C +on the machine C. It references C as the source +for updates to binary files, checking for changes to the F +directory every 120 seconds. + + % bos create -server fs4.abc.com -instance upclientbin -type simple \ + -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \ /usr/afs/bin" The following command creates the fs process fs on the machine -B. Type the command on a single -line. +C. Type the command on a single line. - % bos create -server fs4.abc.com -instance fs -type fs \ - -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \ + % bos create -server fs4.abc.com -instance fs -type fs \ + -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \ /usr/afs/bin/salvager -The following command creates a cron process called -B on the machine B, so -that the BOS Server issues the indicated B command each -day at 3:00 a.m. (the command creates a backup version of -every volume in the file system whose name begins with -B). Note that the issuer provides the complete pathname -to the B command, includes the B<-localauth> flag on it, -and types the entire B command on one line. +The following command creates a cron process called C on the +machine C, so that the BOS Server issues the indicated B command each day at 3:00 a.m. (the command creates a backup +version of every volume in the file system whose name begins with +C). Note that the issuer provides the complete pathname to the +B command, includes the B<-localauth> flag on it, and types the +entire B command on one line. - % bos create -server fs5.abc.com -instance userbackup -type cron \ - -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00 + % bos create -server fs5.abc.com -instance userbackup -type cron \ + -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. -=head1 SEE ALSO +=head1 NOTES -If the -notifier argument is included when this command is used -to define and start a process, the BOS Server invokes the indicated -I when the process exits. The intended use of -a notifier program is to inform administrators when a process exits -unexpectedly, but it can be used to perform any appropriate actions. -The following paragraphs describe the B and -B structures in which the BOS Server records information -about the exiting process. The list of AFS commands related to this one -follows. +If the B<-notifier> argument is included when this command is used to +define and start a process, the BOS Server invokes the indicated +I when the process exits. The intended use of a notifier +program is to inform administrators when a process exits unexpectedly, but +it can be used to perform any appropriate actions. The following +paragraphs describe the bnode and bnode_proc structures in which the +BOS Server records information about the exiting process. The BOS Server constructs and sends on the standard output stream one -B and one B structure for each exiting -process associated with the notifier program. It brackets each -structure with appropriate C and C statements -(C and C, C -and C), which immediately follow the preceding newline -character with no intervening spaces or other characters. If the -notifier program does not need information from a structure, it can scan ahead -in the input stream for the C statement. +bnode and one bnode_proc structure for each exiting process associated +with the notifier program. It brackets each structure with appropriate +C and C statements (C and C, C and C), which immediately follow the preceding +newline character with no intervening spaces or other characters. If the +notifier program does not need information from a structure, it can scan +ahead in the input stream for the C statement. In general, each field in a structure is a string of ASCII text terminated -by the newline character. The format of the information within a -structure possibly varies slightly depending on the type of process associated -with the notifier program. +by the newline character. The format of the information within a structure +possibly varies slightly depending on the type of process associated with +the notifier program. -The C code for the B and bnode_proc structures -follows. Note that the structures sent by the BOS Server do not -necessarily include all of the fields described here, because some are used -only for internal record keeping. The notifier process must robustly -handle the absence of expected fields, as well as the presence of unexpected -fields, on the standard input stream. +The C code for the bnode and bnode_proc structures follows. Note that the +structures sent by the BOS Server do not necessarily include all of the +fields described here, because some are used only for internal record +keeping. The notifier process must robustly handle the absence of expected +fields, as well as the presence of unexpected fields, on the standard +input stream. For proper performance, the notifier program must continue processing the -input stream until it detects the end-of-file (EOF). The BOS Server -closes the standard input file descriptor to the notifier process when it has -completed delivery of the data, and it is the responsibility of the notifier -process to terminate properly. +input stream until it detects the end-of-file (EOF). The BOS Server closes +the standard input file descriptor to the notifier process when it has +completed delivery of the data, and it is the responsibility of the +notifier process to terminate properly. -struct bnode contents +struct bnode contents: struct bnode { struct bnode *next; /* next pointer in top-level's list */ @@ -388,7 +323,7 @@ struct bnode contents char fileGoal; /* same, but to be stored in file */ }; -format of struct bnode explosion +Format of struct bnode explosion: printf("name: %s\n",tp->name); printf("rsTime: %ld\n", tp->rsTime); @@ -402,7 +337,7 @@ format of struct bnode explosion printf("lastErrorName: %s\n", tp->lastErrorName); printf("goal: %d\n", tp->goal); -struct bnode_proc contents +struct bnode_proc contents: struct bnode_proc { struct bnode_proc *next; /* next guy in top-level's list */ @@ -415,7 +350,7 @@ struct bnode_proc contents long flags; /* flags giving process state */ }; -format of struct bnode_proc explosion +Format of struct bnode_proc explosion: printf("comLine: %s\n", tp->comLine); printf("coreName: %s\n", tp->coreName); @@ -423,20 +358,21 @@ format of struct bnode_proc explosion printf("lastExit: %ld\n", tp->lastExit); printf("lastSignal: %ld\n", tp->lastSignal); -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, +L, L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_delete.pod b/doc/man-pages/pod8/bos_delete.pod index 19ed3b014..8f2199b08 100644 --- a/doc/man-pages/pod8/bos_delete.pod +++ b/doc/man-pages/pod8/bos_delete.pod @@ -1,104 +1,94 @@ =head1 NAME -bos delete - Deletes a server process from the /usr/afs/local/BosConfig file +bos delete - Deletes a server process from the BosConfig file =head1 SYNOPSIS -B > -instance >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > + B<-instance> >+ [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-i> >+ [-c >] -[B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-i> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos delete command removes the -B entry for each process indicated by the -B<-instance> argument, on the server machine named by the -B<-server> argument. +The B command removes the F entry +for each process indicated by the B<-instance> argument, on the server +machine named by the B<-server> argument. -Before issuing this command, issue the bos stop command to stop -the process and set its status flag in the B file to -C. The B command fails with an -error message if a process's status flag is C. +Before issuing this command, issue the bos stop command to stop the +process and set its status flag in the F file to C. The +B command fails with an error message if a process's status +flag is C. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to delete the server process entry -from the B file. Identify the machine +from the F file. Identify the machine by IP address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. +unambiguously). For details, see L. -=item -instance -> +=item B<-instance> >+ -Names each process to delete. Use the name assigned with the -B<-instance> argument to the B command; -process names appear in the output of the B -command. +Names each process to delete. Use the name assigned with the B<-instance> +argument to the B command; process names appear in the output +of the B command. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command removes the B, kaserver, -B, and B entries from the -B file on B, a database -server machine being decommissioned. +The following command removes the B, B, B, +and B entries from the F file on C, a +database server machine being decommissioned. - % bos delete -server db3.abc.com -instance buserver kaserver ptserver vlserver + % bos delete -server db3.abc.com \ + -instance buserver kaserver ptserver vlserver =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_exec.pod b/doc/man-pages/pod8/bos_exec.pod index ca400ffc1..e85d8e41c 100644 --- a/doc/man-pages/pod8/bos_exec.pod +++ b/doc/man-pages/pod8/bos_exec.pod @@ -4,88 +4,78 @@ bos exec - Executes a command on a remote server machine =head1 SYNOPSIS -B > -cmd > -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-cmd> > + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-cm> > [-ce >] -[B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-cm> > + [B<-ce> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos exec command executes the indicated command on the file -server machine named by the B<-server> argument. Its intended -use is to reboot the machine, using the B command or -equivalent. +The B command executes the indicated command on the file server +machine named by the B<-server> argument. Its intended use is to reboot +the machine, using the F command or equivalent. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine on which to execute the command. -Identify the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to execute the command. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -cmd -> +=item B<-cmd> > Specifies the complete local disk pathname of the command to execute (for -example, B). Surround this argument with double -quotes ("") if the command contains one or more spaces. +example, F). Surround this argument with double quotes +(C<"">) if the command contains one or more spaces. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command reboots the machine -B. The issuer has previously issued -the B command to shutdown all processes cleanly. +The following command reboots the machine C. The issuer has +previously issued the B command to shutdown all processes +cleanly. % bos exec -server fs2.abc.com -cmd /sbin/shutdown -r now =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_getdate.pod b/doc/man-pages/pod8/bos_getdate.pod index 5811fd86d..971401dfe 100644 --- a/doc/man-pages/pod8/bos_getdate.pod +++ b/doc/man-pages/pod8/bos_getdate.pod @@ -4,102 +4,90 @@ bos getdate - Displays the time stamps on an AFS binary file =head1 SYNOPSIS -B > -file >+ -[B<-dir> >] [B<-cell> >] - [B<-noauth>] [B<-localauth>] [-help] +B B<-server> > B<-file> >+ + [B<-dir> >] [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-f> >+ [-d >] -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-f> >+ + [B<-d> >] [B<-c> >] [B<-n>] [B<-l>] + [B<-h>] =head1 DESCRIPTION -The bos getdate command displays the time stamps on the current -version,C< .BAK> version (if any) and C<.OLD> -version (if any) of each binary file named by the B<-file> -argument. (The BOS Server automatically creates C<.BAK> -and C<.OLD> versions when new binaries are installed with the -B command.) The files must reside in the -B directory on the server machine named by the -B<-server> argument unless the B<-dir> argument indicates an -alternate directory. - -To revert to the C<.BAK> version of a binary, use the -B command. To remove obsolete binary files from -the B directory, use the B -command. +The B command displays the time stamps on the current +version,C< .BAK> version (if any) and C<.OLD> version (if any) of each +binary file named by the B<-file> argument. (The BOS Server automatically +creates C<.BAK> and C<.OLD> versions when new binaries are installed with +the B command.) The files must reside in the F +directory on the server machine named by the B<-server> argument unless +the B<-dir> argument indicates an alternate directory. + +To revert to the C<.BAK> version of a binary, use the B +command. To remove obsolete binary files from the F +directory, use the B command. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine from which to list binary files. -Identify the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine from which to list binary files. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -All server machines of the same AFS system type show the same timestamps if -the binaries were installed properly on the binary distribution machine for -this machine's system type, and if all other machines of that type are -running the appropriate B process. +All server machines of the same AFS system type show the same timestamps +if the binaries were installed properly on the binary distribution machine +for this machine's system type, and if all other machines of that type are +running the appropriate C process. -=item -file -> +=item B<-file> >+ Names each binary file to list. -=item -dir -> +=item B<-dir> > Specifies the complete pathname of the local disk directory containing -each file named by the B<-file> argument. It is necessary only -if the files are not in the B directory. +each file named by the B<-file> argument. It is necessary only if the +files are not in the F directory. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -For each file specified with the -file argument, the output -displays the time stamp on the current (unmarked), C<.BAK>, and -C<.OLD> version. The output explicitly reports that a -version does not exist, rather than simply omitting it. +For each file specified with the -file argument, the output displays the +time stamp on the current (unmarked), C<.BAK>, and C<.OLD> version. The +output explicitly reports that a version does not exist, rather than +simply omitting it. =head1 EXAMPLES The following command examines the time stamps on the files with basename -B on the machine B: +C on the machine C: % bos getdate -server fs2.abc.com -file kaserver File /usr/afs/bin/kaserver dated Mon Jan 4 10:00:36 1999. @@ -111,11 +99,11 @@ None =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_getlog.pod b/doc/man-pages/pod8/bos_getlog.pod index e6ab959d1..108af9ff7 100644 --- a/doc/man-pages/pod8/bos_getlog.pod +++ b/doc/man-pages/pod8/bos_getlog.pod @@ -4,26 +4,25 @@ bos getlog - Prints a server process's log file =head1 SYNOPSIS -B > -file > -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-file> > + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-f> > [-c >] -[B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-f> > + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos getlog command displays on the standard output stream -the specified log file from the machine named by the B<-server> -argument. The BOS Server fetches the log file from the -B directory unless an alternate pathname is provided as -part of the B<-file> argument. +The B command displays on the standard output stream the +specified log file from the machine named by the B<-server> argument. The +BOS Server fetches the log file from the F directory unless +an alternate pathname is provided as part of the B<-file> argument. =head1 CAUTIONS Log files can grow quite large, especially for the database server -processes. To keep them to a manageable size, periodically either use -the UNIX B command to truncate each log file, or use the B command to restart each process. +processes. To keep them to a manageable size, periodically either use the +UNIX B command to truncate each log file, or use the B +command to restart each process. It can take up to five minutes after the file is removed or process restarted for the space occupied by a log file to become available. @@ -32,93 +31,77 @@ restarted for the space occupied by a log file to become available. =over 4 -=item -server -> +=item B<-server> > Indicates the server machine from which to retrieve the log file. -Identify the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Identify the machine by IP address or its host name (either +fully-qualified or abbreviated unambiguously). For details, see L. -=item -file -> +=item B<-file> > -Names the log file to display. If a filename only is provided, the -BOS Server fetches the log file from the B -directory; the standard values are: +Names the log file to display. If a filename only is provided, the BOS +Server fetches the log file from the F directory; the +standard values are: =over 4 -=item AuthLog -> +=item F -The Authentication Server (kaserver) log file +The Authentication Server (B) log file. -=item BackupLog -> +=item F -The Backup Server (buserver) log file +The Backup Server (B) log file. -=item BosLog -> +=item F -The BOS Server (bosserver) log file +The BOS Server (B) log file. -=item FileLog -> +=item F -The File Server (fileserver) log file +The File Server (B) log file. -=item SalvageLog -> +=item F -The Salvager (salvager) log file +The Salvager (B) log file. -=item VLLog -> +=item F -The Volume Location (VL) Server (vlserver) log file +The Volume Location (VL) Server (B) log file. -=item VolserLog -> +=item F -The Volume Server (volserver) log file +The Volume Server (B) log file. =back -If a pathname and filename are provided, the log file is retrieved from the -indicated directory. Partial pathnames are interpreted relative to the -B directory. +If a pathname and filename are provided, the log file is retrieved from +the indicated directory. Partial pathnames are interpreted relative to the +F directory. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -126,14 +109,14 @@ are ignored. The output is preceded by the line - Fetching log file 'I'... + Fetching log file ''... The remainder of the output depends on the particular log file. =head1 EXAMPLES The following example displays the FileLog file from the machine -B: +C: % bos getlog -server fs3.abc.com -file FileLog Fetching log file 'FileLog'... @@ -147,14 +130,14 @@ B: =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_getrestart.pod b/doc/man-pages/pod8/bos_getrestart.pod index 14f13ff85..2e142ea58 100644 --- a/doc/man-pages/pod8/bos_getrestart.pod +++ b/doc/man-pages/pod8/bos_getrestart.pod @@ -4,83 +4,72 @@ bos getrestart - Displays the automatic restart times for server processes =head1 SYNOPSIS -B > [-cell >] -[B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-s> > [B<-c> >] [B<-n>] + [B<-l>] [B<-h>] =head1 DESCRIPTION The bos getrestart command displays two restart times from the -B file on the server machine named by the +F file on the server machine named by the B<-server> argument: =over 4 =item * -The I time at which the BOS Server process -automatically restarts itself and all processes marked with status -C in the B file. The default is Sunday -at 4:00 a.m. - +The I time at which the BOS Server process automatically +restarts itself and all processes marked with status C in the +F file. The default is Sunday at 4:00 a.m. =item * -The I time at which the BOS Server automatically -restarts any process for which the time stamp on the binary file in the -B directory is later than the last restart time for the -process. The default is 5:00 a.m. Use the B command to list a binary file's timestamp, and the -B<-long> flag to the B command to display a -process's most recent restart time. - +The I time at which the BOS Server automatically restarts +any process for which the time stamp on the binary file in the +F directory is later than the last restart time for the +process. The default is 5:00 a.m. Use the B command to list a +binary file's timestamp, and the B<-long> flag to the B +command to display a process's most recent restart time. =back -Use the bos setrestart command to set the restart times. +Use the B command to set the restart times. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine for which to display the restart times. Identify the machine by IP address or its host name (either -fully-qualified or abbreviated unambiguously). For details, see the -introductory reference page for the B command suite. +fully-qualified or abbreviated unambiguously). For details, see L. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -88,54 +77,47 @@ are ignored. The output consists of two lines: - Server I restarts at I to the file -B on the machine -B, which is the binary distribution machine -for server machines running AIX 4.2 in the B -cell. The current version of the B file -is moved to B. - - % bos install -server fs3.abc.com \ +F to the file +F on the machine C, which is the +binary distribution machine for server machines running AIX 4.2 in the +C cell. The current version of the F file +is moved to F. + + % bos install -server fs3.abc.com \ -file /afs/abc.com/rs_aix42/usr/afs/bin/vlserver =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_listhosts.pod b/doc/man-pages/pod8/bos_listhosts.pod index 8ba148a3b..afc6c4564 100644 --- a/doc/man-pages/pod8/bos_listhosts.pod +++ b/doc/man-pages/pod8/bos_listhosts.pod @@ -1,94 +1,86 @@ =head1 NAME -bos listhosts - Displays the contents of the /usr/afs/etc/CellServDB file +bos listhosts - Displays the contents of the CellServDB file =head1 SYNOPSIS -B > [-cell >] -[B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-s> > [B<-c> >] [B<-n>] + [B<-l>] [-h] -B > [-cell >] -[B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-s> > [B<-c> >] [B<-n>] + [B<-l>] [-h] =head1 DESCRIPTION -The bos listhosts command formats and displays the list of a -cell's database server machines from the -B file on the server machine named by the -B<-server> argument. +The B command formats and displays the list of a cell's +database server machines from the F file on the +server machine named by the B<-server> argument. -To alter the list of machines, use the B and bos -removehost commands. +To alter the list of machines, use the B and B commands. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine from which to display the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. For consistent performance in the cell, the output must be the same on -every server machine. The B reference page -explains how to keep the machines synchronized. +every server machine. The B reference page explains how to +keep the machines synchronized. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT The first line of the output names the cell to which the server machine -belongs. Each of the following lines names a database server machine -for that cell. +belongs. Each of the following lines names a database server machine for +that cell. The C number assigned to each database server machine is for -server-internal use only and is not the same as, nor necessarily related to, -the machine's IP address. The BOS Server assigned it as part of +server-internal use only and is not the same as, nor necessarily related +to, the machine's IP address. The BOS Server assigned it as part of performing the B command. =head1 EXAMPLES The following command displays the database server machines listed in the -B file on the machine -B. +F file on the machine C. % bos listhosts fs7.abc.com Cell name is abc.com @@ -102,12 +94,11 @@ None =head1 SEE ALSO -L - -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_listkeys.pod b/doc/man-pages/pod8/bos_listkeys.pod index 8e7cdfb57..ad4dcbbed 100644 --- a/doc/man-pages/pod8/bos_listkeys.pod +++ b/doc/man-pages/pod8/bos_listkeys.pod @@ -1,110 +1,99 @@ =head1 NAME -bos listkeys - Displays the server encryption keys from the -B file +bos listkeys - Displays the server encryption keys from the KeyFile file =head1 SYNOPSIS -B > [B<-showkey>] [-cell >] -[B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-showkey>] + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-sh>] [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-se> > [B<-sh>] [B<-c> >] + [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos listkeys command formats and displays the list of server -encryption keys from the B file on the server +The B command formats and displays the list of server +encryption keys from the F file on the server machine named by the B<-server> argument. -To edit the list of keys, use the B and bos -removekey commands. +To edit the list of keys, use the B and B +commands. =head1 CAUTIONS Displaying actual keys on the standard output stream (by including the -B<-showkey> flag) is a security exposure. Displaying a checksum -is sufficient for most purposes. +B<-showkey> flag) is a security exposure. Displaying a checksum is +sufficient for most purposes. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine from which to display the KeyFile file. Identify the machine by IP address or its host name (either -fully-qualified or abbreviated unambiguously). For details, see the -introductory reference page for the B command suite. +fully-qualified or abbreviated unambiguously). For details, see L. For consistent performance in the cell, the output must be the same on -every server machine. The B reference page explains -how to keep the machines synchronized. +every server machine. The B reference page explains how to +keep the machines synchronized. -=item -showkey -> +=item B<-showkey> Displays the octal digits that constitute each key. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT The output includes one line for each server encryption key listed in the -B file, identified by its key version number. +F file, identified by its key version number. -If the -showkey flag is included, the output displays the actual -string of eight octal numbers that constitute the key. Each octal -number is a backslash and three decimal digits. +If the B<-showkey> flag is included, the output displays the actual string +of eight octal numbers that constitute the key. Each octal number is a +backslash and three decimal digits. -If the -showkey flag is not included, the output represents each -key as a checksum, which is a decimal number derived by encrypting a constant +If the B<-showkey> flag is not included, the output represents each key as +a checksum, which is a decimal number derived by encrypting a constant with the key. -Following the list of keys or checksums, the string C indicates when a key was last added to the B -file. The words C indicate the end of the -output. +Following the list of keys or checksums, the string C +indicates when a key was last added to the F file. The words +C indicate the end of the output. For mutual authentication to work properly, the output from the command -B must match the key or checksum with the same key +C must match the key or checksum with the same key version number in the output from this command. =head1 EXAMPLES The following example shows the checksums for the keys stored in the -B file on the machine -B. +F file on the machine C. % bos listkeys fs3.abc.com key 1 has cksum 972037177 @@ -114,8 +103,8 @@ B. Keys last changed on Mon Apr 12 11:24:46 1999. All done. -The following example shows the actual keys from the KeyFile -file on the machine B. +The following example shows the actual keys from the F file on +the machine C. % bos listkeys fs6.abc.com -showkey key 0 is '\040\205\211\241\345\002\023\211' @@ -126,19 +115,19 @@ file on the machine B. =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_listusers.pod b/doc/man-pages/pod8/bos_listusers.pod index ca3a380af..daf9385e2 100644 --- a/doc/man-pages/pod8/bos_listusers.pod +++ b/doc/man-pages/pod8/bos_listusers.pod @@ -1,69 +1,62 @@ =head1 NAME -bos listusers - Lists the privileged users from the /usr/afs/etc/UserList file +bos listusers - Lists the privileged users from the UserList file =head1 SYNOPSIS -B > [-cell >] -[B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-s> > [B<-c> >] [B<-n>] + [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos listusers command lists the user names from the -B file on the file server machine named by the -B<-server> argument. The users are authorized to issue -privileged B and B commands. +The B command lists the user names from the +F file on the file server machine named by the +B<-server> argument. The users are authorized to issue privileged B +and B commands. -To edit the list of users, use the B and bos -removeuser commands. +To edit the list of users, use the B and B +commands. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine from which to display the UserList file. Identify the machine by IP address or its host name (either -fully-qualified or abbreviated unambiguously). For details, see the -introductory reference page for the B command suite. +fully-qualified or abbreviated unambiguously). For details, see L. For consistent performance in the cell, the output must be the same on -every server machine. The B reference page -explains how to keep the machines synchronized. +every server machine. The B reference page explains how to +keep the machines synchronized. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -74,8 +67,8 @@ B and B commands. =head1 EXAMPLES -The following example lists the users from UserList file on the -machine B. +The following example lists the users from UserList file on the machine +C. % bos listusers fs4.abc.com SUsers are: pat smith jones terry @@ -86,11 +79,11 @@ None =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_prune.pod b/doc/man-pages/pod8/bos_prune.pod index 805225b4b..3410b24ae 100644 --- a/doc/man-pages/pod8/bos_prune.pod +++ b/doc/man-pages/pod8/bos_prune.pod @@ -1,160 +1,134 @@ =head1 NAME -bos prune - Removes obsolete versions of files from the /usr/afs/bin and -B directories +bos prune - Removes obsolete files from /usr/afs/bin and /usr/afs/logs =head1 SYNOPSIS -B > [B<-bak>] [B<-old>] [B<-core>] [-all] -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-bak>] [B<-old>] [B<-core>] + [B<-all>] [B<-cell> >] [B<-noauth>] [B<-localauth>] + [B<-help>] -B > [B<-b>] [B<-o>] [B<-co>] [-a] -[B<-ce> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > [B<-b>] [B<-o>] [B<-co>] [B<-a>] + [B<-ce> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos prune command removes files from the local disk of the -server machine named by the B<-server> argument, as specified by one -or more of the following flags provided on the command line: +The B command removes files from the local disk of the server +machine named by the B<-server> argument, as specified by one or more of +the following flags provided on the command line: =over 4 =item * -The -bak flag removes all files from the -B directory that have a C<.BAK> -extension. - +The B<-bak> flag removes all files from the F directory that +have a C<.BAK> extension. =item * -The -old flag removes all files from the -B directory that have a C<.OLD> -extension. - +The B<-old> flag removes all files from the F directory that +have a C<.OLD> extension. =item * -The -core flag removes all files from the -B directory that have a C -prefix. - +The B<-core> flag removes all files from the F directory +that have a C prefix. =item * -The -all flag removes all three types of files at once. - +The B<-all> flag removes all three types of files at once. =back (If none of these flags are included, the command appears to succeed, but removes no files at all.) -To display the timestamp on the current, C<.BAK>, and -C<.OLD> versions of one or more files, use the B command. +To display the timestamp on the current, C<.BAK>, and C<.OLD> versions of +one or more files, use the B command. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine from which to remove files. Identify -the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine from which to remove files. Identify the +machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -bak -> +=item B<-bak> -Removes all files from the /usr/afs/bin directory that have a -C<.BAK> extension. Do not combine this flag and the -B<-all> flag. +Removes all files from the F directory that have a C<.BAK> +extension. Do not combine this flag and the B<-all> flag. -=item -old -> +=item B<-old> -Removes all files from the /usr/afs/bin directory that have a -C<.OLD> extension. Do not combine this flag and the -B<-all> flag. +Removes all files from the F directory that have a C<.OLD> +extension. Do not combine this flag and the B<-all> flag. -=item -core -> +=item B<-core> -Removes all files from the /usr/afs/logs directory that have a -C prefix. Do not combine this flag and the -B<-all> flag. +Removes all files from the F directory that have a C +prefix. Do not combine this flag and the B<-all> flag. -=item -all -> +=item B<-all> -Combines the effect of the B<-bak>, -old, and -B<-core> flags. Do not combine this flag with any of those -three. +Combines the effect of the B<-bak>, B<-old>, and B<-core> flags. Do not +combine this flag with any of those three. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example removes all files from the /usr/afs/bin -directory on the machine B that have a -C<.BAK> or C<.OLD> extension. +The following example removes all files from the F directory +on the machine C that have a C<.BAK> or C<.OLD> extension. % bos prune -server fs3.abc.com -bak -old -The following example removes all files from the /usr/afs/bin -directory on the machine B that have a -C<.BAK> or C<.OLD> extension, and all files from -the B directory that have a C +The following example removes all files from the F directory +on the machine C that have a C<.BAK> or C<.OLD> extension, +and all files from the F directory that have a C prefix. % bos prune -server db2.abc.com -all =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_removehost.pod b/doc/man-pages/pod8/bos_removehost.pod index 7462341e4..0b7bcb922 100644 --- a/doc/man-pages/pod8/bos_removehost.pod +++ b/doc/man-pages/pod8/bos_removehost.pod @@ -1,114 +1,101 @@ =head1 NAME -bos removehost - Removes a database server machine from the -B file +bos removehost - Removes a database server machine from the CellServDB file =head1 SYNOPSIS -B > -host >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-host> >+ + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-ho> >+ [-c >] -[B<-n>] [B<-l>] [B<-he>] +B B<-s> > B<-ho> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-he>] =head1 DESCRIPTION -The bos removehost command removes the entry for each database -server machine specified with the B<-host> argument from the -B file on the server machine named by the +The B command removes the entry for each database server +machine specified with the B<-host> argument from the +F file on the server machine named by the B<-server> argument. =head1 CAUTIONS After executing this command (and waiting for the Update Server to -propagate the changes, if it is used), restart the database server processes -on all database server machines to force election of a quorum that includes -the new set of machines listed in the B -file. The I explains in more detail -how to add and remove database server machines. +propagate the changes, if it is used), restart the database server +processes on all database server machines to force election of a quorum +that includes the new set of machines listed in the +F file. The I explains +in more detail how to add and remove database server machines. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to change the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. -In cells that run the United States edition of AFS and use the Update -Server to distribute the contents of the B directory, it -is conventional to specify only the system control machine as a value for the -B<-server> argument. In cells that run the international -version of AFS, repeat the command for each file server machine. For -further discussion, see the introductory reference page for the B -command suite. +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. Otherwise, repeat +the command for each file server machine. For further discussion, see +L. -=item -host -> +=item B<-host> >+ -Specifies the fully-qualified host name (such as -B) of each database server machine to -remove from the B file. +Specifies the fully-qualified host name (such as C) of each +database server machine to remove from the B file. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command removes the former database server machine -B from the B file on -the system control machine B. +C from the F file on the system control machine +C. % bos removehost -server fs1.abc.com -host db2.abc.com =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L I diff --git a/doc/man-pages/pod8/bos_removekey.pod b/doc/man-pages/pod8/bos_removekey.pod index c14e9104e..414ce06d6 100644 --- a/doc/man-pages/pod8/bos_removekey.pod +++ b/doc/man-pages/pod8/bos_removekey.pod @@ -1,111 +1,99 @@ =head1 NAME -bos removekey - Removes a server encryption key from the /usr/afs/etc/KeyFile -file +bos removekey - Removes a server encryption key from the KeyFile file =head1 SYNOPSIS -B > -kvno >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > + B<-kvno> >+ [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > -k >+ -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-k> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos removekey command removes each specified encryption key -from the B file on the machine named by the -B<-server> argument. Use the B<-kvno> argument to -identify each key by its key version number; use the B command to display the key version numbers. +The B command removes each specified encryption key from +the F file on the machine named by the B<-server> +argument. Use the B<-kvno> argument to identify each key by its key +version number; use the B command to display the key version +numbers. =head1 CAUTIONS Before removing a obsolete key, verify that the cell's maximum ticket lifetime has passed since the current key was defined using the B and B commands. This ensures that -no clients still possess tickets encrypted with the obsolete key. +setpassword> and B commands. This ensures that no clients +still possess tickets encrypted with the obsolete key. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to change the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. - -In cells that run the United States edition of AFS and use the Update -Server to distribute the contents of the B directory, it -is conventional to specify only the system control machine as a value for the -B<-server> argument. In cells that run the international -version of AFS, repeat the command for each file server machine. For -further discussion, see the introductory reference page for the B -command suite. - -=item -kvno -> +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. + +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. Otherwise, repeat +the command for each file server machine. For further discussion, see +L. + +=item B<-kvno> >+ Specifies the key version number of each key to remove. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command removes the keys with key version numbers 5 and 6 -from the B file on the system control machine -B. +from the F file on the system control machine C. % bos removekey -server fs1.abc.com -kvno 5 6 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_removeuser.pod b/doc/man-pages/pod8/bos_removeuser.pod index 0bf02d442..51916eca2 100644 --- a/doc/man-pages/pod8/bos_removeuser.pod +++ b/doc/man-pages/pod8/bos_removeuser.pod @@ -1,101 +1,89 @@ =head1 NAME -bos removeuser - Removes a privileged user from the /usr/afs/etc/UserList file +bos removeuser - Removes a privileged user from the UserList file =head1 SYNOPSIS -B > -user >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-user> >+ + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-u> >+ [-c >] -[B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-u> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos removeuser command removes each user name specified with -the B<-user> argument from the B file -on the machine named by the B<-server> argument. +The B command removes each user name specified with the +B<-user> argument from the F file on the machine +named by the B<-server> argument. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to change the -B file. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. - -In cells that run the United States edition of AFS and use the Update -Server to distribute the contents of the B directory, it -is conventional to specify only the system control machine as a value for the -B<-server> argument. In cells that run the international -version of AFS, repeat the command for each file server machine. For -further discussion, see the introductory reference page for the B -command suite. - -=item -user -> +F file. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. + +In cells that use the Update Server to distribute the contents of the +F directory, it is conventional to specify only the system +control machine as a value for the B<-server> argument. Otherwise, repeat +the command for each file server machine. For further discussion, see +L. + +=item B<-user> >+ Specifies each user name to remove. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example removes the users B and jones -from the B file on the system control machine -B. +The following example removes the users C and C from the +F file on the system control machine C. % bos removeuser -server fs1.abc.com -user pat jones =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_restart.pod b/doc/man-pages/pod8/bos_restart.pod index 5c413c3e3..4a3a7ab84 100644 --- a/doc/man-pages/pod8/bos_restart.pod +++ b/doc/man-pages/pod8/bos_restart.pod @@ -4,157 +4,138 @@ bos restart - Restarts a server process =head1 SYNOPSIS -B > [B<-instance> >+] [-bosserver] -[B<-all>] [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-instance> >+] + [B<-bosserver>] [B<-all>] [B<-cell> >] [B<-noauth>] + [B<-localauth>] [B<-help>] -B > [B<-i> >+] [B<-b>] [-a] -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > [B<-i> >+] [B<-b>] + [B<-a>] [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos restart command stops and immediately restarts server -processes on the server machine named by the B<-server> -argument. Indicate which process or processes to restart by providing -one of the following arguments: +The B command stops and immediately restarts server processes +on the server machine named by the B<-server> argument. Indicate which +process or processes to restart by providing one of the following +arguments: =over 4 =item * -The -instance argument names each AFS server process to stop -and restart immediately, regardless of its status flag in the -B file. Do not include -B in the list of processes; use the -B<-bosserver> flag instead. - +The B<-instance> argument names each AFS server process to stop and +restart immediately, regardless of its status flag in the +F file. Do not include B in the list +of processes; use the B<-bosserver> flag instead. =item * -The -bosserver flag stops all AFS server processes running on -the machine, including the BOS Server. A new BOS Server starts -immediately, and it starts a new instance of each process that is marked with -the C status flag in the B file. - +The B<-bosserver> flag stops all AFS server processes running on the +machine, including the BOS Server. A new BOS Server starts immediately, +and it starts a new instance of each process that is marked with the +C status flag in the F file. =item * -The -all flag stops all AFS server processes running on the -machine, except the BOS Server, and immediately restarts the processes that -are marked with the C status flag in the B -file. - +The B<-all> flag stops all AFS server processes running on the machine, +except the BOS Server, and immediately restarts the processes that are +marked with the C status flag in the F file. =back -This command does not change a process's status flag in the -B file. +This command does not change a process's status flag in the F +file. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine on which to restart each process. -Identify the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to restart each process. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -instance -> +=item B<-instance> >+ Names each process to stop and then restart immediately regardless of its -status flag setting. Use the process name assigned with the -B<-instance> argument to the B command. The -output from the B command lists the names. Provide -this flag or one of the B<-bosserver> or B<-all> options, but -do not combine them. +status flag setting. Use the process name assigned with the B<-instance> +argument to the B command. The output from the B +command lists the names. Provide this flag or one of the B<-bosserver> or +B<-all> options, but do not combine them. -=item -bosserver -> +=item B<-bosserver> Stops all AFS server processes running on the machine, including the BOS Server. A new BOS Server instance immediately starts, and starts all -processes marked with the C status flag in the -B file. Provide this flag or one of the -B<-instance> or B<-all> options, but do not combine -them. +processes marked with the C status flag in the F +file. Provide this flag or one of the B<-instance> or B<-all> options, but +do not combine them. -=item -all -> +=item B<-all> Stops all AFS server processes running on the machine other than the BOS Server, and immediately restarts the processes marked with the B -status flag in the B file. Provide this flag or one -of the B<-instance> or B<-bosserver> options, but do not -combine them. +status flag in the F file. Provide this flag or one of the +B<-instance> or B<-bosserver> options, but do not combine them. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command stops and restarts all processes running on the -machine B, including the BOS Server. +machine C, including the BOS Server. % bos restart -server fs3.abc.com -bosserver The following command stops and restarts all processes running on the -machine B, excluding the BOS Server. +machine C, excluding the BOS Server. % bos restart -server fs5.abc.com -all The following command stops and restarts the Protection Server and Volume -Location (VL) Server processes on the machine -B: +Location (VL) Server processes on the machine C: % bos restart -server db3.abc.com -instance ptserver vlserver =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_salvage.pod b/doc/man-pages/pod8/bos_salvage.pod index f3a282e24..3cf188a22 100644 --- a/doc/man-pages/pod8/bos_salvage.pod +++ b/doc/man-pages/pod8/bos_salvage.pod @@ -4,31 +4,30 @@ bos salvage - Restores internal consistency to a file system or volume =head1 SYNOPSIS -B > [-partition >] -[B<-volume> >] - [B<-file> >] [B<-all>] [-showlog] - [-parallel >] - [-tmpdir >] - [B<-orphans> | B | attach>] - [-cell >] - [B<-noauth>] [B<-localauth>] [-help] - -B > [-part >] -[B<-v> >] - [B<-f> >] [B<-a>] [-sh] - [-para >] - [-t >] - [B<-o> | B | attach>] - [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-server> > + [B<-partition> >] + [B<-volume> >] + [B<-file> >] [B<-all>] [B<-showlog>] + [B<-parallel> >] + [B<-tmpdir> >] + [B<-orphans> (ignore | remove | attach)] [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] + +B B<-se> > [B<-part> >] + [B<-v> >] + [B<-f> >] [B<-a>] [B<-sh>] + [<-para> >] + [B<-t> >] + [B<-o> (ignore | remove | attach)] [B<-c> >] [B<-n>] + [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos salvage command salvages (restores internal consistency -to) one or more volumes on the file server machine named by the -B<-server> argument. When processing one or more partitions, -the command restores consistency to corrupted read/write volumes where -possible. For read-only or backup volumes, it inspects only the volume -header: +The B command salvages (restores internal consistency to) one +or more volumes on the file server machine named by the B<-server> +argument. When processing one or more partitions, the command restores +consistency to corrupted read/write volumes where possible. For read-only +or backup volumes, it inspects only the volume header: =over 4 @@ -36,21 +35,17 @@ header: If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log file, -B. Issue the B -or B command to create the read-only or backup volume -again. - +F. Issue the B or B +command to create the read-only or backup volume again. =item * If the volume header is intact, the Salvager skips the volume (does not -check for corruption in the contents). However, if the File Server -notices corruption as it initializes, it sometimes refuses to attach the -volume or bring it online. In this case, it is simplest to remove the -volume by issuing the B or B -command. Then issue the B or B -command to create it again. - +check for corruption in the contents). However, if the File Server notices +corruption as it initializes, it sometimes refuses to attach the volume or +bring it online. In this case, it is simplest to remove the volume by +issuing the B or B command. Then issue the B or B command to create it again. =back @@ -60,151 +55,140 @@ Use the indicated arguments to salvage a specific number of volumes: =item * -To process all volumes on a file server machine, provide the -B<-server> argument and the B<-all> flag. No volumes on -the machine are accessible to Cache Managers during the salvage operation, -because the BOS Server stops the File Server and Volume Server processes while -the Salvager runs. The BOS Server automatically restarts them when the -operation completes. - +To process all volumes on a file server machine, provide the B<-server> +argument and the B<-all> flag. No volumes on the machine are accessible to +Cache Managers during the salvage operation, because the BOS Server stops +the File Server and Volume Server processes while the Salvager runs. The +BOS Server automatically restarts them when the operation completes. =item * -To process all volumes on one partition, provide the -server -and B<-partition> arguments. As for a salvage of the entire -machine, no volumes on the machine are accessible to Cache Managers during the -salvage operation. The BOS Server automatically restarts the File -Server and Volume Server when the operation completes. - +To process all volumes on one partition, provide the B<-server> and +B<-partition> arguments. As for a salvage of the entire machine, no +volumes on the machine are accessible to Cache Managers during the salvage +operation. The BOS Server automatically restarts the File Server and +Volume Server when the operation completes. =item * -To salvage only one read/write volume, combine the -server, -B<-partition>, and B<-volume> arguments. Only that -volume is inaccessible to Cache Managers, because the BOS Server does not -shutdown the File Server and Volume Server processes during the salvage of a -single volume. Do not name a read-only or backup volume with the -B<-volume> argument. Instead, remove the volume, using the -B or B command. Then create a new -copy of the volume with the B or B -command. - +To salvage only one read/write volume, combine the B<-server>, +B<-partition>, and B<-volume> arguments. Only that volume is inaccessible +to Cache Managers, because the BOS Server does not shutdown the File +Server and Volume Server processes during the salvage of a single +volume. Do not name a read-only or backup volume with the B<-volume> +argument. Instead, remove the volume, using the B or B command. Then create a new copy of the volume with the B +or B command. =back -During the salvage of an entire machine or partition, the bos -status command reports the B process's auxiliary status -as C. - -The Salvager always writes a trace to the -B file on the file server machine where it -runs. To record the trace in another file as well (either in AFS or on -the local disk of the machine where the B command is -issued), name the file with the B<-file> argument. To display -the trace on the standard output stream as it is written to the -B file, include the B<-showlog> +During the salvage of an entire machine or partition, the B +command reports the C process's auxiliary status as C. + +The Salvager always writes a trace to the F file +on the file server machine where it runs. To record the trace in another +file as well (either in AFS or on the local disk of the machine where the +B command is issued), name the file with the B<-file> +argument. To display the trace on the standard output stream as it is +written to the F file, include the B<-showlog> flag. -By default, multiple Salvager subprocesses run in parallel: one for -each partition up to four, and four subprocesses for four or more -partitions. To increase or decrease the number of subprocesses running -in parallel, provide a positive integer value for the B<-parallel> -argument. - -If there is more than one server partition on a physical disk, the Salvager -by default salvages them serially to avoid the inefficiency of constantly -moving the disk head from one partition to another. However, this -strategy is often not ideal if the partitions are configured as logical -volumes that span multiple disks. To force the Salvager to salvage -logical volumes in parallel, provide the string B as the value -for the B<-parallel> argument. Provide a positive integer to -specify the number of subprocesses to run in parallel (for example, -B<-parallel 5all> for five subprocesses), or omit the integer to run -up to four subprocesses, depending on the number of logical volumes being -salvaged. - -The Salvager creates temporary files as it runs, by default writing them to -the partition it is salvaging. The number of files can be quite large, -and if the partition is too full to accommodate them, the Salvager terminates -without completing the salvage operation (it always removes the temporary -files before exiting). Other Salvager subprocesses running at the same -time continue until they finish salvaging all other partitions where there is -enough disk space for temporary files. To complete the interrupted -salvage, reissue the command against the appropriate partitions, adding the -B<-tmpdir> argument to redirect the temporary files to a local disk -directory that has enough space. - -The -orphans argument controls how the Salvager handles orphaned -files and directories that it finds on server partitions it is -salvaging. An I element is completely inaccessible -because it is not referenced by the vnode of any directory that can act as its -parent (is higher in the filespace). Orphaned objects occupy space on -the server partition, but do not count against the volume's quota. +By default, multiple Salvager subprocesses run in parallel: one for each +partition up to four, and four subprocesses for four or more +partitions. To increase or decrease the number of subprocesses running in +parallel, provide a positive integer value for the B<-parallel> argument. + +If there is more than one server partition on a physical disk, the +Salvager by default salvages them serially to avoid the inefficiency of +constantly moving the disk head from one partition to another. However, +this strategy is often not ideal if the partitions are configured as +logical volumes that span multiple disks. To force the Salvager to salvage +logical volumes in parallel, provide the string C as the value for +the B<-parallel> argument. Provide a positive integer to specify the +number of subprocesses to run in parallel (for example, C<-parallel 5all> +for five subprocesses), or omit the integer to run up to four +subprocesses, depending on the number of logical volumes being salvaged. + +The Salvager creates temporary files as it runs, by default writing them +to the partition it is salvaging. The number of files can be quite large, +and if the partition is too full to accommodate them, the Salvager +terminates without completing the salvage operation (it always removes the +temporary files before exiting). Other Salvager subprocesses running at +the same time continue until they finish salvaging all other partitions +where there is enough disk space for temporary files. To complete the +interrupted salvage, reissue the command against the appropriate +partitions, adding the B<-tmpdir> argument to redirect the temporary files +to a local disk directory that has enough space. + +The B<-orphans> argument controls how the Salvager handles orphaned files +and directories that it finds on server partitions it is salvaging. An +I element is completely inaccessible because it is not +referenced by the vnode of any directory that can act as its parent (is +higher in the filespace). Orphaned objects occupy space on the server +partition, but do not count against the volume's quota. =head1 CAUTIONS Running this command can result in data loss if the Salvager process can -repair corruption only by removing the offending data. Consult the -I for more information. +repair corruption only by removing the offending data. Consult the I for more information. =head1 OPTIONS =over 4 -=item -server +=item B<-server> > -Indicates the file server machine on which to salvage volumes. -Identify the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the file server machine on which to salvage volumes. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -partition +=item B<-partition> > -Specifies a single partition on which to salvage all volumes. -Provide the complete partition name (for example B) or one of -the following abbreviated forms: +Specifies a single partition on which to salvage all volumes. Provide the +complete partition name (for example F) or one of the following +abbreviated forms: - B = B = B = 0 - B = B = B = 1 + /vicepa = vicepa = a = 0 + /vicepb = vicepb = b = 1 -After /vicepz (for which the index is 25) comes +After F (for which the index is 25) comes - B = B = B = 26 - B = B = B = 27 + /vicepaa = vicepaa = aa = 26 + /vicepab = vicepab = ab = 27 and so on through - B = B = B = 255 + /vicepiv = vicepiv = iv = 255 -=item -volume +=item B<-volume> > Specifies the name or volume ID number of a read/write volume to -salvage. The B<-partition> argument must be provided along with -this one. +salvage. The B<-partition> argument must be provided along with this one. -=item -file +=item B<-file> > Specifies the complete pathname of a file into which to write a trace of -the salvage operation, in addition to the B -file on the server machine. If the file pathname is local, the trace is -written to the specified file on the local disk of the machine where the -B command is issued. If the B<-volume> -argument is included, the file can be in AFS, though not in the volume being -salvaged. Do not combine this argument with the B<-showlog> -flag. +the salvage operation, in addition to the F file +on the server machine. If the file pathname is local, the trace is written +to the specified file on the local disk of the machine where the B command is issued. If the B<-volume> argument is included, the +file can be in AFS, though not in the volume being salvaged. Do not +combine this argument with the B<-showlog> flag. -=item -all +=item B<-all> Salvages all volumes on all of the partitions on the machine named by the B<-server> argument. -=item -showlog +=item B<-showlog> Displays the trace of the salvage operation on the standard output stream, -as well as writing it to the B file. -Do not combine this flag with the B<-file> argument. +as well as writing it to the F file. Do not +combine this flag with the B<-file> argument. -=item -parallel +=item B<-parallel> > Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values: @@ -213,150 +197,139 @@ parallel. Provide one of three values: =item * -An integer from the range B<1> to 32. A value of -B<1> means that a single Salvager process salvages the partitions -sequentially. - +An integer from the range C<1> to C<32>. A value of C<1> means that a +single Salvager process salvages the partitions sequentially. =item * -The string all to run up to four Salvager subprocesses in -parallel on partitions formatted as logical volumes that span multiple -physical disks. Use this value only with such logical volumes. - +The string C to run up to four Salvager subprocesses in parallel on +partitions formatted as logical volumes that span multiple physical +disks. Use this value only with such logical volumes. =item * -The string all followed immediately (with no intervening space) -by an integer from the range B<1> to B<32>, to run the -specified number of Salvager subprocesses in parallel on partitions formatted -as logical volumes. Use this value only with such logical -volumes. - +The string all followed immediately (with no intervening space) by an +integer from the range C<1> to C<32>, to run the specified number of +Salvager subprocesses in parallel on partitions formatted as logical +volumes. Use this value only with such logical volumes. =back The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one process to salvage a single -volume. If this argument is omitted, up to four Salvager subprocesses -run in parallel. +volume. If this argument is omitted, up to four Salvager subprocesses run +in parallel. -=item -tmpdir +=item B<-tmpdir> > Specifies the full pathname of a local disk directory to which the Salvager process writes temporary files as it runs. If this argument is omitted, or specifies an ineligible or nonexistent directory, the Salvager process writes the files to the partition it is currently salvaging. -=item -orphans +=item B<-orphans> (ignore | remove | attach) -Controls how the Salvager handles orphaned files and directories. -Choose one of the following three values: +Controls how the Salvager handles orphaned files and directories. Choose +one of the following three values: =over 4 =item ignore Leaves the orphaned objects on the disk, but prints a message to the -B file reporting how many orphans were found -and the approximate number of kilobytes they are consuming. This is the +F file reporting how many orphans were found and +the approximate number of kilobytes they are consuming. This is the default if the B<-orphans> argument is omitted. =item remove Removes the orphaned objects, and prints a message to the -B file reporting how many orphans were -removed and the approximate number of kilobytes they were consuming. +F file reporting how many orphans were removed +and the approximate number of kilobytes they were consuming. =item attach Attaches the orphaned objects by creating a reference to them in the vnode -of the volume's root directory. Since each object's actual -name is now lost, the Salvager assigns each one a name of the following -form: +of the volume's root directory. Since each object's actual name is now +lost, the Salvager assigns each one a name of the following form: =over 4 +=item * -_ _ORPHANFILE_ _.I for files +C<__ORPHANFILE__.I> for files. +=item * -_ _ORPHANDIR_ _.I for directories +C<__ORPHANDIR__.I> for directories. =back where I is a two-digit number that uniquely identifies each -object. The orphans are charged against the volume's quota and -appear in the output of the B command issued against the -volume's root directory. +object. The orphans are charged against the volume's quota and appear in +the output of the B command issued against the volume's root +directory. =back -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command salvages all volumes on the /vicepd -partition of the machine B: +The following command salvages all volumes on the F partition of +the machine C: % bos salvage -server db3.abc.com -partition /vicepd The following command salvages the volume with volume ID number 536870988 -on partition B of the machine -B: +on partition F of the machine C: % bos salvage -server fs2.abc.com -partition /vicepb -volume 536870988 The following command salvages all volumes on the machine -B. Six Salvager processes run in -parallel rather than the default four. +C. Six Salvager processes run in parallel rather than the +default four. % bos salvage -server fs4.abc.com -all -parallel 6 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, +L, +L, +L, +L, +L, L, L, L, diff --git a/doc/man-pages/pod8/bos_setauth.pod b/doc/man-pages/pod8/bos_setauth.pod index 87e3865be..e1256d794 100644 --- a/doc/man-pages/pod8/bos_setauth.pod +++ b/doc/man-pages/pod8/bos_setauth.pod @@ -4,112 +4,98 @@ bos setauth - Sets authorization checking requirements for all server processes =head1 SYNOPSIS -bos setauth -server > -B<-authrequired> > - [B<-cell> >] [B<-noauth>] [B<-localauth>] [-help] +B B<-server> > B<-authrequired> (on | off) + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -bos seta -s > -B<-a> > - [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-s> > B<-a> (on | off) + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos setauth command enables or disables authorization -checking on the server machine named by the B<-server> -argument. When authorization checking is enabled (the normal case), the -AFS server processes running on the machine verify that the issuer of a -command meets its privilege requirements. When authorization checking -is disabled, server processes perform any action for anyone, including the -unprivileged user B; this security exposure precludes -disabling of authorization checking except during installation or -emergencies. +The B command enables or disables authorization checking on +the server machine named by the B<-server> argument. When authorization +checking is enabled (the normal case), the AFS server processes running on +the machine verify that the issuer of a command meets its privilege +requirements. When authorization checking is disabled, server processes +perform any action for anyone, including the unprivileged user +C; this security exposure precludes disabling of authorization +checking except during installation or emergencies. To indicate to the server processes that authorization checking is disabled, the BOS Server creates the zero-length file -B on its local disk. All AFS server -processes constantly monitor for the B file's presence -and do not check for authorization when it is present. The BOS Server -removes the file when this command is used to reenable authorization -checking. +F on its local disk. All AFS server processes +constantly monitor for the F file's presence and do not check for +authorization when it is present. The BOS Server removes the file when +this command is used to reenable authorization checking. =head1 CAUTIONS -Do not create the NoAuth file directly, except when directed by -instructions for dealing with emergencies (doing so requires being logged in -as the local superuser B). Use this command -instead. +Do not create the F file directly, except when directed by +instructions for dealing with emergencies (doing so requires being logged +in as the local superuser C). Use this command instead. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to enable or disable authorization checking. Identify the machine by IP address or its host name (either -fully-qualified or abbreviated unambiguously). For details, see the -introductory reference page for the B command suite. +fully-qualified or abbreviated unambiguously). For details, see L. -=item -authrequired -> +=item B<-authrequired> (on | off) -Enables authorization checking if the value is on, or disables -it if the value is B. +Enables authorization checking if the value is C, or disables it if +the value is C. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following example disables authorization checking on the machine -B: +C: % bos setauth -server fs7.abc.com -authrequired off =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_setcellname.pod b/doc/man-pages/pod8/bos_setcellname.pod index 34f639077..62371d67c 100644 --- a/doc/man-pages/pod8/bos_setcellname.pod +++ b/doc/man-pages/pod8/bos_setcellname.pod @@ -1,138 +1,119 @@ =head1 NAME -bos setcellname - Sets the cell's name in the /usr/afs/etc/ThisCell and -B files +bos setcellname - Sets the cell's name in ThisCell and CellServDB =head1 SYNOPSIS -B > -name > -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > B<-name> > + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-n> > [B<-c> >] [B<-n>] [B<-l>] [-h] +B B<-s> > B<-n> > + [B<-c> >] [B<-n>] [B<-l>] [-h] =head1 DESCRIPTION -The bos setcellname command establishes the cell's name and -makes the server machine named by the B<-server> argument a member of -it, by recording the value of the B<-name> argument in two files which -it creates on the local disk: +The B command establishes the cell's name and makes the +server machine named by the B<-server> argument a member of it, by +recording the value of the B<-name> argument in two files which it creates +on the local disk: =over 4 =item * -/usr/afs/etc/ThisCell - +F =item * -/usr/afs/etc/CellServDB. The cell name appears on the -first line in the file, preceded by the required C<>> symbol. -The machine name specified with the B<-server> argument appears on the -second line along with its IP address as obtained from the cell's naming -service. The machine is thus designated as the cell's first -database server machine. - +F. The cell name appears on the first line in the +file, preceded by the required C<< > >> symbol. The machine name +specified with the B<-server> argument appears on the second line along +with its IP address as obtained from the cell's naming service. The +machine is thus designated as the cell's first database server machine. =back =head1 CAUTIONS -Issue this command only when the installing the cell's first AFS -server machine. The I explains how to -copy over the B and B files from this or -another appropriate machine during installation of additional server -machines. +Issue this command only when the installing the cell's first AFS server +machine. The I explains how to copy over the +F and F files from this or another appropriate +machine during installation of additional server machines. Be sure to choose a satisfactory cell name when issuing this command, -because changing a cell's name is very complicated; for one thing, -it requires changing every password in the Authentication Database. -Consult the I for advice on choosing a -cell name. If changing the cell's name is absolutely necessary, -contact AFS Product Support for complete instructions. +because changing a cell's name is very complicated; for one thing, it +requires changing every password in the Authentication Database. Consult +the I for advice on choosing a cell name. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine on which to set the cell name in the -B and B file. It is always the -first machine installed in a cell. Identify the machine by IP address -or its host name (either fully-qualified or abbreviated unambiguously). -For details, see the introductory reference page for the B -command suite. +F and F file. It is always the first machine +installed in a cell. Identify the machine by IP address or its host name +(either fully-qualified or abbreviated unambiguously). For details, see +L. -=item -name -> +=item B<-name> > Defines the cell name, using standard Internet domain name format (the -actual domain name is usually appropriate). Examples are -B for the ABC Corporation and -B for the State University. It must match -the value of the B<-cell> argument, if that is provided. +actual domain name is usually appropriate). Examples are C for +the ABC Corporation and C for the State University. It must +match the value of the B<-cell> argument, if that is provided. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command defines the cell name abc.com in -the B and B files on the machine -B as it is installed as the cell's -first server machine. +The following command defines the cell name C in the F +and F files on the machine C as it is installed +as the cell's first server machine. % bos setcellname -server fs1.abc.com -name abc.com =head1 PRIVILEGE REQUIRED -Authorization checking is normally turned off during installation, which is -the only recommended time to use this command; in this case no privilege -is required. If authorization checking is turned on, the issuer must be -listed in the B file on the machine named by -the B<-server> argument, or must be logged in as the local superuser -B if the B<-localauth> flag is included. +Authorization checking is normally turned off during installation, which +is the only recommended time to use this command; in this case no +privilege is required. If authorization checking is turned on, the issuer +must be listed in the F file on the machine named +by the B<-server> argument, or must be logged in as the local superuser +C if the B<-localauth> flag is included. =head1 SEE ALSO -L - -L, -L - -L, -L +L, +L, +L, +L, +L I diff --git a/doc/man-pages/pod8/bos_setrestart.pod b/doc/man-pages/pod8/bos_setrestart.pod index 053675851..2bcaf2673 100644 --- a/doc/man-pages/pod8/bos_setrestart.pod +++ b/doc/man-pages/pod8/bos_setrestart.pod @@ -1,78 +1,72 @@ =head1 NAME -bos setrestart - Sets the date and time at which the BOS Server restarts processes +bos setrestart - Sets when the BOS Server restarts processes =head1 SYNOPSIS -B > -time > -[B<-general>] [B<-newbinary>] [B<-cell> >] - [B<-noauth>] [B<-localauth>] [-help] +B B<-server> > + B<-time> > [B<-general>] [B<-newbinary>] + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-t> > [B<-g>] [-ne] -[B<-c> >] [B<-no>] [B<-l>] [B<-h>] +B B<-s> > B<-t> > + [B<-g>] [B<-ne>] [B<-c> >] [B<-no>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos setrestart command records in the -B file the times at which the BOS Server -running on the server machine named by the B<-server> argument -performs two types of restarts: +The B command records in the F +file the times at which the BOS Server running on the server machine named +by the B<-server> argument performs two types of restarts: =over 4 =item * -A I. By default, once per week the BOS -Server restarts itself and then any AFS process marked with the C -status flag in the B file (equivalent in effect to issuing -the B command with the B<-bosserver> -flag). The default setting is 4:00 a.m. each Sunday -morning. - +A I. By default, once per week the BOS Server restarts +itself and then any AFS process marked with the C status flag in the +F file (equivalent in effect to issuing the B +command with the B<-bosserver> flag). The default setting is 4:00 +a.m. each Sunday morning. =item * -A I. By default, once per day the BOS -Server restarts any currently running process for which the timestamp on the -binary file in the B directory is later than the time -the process last started or restarted. The default is 5:00 -a.m. each day. - +A I. By default, once per day the BOS Server restarts any +currently running process for which the timestamp on the binary file in +the F directory is later than the time the process last +started or restarted. The default is 5:00 a.m. each day. =back =head1 CAUTIONS -Restarting a process makes it unavailable for a period of time. The -B process has potentially the longest outage, depending on how -many volumes the file server machine houses (the File Server and Volume Server -reattach each volume when they restart). The default settings are -designed to coincide with periods of low usage, so that the restarts disturb -the smallest possible number of users. +Restarting a process makes it unavailable for a period of time. The B +process has potentially the longest outage, depending on how many volumes +the file server machine houses (the File Server and Volume Server reattach +each volume when they restart). The default settings are designed to +coincide with periods of low usage, so that the restarts disturb the +smallest possible number of users. -If the setting specified with the -time argument is within one -hour of the current time, the BOS Server does not restart any processes until -the next applicable opportunity (the next day for binary restarts, or the next +If the setting specified with the B<-time> argument is within one hour of +the current time, the BOS Server does not restart any processes until the +next applicable opportunity (the next day for binary restarts, or the next week for general restarts). -The command changes only one type of restart setting at a time; issue -the command twice to change both settings. +The command changes only one type of restart setting at a time; issue the +command twice to change both settings. =head1 OPTIONS =over 4 -=item -server +=item B<-server> > -Indicates the server machine on which to set a new restart time. -Identify the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to set a new restart time. Identify +the machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -time +=item B<-time> > -Specifies the restart time. By convention the general restart is -defined as weekly (specifies both a day and a time), and the binary restart is +Specifies the restart time. By convention the general restart is defined +as weekly (specifies both a day and a time), and the binary restart is defined as daily (specifies only a time). However, it is acceptable to define a daily general restart or weekly binary restart. @@ -82,114 +76,99 @@ There are four acceptable values for either type of restart setting: =item * -The string never, which directs the BOS Server never to perform -the indicated type of restart. - +The string C, which directs the BOS Server never to perform the +indicated type of restart. =item * -The string now, which directs the BOS Server to perform the -restart immediately and never again. - +The string C, which directs the BOS Server to perform the restart +immediately and never again. =item * A time of day (the conventional type of value for the binary restart -time). Separate the hours and minutes with a colon -(I:I), and use either 24-hour format, or a value -in the range from B<1:00> through B<12:59> with -the addition of B or B. For example, both -B<14:30> and B<"2:30 pm"> indicate 2:30 in -the afternoon. Surround this parameter with double quotes (B<" -">) if it contains a space. - +time). Separate the hours and minutes with a colon (I), an use +either 24-hour format, or a value in the range from C<1:00> through +C<12:59> with the addition of C or C. For example, both C<14:30> +and C<"2:30 pm"> indicate 2:30 in the afternoon. Surround this parameter +with double quotes (C<"">) if it contains a space. =item * A day of the week and time of day, separated by a space and surrounded -with double quotes (B<" ">). This is the conventional type of -value for the general restart. For the day, provide either the whole -name or the first three letters, all in lowercase letters (B -or B, B or B, and so on). -For the time, use the same format as when specifying the time alone. - +with double quotes (C<"">). This is the conventional type of value for the +general restart. For the day, provide either the whole name or the first +three letters, all in lowercase letters (C or C, C +or C, and so on). For the time, use the same format as when +specifying the time alone. =back If desired, precede a time or day and time definition with the string -B or B. These words do not change the -meaning, but possibly make the output of the B command -easier to understand. +C or C. These words do not change the meaning, but possibly +make the output of the B command easier to understand. -=item -general -> +=item B<-general> Sets the general restart time. -=item -newbinary -> +=item B<-newbinary> Sets the binary restart time. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command sets the general restart time on the machine -B to Saturday at 3:30 am. +C to Saturday at 3:30 am. % bos setrestart -server fs4.abc.com -time "sat 3:30" -general The following command sets the binary restart time on the machine -B to 11:45 pm. +C to 11:45 pm. % bos setrestart -server fs6.abc.com -time 23:45 -newbinary =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_shutdown.pod b/doc/man-pages/pod8/bos_shutdown.pod index 514897c5a..a1d92d492 100644 --- a/doc/man-pages/pod8/bos_shutdown.pod +++ b/doc/man-pages/pod8/bos_shutdown.pod @@ -1,136 +1,122 @@ =head1 NAME -bos shutdown - Stops a process without changing its status flag in the -B file +bos shutdown - Stops a process without changing its status flag =head1 SYNOPSIS -B > [B<-instance> >+] [-wait] -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > + [B<-instance> >+] [B<-wait>] [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > [B<-i> >+] [-w] -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > [B<-i> >+] [B<-w>] + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos shutdown command stops, on the server machine named by -the B<-server> argument, either +The B command stops, on the server machine named by the +B<-server> argument, either =over 4 =item * -All of the currently running AFS server processes, except the BOS Server - +All of the currently running AFS server processes, except the BOS Server. =item * -Only the processes specified by the -instance argument - +Only the processes specified by the B<-instance> argument. =back This command does not change a process's status flag in the -B file, but only in the BOS Server's -memory. To stop a process and change its B status -flag, use the B command instead. +F file, but only in the BOS Server's memory. To +stop a process and change its F status flag, use the B command instead. Once stopped with this command, a process does not run again until an -administrator starts it by using the B, B, or B command, or until the BOS Server -restarts (assuming that the process's B status flag is -C). +administrator starts it by using the B, B, or +B command, or until the BOS Server restarts (assuming that +the process's F status flag is C). =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine on which to stop processes. Identify -the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to stop processes. Identify the +machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -instance -> +=item B<-instance> >+ Names each process to stop. Use the process name assigned with the -B<-instance> argument to the B command. The -output from the B command lists the names. Omit -this argument to stop all processes other than the BOS Server. +B<-instance> argument to the B command. The output from the +B command lists the names. Omit this argument to stop all +processes other than the BOS Server. -=item -wait -> +=item B<-wait> Delays the return of the command shell prompt until all processes actually -stop. If this argument is omitted, the prompt returns almost -immediately even if all processes are not stopped. +stop. If this argument is omitted, the prompt returns almost immediately +even if all processes are not stopped. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command stops all processes other than the BOS Server on the -machine B. +machine C. % bos shutdown fs3.abc.com -The following command stops the upserver process (server portion -of the Update Server) on the machine -B. +The following command stops the C process (server portion of the +Update Server) on the machine C. % bos shutdown -server fs5.abc.com -instance upserver =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_start.pod b/doc/man-pages/pod8/bos_start.pod index 57218a8c9..36f7d0e76 100644 --- a/doc/man-pages/pod8/bos_start.pod +++ b/doc/man-pages/pod8/bos_start.pod @@ -1,106 +1,94 @@ =head1 NAME -bos start - Starts a process after setting its status flag in the -B file +bos start - Starts a process after setting its status flag =head1 SYNOPSIS -B > -instance >+ -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > + B<-instance> >+ [B<-cell> >] + [B<-noauth>] [B<-localauth>] [B<-help>] -B > -i >+ -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-i> >+ + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos start command sets the status flag for each process -specified by the B<-instance> argument to C in the -B file and in the BOS Server's memory -on the server machine named by the B<-server> argument, then starts -it. If the process is already running, the command's only effect -is to guarantee that the status flag is C; it does not -restart the process. +The B command sets the status flag for each process specified +by the B<-instance> argument to C in the F +file and in the BOS Server's memory on the server machine named by the +B<-server> argument, then starts it. If the process is already running, +the command's only effect is to guarantee that the status flag is C; +it does not restart the process. -To start a process without changing its status flag in the -B file, use the B command -instead. +To start a process without changing its status flag in the F +file, use the B command instead. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine on which to start processes. Identify -the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to start processes. Identify the +machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -instance -> +=item B<-instance> >+ Names each process to start. Use the process name assigned with the -B<-instance> argument to the B command. The -output from the B command lists the names. +B<-instance> argument to the B command. The output from the +B command lists the names. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command changes the status flag for the -B and B processes to C -in the B file on the machine -B and starts them running. +The following command changes the status flag for the C and +C processes to C in the F file on the machine +C and starts them running. % bos start -server fs6.abc.com -instance upclientbin upclientetc =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_startup.pod b/doc/man-pages/pod8/bos_startup.pod index c81dc655c..70f795e81 100644 --- a/doc/man-pages/pod8/bos_startup.pod +++ b/doc/man-pages/pod8/bos_startup.pod @@ -1,122 +1,110 @@ =head1 NAME -bos startup - Starts a process without changing its status flag in the -B file +bos startup - Starts a process without changing its status flag =head1 SYNOPSIS -B > [-instance >+] -[B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > [B<-instance> >+] + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > [-i >+] -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > [B<-i> >+] + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos startup command starts, on the server machine named by -the B<-server> argument, either +The B command starts, on the server machine named by the +B<-server> argument, either: =over 4 =item * -All AFS server processes not currently running but marked with the -C status flag in the B file - +All AFS server processes not currently running but marked with the C +status flag in the F file. =item * -Each process specified by -instance argument, even if its -status flag in the B file is C. - +Each process specified by B<-instance> argument, even if its status flag +in the B file is C. =back -To start a process and set its BosConfig status flag to -C, use the B command instead. +To start a process and set its F status flag to C, use the +B command instead. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine on which to start processes. Identify -the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to start processes. Identify the +machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -instance -> +=item B<-instance> >+ Names each process to start. Use the process name assigned with the -B<-instance> argument to the B command. The -output from the B command lists the names. +B<-instance> argument to the B command. The output from the +B command lists the names. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command starts all processes marked with status flag -C in the B file on the machine -B that are not currently running. +The following command starts all processes marked with status flag C +in the F file on the machine C that are not +currently running. % bos startup fs3.abc.com -The following command starts the B, kaserver, -B, and B processes running on the machine -B, even if their status flags in the -B file are C. +The following command starts the B, B, B, +and B processes running on the machine C, even if +their status flags in the F file are C. - % bos startup -server db2.abc.com -instance buserver kaserver ptserver vlserver + % bos startup -server db2.abc.com \ + -instance buserver kaserver ptserver vlserver =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_status.pod b/doc/man-pages/pod8/bos_status.pod index 24a9eed9b..bd6edef1f 100644 --- a/doc/man-pages/pod8/bos_status.pod +++ b/doc/man-pages/pod8/bos_status.pod @@ -20,30 +20,25 @@ server machine named by the B<-server> argument, either =item * All of the AFS server processes listed in the -B file - +F file =item * Only these processes named by the -instance argument - =back =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the server machine for which to report server process status. Identify the machine by IP address or its host name (either -fully-qualified or abbreviated unambiguously). For details, see the -introductory reference page for the B command suite. +fully-qualified or abbreviated unambiguously). For details, see L. =item -instance -> Names each process for which to report status. Use the process name assigned with the B<-instance> argument to the B @@ -51,36 +46,29 @@ command. The output from the B command lists the names. =item -long -> Produces more detailed status information. -=item -cell -> +=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 B reference page. +argument with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the +Assigns the unprivileged identity C to the issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +flag. For more details, see L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command +F file. The B command interpreter presents the ticket to the BOS Server during mutual authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +B<-noauth> options. For more details, see L. -=item -help +=item B<-help> Prints the online help for this command. All other valid options are ignored. @@ -102,13 +90,11 @@ B entries, this message indicates only that the command is scheduled to run, not necessarily that it was executing when the B command was issued. - =item * C. The process is not running, and its B status flag is C. - =item * C. The process is not running @@ -116,21 +102,18 @@ although its status flag in the B file is C. Either an administrator used the B command to stop it, or the - =item * BOS Server stopped trying to restart it after numerous failed attempts. In the second case, the auxiliary message is C. - =item * C. The process is running although its status flag in the B file is C. An administrator has used the B command to start it. - =back If one of the following special circumstances applies to the process, the @@ -141,18 +124,16 @@ indicated message appears in its entry: =item * C. The process failed and created a core -file in the B directory. If the BOS Server was +file in the F directory. If the BOS Server was able to restart the process after the failure, the primary status is C. - =item * C. The reason for the primary status C is that the BOS Server's attempts to restart the process all failed. - =back The entry for the fs process always includes a second line to @@ -166,14 +147,12 @@ following: C. The File Server and Volume Server components of the File Server process are running normally. - =item * C. The Salvager is running, so the File Server and Volume Server are temporarily disabled. The BOS Server restarts them as soon as the Salvager is finished. - =back The entry for a cron process includes an C, C, or C). - =item * The day and time the process last started or restarted. - =item * The number of C, which is how many times the BOS Server has started or restarted the process since it started itself. - =item * The C time when the process (or one of the component @@ -208,7 +184,6 @@ processes in the B process) last terminated. This line does not appear if the process has not terminated since the BOS Server started. - =item * The C time when the process (or one of the @@ -217,25 +192,22 @@ error. A further explanation such as C sometimes appears. This line does not appear if the process has not failed since the BOS Server started. - =item * Each command that the BOS Server invokes to start the process, as specified by the B<-cmd> argument to the B command. - =item * The pathname of the notifier program that the BOS Server invokes when the process terminates (if any), as specified by the B<-notifier> argument to the B command. - =back If the -long flag is provided and the BOS Server discovers that -the mode bits on files and subdirectories in the local B +the mode bits on files and subdirectories in the local F directory differ from the expected values, it prints the following warning message: @@ -285,11 +257,11 @@ None L, L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_stop.pod b/doc/man-pages/pod8/bos_stop.pod index cef0894ee..fa1b48b90 100644 --- a/doc/man-pages/pod8/bos_stop.pod +++ b/doc/man-pages/pod8/bos_stop.pod @@ -1,107 +1,97 @@ =head1 NAME -bos stop - Stops a process after changing its status flag in the -B file +bos stop - Stops a process after changing its status flag =head1 SYNOPSIS -B > -instance >+ -[B<-wait>] [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] +B B<-server> > + B<-instance> >+ [B<-wait>] + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > -i >+ -[B<-w>] [B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-i> >+ + [B<-w>] [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The bos stop command sets the status flag for each process -specified with the B<-instance> argument to C in the -B file on the server machine named by the +The B command sets the status flag for each process specified +with the B<-instance> argument to C in the +F file on the server machine named by the B<-server> argument, then stops it. -To stop a process without changing its BosConfig status flag, -use the B command instead. +To stop a process without changing its F status flag, use the +B command instead. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > -Indicates the server machine on which to stop processes. Identify -the machine by IP address or its host name (either fully-qualified or -abbreviated unambiguously). For details, see the introductory reference -page for the B command suite. +Indicates the server machine on which to stop processes. Identify the +machine by IP address or its host name (either fully-qualified or +abbreviated unambiguously). For details, see L. -=item -instance -> +=item B<-instance> >+ Names each process to stop. Use the process name assigned with the -B<-instance> argument to the B command. The -output from the B command lists the names. +B<-instance> argument to the B command. The output from the +B command lists the names. -=item -wait -> +=item B<-wait> Delays the return of the command shell prompt until all processes actually -stop. If this argument is omitted, the prompt returns almost -immediately even if all processes are not stopped. +stop. If this argument is omitted, the prompt returns almost immediately +even if all processes are not stopped. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example command stops the upserver and -B on the machine B. +The following example command stops the B and B +processes on the machine C. % bos stop -server fs7.abc.com -instance upserver runntp =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bos_uninstall.pod b/doc/man-pages/pod8/bos_uninstall.pod index 8c9725e01..636f8409c 100644 --- a/doc/man-pages/pod8/bos_uninstall.pod +++ b/doc/man-pages/pod8/bos_uninstall.pod @@ -4,120 +4,107 @@ bos uninstall - Reverts to the former version of a process's binary file =head1 SYNOPSIS -B > -file >+ -[B<-dir> >] [B<-cell> >] - [B<-noauth>] [B<-localauth>] [-help] +B B<-server> > + B<-file> >+ [B<-dir> >] + [B<-cell> >] [B<-noauth>] [B<-localauth>] [B<-help>] -B > B<-f> >+ [-d >] -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B B<-s> > B<-f> >+ + [B<-d> >] [B<-c> >] [B<-n>] [B<-l>] + [B<-h>] =head1 DESCRIPTION -The bos uninstall command replaces each binary file specified by -the B<-file> argument with its C<.BAK>version on the -server machine named by the B<-server> argument, which is normally the -binary distribution machine for its CPU/operating system type. It also -changes the extension on the current C<.OLD> version (if any) -to C<.BAK>. Each binary file must reside in the local -B directory unless the B<-dir> argument names an -alternate directory. - -To start using the reverted binary immediately, issue the bos -restart command. Otherwise, the BOS Server automatically restarts -the process at the time defined in the B -file; use the B command to display the time and -the B time to set it. +The B command replaces each binary file specified by the +B<-file> argument with its C<.BAK> version on the server machine named by +the B<-server> argument, which is normally the binary distribution machine +for its CPU/operating system type. It also changes the extension on the +current C<.OLD> version (if any) to C<.BAK>. Each binary file must reside +in the local F directory unless the B<-dir> argument names +an alternate directory. + +To start using the reverted binary immediately, issue the B +command. Otherwise, the BOS Server automatically restarts the process at +the time defined in the F file; use the B command to display the time and the B time to +set it. =head1 OPTIONS =over 4 -=item -server -> +=item B<-server> > Indicates the binary distribution machine on which to revert to the -C<.BAK> version of binaries. Identify the machine by IP -address or its host name (either fully-qualified or abbreviated -unambiguously). For details, see the introductory reference page for -the B command suite. +C<.BAK> version of binaries. Identify the machine by IP address or its +host name (either fully-qualified or abbreviated unambiguously). For +details, see L. If the machine is not a binary distribution machine and is running an -B process, then the files are overwritten the next time -the B process fetches the corresponding file from the +C process, then the files are overwritten the next time the +C process fetches the corresponding file from the distribution machine (by default within five minutes). -=item -file -> +=item B<-file> >+ -Names each binary file to replace with its C<.BAK> -version. +Names each binary file to replace with its C<.BAK> version. -=item -dir -> +=item B<-dir> > Provides the complete pathname of the local disk directory containing each -file named by the B<-file> argument. It is necessary only if -the binaries are not in the B directory. +file named by the B<-file> argument. It is necessary only if the binaries +are not in the F directory. -=item -cell -> +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -noauth -> +=item B<-noauth> -Assigns the unprivileged identity anonymous to the -issuer. Do not combine this flag with the B<-localauth> -flag. For more details, see the introductory B reference -page. +Assigns the unprivileged identity C to the issuer. Do not +combine this flag with the B<-localauth> flag. For more details, see +L. -=item -localauth -> +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B command -interpreter presents the ticket to the BOS Server during mutual -authentication. Do not combine this flag with the B<-cell> or -B<-noauth> options. For more details, see the introductory -B reference page. +F file. The B command interpreter presents the +ticket to the BOS Server during mutual authentication. Do not combine this +flag with the B<-cell> or B<-noauth> options. For more details, see +L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example command overwrites the -B file on the machine -B with its C<.BAK>version, -and the current C<.BAK> version by the -C<.OLD>version. +The following example command overwrites the F file +on the machine C with its C<.BAK> version, and the current +C<.BAK> version by the C<.OLD> version. % bos uninstall -server fs4.abc.com -file kaserver =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -the machine named by the B<-server> argument, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on the +machine named by the B<-server> argument, or must be logged onto a server +machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/bosserver.pod b/doc/man-pages/pod8/bosserver.pod index 721c0f6ac..6296af0a1 100644 --- a/doc/man-pages/pod8/bosserver.pod +++ b/doc/man-pages/pod8/bosserver.pod @@ -4,18 +4,14 @@ bosserver - Initializes the BOS Server =head1 SYNOPSIS -B [B<-noauth>] [B<-log>] [B<-enable_peer_stats>] [-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. +B [B<-noauth>] [B<-log>] [B<-enable_peer_stats>] + [B<-enable_process_stats>] [B<-help>] =head1 DESCRIPTION -The bosserver command initializes the Basic OverSeer (BOS) -Server (B process). In the conventional -configuration, the binary file is located in the B -directory on a file server machine. +The bosserver command initializes the Basic OverSeer (BOS) Server +(B process). In the conventional configuration, the binary file +is located in the F directory on a file server machine. The BOS Server must run on every file server machine and helps to automate file server administration by performing the following tasks: @@ -27,85 +23,78 @@ file server administration by performing the following tasks: Monitors the other AFS server processes on the local machine, to make sure they are running correctly. - =item * Automatically restarts failed processes, without contacting a human operator. When restarting multiple server processes simultaneously, the -BOS Server takes interdependencies into account and initiates restarts in the -correct order. -L<(1)> -L<(1)> - +BOS Server takes interdependencies into account and initiates restarts in +the correct order. =item * -Processes commands from the bos suite that administrators issue -to verify the status of server processes, install and start new processes, -stop processes either temporarily or permanently, and restart halted -processes. - +Processes commands from the bos suite that administrators issue to verify +the status of server processes, install and start new processes, stop +processes either temporarily or permanently, and restart halted processes. =item * -Manages system configuration information: the files that list the -cell's server encryption keys, database server machines, and users -privileged to issue commands from the B and B -suites. - +Manages system configuration information: the files that list the cell's +server encryption keys, database server machines, and users privileged to +issue commands from the B and B suites. =back The BOS Server logs a default set of important events in the file -B. To record the name of any user who -performs a privileged B command (one that requires being listed -in the B file), add the B<-log> -flag. To display the contents of the B file, use the -B command. +F. To record the name of any user who performs a +privileged B command (one that requires being listed in the +F file), add the B<-log> flag. To display the +contents of the B file, use the B command. The first time that the BOS Server initializes on a server machine, it -creates several files and subdirectories in the local B +creates several files and subdirectories in the local F directory, and sets their mode bits to protect them from unauthorized -access. Each time it restarts, it checks that the mode bits still -comply with the settings listed in the following chart. A question mark -indicates that the BOS Server initially turns off the bit (sets it to the -hyphen), but does not check it at restart. +access. Each time it restarts, it checks that the mode bits still comply +with the settings listed in the following chart. A question mark indicates +that the BOS Server initially turns off the bit (sets it to the hyphen), +but does not check it at restart. -If the mode bits do not comply, the BOS Server writes the following warning -to the B file: +If the mode bits do not comply, the BOS Server writes the following +warning to the F file: Bosserver reports inappropriate access on server directories However, the BOS Server does not reset the mode bits, so the administrator -can set them to alternate values if desired (with the understanding that the -warning message then appears at startup). +can set them to alternate values if desired (with the understanding that +the warning message then appears at startup). + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. =head1 OPTIONS =over 4 -=item -noauth +=item B<-noauth> -Assigns the unprivileged identity anonymous to the issuer, -which is useful only when authorization checking is disabled on the server -machine (for instance, during the installation of a file server -machine.) +Assigns the unprivileged identity C to the issuer, which is +useful only when authorization checking is disabled on the server machine +(for instance, during the installation of a file server machine.) -=item -log +=item B<-log> -Records in the /usr/afs/logs/BosLog file the names of all users -who successfully issue a privileged B command (one that requires -being listed in the B file). +Records in the F file the names of all users who +successfully issue a privileged B command (one that requires being +listed in the F file). -=item -enable_peer_stats +=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. +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 -enable_process_stats +=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, @@ -113,10 +102,10 @@ 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 -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -129,24 +118,24 @@ users who issue privileged B commands. =head1 PRIVILEGE REQUIRED -The issuer most be logged onto a file server machine as the local superuser -B. +The issuer most be logged onto a file server machine as the local +superuser C. =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 =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/buserver.pod b/doc/man-pages/pod8/buserver.pod index 336e4c1be..8c986207e 100644 --- a/doc/man-pages/pod8/buserver.pod +++ b/doc/man-pages/pod8/buserver.pod @@ -4,110 +4,104 @@ buserver - Initializes the Backup Server =head1 SYNOPSIS -B [-database >] -[B<-cellservdb> >] - [B<-resetdb>] [B<-noauth>] [-smallht] - [-servers >+] - [B<-enable_peer_stats>] [-enable_process_stats] - [-help] - -This command does not use the syntax conventions of the AFS command -suites. Provide the command name and all option names in full. +B [B<-database> >] + [B<-cellservdb> >] [B<-resetdb>] + [B<-noauth>] [B<-smallht>] [-servers >+] + [B<-enable_peer_stats>] [-enable_process_stats] [B<-help>] =head1 DESCRIPTION -The buserver command initializes the Backup Server, which runs -on database server machines and maintains the Backup Database. In the +The B command initializes the Backup Server, which runs on +database server machines and maintains the Backup Database. In the conventional configuration, the binary file is located in the -B directory on a file server machine. +F directory on a file server machine. -The buserver command is not normally issued at the command shell +The B command is not normally issued at the command shell prompt, but rather placed into a database server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a file server machine as the local superuser -B. +F file with the B command. If it is +ever issued at the command shell prompt, the issuer must be logged onto a +file server machine as the local superuser C. As it initializes, the Backup Server process creates the two files that -constitute the Backup Database, B and -B, in the B directory if they -do not already exist. The Backup Database houses information about -volume sets and entries, the dump hierarchy, Tape Coordinators, and previously -performed dump sets. Use the commands in the B suite to -administer the database. +constitute the Backup Database, F and F, in the +F directory if they do not already exist. The Backup Database +houses information about volume sets and entries, the dump hierarchy, Tape +Coordinators, and previously performed dump sets. Use the commands in the +B suite to administer the database. The Backup Server records a trace of its activity in the -B file. Use the B -command to display the contents of the file. +F file. Use the B command to display +the contents of the file. + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. =head1 CAUTIONS -The B process reserves port 7021 for its -use. Unexpected behavior can occur if another process tries to reserve -this port while the B process is running. +The B process reserves port 7021 for its use. Unexpected +behavior can occur if another process tries to reserve this port while the +B process is running. =head1 OPTIONS =over 4 -=item -database +=item B<-database> > Specifies the pathname of an alternate directory for the Backup Database -files, ending in a final slash (B). If this argument is not -provided, the default is the B directory. +files, ending in a final slash (C). If this argument is not provided, +the default is the F directory. -=item -cellservdb +=item B<-cellservdb> > Specifies the pathname of the directory from which the Backup Server reads -in an alternate version of the B file. This -argument is mandatory for correct functioning when the Backup Server is -running on a subset of the cell's database server machines that is not a -majority of the machines listed in the standard -B file (which the Backup Server consults if -this argument is not provided). It is not appropriate in any other -circumstances. +in an alternate version of the F file. This argument is +mandatory for correct functioning when the Backup Server is running on a +subset of the cell's database server machines that is not a majority of +the machines listed in the standard F file (which +the Backup Server consults if this argument is not provided). It is not +appropriate in any other circumstances. -=item -resetdb +=item B<-resetdb> Removes all of the information in the Backup Database files in the -B directory, leaving zero-length versions of them. -The backup operator must recreate the configuration entries in the database +F directory, leaving zero-length versions of them. The +backup operator must recreate the configuration entries in the database (for volume sets, the dump hierarchy and so on) before performing backup operations. -=item -noauth +=item B<-noauth> Establishes an unauthenticated connection between the issuer and the Backup Server, in which the Backup Server treats the issuer as the -unprivileged user B. It is useful only when -authorization checking is disabled on the database server machine. In -normal circumstances, the Backup Server allows only authorized (privileged) -users to issue commands that affect or contact the Backup Database, and -refuses to perform such an action even if the B<-noauth> flag is -used. +unprivileged user C. It is useful only when authorization +checking is disabled on the database server machine. In normal +circumstances, the Backup Server allows only authorized (privileged) users +to issue commands that affect or contact the Backup Database, and refuses +to perform such an action even if the B<-noauth> flag is used. -=item -smallht +=item B<-smallht> Directs the Backup Server to use smaller internal hash tables for the -Backup Database, which reduces memory requirements but can make data access -take longer. +Backup Database, which reduces memory requirements but can make data +access take longer. -=item -servers +=item B<-servers> >+ Specifies the database server machines on which to start the Backup -Server. Use this argument if running the Backup Server on a subset of -the database server machines that is not a majority of the machines listed in -the B file. +Server. Use this argument if running the Backup Server on a subset of the +database server machines that is not a majority of the machines listed in +the F file. -=item -enable_peer_stats +=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. +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 -enable_process_stats +=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, @@ -115,41 +109,38 @@ 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 -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example bos create command creates a -B process on the file server machine -B. It appears here on two lines only -for legibility. +The following example B command creates a C process +on the file server machine C. It appears here on two lines +only for legibility. - % bos create -server fs3.abc.com -instance buserver \ + % bos create -server fs3.abc.com -instance buserver \ -type simple -cmd /usr/afs/bin/buserver =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the superuser root on a file -server machine to issue the command at a command shell prompt. It is -conventional instead to create and start the process by issuing the B command. +The issuer must be logged in as the superuser C on a file server +machine to issue the command at a command shell prompt. It is conventional +instead to create and start the process by issuing the B +command. =head1 SEE ALSO -L, -L, -L - -L - -L, -L, -L +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/butc.pod b/doc/man-pages/pod8/butc.pod index 27396e990..dc386c41f 100644 --- a/doc/man-pages/pod8/butc.pod +++ b/doc/man-pages/pod8/butc.pod @@ -4,86 +4,77 @@ butc - Initializes the Tape Coordinator process =head1 SYNOPSIS -B [B<-port> >] [B<-debuglevel> < B<0> | B<1> | 2 >] -[B<-cell> >] [B<-noautoquery>] - [B<-localauth>] [-help] +B [B<-port> >] [B<-debuglevel> (0 | 1 | 2)] + [B<-cell> >] [B<-noautoquery>] [B<-localauth>] [B<-help>] -B [B<-p> >] [B<-d> < B<0> | B<1> | 2 >] -[B<-c> >] [B<-n>] [B<-l>] [B<-h>] +B [B<-p> >] [B<-d> (0 | 1 | 2)] + [B<-c> >] [B<-n>] [B<-l>] [B<-h>] =head1 DESCRIPTION -The butc command initializes a Tape Coordinator process on a -Tape Coordinator machine, enabling an operator to direct Backup System -requests to the associated tape device or backup data file. (The Tape -Coordinator controls a backup data file if the B instruction -appears in the BI file that -corresponds to the Tape Coordinator's entry in the -B file. For the sake of simplicity, -the following discusses tape devices only.) +The B command initializes a Tape Coordinator process on a Tape +Coordinator machine, enabling an operator to direct Backup System requests +to the associated tape device or backup data file. (The Tape Coordinator +controls a backup data file if the C instruction appears in the +F> file that corresponds to the Tape +Coordinator's entry in the F file. For the +sake of simplicity, the following discusses tape devices only.) It is conventional to start and run the Tape Coordinator in the foreground. In this case, it runs on its own connection, which is -unavailable for any other use and must remain open the entire time the Tape -Coordinator is to accept backup requests and while it is executing +unavailable for any other use and must remain open the entire time the +Tape Coordinator is to accept backup requests and while it is executing them. (When using a window manager, the connection corresponds to a separate command shell window.) The Tape Coordinator can run in the -background if the BI file is configured to -eliminate any need for the Tape Coordinator to prompt the operator. In -both the foreground and background, the Tape Coordinator writes operation -traces and other output to the standard output stream on the connection over -which it was started. Use the B<-debuglevel> argument to -control the amount of information that appears. The Tape Coordinator -also writes traces and error messages to two files in the local -B directory: +background if the F> file is configured to eliminate +any need for the Tape Coordinator to prompt the operator. In both the +foreground and background, the Tape Coordinator writes operation traces +and other output to the standard output stream on the connection over +which it was started. Use the B<-debuglevel> argument to control the +amount of information that appears. The Tape Coordinator also writes +traces and error messages to two files in the local F +directory: =over 4 =item * -The TE_I file records problems that the Tape -Coordinator encounters as it executes backup operations. - +The F> file records problems that the Tape Coordinator +encounters as it executes backup operations. =item * -The TL_I file records a trace of operations -as well as the same errors written to the BI -file. - +The F> file records a trace of operations as well as the +same errors written to the F> file. =back -The Tape Coordinator creates the files automatically as it -initializes. If there are existing files, the Tape Coordinator renames -them with a B<.old> extension, overwriting the existing -B<.old> files if they exist. It derives the -I part of the file names by stripping off the device -name's B prefix and replacing any other slashes with -underscores. For example, the files are called B and -B for a device called B. - -By default, at the beginning of each operation the Tape Coordinator prompts -for the operator to insert the first tape into the drive and press ->. To suppress this prompt, include the -B<-noautoquery> flag on the command line or the instruction -B in the -BI file. When the -prompt is suppressed, the first required tape must be in the drive before a -B command is issued. For subsequent tapes, the Tape -Coordinator uses its normal tape acquisition routine: if the -BI file includes a -B instruction, the Tape Coordinator invokes the indicated -command; otherwise, it prompts the operator for the next tape. +The Tape Coordinator creates the files automatically as it initializes. If +there are existing files, the Tape Coordinator renames them with a C<.old> +extension, overwriting the existing C<.old> files if they exist. It +derives the I part of the file names by stripping off the +device name's F prefix and replacing any other slashes with +underscores. For example, the files are called F and +F for a device called F. + +By default, at the beginning of each operation the Tape Coordinator +prompts for the operator to insert the first tape into the drive and press +Return. To suppress this prompt, include the B<-noautoquery> flag on the +command line or the instruction C in the +F> file. When the prompt is suppressed, +the first required tape must be in the drive before a B command is +issued. For subsequent tapes, the Tape Coordinator uses its normal tape +acquisition routine: if the F> file +includes a C instruction, the Tape Coordinator invokes the +indicated command; otherwise, it prompts the operator for the next tape. To stop the Tape Coordinator process, enter an interrupt signal such as -> over the dedicated connection (in the command shell -window). +Ctrl-C over the dedicated connection (in the command shell window). -To cancel a backup operation that involves a tape before it -begins (assuming the initial tape prompt has not been suppressed), enter the -letter B (for B) and press > at -the Tape Coordinator's prompt for the first tape. +To cancel a backup operation that involves a tape before it begins +(assuming the initial tape prompt has not been suppressed), enter the +letter C (for C) and press Return at the Tape Coordinator's +prompt for the first tape. Tape Coordinator operation depends on the correct configuration of certain files, as described in the following list: @@ -92,145 +83,128 @@ files, as described in the following list: =item * -The local /usr/afs/backup/tapeconfig file must include an entry -for the Tape Coordinator that specifies its device name and port offset -number, among other information; for details, see the -B reference page. - +The local F file must include an entry for the +Tape Coordinator that specifies its device name and port offset number, +among other information; for details, L. =item * -The port offset number recorded in the Tape Coordinator's entry in -the Backup Database must match the one in the B -file. Create the Backup Database entry by using the B command. - +The port offset number recorded in the Tape Coordinator's entry in the +Backup Database must match the one in the F file. Create the +Backup Database entry by using the B command. =item * -The optional /usr/afs/backup/CFG_I file can -contain instructions for mounting and unmounting tapes automatically (when -using a tape stacker or jukebox, for instance) or automating other aspects of -the backup process. The I part of the name is -derived as described previously for the BI and -BI files. - +The optional F> file can contain +instructions for mounting and unmounting tapes automatically (when using a +tape stacker or jukebox, for instance) or automating other aspects of the +backup process. The I part of the name is derived as +described previously for the F> and F> +files. =back =head1 CAUTIONS -If the Tape Coordinator machine is an AIX machine, use the SMIT -utility to set the device's block size to 0 (zero), indicating variable -block size. Otherwise, tape devices attached to machines running other -operating systems sometimes cannot read tapes written on AIX machines. -For instructions, see the I chapter -about configuring the Backup System. +If the Tape Coordinator machine is an AIX machine, use the SMIT utility to +set the device's block size to 0 (zero), indicating variable block +size. Otherwise, tape devices attached to machines running other operating +systems sometimes cannot read tapes written on AIX machines. For +instructions, see the I chapter about +configuring the Backup System. =head1 OPTIONS =over 4 -=item -port +=item B<-port> > -Specifies the port offset number of the Tape Coordinator to -initialize. +Specifies the port offset number of the Tape Coordinator to initialize. -=item -debuglevel +=item B<-debuglevel> Controls the amount and type of messages the Tape Coordinator displays on -the standard output stream. Provide one of three acceptable -values: +the standard output stream. Provide one of three acceptable values: =over 4 =item * -0 to display the minimum level of detail required to describe -Tape Coordinator operations, including prompts for tapes, messages that -indicate the beginning and end of operations, and error messages. This -is the default value. - +C<0> to display the minimum level of detail required to describe Tape +Coordinator operations, including prompts for tapes, messages that +indicate the beginning and end of operations, and error messages. This is +the default value. =item * -1 to display the names of the volumes being dumped or restored -as well as the information displayed at level 0. - +C<1> to display the names of the volumes being dumped or restored as well +as the information displayed at level C<0>. =item * -2 to display all messages also being written to the -BI log file. - +C<2> to display all messages also being written to the +F> log file. =back -=item -cell +=item B<-cell> > Names the cell in which the Tape Coordinator operates (the cell to which the file server machines that house affected volumes belong). If this -argument is omitted, the Tape Coordinator runs in the local cell as defined in -the local B file. Do not combine this +argument is omitted, the Tape Coordinator runs in the local cell as +defined in the local F file. Do not combine this flag with the B<-localauth> argument. -=item -noautoquery +=item B<-noautoquery> -Suppresses the Tape Coordinator's prompt for insertion of the first -tape needed for an operation. The operator must insert the tape into -the drive before issuing the B command that initializes the -operation. +Suppresses the Tape Coordinator's prompt for insertion of the first tape +needed for an operation. The operator must insert the tape into the drive +before issuing the B command that initializes the operation. -=item -localauth +=item B<-localauth> Constructs a server ticket using the server encryption key with the -highest key version number in the local -B. The B command -interpreter presents the ticket, which never expires, to the Volume Server and -Volume Location Server to use in mutual authentication. +highest key version number in the local F. The +B command interpreter presents the ticket, which never expires, to +the Volume Server and Volume Location Server to use in mutual +authentication. -Do not combine this argument with the -cell flag, and use it -only when logged on to a server machine as the local superuser -B; client machines do not have -B file. +Do not combine this argument with the B<-cell> flag, and use it only when +logged on to a server machine as the local superuser C; client +machines do not have F file. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command starts the Tape Coordinator with port offset -B<7> at debug level B<1>, meaning the Tape Coordinator reports -the names of volumes it is dumping or restoring. +The following command starts the Tape Coordinator with port offset C<7> at +debug level C<1>, meaning the Tape Coordinator reports the names of +volumes it is dumping or restoring. % butc -port 7 -debuglevel 1 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server or Volume Location (VL) Server is -running, and on every file server machine that houses a volume to be backed -up. If the B<-localauth> flag is included, the issuer must -instead be logged on to the Tape Coordinator machine as the local superuser -B In addition, the issuer must be able to read and write -to the log and configuration files in the local B -directory. +The issuer must be listed in the F file on every +machine where the Backup Server or Volume Location (VL) Server is running, +and on every file server machine that houses a volume to be backed up. If +the B<-localauth> flag is included, the issuer must instead be logged on +to the Tape Coordinator machine as the local superuser C. In +addition, the issuer must be able to read and write to the log and +configuration files in the local F directory. =head1 SEE ALSO -L(1)>, -L, -L(1)>, -L - -L(1)>, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/fileserver.pod b/doc/man-pages/pod8/fileserver.pod index 57793614b..5cfc909fc 100644 --- a/doc/man-pages/pod8/fileserver.pod +++ b/doc/man-pages/pod8/fileserver.pod @@ -4,92 +4,75 @@ fileserver - Initializes the File Server component of the fs process =head1 SYNOPSIS -B [B<-d> >] [-p >] -[B<-spare> >] - [B<-pctspare> >] [-b >] - [B<-l> >] [-s >] - [B<-vc> >] [-w >] - [-cb >] - [-banner (print banner every 10 minutes)] - [-novbc (whole volume cbs disabled)] - [-implicit >] - [-hr >] - [-busyat n>>] - [-rxpck >] - [-rxdbg (enable rx debugging)] - [-rxdbge (enable rxevent debugging)] - [-m >] - [-lock (keep fileserver from swapping)] - [B<-L> (large server conf)] [-S (small server conf)] - [B<-k> >] [-realm >] - [-udpsize >] - [B<-enable_peer_stats>] [-enable_process_stats] - [-help] - -This command does not use the syntax conventions of the AFS command -suites. Provide the command name and all option names in full. +B [B<-d> >] [B<-p> >] + [B<-spare> >] + [B<-pctspare> >] [B<-b> >] + [B<-l> >] [B<-s> >] + [B<-vc> >] [B<-w> >] + [B<-cb> >] [B<-banner>] [B<-novbc>] + [B<-implicit> >] + [B<-hr> >] + [B<-busyat> n >>>] + [B<-rxpck> >] + [B<-rxdbg>] [B<-rxdbge>] [B<-m> >] + [B<-lock>] [B<-L>] [B<-S>] [B<-k> >] + [B<-realm> >] + [B<-udpsize> >] + [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>] =head1 DESCRIPTION -The fileserver command initializes the File Server component of -the B process. In the conventional configuration, its -binary file is located in the B directory on a file -server machine. +The B command initializes the File Server component of the +C process. In the conventional configuration, its binary file is +located in the F directory on a file server machine. -The fileserver command is not normally issued at the command -shell prompt, but rather placed into a database server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a file server machine as the local superuser -B. +The B command is not normally issued at the command shell +prompt, but rather placed into a database server machine's +F file with the B command. If it is +ever issued at the command shell prompt, the issuer must be logged onto a +file server machine as the local superuser C. -The File Server creates the /usr/afs/logs/FileLog log file as it +The File Server creates the F log file as it initializes, if the file does not already exist. It does not write a -detailed trace by default, but use the B<-d> option to increase the -amount of detail. Use the B command to display the -contents of the log file. - -The command's arguments enable the administrator to control many -aspects of the File Server's performance, as detailed in the -B section. By default the B -command sets values for many arguments that are suitable for a medium-sized -file server machine. To set values suitable for a small or large file -server machine, use the B<-S> or B<-L> flag +detailed trace by default, but use the B<-d> option to increase the amount +of detail. Use the B command to display the contents of the +log file. + +The command's arguments enable the administrator to control many aspects +of the File Server's performance, as detailed in L. By default +the B command sets values for many arguments that are suitable +for a medium-sized file server machine. To set values suitable for a small +or large file server machine, use the B<-S> or B<-L> flag respectively. The following list describes the parameters and -corresponding argument for which the B command sets -default values, and L summarizes the setting for each of the three machine -sizes. +corresponding argument for which the B command sets default +values, and the table below summarizes the setting for each of the three +machine sizes. =over 4 =item * The maximum number of lightweight processes (LWPs) the File Server uses to -handle requests for data; corresponds to the B<-p> -argument. The File Server always uses a minimum of 32 KB for these -processes. - +handle requests for data; corresponds to the B<-p> argument. The File +Server always uses a minimum of 32 KB for these processes. =item * -The maximum number of directory blocks the File Server caches in -memory; corresponds to the B<-b> argument. Each cached -directory block (buffer) consumes 2,092 bytes of memory. - +The maximum number of directory blocks the File Server caches in memory; +corresponds to the B<-b> argument. Each cached directory block (buffer) +consumes 2,092 bytes of memory. =item * The maximum number of large vnodes the File Server caches in memory for -tracking directory elements; corresponds to the B<-l> -argument. Each large vnode consumes 292 bytes of memory. - +tracking directory elements; corresponds to the B<-l> argument. Each large +vnode consumes 292 bytes of memory. =item * The maximum number of small vnodes the File Server caches in memory for -tracking file elements; corresponds to the B<-s> argument. -Each small vnode consumes 100 bytes of memory. - +tracking file elements; corresponds to the B<-s> argument. Each small +vnode consumes 100 bytes of memory. =item * @@ -97,202 +80,195 @@ The maximum volume cache size, which determines how many volumes the File Server can cache in memory before having to retrieve data from disk; corresponds to the B<-vc> argument. - =item * The maximum number of callback structures the File Server caches in -memory; corresponds to the B<-cb> argument. Each callback -structure consumes 16 bytes of memory. - +memory; corresponds to the B<-cb> argument. Each callback structure +consumes 16 bytes of memory. =item * -The maximum number of Rx packets the File Server uses; -corresponds to the B<-rxpck> argument. Each packet consumes -1544 bytes of memory. - +The maximum number of Rx packets the File Server uses; corresponds to the +B<-rxpck> argument. Each packet consumes 1544 bytes of memory. =back -L +The default values are: -To override any of the values, provide the indicated argument (which can be -combined with the B<-S> or B<-L> flag). + Parameter (Argument) Small (-S) Medium Large (-L) + --------------------------------------------------------------------- + Number of LWPs (-p) 6 9 12 + Number of cached dir blocks (-b) 70 90 120 + Number of cached large vnodes (-l) 200 400 600 + Number of cached small vnodes (-s) 200 400 600 + Maximum volume cache size (-vc) 200 400 600 + Number of callbacks (-cb) 20,000 60,000 64,000 + Number of Rx packets (-rxpck) 100 150 200 -The amount of memory required for the File Server varies. The -approximate default memory usage is 751 KB when the B<-S> flag is used -(small configuration), 1.1 MB when all defaults are used (medium -configuration), and 1.4 MB when the B<-L> flag is used (large -configuration). If additional memory is available, increasing the value -of the B<-cb> and B<-vc> arguments can improve File Server -performance most directly. +To override any of the values, provide the indicated argument (which can +be combined with the B<-S> or B<-L> flag). + +The amount of memory required for the File Server varies. The approximate +default memory usage is 751 KB when the B<-S> flag is used (small +configuration), 1.1 MB when all defaults are used (medium configuration), +and 1.4 MB when the B<-L> flag is used (large configuration). If +additional memory is available, increasing the value of the B<-cb> and +B<-vc> arguments can improve File Server performance most directly. By default, the File Server allows a volume to exceed its quota by 1 MB -when an application is writing data to an existing file in a volume that is -full. The File Server still does not allow users to create new files in -a full volume. To change the default, use one of the following -arguments: -L<(1)> +when an application is writing data to an existing file in a volume that +is full. The File Server still does not allow users to create new files in +a full volume. To change the default, use one of the following arguments: =over 4 =item * -Set the -spare argument to the number of extra kilobytes that -the File Server allows as overage. A value of B<0> allows no -overage. - +Set the B<-spare> argument to the number of extra kilobytes that the File +Server allows as overage. A value of C<0> allows no overage. =item * -Set the -pctspare argument to the percentage of the -volume's quota the File Server allows as overage. - +Set the B<-pctspare> argument to the percentage of the volume's quota the +File Server allows as overage. =back -By default, the File Server implicitly grants the a -(B) and B (B) permissions to -the B on the access control list (ACL) of -every directory in the volumes stored on its file server machine. In -other words, the group's members can exercise those two permissions even -when an entry for the group does not appear on an ACL. To change the -set of default permissions, use the B<-implicit> argument. - -The File Server maintains a I -(I) for each client machine from which it has received a -data access request. Like the CPS for a user, a host CPS lists all of -the Protection Database groups to which the machine belongs, and the File -Server compares the host CPS to a directory's ACL to determine in what -manner users on the machine are authorized to access the directory's -contents. When the B or B -command is used to change the groups to which a machine belongs, the File -Server must recompute the machine's host CPS in order to notice the -change. By default, the File Server contacts the Protection Server -every two hours to recompute host CPSs, implying that it can take that long -for changed group memberships to become effective. To change this -frequency, use the B<-hr> argument. +By default, the File Server implicitly grants the C (administer) and +C (lookup) permissions to system:administrators on the access control +list (ACL) of every directory in the volumes stored on its file server +machine. In other words, the group's members can exercise those two +permissions even when an entry for the group does not appear on an ACL. To +change the set of default permissions, use the B<-implicit> argument. + +The File Server maintains a I (I) for each client machine from which it has received a data access +request. Like the CPS for a user, a host CPS lists all of the Protection +Database groups to which the machine belongs, and the File Server compares +the host CPS to a directory's ACL to determine in what manner users on the +machine are authorized to access the directory's contents. When the B or B command is used to change the groups to +which a machine belongs, the File Server must recompute the machine's host +CPS in order to notice the change. By default, the File Server contacts +the Protection Server every two hours to recompute host CPSs, implying +that it can take that long for changed group memberships to become +effective. To change this frequency, use the B<-hr> argument. The File Server generates the following message when a partition is nearly full: No space left on device +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + =head1 CAUTIONS -Do not use the B<-k> and -w arguments, which are -intended for use by the AFS Development group only. Changing them from -their default values can result in unpredictable File Server behavior. -In any case, on many operating systems the File Server uses native threads -rather than the LWP threads, so using the B<-k> argument to set the -number of LWP threads has no effect. +Do not use the B<-k> and -w arguments, which are intended for use by the +AFS Development group only. Changing them from their default values can +result in unpredictable File Server behavior. In any case, on many +operating systems the File Server uses native threads rather than the LWP +threads, so using the B<-k> argument to set the number of LWP threads has +no effect. -Do not specify both the B<-spare> and -pctspare -arguments. Doing so causes the File Server to exit, leaving an error -message in the B file. +Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so +causes the File Server to exit, leaving an error message in the +F file. -Options that are available only on some system types, such as the -B<-m> and B<-lock> options, appear in the output generated by -the B<-help> option only on the relevant system type. +Options that are available only on some system types, such as the B<-m> +and B<-lock> options, appear in the output generated by the B<-help> +option only on the relevant system type. =head1 OPTIONS =over 4 -=item -d +=item B<-d> > Sets the detail level for the debugging trace written to the -B file. Provide one of the following -values, each of which produces an increasingly detailed trace: -B<0>, B<1>, B<5>, B<25>, and -B<125>. The default value of B<0> produces only a few -messages. +F file. Provide one of the following values, each +of which produces an increasingly detailed trace: C<0>, C<1>, C<5>, C<25>, +and C<125>. The default value of C<0> produces only a few messages. -=item -p +=item B<-p> > -Sets the number of threads to run. Provide a positive -integer. The File Server creates and uses five threads for special -purposes, in addition to the number specified (but if this argument specifies -the maximum possible number, the File Server automatically uses five of the -threads for its own purposes). +Sets the number of threads to run. Provide a positive integer. The File +Server creates and uses five threads for special purposes, in addition to +the number specified (but if this argument specifies the maximum possible +number, the File Server automatically uses five of the threads for its own +purposes). -The maximum number of threads can differ in each release of AFS. -Consult the I for the current release. +The maximum number of threads can differ in each release of AFS. Consult +the I for the current release. -=item -spare +=item B<-spare> > Specifies the number of additional kilobytes an application can store in a -volume after the quota is exceeded. Provide a positive integer; a -value of B<0> prevents the volume from ever exceeding its -quota. Do not combine this argument with the B<-pctspare> -argument. +volume after the quota is exceeded. Provide a positive integer; a value of +C<0> prevents the volume from ever exceeding its quota. Do not combine +this argument with the B<-pctspare> argument. -=item -pctspare +=item B<-pctspare> > Specifies the amount by which the File Server allows a volume to exceed -its quota, as a percentage of the quota. Provide an integer between -B<0> and B<99>. A value of B<0> prevents the -volume from ever exceeding its quota. Do not combine this argument with -the B<-spare> argument. +its quota, as a percentage of the quota. Provide an integer between C<0> +and C<99>. A value of C<0> prevents the volume from ever exceeding its +quota. Do not combine this argument with the B<-spare> argument. -=item -b +=item B<-b> > -Sets the number of directory buffers. Provide a positive -integer. +Sets the number of directory buffers. Provide a positive integer. -=item -l +=item B<-l> > Sets the number of large vnodes available in memory for caching directory elements. Provide a positive integer. -=item -s +=item B<-s> > Sets the number of small vnodes available in memory for caching file elements. Provide a positive integer. -=item -vc +=item B<-vc> > -Sets the number of volumes the File Server can cache in memory. -Provide a positive integer. +Sets the number of volumes the File Server can cache in memory. Provide a +positive integer. -=item -w +=item B<-w> > Sets the interval at which the daemon spawned by the File Server performs -its maintenance tasks. Do not use this argument; changing the -default value can cause unpredictable behavior. +its maintenance tasks. Do not use this argument; changing the default +value can cause unpredictable behavior. -=item -cb +=item B<-cb> > -Sets the number of callbacks the File Server can track. Provide a -positive integer. +Sets the number of callbacks the File Server can track. Provide a positive +integer. -=item -banner +=item B<-banner> -Prints the following banner to /dev/console about every 10 -minutes. +Prints the following banner to F about every 10 minutes. File Server is running at I (B) and B -(B) permissions to the B -group only. These requirements prevent unauthorized users from -substituting a spurious B binary. - -The AFS distribution includes an example kpwvalid program that -checks that the password is at least eight characters long; the code for -it appears in the following B section. +The B command checks the quality of a new password passed to it +from the B or B command. It is optional. If it +exists, it must reside in the same AFS directory as the binaries for the +B and B command suites (create a symbolic link from the +client machine's local disk to this directory). The directory's ACL must +extend the C (administer) and C (write) permissions to the +system:administrators group only. These requirements prevent unauthorized +users from substituting a spurious B binary. + +The AFS distribution includes an example B program that checks +that the password is at least eight characters long; the code for it +appears in L below. The script or program must accept a sequence of password strings, one per -line, on the standard input stream. The first is the current password -and is ignored. Each subsequent string is a candidate password to be +line, on the standard input stream. The first is the current password and +is ignored. Each subsequent string is a candidate password to be checked. The program must write the following to the standard output stream for each one: @@ -29,15 +31,13 @@ stream for each one: =item * -C<0> (zero) and a newline character to indicate that the password -is acceptable - +C<0> (zero) and a newline character to indicate that the password is +acceptable. =item * A non-zero decimal number and a newline character to indicate that the -password is not acceptable - +password is not acceptable. =back @@ -74,7 +74,7 @@ that the requested password includes eight or more characters. =head1 SEE ALSO -L, +L, L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/package.pod b/doc/man-pages/pod8/package.pod index 3f0ec56d1..1e572fa6b 100644 --- a/doc/man-pages/pod8/package.pod +++ b/doc/man-pages/pod8/package.pod @@ -4,172 +4,160 @@ package - Configures files and directories on the local disk =head1 SYNOPSIS -B [B] [-config >] -[B<-fullconfig> >] - [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>] [-rebootfiles] - [B<-debug>] [-help] +B [I] [B<-config> >] + [B<-fullconfig> >] + [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>] + [B<-rebootfiles>] [B<-debug>] [B<-help>] -B [B] [-c >] -[B<-f> >] - [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [-h] +B [B] [B<-c> >] + [B<-f> >] + [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [B<-h>] =head1 DESCRIPTION -The package command configures the machine's local disk to -comply with the instructions in the configuration file named by the -B<-config> or B<-fullconfig> argument. +The B command configures the machine's local disk to comply with +the instructions in the configuration file named by the B<-config> or +B<-fullconfig> argument. -By default, the package command alters any existing local disk -element whose contents or configuration does not match the element defined in -the configuration file. For example, if a configuration file -B instruction defines a directory that has the same name as a -symbolic link on the local disk, the B command replaces the -symbolic link with the directory. The B and B -instructions include an optional I field that alters this -behavior. +By default, the package command alters any existing local disk element +whose contents or configuration does not match the element defined in the +configuration file. For example, if a configuration file C instruction +defines a directory that has the same name as a symbolic link on the local +disk, the B command replaces the symbolic link with the +directory. The C and C instructions include an optional +I field that alters this behavior. -Also by default, the package command takes no action on elements -on the local disk that are not mentioned in the configuration file. Use -the B instruction's B update code to remove files -from the disk directory that are not mentioned in the configuration -file. +Also by default, the package command takes no action on elements on the +local disk that are not mentioned in the configuration file. Use the C +instruction's C update code to remove files from the disk directory +that are not mentioned in the configuration file. -Before running the package command, the administrator must -create the template file and other files on the local disk. For -instructions, see the I. +Before running the package command, the administrator must create the +template file and other files on the local disk. For instructions, see the +I. -It is not possible to configure a remote client machine's disk using -this command. +It is not possible to configure a remote client machine's disk using this +command. =head1 CAUTIONS -The package command interpreter exits without executing any -instruction if there are any syntax errors or incorrect values in the -configuration file. +The package command interpreter exits without executing any instruction if +there are any syntax errors or incorrect values in the configuration file. =head1 OPTIONS =over 4 -=item initcmd +=item [I] -Accommodates the command's use of the AFS command parser, and is -optional. +Accommodates the command's use of the AFS command parser, and is optional. -=item -config +=item B<-config> > Specifies the pathname of the configuration file to use, ending in the file's base name, which omits the suffix that indicates the machine -type. The B command determines the machine's -system type name and automatically appends it to the base name. An -example of the proper value for this argument is B rather than -B. Partial pathnames are interpreted -relative to the current working directory. +type. The B command determines the machine's system type name and +automatically appends it to the base name. An example of the proper value +for this argument is C rather than C. Partial +pathnames are interpreted relative to the current working directory. -Provide this argument or the -fullconfig argument. +Provide this argument or the B<-fullconfig> argument. -=item -fullconfig +=item B<-fullconfig> > Specifies the configuration file to use. Two types of values are -acceptable: +acceptable: =over 4 =item * The full pathname of the configuration file to use, complete with an -extension indicating the machine type (examples: -B, B). - +extension indicating the machine type (examples: C, +C). =item * -The string stdin to indicate that the issuer is providing -configuration information via the standard input stream, either by piping in -the contents of a file, or by typing configuration lines at the shell. -In the latter case, type B<> to conclude the input. - +The string C to indicate that the issuer is providing configuration +information via the standard input stream, either by piping in the +contents of a file, or by typing configuration lines at the shell. In the +latter case, type Ctrl-D to conclude the input. =back -Provide this argument or the -config argument. +Provide this argument or the B<-config> argument. -=item -overwrite +=item B<-overwrite> Overwrites elements on the local disk with the source version indicated in -the configuration file, even if the owner B (B) mode -bit is turned on the disk element. Files protected by the B -update code on an B line in the configuration file are not -overwritten. +the configuration file, even if the owner write (C) mode bit is turned +on the disk element. Files protected by the C update code on an C +line in the configuration file are not overwritten. -=item -noaction +=item B<-noaction> Checks the sequence of operations to be performed when the command actually runs and reports any problems that the B command -interpreter expects to encounter. No elements on the local disk or in -AFS are changed. If the B<-verbose> flag is also provided, the -trace includes all actions to be performed as well as anticipated -errors. +interpreter expects to encounter. No elements on the local disk or in AFS +are changed. If the B<-verbose> flag is also provided, the trace includes +all actions to be performed as well as anticipated errors. -=item -silent +=item B<-silent> Suppresses some of the trace messages sent to the standard output stream by default. The output still reports major problems. -=item -verbose +=item B<-verbose> -Produces on the standard output stream a detailed trace of the -command's execution. If this argument is omitted, only warnings -and error messages appear. +Produces on the standard output stream a detailed trace of the command's +execution. If this argument is omitted, only warnings and error messages +appear. -=item -rebootfiles +=item B<-rebootfiles> -Prevents overwriting of any file marked with the Q update code -on an B line in the configuration file. This effectively -prevents the machine from rebooting automatically again when the -B command is invoked in the machine's AFS initialization -file. +Prevents overwriting of any file marked with the C update code on an +C line in the configuration file. This effectively prevents the machine +from rebooting automatically again when the B command is invoked +in the machine's AFS initialization file. -=item -debug +=item B<-debug> Enables debugging output, which is directed to the standard output stream by default. By default, no debugging output is produced. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -This command is usually invoked in a client machine's AFS -initialization file (B or equivalent), rather than issued at -the command shell prompt. +This command is usually invoked in a client machine's AFS initialization +file (F or equivalent), rather than issued at the command shell +prompt. -The following command invokes the version of the staff -configuration file appropriate for this machine's system type, and -produces verbose output. +The following command invokes the version of the staff configuration file +appropriate for this machine's system type, and produces verbose output. # /etc/package -c staff -v -The following example uses the configuration file whose basename is defined -in the B file on the local machine. This -method enables the administrator to use the same B command in -every machine's AFS initialization file but still customize configuration -by putting the appropriate basename in the B -file. +The following example uses the configuration file whose basename is +defined in the F file on the local machine. This method enables +the administrator to use the same B command in every machine's +AFS initialization file but still customize configuration by putting the +appropriate basename in the F file. # /etc/package -c `cat /.package` -v =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the local superuser root. +The issuer must be logged in as the local superuser C. =head1 SEE ALSO -L +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/package_apropos.pod b/doc/man-pages/pod8/package_apropos.pod deleted file mode 100644 index fe9ac63cb..000000000 --- a/doc/man-pages/pod8/package_apropos.pod +++ /dev/null @@ -1,69 +0,0 @@ -=head1 NAME - -package apropos - Displays each help entry containing a keyword string - -=head1 SYNOPSIS - -B [B<-topic> >] [-help] - -B [B<-t> >] [-h] - -=head1 DESCRIPTION - -The package apropos command displays the first line of the -online help entry for any B 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 package help -command. - -=head1 OPTIONS - -=over 4 - -=item -topic - -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 -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 -B command where the string specified with the -B<-topic> argument is part of the command name or first line. - -=head1 EXAMPLES - -The following command lists all package commands that include -the word B in their names or short descriptions: - - % package apropos help - apropos: search by help text - help: get help on commands - -=head1 PRIVILEGE REQUIRED - -None - -=head1 SEE ALSO - -L, -L - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/package_help.pod b/doc/man-pages/pod8/package_help.pod deleted file mode 100644 index 4f8220e2d..000000000 --- a/doc/man-pages/pod8/package_help.pod +++ /dev/null @@ -1,99 +0,0 @@ -=head1 NAME - -package help - Displays the syntax of specified package commands or lists -functional descriptions of all B commands - -=head1 SYNOPSIS - -B [B<-topic> >+] [-help] - -B [B<-t> >+] [-h] - -=head1 DESCRIPTION - -The package help command displays the complete online help entry -(short description and syntax statement) for each command operation code -specified by the B<-topic> argument. If the B<-topic> -argument is omitted, the output includes the first line (name and short -description) of the online help entry for every B -command. - -To list every package command whose name or short description -includes a specified keyword, use the B -command. - -=head1 OPTIONS - -=over 4 - -=item -topic - -Indicates each command for which to display the complete online help -entry. Omit the B part of the command name, providing -only the operation code (for example, specify B, not -B). If this argument is omitted, the output -briefly describes every B command. - -=item -help - -Prints the online help for this command. All other valid options -are ignored. - -=back - -=head1 OUTPUT - -The online help entry for each package command consists of the -following two or three lines: - -=over 4 - -=item * - -The first line names the command and briefly describes its -function. - - -=item * - -The second line lists aliases for the command, if any. - - -=item * - -The final line, which begins with the string C, lists the -command's options in the prescribed order. Online help entries use -the same symbols (for example, brackets) as the reference pages in this -document. - - -=back - -=head1 EXAMPLES - -The following command displays the online help entry for the package -initcmd command: - - % package help initcmd - package initcmd: initialize the program - Usage: package [initcmd] [-config ] - [-fullconfig ] - [-overwrite] [-noaction] [-verbose] [-silent] [-rebootfiles] - [-debug] [-help] - -=head1 PRIVILEGE REQUIRED - -None - -=head1 SEE ALSO - -L, -L - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/package_test.pod b/doc/man-pages/pod8/package_test.pod deleted file mode 100644 index 91e98f62c..000000000 --- a/doc/man-pages/pod8/package_test.pod +++ /dev/null @@ -1,53 +0,0 @@ -=head1 NAME - -package_test - Tests the validity of a package configuration file - -=head1 SYNOPSIS - -package_test > - -This command does not use the syntax conventions of the AFS command -suites. Provide the command name in full. - -=head1 DESCRIPTION - -The package_test command tests the validity of a -B configuration file created when a prototype file is -compiled. The command interpreter prints error messages on the standard -output stream. - -=head1 OPTIONS - -=over 4 - -=item I - -Specifies the package configuration file to validate. - -=back - -=head1 EXAMPLES - -The following example tests the validity of the package -configuration file I. - - % package_test staff.sun4x_56 - -=head1 PRIVILEGE REQUIRED - -None - -=head1 SEE ALSO - -L - -L - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. diff --git a/doc/man-pages/pod8/prdb_check.pod b/doc/man-pages/pod8/prdb_check.pod index cd86e22e8..c5bd758f5 100644 --- a/doc/man-pages/pod8/prdb_check.pod +++ b/doc/man-pages/pod8/prdb_check.pod @@ -4,87 +4,81 @@ prdb_check - Checks the integrity of the Protection Database =head1 SYNOPSIS -B > [B<-uheader>] [B<-pheader>] [-entries] -[B<-verbose>] [B<-help>] +B B<-database> > [B<-uheader>] [B<-pheader>] + [B<-entries>] [B<-verbose>] [B<-help>] -B > [B<-u>] [B<-p>] [B<-e>] [B<-v>] [-h] +B B<-d> > [B<-u>] [B<-p>] [B<-e>] [B<-v>] [B<-h>] =head1 DESCRIPTION -The prdb_check command checks the integrity of the Protection -Database, reporting any errors or corruption it finds. If there are -problems, do not issue any B commands until the database is -repaired. +The B command checks the integrity of the Protection Database, +reporting any errors or corruption it finds. If there are problems, do not +issue any B commands until the database is repaired. =head1 CAUTIONS The results can be unpredictable if the Protection Server makes changes to the Protection Database while this command is running. Use the B command to shutdown the local B process -before running this command, or before creating a second copy of the -B file (with a different name) on which to run the -command. +shutdown> command to shutdown the local B process before running +this command, or before creating a second copy of the F file +(with a different name) on which to run the command. =head1 OPTIONS =over 4 -=item -database +=item B<-database> > -Names the Protection Database (copy of the prdb.DB0 -file) to check. If the current working directory is not the location of -the file, provide a pathname, either full or relative to the current working -directory. +Names the Protection Database (copy of the F file) to check. If +the current working directory is not the location of the file, provide a +pathname, either full or relative to the current working directory. -=item -uheader +=item B<-uheader> -Displays information which Ubik maintains in the database's -header. +Displays information which Ubik maintains in the database's header. -=item -pheader +=item B<-pheader> Displays information which the Protection Server maintains in the database's header. -=item -entries +=item B<-entries> -Outputs every entry in the database. Some of the information is -similar to that returned by the B command. +Outputs every entry in the database. Some of the information is similar to +that returned by the B command. -=item -verbose +=item B<-verbose> Reports additional information about the database, including the number of -entries in the database and a trace of the internal database structures the -command is verifying. +entries in the database and a trace of the internal database structures +the command is verifying. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT If there are errors in the database, the output always reports them on the -standard error stream. If any options other than B<-database> -or B<-help> are provided, the output written to the standard output -stream includes additional information as described for each option in the -preceding B section of this reference page. The output -is intended for debugging purposes and is meaningful to someone familiar with -the internal structure of the Protection Database. +standard error stream. If any options other than B<-database> or B<-help> +are provided, the output written to the standard output stream includes +additional information as described for each option in L. The +output is intended for debugging purposes and is meaningful to someone +familiar with the internal structure of the Protection Database. =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the local superuser root. +The issuer must be logged in as the local superuser C. =head1 SEE ALSO -L - -L, +L, +L, L, -L +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/ptserver.pod b/doc/man-pages/pod8/ptserver.pod index 63cdc3cc9..e0c4a0fcd 100644 --- a/doc/man-pages/pod8/ptserver.pod +++ b/doc/man-pages/pod8/ptserver.pod @@ -4,25 +4,22 @@ ptserver - Initializes the Protection Server =head1 SYNOPSIS -B [B<-database> >] [B<-p> >] [-rebuildDB] -[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. +B [B<-database> >] [B<-p> >] + [B<-rebuildDB>] [B<-enable_peer_stats>] [B<-enable_process_stats>] + [B<-help>] =head1 DESCRIPTION -The ptserver command initializes the Protection Server, which -must run on every database server machine. In the conventional -configuration, its binary file is located in the B -directory on a file server machine. +The B command initializes the Protection Server, which must run +on every database server machine. In the conventional configuration, its +binary file is located in the F directory on a file server +machine. -The ptserver command is not normally issued at the command shell -prompt, but rather placed into a database server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a file server machine as the local superuser -B. +The ptserver command is not normally issued at the command shell prompt, +but rather placed into a database server machine's +F file with the B command. If it is +ever issued at the command shell prompt, the issuer must be logged onto a +file server machine as the local superuser C. The Protection Server performs the following tasks: @@ -31,59 +28,55 @@ The Protection Server performs the following tasks: =item * Maintains the Protection Database, which contains entries for every user -and group in the cell. Use the B commands to administer -the database. - +and group in the cell. Use the B commands to administer the database. =item * Allocates AFS IDs for new user, machine and group entries and maps each ID to the corresponding name. - =item * Generates a current protection subgroup (CPS) at the File Server's -request. The CPS lists all groups to which a user or machine -belongs. - +request. The CPS lists all groups to which a user or machine belongs. =back +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + =head1 OPTIONS =over 4 -=item -database +=item B<-database> > Specifies the pathname of an alternate directory in which the Protection -Database files reside. Provide the complete pathname, ending in the -base filename to which the B<.DB0> and -B<.DBSYS1> extensions are appended. For example, the -appropriate value for the default database files is -B. +Database files reside. Provide the complete pathname, ending in the base +filename to which the C<.DB0> and C<.DBSYS1> extensions are appended. For +example, the appropriate value for the default database files is +F. -=item -p +=item B<-p> > -Sets the number of server lightweight processes (LWPs) to run. -Provide a positive integer from the range B<3> to -B<16>. The default value is 3. +Sets the number of server lightweight processes (LWPs) to run. Provide a +positive integer from the range C<3> to C<16>. The default value is C<3>. -=item -rebuildDB +=item B<-rebuildDB> Rebuilds the Protection Database at the beginning of Protection Server initialization. Use this argument only in consultation with AFS Development or Product Support. -=item -enable_peer_stats +=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. +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 -enable_process_stats +=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, @@ -91,36 +84,35 @@ 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 -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following B command creates a ptserver -process on the machine B. The -command appears here on multiple lines only for legibility. +The following B command creates a C process on the +machine C. The command appears here on multiple lines only +for legibility. - % bos create -server fs3.abc.com -instance ptserver \ + % bos create -server fs3.abc.com -instance ptserver \ -type simple -cmd /usr/afs/bin/ptserver =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the superuser root on a file -server machine to issue the command at a command shell prompt. It is -conventional instead to create and start the process by issuing the B command. +The issuer must be logged in as the superuser C on a file server +machine to issue the command at a command shell prompt. It is conventional +instead to create and start the process by issuing the B +command. =head1 SEE ALSO -L, -L - -L, -L, +L, +L, +L, +L, L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/salvager.pod b/doc/man-pages/pod8/salvager.pod index 48e3571b2..84325e956 100644 --- a/doc/man-pages/pod8/salvager.pod +++ b/doc/man-pages/pod8/salvager.pod @@ -4,28 +4,24 @@ salvager - Initializes the Salvager component of the fs process =head1 SYNOPSIS -B [B] [-partition >] -[B<-volumeid> >] [B<-debug>] - [B<-nowrite>] [B<-inodes>] [B<-force>] [-oktozap] - [B<-rootinodes>] [B<-salvagedirs>] [-blockreads] - [-parallel >] - [-tmpdir >] - [B<-showlog>] [B<-showsuid>] [-showmounts] - [B<-orphans> | B | 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. +B [I] [B<-partition> >] + [B<-volumeid> >] [B<-debug>] [B<-nowrite>] + [B<-inodes>] [B<-force>] [B<-oktozap>] [B<-rootinodes>] + [B<-salvagedirs>] [B<-blockreads>] + [B<-parallel> >] + [B<-tmpdir> >] + [B<-showlog>] [B<-showsuid>] [B<-showmounts>] + [B<-orphans> (ignore | remove | attach)] [B<-help>] =head1 DESCRIPTION -The salvager command initializes the Salvager component of the -B process. In the conventional configuration, its binary -file is located in the B directory on a file server -machine. +The B command initializes the Salvager component of the C +process. In the conventional configuration, its binary file is located in +the F directory on a file server machine. The Salvager restores internal consistency to corrupted read/write volumes -on the local file server machine where possible. For read-only or -backup volumes, it inspects only the volume header: +on the local file server machine where possible. For read-only or backup +volumes, it inspects only the volume header: =over 4 @@ -33,316 +29,294 @@ backup volumes, it inspects only the volume header: If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log file, -B. Issue the B -or B command to create the read-only or backup volume -again. - +F. Issue the B or B +command to create the read-only or backup volume again. =item * If the volume header is intact, the Salvager skips the volume (does not -check for corruption in the contents). However, if the File Server -notices corruption as it initializes, it sometimes refuses to attach the -volume or bring it online. In this case, it is simplest to remove the -volume by issuing the B or B -command. Then issue the B or B -command to create it again. - +check for corruption in the contents). However, if the File Server notices +corruption as it initializes, it sometimes refuses to attach the volume or +bring it online. In this case, it is simplest to remove the volume by +issuing the B or B command. Then issue the B or B command to create it again. =back -Unlike other server process initialization commands, the -B command is designed to be issued at the command shell -prompt, as well as being placed into a file server machine's -B file with the B -command. It is also possible to invoke the Salvager remotely by issuing -the B command. +Unlike other server process initialization commands, the B +command is designed to be issued at the command shell prompt, as well as +being placed into a file server machine's F file +with the B command. It is also possible to invoke the Salvager +remotely by issuing the B command. -Combine the command's options as indicated to salvage different -numbers of read/write volumes: +Combine the command's options as indicated to salvage different numbers of +read/write volumes: =over 4 =item * -To salvage all volumes on the file server machine, provide no -arguments. No volumes on the machine are accessible to Cache Managers -during the salvage, because the BOS Server stops the File Server and Volume -Server processes while the Salvager runs. - +To salvage all volumes on the file server machine, provide no arguments. +No volumes on the machine are accessible to Cache Managers during the +salvage, because the BOS Server stops the File Server and Volume Server +processes while the Salvager runs. =item * -To salvage all of the volumes on one partition, provide the -B<-partition> argument. As for a salvage of all volumes on the -machine, no volumes on the machine are accessible to Cache Managers during the -salvage operation. - +To salvage all of the volumes on one partition, provide the B<-partition> +argument. As for a salvage of all volumes on the machine, no volumes on +the machine are accessible to Cache Managers during the salvage operation. =item * -To salvage only one volume, combine the -partition and -B<-volumeid> arguments. Only that volume is inaccessible to -Cache Managers, because the BOS Server does not shutdown the File Server and -Volume Server processes. - +To salvage only one volume, combine the B<-partition> and B<-volumeid> +arguments. Only that volume is inaccessible to Cache Managers, because the +BOS Server does not shutdown the File Server and Volume Server processes. =back The Salvager normally salvages only those read/write volumes that are -marked as having been active when a crash occurred. To have it salvage -all relevant read/write volumes, add the B<-force> flag. +marked as having been active when a crash occurred. To have it salvage all +relevant read/write volumes, add the B<-force> flag. -The Salvager normally creates new inodes as it repairs damage. If -the partition is so full that there is no room for new inodes, use the +The Salvager normally creates new inodes as it repairs damage. If the +partition is so full that there is no room for new inodes, use the B<-nowrite> argument to bringing undamaged volumes online without -attempting to salvage damaged volumes. Then use the B -command to move one or more of the undamaged volumes to other partitions, -freeing up the space that the Salvager needs to create new inodes. - -By default, multiple Salvager subprocesses run in parallel: one for -each partition up to four, and four subprocesses for four or more -partitions. To increase or decrease the number of subprocesses running -in parallel, provide a positive integer value for the B<-parallel> -argument. - -If there is more than one server partition on a physical disk, the Salvager -by default salvages them serially to avoid the inefficiency of constantly -moving the disk head from one partition to another. However, this -strategy is often not ideal if the partitions are configured as logical -volumes that span multiple disks. To force the Salvager to salvage -logical volumes in parallel, provide the string B as the value -for the B<-parallel> argument. Provide a positive integer to -specify the number of subprocesses to run in parallel (for example, -B<-parallel 5all> for five subprocesses), or omit the integer to run -up to four subprocesses, depending on the number of logical volumes being -salvaged. - -The Salvager creates temporary files as it runs, by default writing them to -the partition it is salvaging. The number of files can be quite large, -and if the partition is too full to accommodate them, the Salvager terminates -without completing the salvage operation (it always removes the temporary -files before exiting). Other Salvager subprocesses running at the same -time continue until they finish salvaging all other partitions where there is -enough disk space for temporary files. To complete the interrupted -salvage, reissue the command against the appropriate partitions, adding the -B<-tmpdir> argument to redirect the temporary files to a local disk -directory that has enough space. - -The -orphans argument controls how the Salvager handles orphaned -files and directories that it finds on server partitions it is -salvaging. An I element is completely inaccessible -because it is not referenced by the vnode of any directory that can act as its -parent (is higher in the filespace). Orphaned objects occupy space on -the server partition, but do not count against the volume's quota. +attempting to salvage damaged volumes. Then use the B command to +move one or more of the undamaged volumes to other partitions, freeing up +the space that the Salvager needs to create new inodes. + +By default, multiple Salvager subprocesses run in parallel: one for each +partition up to four, and four subprocesses for four or more +partitions. To increase or decrease the number of subprocesses running in +parallel, provide a positive integer value for the B<-parallel> argument. + +If there is more than one server partition on a physical disk, the +Salvager by default salvages them serially to avoid the inefficiency of +constantly moving the disk head from one partition to another. However, +this strategy is often not ideal if the partitions are configured as +logical volumes that span multiple disks. To force the Salvager to salvage +logical volumes in parallel, provide the string C as the value for +the B<-parallel> argument. Provide a positive integer to specify the +number of subprocesses to run in parallel (for example, C<-parallel 5all> +for five subprocesses), or omit the integer to run up to four +subprocesses, depending on the number of logical volumes being salvaged. + +The Salvager creates temporary files as it runs, by default writing them +to the partition it is salvaging. The number of files can be quite large, +and if the partition is too full to accommodate them, the Salvager +terminates without completing the salvage operation (it always removes the +temporary files before exiting). Other Salvager subprocesses running at +the same time continue until they finish salvaging all other partitions +where there is enough disk space for temporary files. To complete the +interrupted salvage, reissue the command against the appropriate +partitions, adding the B<-tmpdir> argument to redirect the temporary files +to a local disk directory that has enough space. + +The B<-orphans> argument controls how the Salvager handles orphaned files +and directories that it finds on server partitions it is salvaging. An +I element is completely inaccessible because it is not +referenced by the vnode of any directory that can act as its parent (is +higher in the filespace). Orphaned objects occupy space on the server +partition, but do not count against the volume's quota. To generate a list of all mount points that reside in one or more volumes, -rather than actually salvaging them, include the B<-showmounts> -flag. +rather than actually salvaging them, include the B<-showmounts> flag. + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. =head1 OPTIONS =over 4 -=item initcmd +=item [I] -Accommodates the command's use of the AFS command parser, and is -optional. +Accommodates the command's use of the AFS command parser, and is optional. -=item -partition +=item B<-partition> > -Specifies the name of the partition to salvage. Specify the full -partition name using the form BI or -BI. Omit this argument to salvage every -partition on the file server machine. +Specifies the name of the partition to salvage. Specify the full partition +name using the form F> or F>. Omit this argument to +salvage every partition on the file server machine. -=item -volumeid +=item B<-volumeid> > -Specifies the volume ID of a specific read/write volume to salvage. -The B<-partition> argument must be provided along with this one and -specify the volume's actual site. +Specifies the volume ID of a specific read/write volume to salvage. The +B<-partition> argument must be provided along with this one and specify +the volume's actual site. -=item -debug +=item B<-debug> Allows only one Salvager subprocess to run at a time, regardless of the -setting of the B<-parallel> option. Include it when running the -Salvager in a debugger to make the trace easier to interpret. +setting of the B<-parallel> option. Include it when running the Salvager +in a debugger to make the trace easier to interpret. -=item -nowrite +=item B<-nowrite> Brings all undamaged volumes online without attempting to salvage any damaged volumes. -=item -inodes +=item B<-inodes> -Records in the /usr/afs/logs/SalvageLog file a list of all AFS -inodes that the Salvager modified. +Records in the F file a list of all AFS inodes +that the Salvager modified. -=item -force +=item B<-force> Inspects all volumes for corruption, not just those that are marked as having been active when a crash occurred. -=item -oktozap +=item B<-oktozap> -Removes a volume that is so damaged that even issuing the vos -zap command with the B<-force> flag is ineffective. Use -this argument only in consultation with AFS Development or Product -Support. Combine it with the B<-partition> and -B<-volumeid> arguments to identify the volume to remove. +Removes a volume that is so damaged that even issuing the B +command with the B<-force> flag is ineffective. Use this argument only in +consultation with AFS Development or Product Support. Combine it with the +B<-partition> and B<-volumeid> arguments to identify the volume to remove. -=item -rootinodes +=item B<-rootinodes> -Records in the /usr/afs/logs/SalvageLog file a list of all AFS -inodes owned by the local superuser B. +Records in the F file a list of all AFS inodes +owned by the local superuser C. -=item -salvagedirs +=item B<-salvagedirs> Salvages entire directory structures, even if they do not appear to be damaged. By default, the Salvager salvages a directory only if it is flagged as corrupted. -=item -blockreads +=item B<-blockreads> Forces the Salvager to read a partition one disk block (512 bytes) at a time and to skip any blocks that are too badly damaged to be salvaged. This allows it to salvage as many volumes as possible. By default, the -Salvager reads large disk blocks, which can cause it to exit prematurely if it -encounters disk errors. Use this flag if the partition to be salvaged -has disk errors. +Salvager reads large disk blocks, which can cause it to exit prematurely +if it encounters disk errors. Use this flag if the partition to be +salvaged has disk errors. -=item -parallel +=item B<-parallel> > -Specifies the maximum number of Salvager subprocesses to run in -parallel. Provide one of three values: +Specifies the maximum number of Salvager subprocesses to run in parallel. +Provide one of three values: =over 4 =item * -An integer from the range B<1> to 32. A value of -B<1> means that a single Salvager process salvages the partitions -sequentially. - +An integer from the range C<1> to C<32>. A value of C<1> means that a +single Salvager process salvages the partitions sequentially. =item * -The string all to run up to four Salvager subprocesses in -parallel on partitions formatted as logical volumes that span multiple -physical disks. Use this value only with such logical volumes. - +The string C to run up to four Salvager subprocesses in parallel on +partitions formatted as logical volumes that span multiple physical +disks. Use this value only with such logical volumes. =item * -The string all followed immediately (with no intervening space) -by an integer from the range B<1> to B<32>, to run the -specified number of Salvager subprocesses in parallel on partitions formatted -as logical volumes. Use this value only with such logical -volumes. - +The string C followed immediately (with no intervening space) by an +integer from the range C<1> to C<32>, to run the specified number of +Salvager subprocesses in parallel on partitions formatted as logical +volumes. Use this value only with such logical volumes. =back The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one process to salvage a single -volume. If this argument is omitted, up to four Salvager subprocesses -run in parallel. +volume. If this argument is omitted, up to four Salvager subprocesses run +in parallel. -=item -tmpdir +=item B<-tmpdir> > Names a local disk directory in which the Salvager places the temporary -files it creates during a salvage operation, instead of writing them to the -partition being salvaged (the default). If the Salvager cannot write to -the specified directory, it attempts to write to the partition being +files it creates during a salvage operation, instead of writing them to +the partition being salvaged (the default). If the Salvager cannot write +to the specified directory, it attempts to write to the partition being salvaged. -=item -showlog +=item B<-showlog> Displays on the standard output stream all log data that is being written -to the B file. +to the F file. -=item -showsuid +=item B<-showsuid> Displays a list of the pathnames for all files that have the setuid or setgid mode bit set. -=item -showmounts +=item B<-showmounts> -Records in the /usr/afs/logs/SalvageLog file all mount points -found in each volume. The Salvager does not repair corruption in the -volumes, if any exists. +Records in the F file all mount points found in +each volume. The Salvager does not repair corruption in the volumes, if +any exists. -=item -orphans +=item B<-orphans> (ignore | remove | attach) -Controls how the Salvager handles orphaned files and directories. -Choose one of the following three values: +Controls how the Salvager handles orphaned files and directories. Choose +one of the following three values: =over 4 =item ignore Leaves the orphaned objects on the disk, but prints a message to the -B file reporting how many orphans were found -and the approximate number of kilobytes they are consuming. This is the +F file reporting how many orphans were found and +the approximate number of kilobytes they are consuming. This is the default if the B<-orphans> argument is omitted. =item remove Removes the orphaned objects, and prints a message to the -B file reporting how many orphans were -removed and the approximate number of kilobytes they were consuming. +F file reporting how many orphans were removed +and the approximate number of kilobytes they were consuming. =item attach Attaches the orphaned objects by creating a reference to them in the vnode -of the volume's root directory. Since each object's actual -name is now lost, the Salvager assigns each one a name of the following -form: +of the volume's root directory. Since each object's actual name is now +lost, the Salvager assigns each one a name of the following form: =over 4 +=item C<__ORPHANFILE__.I> for files. -_ _ORPHANFILE_ _.I for files - - -_ _ORPHANDIR_ _.I for directories +=item C<__ORPHANDIR__.I> for directories. =back where I is a two-digit number that uniquely identifies each -object. The orphans are charged against the volume's quota and -appear in the output of the B command issued against the -volume's root directory. +object. The orphans are charged against the volume's quota and appear in +the output of the B command issued against the volume's root +directory. =back -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following command instructs the Salvager to attempt to salvage the -volume with volume ID 258347486 on B on the local -machine. +volume with volume ID 258347486 on F on the local machine. % /usr/afs/bin/salvager -partition /vicepg -volumeid 258347486 =head1 PRIVILEGE REQUIRED To issue the command at the shell prompt, the issuer must be logged in as -the local superuser B. +the local superuser C. =head1 SEE ALSO -L, -L, -L, -L, -L, +L, +L, +L, +L, +L, L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/upclient.pod b/doc/man-pages/pod8/upclient.pod index 20169444f..79b7175db 100644 --- a/doc/man-pages/pod8/upclient.pod +++ b/doc/man-pages/pod8/upclient.pod @@ -4,173 +4,147 @@ upclient - Initializes the client portion of the Update Server =head1 SYNOPSIS -B > [B<-crypt>] [B<-clear>] [-t >] -[B<-verbose>]* >+ [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. +B > [B<-crypt>] [B<-clear>] [B<-t> >] + [B<-verbose>]* >+ [B<-help>] =head1 DESCRIPTION -The upclient command initializes the client portion of the -Update Server. In the conventional configuration, its binary file is -located in the B directory on a file server -machine. - -The upclient command is not normally issued at the command shell -prompt but rather placed into a file server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a database server machine as the local superuser -B. - -The upclient process periodically checks that all files in each -local directory named by the I argument match the files in the -corresponding directory on the source machine named by the -Iargument. If a file does not match, the -B process requests the source copy from the -B process running on the source machine. - -By default, the upclient process in the United States edition of -AFS requests that the B process encrypt the data before -transferring it, whereas in the international edition it requests unencrypted -transfer. If using the United States edition, use the B<-clear> -flag to request unencrypted transfer if appropriate. (The -B<-crypt> flag explicitly sets the default in the United States -edition, and is not available in the international edition.) - -In the conventional configuration, separate instances of the -B process request data from the B and -B directories, except on machines for which the system -control machine is also the binary distribution machine for the machine's -system type. The conventional names for the separate instances are -B and B respectively. - -The B and upserver processes always mutually -authenticate, whether or not the data they pass is encrypted; they use -the key with the highest key version number in the -B file to construct a server ticket for mutual -authentication. +The upclient command initializes the client portion of the Update +Server. In the conventional configuration, its binary file is located in +the F directory on a file server machine. + +The upclient command is not normally issued at the command shell prompt +but rather placed into a file server machine's F +file with the B command. If it is ever issued at the command +shell prompt, the issuer must be logged onto a database server machine as +the local superuser C. + +The upclient process periodically checks that all files in each local +directory named by the I argument match the files in the +corresponding directory on the source machine named by the I +argument. If a file does not match, the B process requests the +source copy from the B process running on the source machine. + +By default, the B process requests that the B process +encrypt the data before transferring it. Use the B<-clear> flag to +request unencrypted transfer if appropriate. (The B<-crypt> flag +explicitly sets the default.) + +In the conventional configuration, separate instances of the B +process request data from the F and F +directories, except on machines for which the system control machine is +also the binary distribution machine for the machine's system type. The +conventional names for the separate instances are C and +C respectively. + +The B and B processes always mutually authenticate, +whether or not the data they pass is encrypted; they use the key with the +highest key version number in the F file to +construct a server ticket for mutual authentication. + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. =head1 CAUTIONS Do not use the Update Server to distribute the contents of the -B directory if using the international edition of -AFS. The contents of this directory are sensitive and the international -edition of AFS does not include the encryption routines necessary for -encrypting files before transfer across the network. +F directory using the B<-clear> option. The contents of +this directory are sensitive. =head1 OPTIONS =over 4 -=item I +=item > -Names either the cell's system control machine (if the requested -directory is B), or the binary distribution machine for -the local machine's CPU and operating system type (if the requested -directory is B). +Names either the cell's system control machine (if the requested directory +is F), or the binary distribution machine for the local +machine's CPU and operating system type (if the requested directory is +F). -=item -crypt +=item B<-crypt> -Requests the transfer of data from the upserver process in -encrypted form. With the United States edition of AFS, use this flag to -set the default explicitly. Provide this flag or the B<-crypt> -flag, but not both. +Requests the transfer of data from the upserver process in encrypted +form. This is the default; this flag just sets the default explicitly. +Do not use this flag with the B<-clear> flag. -=item -clear +=item B<-clear> -Requests transfer of data from the upserver process in -unencrypted form. Use this flag to change from the default for the -United States edition of AFS. Provide this flag or the -B<-crypt> flag, but not both. +Requests transfer of data from the B process in unencrypted +form. Provide this flag or the B<-crypt> flag, but not both. -=item -t +=item B<-t> > Specifies how often to check for changes in each specified directory, as a -number of seconds. If this argument is omitted, the default is 300 (5 -minutes). This argument determines the maximum amount of time it takes -for a change made on the source machine to propagate to this machine. +number of seconds. If this argument is omitted, the default is C<300> (5 +minutes). This argument determines the maximum amount of time it takes for +a change made on the source machine to propagate to this machine. -=item -verbose +=item B<-verbose>* -Writes a trace of the upclient process's operations on the -standard output stream, which usually corresponds to the machine -console. Provide one, two, or three instances of the flag; each -additional instance generates increasingly numerous and detailed -messages. +Writes a trace of the upclient process's operations on the standard output +stream, which usually corresponds to the machine console. Provide one, +two, or three instances of the flag; each additional instance generates +increasingly numerous and detailed messages. -=item I +=item >+ -Names each directory to check for modified files. The conventional -choices are the following: +Names each directory to check for modified files. The conventional choices +are the following: =over 4 =item * -/usr/afs/bin, in which case the recommended name for the -process (assigned with the B<-instance> argument to the B command) is B. The I -is the binary distribution machine for the local machine's system -type. Use the B<-clear> flag be used for the -B directory, since binaries are not particularly -sensitive and encrypting them can take a long time. - +F, in which case the recommended name for the process +(assigned with the B<-instance> argument to the B command) is +C. The I is the binary distribution machine for the +local machine's system type. You may wish to use the B<-clear> flag for +the F directory, since binaries are not particularly +sensitive and encrypting them takes system resources. =item * -/usr/afs/etc, in which case the recommended name for the -process (assigned with the B<-instance> argument to the B command) is B. The I -is the cell's system control machine. Use the B<-crypt> -flag for the B directory, since it contains the -B file and other data vital to cell security. - - -As a reminder, do not use the Update Server to transfer the contents of the -B directory if using the international edition of -AFS. +F, in which case the recommended name for the process +(assigned with the B<-instance> argument to the B command) is +C. The I is the cell's system control machine. Use +the B<-crypt> flag for the F directory, since it contains +the F file and other data vital to cell security. =back -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following bos create command creates an -B process on the machine -B that refers to the machine -B as the source for the -B directory (thus B -is the binary distribution machine for machines of -B's type). The files in the -B directory are distributed every 120 seconds. +The following bos create command creates an C process on the +machine C that refers to the machine C as the +source for the F directory (thus C is the +binary distribution machine for machines of C's type). The +files in the F directory are distributed every 120 seconds. The command requests transfer in unencrypted form. - % bos create -server fs4.abc.com -instance upclientbin -type simple \ - -cmd "/usr/afs/bin/upclient fs1.abc.com -clear \ + % bos create -server fs4.abc.com -instance upclientbin -type simple \ + -cmd "/usr/afs/bin/upclient fs1.abc.com -clear \ -t 120 /usr/afs/bin" =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the superuser root on a file -server machine to issue the command at a command shell prompt. It is -conventional instead to create and start the process by issuing the B command. +The issuer must be logged in as the superuser C on a file server +machine to issue the command at a command shell prompt. It is conventional +instead to create and start the process by issuing the B +command. =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/upserver.pod b/doc/man-pages/pod8/upserver.pod index c840353a6..8944df1e0 100644 --- a/doc/man-pages/pod8/upserver.pod +++ b/doc/man-pages/pod8/upserver.pod @@ -4,128 +4,110 @@ upserver - Initializes the server portion of the Update Server =head1 SYNOPSIS -B [>+] [B<-crypt> >+] [-clear >+] -[B<-auth> >+] [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. +B [>+] [B<-crypt> >+] + [B<-clear> >+] [B<-auth> >+] [B<-help>] =head1 DESCRIPTION -The upserver command initializes the server portion of the -Update Server (the B process). In the conventional -configuration, its binary file is located in the B -directory on a file server machine. - -The upserver command is not normally issued at the command shell -prompt but rather placed into a file server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a database server machine as the local superuser -B. - -The upserver command specifies which of the directories on the -local disk are eligible for distribution in response to requests from the -client portion of the Update Server (the B process) running -on other machines. If no directories are specified, the -B process distributes the contents of any directory on its -local disk. - -The upserver process can distribute a directory's contents -in encrypted or unencrypted form. By default, it does not use -encryption unless an B process requests it (this default is -equivalent to setting the B<-clear> flag). When the -B<-crypt> flag is provided, the B process only -fulfills requests for encrypted transfer. - -For the United States edition of AFS, using the -crypt flag -guarantees that the B process transfers a directory's -contents only in encrypted form. For the international edition, using -the B<-crypt> flag completely blocks data transfer, because the -international edition of the B process cannot request -encrypted transfer (the B initialization command does not -include the B<-crypt> flag). - -The B and upserver processes always mutually -authenticate, whether or not the data they pass is encrypted; they use -the key with the highest key version number in the -B file to construct a server ticket for mutual -authentication. +The B command initializes the server portion of the Update +Server (the C process). In the conventional configuration, its +binary file is located in the F directory on a file server +machine. + +The B command is not normally issued at the command shell prompt +but rather placed into a file server machine's F +file with the B command. If it is ever issued at the command +shell prompt, the issuer must be logged onto a database server machine as +the local superuser C. + +The B command specifies which of the directories on the local +disk are eligible for distribution in response to requests from the client +portion of the Update Server (the B process) running on other +machines. If no directories are specified, the B process +distributes the contents of any directory on its local disk. + +The B process can distribute a directory's contents in encrypted +or unencrypted form. By default, it does not use encryption unless an +B process requests it (this default is equivalent to setting the +B<-clear> flag). When the B<-crypt> flag is provided, the B +process only fulfills requests for encrypted transfer. + +The B and B processes always mutually authenticate, +whether or not the data they pass is encrypted; they use the key with the +highest key version number in the F file to +construct a server ticket for mutual authentication. + +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. =head1 CAUTIONS Do not use the Update Server to distribute the contents of the -B directory if using the international edition of -AFS. The contents of this directory are sensitive and the international -edition of AFS does not include the encryption routines necessary for -encrypting files before transfer across the network. +F directory without the B<-crypt> flag. The contents of +this directory are sensitive. =head1 OPTIONS =over 4 -=item I +=item >+ Names each directory to distribute in unencrypted form (because they -appear before the first B<-crypt> or B<-clear> flag on the -command line). If this argument is omitted, all directories on the -machine's local disk are eligible for distribution. +appear before the first B<-crypt> or B<-clear> flag on the command +line). If this argument is omitted, all directories on the machine's local +disk are eligible for distribution. -=item -crypt +=item B<-crypt> >+ -Precedes a list of one or more directories that the upserver -process distributes only in encrypted form. +Precedes a list of one or more directories that the B process +distributes only in encrypted form. -=item -clear +=item B<-clear> >+ -Precedes a list of one or more directories that the upserver -process distributes in unencrypted form unless the B process -requests them in encrypted form. Use this argument only if a list of -directories headed by the B<-crypt> flag precedes it on the command -line. +Precedes a list of one or more directories that the B process +distributes in unencrypted form unless the B process requests +them in encrypted form. Use this argument only if a list of directories +headed by the B<-crypt> flag precedes it on the command line. -=item -auth +=item B<-auth> >+ -Precedes a list of one or more directories which the upserver -process distributes using a form of encryption that is intermediate in -complexity and security between the unencrypted and encrypted levels set by -the B<-clear> and B<-crypt> arguments. Do not use this -argument, because the B process does not have a -corresponding argument that it can use to request data transfer at this -level. +Precedes a list of one or more directories which the upserver process +distributes using a form of encryption that is intermediate in complexity +and security between the unencrypted and encrypted levels set by the +B<-clear> and B<-crypt> arguments. Do not use this argument, because the +B process does not have a corresponding argument that it can use +to request data transfer at this level. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following example bos create command defines and starts an -B process on the host machine -B. The last parameter (enclosed in -quotes) instructs the B process to distribute the contents -of the B directory in unencrypted form and the contents -of the B directory in encrypted form. +The following example bos create command defines and starts an B +process on the host machine C. The last parameter (enclosed +in quotes) instructs the B process to distribute the contents of +the F directory in unencrypted form and the contents of the +F directory in encrypted form. - % bos create -server fs1.abc.com -instance upserver -type simple \ - -cmd "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc" + % bos create -server fs1.abc.com -instance upserver -type simple \ + -cmd "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc" =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the superuser root on a file -server machine to issue the command at a command shell prompt. It is -conventional instead to create and start the process by issuing the B command. +The issuer must be logged in as the superuser C on a file server +machine to issue the command at a command shell prompt. It is conventional +instead to create and start the process by issuing the B +command. =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/uss.pod b/doc/man-pages/pod8/uss.pod index c2703d348..e309385ba 100644 --- a/doc/man-pages/pod8/uss.pod +++ b/doc/man-pages/pod8/uss.pod @@ -4,10 +4,10 @@ uss - Introduction to the uss command suite =head1 DESCRIPTION -The commands in the uss command suite help administrators to -create AFS user accounts more easily and efficiently. If B -commands are not used, creating an account requires issuing at least six -separate commands to five different AFS servers. +The commands in the B command suite help administrators to create AFS +user accounts more easily and efficiently. If B commands are not +used, creating an account requires issuing at least six separate commands +to five different AFS servers. There are three main commands in the suite: @@ -15,110 +15,101 @@ There are three main commands in the suite: =item * -The uss add command creates a single complete user account, -based on command line arguments and instructions in a template file. - +The B command creates a single complete user account, based on +command line arguments and instructions in a template file. =item * -The uss bulk command creates multiple complete accounts at -once, based on command line arguments, instructions in a template file and a -bulk input file. - +The B command creates multiple complete accounts at once, based +on command line arguments, instructions in a template file and a bulk +input file. =item * -the uss delete command removes most parts of a user -account. - +The B command removes most parts of a user account. =back -To obtain help, issue the B and uss help -commands. +To obtain help, issue the B and B commands. =head1 OPTIONS The following arguments and flags are available on many commands in the -B suite. The reference page for each command also lists -them, but they are described here in greater detail. +B suite. The reference page for each command also lists them, but +they are described here in greater detail. =over 4 -=item -admin -> +=item B<-admin> > Specifies the AFS user name under which to establish a connection to the AFS server processes that administer the various parts of a user account. If it is omitted, the connection is established under the issuer's effective user ID (his or her identity in the local file system). Even when this argument is included, UNIX commands that run -during the B operation (for instance, the UNIX -B command) run under the effective user ID. +during the B operation (for instance, the UNIX F command) +run under the effective user ID. -=item -cell -> +=item B<-cell> > -Names the cell in which to run the command. It is acceptable to -abbreviate the cell name to the shortest form that distinguishes it from the -other entries in the B file on the local -machine. If the B<-cell> argument is omitted, the command -interpreter determines the name of the local cell by reading the following in -order: +Names the cell in which to run the command. It is acceptable to abbreviate +the cell name to the shortest form that distinguishes it from the other +entries in the F file on the local machine. If +the B<-cell> argument is omitted, the command interpreter determines the +name of the local cell by reading the following in order: -=item * +=over 4 -The value of the AFSCELL environment variable +=item * +The value of the AFSCELL environment variable. =item * -The local /usr/vice/etc/ThisCell file +The local F file. +=back -=item -dryrun +=item B<-dryrun> Reports actions that the command interpreter needs to perform when -executing the B operation, without actually performing -them. Include this flag to verify that the command produces the desired -account configuration. Combine it with the B<-verbose> flag to -yield even more detailed information. Note that the output does not -necessarily reveal all possible problems that can prevent successful execution -of the command, especially those that result from transient server or network -outages. +executing the B operation, without actually performing them. Include +this flag to verify that the command produces the desired account +configuration. Combine it with the B<-verbose> flag to yield even more +detailed information. Note that the output does not necessarily reveal all +possible problems that can prevent successful execution of the command, +especially those that result from transient server or network outages. -=item -help +=item B<-help> -Prints a command's online help message on the standard output -stream. Do not combine this flag with any of the command's other -options; when it is provided, the command interpreter ignores all other -options, and only prints the help message. +Prints a command's online help message on the standard output stream. Do +not combine this flag with any of the command's other options; when it is +provided, the command interpreter ignores all other options, and only +prints the help message. -=item -skipauth +=item B<-skipauth> Bypasses mutual authentication with the AFS Authentication Server, -allowing a site that uses Kerberos instead of the AFS Authentication Server to -substitute that form of authentication. +allowing a site that uses Kerberos instead of the AFS Authentication +Server to substitute that form of authentication. =back =head1 PRIVILEGE REQUIRED -The issuer of a uss command must have all the rights required -for performing the equivalent actions individually. See each -B command's reference page. +The issuer of a B command must have all the rights required for +performing the equivalent actions individually. See each B command's +reference page. =head1 SEE ALSO -L - -L - -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/uss_add.pod b/doc/man-pages/pod8/uss_add.pod index 3e47a69de..080fb5a40 100644 --- a/doc/man-pages/pod8/uss_add.pod +++ b/doc/man-pages/pod8/uss_add.pod @@ -4,328 +4,316 @@ uss add - Creates a user account =head1 SYNOPSIS -B > [-realname >] -[B<-pass> >] - [-pwexpires never)>>] - [-server >] - [-partition >] - [-mount >] - [-uid >] - [-template >] - [B<-verbose>] [-var >+] - [B<-cell> >] [-admin >] - [B<-dryrun>] [B<-skipauth>] [B<-overwrite>] [-help] - -B > [-r >] -[B<-pas> >] - [-pw never)>>] - [-se >] - [-par >] - [B<-m> >] [-ui >] - [B<-t> >] [-ve] - [B<-va> >+] [-c >] - [B<-a> >] [B<-d>] [B<-sk>] [B<-o>] [-h] +B B<-user> > [B<-realname> >] + [B<-pass> >] + [B<-pwexpires> never) >>>] + [B<-server> >] + [B<-partition> >] + [B<-mount> >] + [B<-uid> >] + [B<-template> >] + [B<-verbose>] [B<-var> >+] + [B<-cell> >] [B<-admin> >] + [B<-dryrun>] [B<-skipauth>] [B<-overwrite>] [B<-help>] + +B B<-us> > [B<-r> >] + [B<-pas> >] + [B<-pw> never) >>>] + [B<-se> >] + [B<-par> >] + [B<-m> >] + [B<-ui> >] + [B<-t> >] [B<-ve>] + [B<-va> >+] [B<-c> >] + [B<-a> >] [B<-d>] [B<-sk>] [B<-o>] + [B<-h>] =head1 DESCRIPTION -The uss add command creates entries in the Protection Database -and Authentication Database for the user name specified by the -B<-user> argument. By default, the Protection Server -automatically allocates an AFS user ID (UID) for the new user; to specify -an alternate AFS UID, include the B<-uid> argument. If a -password is provided with the B<-pass> argument, it is stored as the -user's password in the Authentication Database after conversion into a -form suitable for use as an encryption key. Otherwise, the string -B is assigned as the user's initial password. +The B command creates entries in the Protection Database and +Authentication Database for the user name specified by the B<-user> +argument. By default, the Protection Server automatically allocates an AFS +user ID (UID) for the new user; to specify an alternate AFS UID, include +the B<-uid> argument. If a password is provided with the B<-pass> +argument, it is stored as the user's password in the Authentication +Database after conversion into a form suitable for use as an encryption +key. Otherwise, the string C is assigned as the user's initial +password. The other results of the command depend on which instructions and which of a defined set of variables appear in the template file specified with the -B<-template> argument. Many of the command's arguments -supply a value for one of the defined variables, and failure to provide an -argument when the corresponding variable appears in the template file halts -the account creation process at the point where the command interpreter first +B<-template> argument. Many of the command's arguments supply a value for +one of the defined variables, and failure to provide an argument when the +corresponding variable appears in the template file halts the account +creation process at the point where the command interpreter first encounters the variable in the template file. -To create multiple accounts with a single command, use the uss -bulk command. To delete accounts with a single command, use the -B command. +To create multiple accounts with a single command, use the B +command. To delete accounts with a single command, use the B +command. =head1 OPTIONS =over 4 -=item -user +=item B<-user> > Names the user's Authentication Database and Protection Database -entries. It can include up to eight alphanumeric characters, but not -any of the following characters: B<:> (colon), -B<@> (at-sign), B<.> (period), space, or -newline. Because it becomes the username (the name under which a user -logs in), it is best not to include shell metacharacters and to obey the -restrictions that many operating systems impose on usernames (usually, to -contain no more than eight lowercase letters). +entries. It can include up to eight alphanumeric characters, but not any +of the following characters: C<:> (colon), C<@> (at-sign), C<.> (period), +space, or newline. Because it becomes the username (the name under which a +user logs in), it is best not to include shell metacharacters and to obey +the restrictions that many operating systems impose on usernames (usually, +to contain no more than eight lowercase letters). Corresponding variable in the template file: $USER. -=item -realname +=item B<-realname> > -Specifies the user's full name. If it contains spaces or -punctuation, surround it with double quotes. If not provided, it -defaults to the user name provided with the B<-user> argument. +Specifies the user's full name. If it contains spaces or punctuation, +surround it with double quotes. If not provided, it defaults to the user +name provided with the B<-user> argument. -Corresponding variable in the template file: $NAME. Many -operating systems include a field for the full name in a user's entry in -the local password file (B or equivalent), and this -variable can be used to pass a value to be used in that field. +Corresponding variable in the template file: $NAME. Many operating systems +include a field for the full name in a user's entry in the local password +file (F or equivalent), and this variable can be used to pass +a value to be used in that field. -=item -pass +=item B<-pass> > -Specifies the user's initial password. Although the AFS -commands that handle passwords accept strings of virtually unlimited length, -it is best to use a password of eight characters or less, which is the maximum -length that many applications and utilities accept. If not provided, -this argument defaults to the string B. +Specifies the user's initial password. Although the AFS commands that +handle passwords accept strings of virtually unlimited length, it is best +to use a password of eight characters or less, which is the maximum length +that many applications and utilities accept. If not provided, this +argument defaults to the string C. Corresponding variable in the template file: none. -=item -pwexpires +=item B<-pwexpires> > -Sets the number of days after a user's password is changed that it -remains valid. Provide an integer from the range B<1> through -B<254> to specify the number of days until expiration, or the value -B<0> to indicate that the password never expires (the default). +Sets the number of days after a user's password is changed that it remains +valid. Provide an integer from the range C<1> through C<254> to specify +the number of days until expiration, or the value C<0> to indicate that +the password never expires (the default). When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the B -command to change the password (after that, only an administrator can change -it). +command to change the password (after that, only an administrator can +change it). Corresponding variable in the template file: $PWEXPIRES. -=item -server +=item B<-server> > -Names the file server machine on which to create the new user's -volume. It is best to provide a fully qualified hostname (for example, -B), but an abbreviated form is acceptable -provided that the cell's naming service is available to resolve it at the -time the volume is created. +Names the file server machine on which to create the new user's volume. It +is best to provide a fully qualified hostname (for example, +C), but an abbreviated form is acceptable provided that the +cell's naming service is available to resolve it at the time the volume is +created. Corresponding variable in the template file: $SERVER. -=item -partition +=item B<-partition> > -Specifies the partition on which to create the user's volume; it -must be on the file server machine named by the B<-server> -argument. Provide the complete partition name (for example -B) or one of the following abbreviated forms: +Specifies the partition on which to create the user's volume; it must be +on the file server machine named by the B<-server> argument. Provide the +complete partition name (for example F) or one of the following +abbreviated forms: - B = B = B = 0 - B = B = B = 1 + /vicepa = vicepa = a = 0 + /vicepb = vicepb = b = 1 -After /vicepz (for which the index is 25) comes +After F (for which the index is 25) comes - B = B = B = 26 - B = B = B = 27 + /vicepaa = vicepaa = aa = 26 + /vicepab = vicepab = ab = 27 and so on through - B = B = B = 255 + /vicepiv = vicepiv = iv = 255 Corresponding variable in the template file: $PART. -=item -mount +=item B<-mount> > -Specifies the pathname for the user's home directory. Partial -pathnames are interpreted relative to the current working directory. +Specifies the pathname for the user's home directory. Partial pathnames +are interpreted relative to the current working directory. Specify the read/write path to the directory, to avoid the failure that results from attempting to create a new mount point in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, -B). For further discussion of the -concept of read/write and read-only paths through the filespace, see the -B reference page. - -Corresponding variable in template: $MTPT, but in the template -file's B instruction only. Occurrences of the $MTPT -variable in template instructions that follow the B instruction -take their value from the B instruction's -B field. Thus the value of this command line -argument becomes the value for the $MTPT variable in instructions that follow -the B instruction only if the string $MTPT appears alone in the -B instruction's B field. - -=item -uid - -Specifies a positive integer other than 0 (zero) to assign as the -user's AFS UID. If this argument is omitted, the Protection Server -assigns an AFS UID that is one greater than the current value of the -C C C counter (use the B command to display the counter). If including this -argument, it is best first to use the B command to verify -that no existing account already has the desired AFS UID; it one does, -the account creation process terminates with an error. +F). For further discussion of the concept of read/write and +read-only paths through the filespace, see the B reference +page. + +Corresponding variable in template: $MTPT, but in the template file's C +instruction only. Occurrences of the $MTPT variable in template +instructions that follow the C instruction take their value from the +C instruction's I field. Thus the value of this command +line argument becomes the value for the $MTPT variable in instructions +that follow the C instruction only if the string $MTPT appears alone in +the C instruction's I field. + +=item B<-uid> > + +Specifies a positive integer other than 0 (zero) to assign as the user's +AFS UID. If this argument is omitted, the Protection Server assigns an AFS +UID that is one greater than the current value of the C +counter (use the B command to display the counter). If +including this argument, it is best first to use the B +command to verify that no existing account already has the desired AFS +UID; it one does, the account creation process terminates with an error. Corresponding variable in the template file: $UID. -=item -template +=item B<-template> > -Specifies the pathname of the template file. If this argument is -omitted, the command interpreter searches the following directories in the -indicated order for a file called B: +Specifies the pathname of the template file. If this argument is omitted, +the command interpreter searches the following directories in the +indicated order for a file called C: -=item * +=over 4 -The current working directory +=item * +The current working directory. =item * -BI/common/uss, where -I names the local cell - +F/common/uss>, where I names the local cell. =item * -/etc +F +=back -If the issuer provides a filename other than uss.template -but without a pathname, the command interpreter searches for it in the -indicated directories. If the issuer provides a full or partial -pathname, the command interpreter consults the specified file only; it -interprets partial pathnames relative to the current working directory. +If the issuer provides a filename other than C but without a +pathname, the command interpreter searches for it in the indicated +directories. If the issuer provides a full or partial pathname, the +command interpreter consults the specified file only; it interprets +partial pathnames relative to the current working directory. If the specified template file is empty (zero-length), the command creates -Protection and Authentication Database entries only. +Protection and Authentication Database entries only. -The uss Template File reference page details the file's -format. +L details the file's format. -=item -verbose +=item B<-verbose> -Produces on the standard output stream a detailed trace of the -command's execution. If this argument is omitted, only warnings -and error messages appear. +Produces on the standard output stream a detailed trace of the command's +execution. If this argument is omitted, only warnings and error messages +appear. -=item -var +=item B<-var> > Specifies values for each of the number variables $1 through $9 that can -appear in the template file. Use the number variables to assign values -to variables in the B template file that are not part of the -standard set. +appear in the template file. Use the number variables to assign values to +variables in the B template file that are not part of the standard +set. Corresponding variables in the template file: $1 through $9. For each instance of this argument, provide two parts in the indicated -order, separated by a space: +order, separated by a space: =over 4 =item * -The integer from the range B<1> through 9 that matches -the variable in the template file. Do not precede it with a dollar -sign. - +The integer from the range C<1> through C<9> that matches the variable in +the template file. Do not precede it with a dollar sign. =item * A string of alphanumeric characters to assign as the value of the variable. - =back -See the chapter on uss in the I for further explanation. +See the chapter on uss in the I for further +explanation. -=item -cell +=item B<-cell> > -Specifies the cell in which to run the command. For more details, -see the introductory B reference page. +Specifies the cell in which to run the command. For more details, see +L. -=item -admin +=item B<-admin> > Specifies the AFS user name under which to establish authenticated -connections to the AFS server processes that maintain the various components -of a user account. For more details, see the introductory -B reference page. +connections to the AFS server processes that maintain the various +components of a user account. For more details, see L. -=item -dryrun +=item B<-dryrun> Reports actions that the command interpreter needs to perform while -executing the command, without actually performing them. For more -details, see the introductory B reference page. +executing the command, without actually performing them. For more details, +see L. -=item -skipauth +=item B<-skipauth> Prevents authentication with the AFS Authentication Server, allowing a site using Kerberos to substitute that form of authentication. -=item -overwrite +=item B<-overwrite> Overwrites any directories, files and links that exist in the file system -and for which there are definitions in B, B, -B, B, or B instructions in the template file -named by the B<-template> argument. If this flag is omitted, -the command interpreter prompts once for confirmation that it is to overwrite -all such elements. +and for which there are definitions in C, C, C, C, or C +instructions in the template file named by the B<-template> argument. If +this flag is omitted, the command interpreter prompts once for +confirmation that it is to overwrite all such elements. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The combination of the following example uss add command and -B instruction in a template file called B -creates Protection and Authentication Database entries named B, -and a volume called C with a quota of 2500 kilobyte -blocks, mounted at the pathname -B. The access control list (ACL) -on the mount point grants B all rights. - -The issuer of the uss add command provides only the template -file's name, not its complete pathname, because it resides in the current -working directory. The command and B instruction appear here -on two lines only for legibility; there are no line breaks in the actual -instruction or command. - - V user.$USER $SERVER.abc.com /vice$PART $1 \ +The combination of the following example uss add command and C +instruction in a template file called C creates Protection and +Authentication Database entries named C, and a volume called +C with a quota of 2500 kilobyte blocks, mounted at the +pathname F. The access control list (ACL) on the +mount point grants C all rights. + +The issuer of the B command provides only the template file's +name, not its complete pathname, because it resides in the current working +directory. The command and C instruction appear here on two lines only +for legibility; there are no line breaks in the actual instruction or +command. + + V user.$USER $SERVER.abc.com /vice$PART $1 \ /afs/abc.com/usr/$USER $UID $USER all - % uss add -user smith -realname "John Smith" -pass js_pswd -server fs2 \ - -partition b -template uss.tpl -var 1 2500 - + % uss add -user smith -realname "John Smith" -pass js_pswd \ + -server fs2 -partition b -template uss.tpl -var 1 2500 =head1 PRIVILEGE REQUIRED -The issuer (or the user named by the -admin argument) must -belong to the B group in the Protection -Database and must have the C flag turned on in his or her -Authentication Database entry. +The issuer (or the user named by the B<-admin> argument) must belong to +the system:administrators group in the Protection Database and must have +the C flag turned on in his or her Authentication Database entry. -If the template contains a V instruction, the issuer must be -listed in the B file and must have at least -B (B) and B (B) -permissions on the ACL of the directory that houses the new mount -point. If the template file includes instructions for creating other -types of objects (directories, files or links), the issuer must have each -privilege necessary to create them. +If the template contains a C instruction, the issuer must be listed in +the F file and must have at least C (administer) +and C (insert) permissions on the ACL of the directory that houses the +new mount point. If the template file includes instructions for creating +other types of objects (directories, files or links), the issuer must have +each privilege necessary to create them. =head1 SEE ALSO -L, -L - +L, +L, L, -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/uss_apropos.pod b/doc/man-pages/pod8/uss_apropos.pod index 215c947d2..e7db9677d 100644 --- a/doc/man-pages/pod8/uss_apropos.pod +++ b/doc/man-pages/pod8/uss_apropos.pod @@ -4,34 +4,32 @@ uss apropos - Displays each help entry containing a keyword string. =head1 SYNOPSIS -B > [-help] +B B<-topic> > [B<-help>] -B > [-h] +B B<-t> > [B<-h>] =head1 DESCRIPTION -The uss apropos command displays the first line of the online -help entry for any B command that has in its name or short -description the string specified by the B<-topic> argument. +The B command displays the first line of the online help +entry for any B 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 uss help -command. +To display the syntax for a command, use the B command. =head1 OPTIONS =over 4 -=item -topic -> +=item B<-topic> >+ -Specifies the keyword string to match, in lowercase letters only. -If the string is more than a single word, surround it with double quotes ("") +Specifies the keyword string to match, in lowercase letters only. If the +string is more than a single word, surround it with double quotes (C<"">) or other delimiters. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -39,13 +37,13 @@ are ignored. 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 -B command where the string specified by the B<-topic> -argument is part of the command name or first line. +B command where the string specified by the B<-topic> argument is +part of the command name or first line. =head1 EXAMPLES -The following command lists all uss commands that include the -word B in their names or short descriptions: +The following command lists all uss commands that include the word +C in their names or short descriptions: % uss apropos create add: create a new user @@ -56,8 +54,8 @@ None =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/uss_bulk.pod b/doc/man-pages/pod8/uss_bulk.pod index b8ad687d4..7aa71dbef 100644 --- a/doc/man-pages/pod8/uss_bulk.pod +++ b/doc/man-pages/pod8/uss_bulk.pod @@ -4,141 +4,137 @@ uss bulk - Executes multiple uss commands listed in a file =head1 SYNOPSIS -B > [-template >] -[B<-verbose>] [B<-cell> >] - [B<-admin> >] [-dryrun] - [B<-skipauth>] [-overwrite] - [-pwexpires never)>>] - [B<-pipe>] [-help] - -B > [B<-t> >] [-v] -[B<-c> >] [B<-a> >] [B<-d>] [B<-s>] - [B<-o>] [-pw never)>>] - [B<-pi>] [-h] +B B<-file> > + [B<-template> >] [B<-verbose>] + [B<-cell> >] + [B<-admin> >] [B<-dryrun>] + [B<-skipauth>] [B<-overwrite>] + [B<-pwexpires> never)>>] + [B<-pipe>] [B<-help>] + +B B<-f> > [B<-t> >] + [B<-v>] [B<-c> >] + [B<-a> >] [B<-d>] [B<-s>] + [B<-o>] [B<-pw> never)>>] + [B<-pi>] [B<-h>] =head1 DESCRIPTION -The B command executes the uss commands listed -in the B specified with the B<-file> -argument. If the bulk input file includes B instructions -that reference a template file, then the B<-template> argument is -required. +The B command executes the uss commands listed in the I specified with the B<-file> argument. If the bulk input file +includes B instructions that reference a template file, then the +B<-template> argument is required. -To create a single account, use the uss add command. To -delete one or more accounts, use the B command. +To create a single account, use the B command. To delete one or +more accounts, use the B command. =head1 OPTIONS =over 4 -=item -file +=item B<-file> > -Specifies the pathname of the bulk input file. Partial pathnames -are interpreted relative to the current working directory. For details -on the file's format, see L. +Specifies the pathname of the bulk input file. Partial pathnames are +interpreted relative to the current working directory. For details on the +file's format, see L. -=item -template +=item B<-template> > -Specifies the pathname of the template file for any uss add -commands that appear in the bulk input file. Partial pathnames are -interpreted relative to the current working directory. For details on -the file's format, see L. +Specifies the pathname of the template file for any uss add commands that +appear in the bulk input file. Partial pathnames are interpreted relative +to the current working directory. For details on the file's format, see +L. -=item -verbose +=item B<-verbose> -Produces on the standard output stream a detailed trace of the -command's execution. If this argument is omitted, only warnings -and error messages appear. +Produces on the standard output stream a detailed trace of the command's +execution. If this argument is omitted, only warnings and error messages +appear. -=item -cell +=item B<-cell> > -Specifies the cell in which to run the command. For more details, -see the introductory B reference page. +Specifies the cell in which to run the command. For more details, see +L. -=item -admin +=item B<-admin> > Specifies the AFS user name under which to establish authenticated -connections to the AFS server processes that maintain the various components -of a user account. For more details, see the introductory -B reference page. +connections to the AFS server processes that maintain the various +components of a user account. For more details, see L. -=item -dryrun +=item B<-dryrun> Reports actions that the command interpreter needs to perform while -executing the command, without actually performing them. For more -details, see the introductory B reference page. +executing the command, without actually performing them. For more details, +see L. -=item -skipauth +=item B<-skipauth> Prevents authentication with the AFS Authentication Server, allowing a site using Kerberos to substitute that form of authentication. -=item -overwrite +=item B<-overwrite> Overwrites any directories, files and links that exist in the file system -and for which there are also B, B, B, -B, or B instructions in a template file referenced by an -B instruction in the bulk input file. If this flag is -omitted, the command interpreter prompts, once for each B -instruction in the bulk input file, for confirmation that it should overwrite -such elements. Do not include this flag if the bulk input file does not -contain B instructions. - -=item -pwexpires - -Sets the number of days after a user's password is changed that it -remains valid, for each user named by an B instruction in the -bulk input file. Provide an integer from the range B<1> through -B<254> to specify the number of days until expiration, or the value -B<0> to indicate that the password never expires (the default). +and for which there are also C, C, C, C, or C instructions +in a template file referenced by an C instruction in the bulk input +file. If this flag is omitted, the command interpreter prompts, once for +each C instruction in the bulk input file, for confirmation that it +should overwrite such elements. Do not include this flag if the bulk input +file does not contain C instructions. + +=item B<-pwexpires> > + +Sets the number of days after a user's password is changed that it remains +valid, for each user named by an C instruction in the bulk input +file. Provide an integer from the range C<1> through C<254> to specify the +number of days until expiration, or the value C<0> to indicate that the +password never expires (the default). When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the B -command to change the password (after that, only an administrator can change -it). +command to change the password (after that, only an administrator can +change it). -=item -pipe +=item B<-pipe> Suppresses the Authentication Server's prompt for the password of the issuer or the user named by the B<-admin> argument (the Authentication Server always separately authenticates the creator of an entry in the Authentication Database). Instead, the command interpreter accepts the password via the standard input stream, as piped in from another -program. This enables the B command to run as part of -unattended batch jobs. +program. This enables the B command to run as part of unattended +batch jobs. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES The following example command executes the instructions in the bulk input -file called B, which includes B -instructions that refer to the template file -B. Both files reside in the current +file called F, which includes C instructions that refer +to the template file F. Both files reside in the current working directory. % uss bulk new_students student.template =head1 PRIVILEGE REQUIRED -The issuer (or the user named by the -admin argument) must have -the privileges necessary to run the commands that correspond to instructions +The issuer (or the user named by the B<-admin> argument) must have the +privileges necessary to run the commands that correspond to instructions in the bulk input file. =head1 SEE ALSO -L - -L - -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/uss_delete.pod b/doc/man-pages/pod8/uss_delete.pod index ab9bd81eb..9efbd39fb 100644 --- a/doc/man-pages/pod8/uss_delete.pod +++ b/doc/man-pages/pod8/uss_delete.pod @@ -4,46 +4,42 @@ uss delete - Deletes a user account =head1 SYNOPSIS -B > [-mountpoint >] -[B<-savevolume>] [B<-verbose>] [B<-cell> >] - [B<-admin> >] [-dryrun] - [B<-skipauth>] [-help] +B B<-user> > + [B<-mountpoint> >] + [B<-savevolume>] [B<-verbose>] [B<-cell> >] + [B<-admin> >] [B<-dryrun>] + [B<-skipauth>] [B<-help>] -B > [B<-m> >] [B<-sa>] [-v] -[B<-c> >] B<-a> >] - [B<-d>] [B<-sk>] [-h] +B B<-u> > [B<-m> >] + [B<-sa>] [B<-v>] [B<-c> >] + [B<-a> >] [B<-d>] [B<-sk>] [B<-h>] =head1 DESCRIPTION -The uss delete command removes the Authentication Database and -Protection Database entries for the user named by B<-user> -argument. In addition, it can remove the user's home volume and -associated VLDB entry, a mount point for the volume or both, depending on -whether the B<-mountpoint> and B<-savevolume> options are -provided. +The B command removes the Authentication Database and +Protection Database entries for the user named by B<-user> argument. In +addition, it can remove the user's home volume and associated VLDB entry, +a mount point for the volume or both, depending on whether the +B<-mountpoint> and B<-savevolume> options are provided. =over 4 =item * -To remove both the volume and mount point, use the -mountpoint -argument to name the user's home directory. It is best to create a -tape backup of a volume before deleting it. Note that other mount -points for the volume are not removed, if they exist. - +To remove both the volume and mount point, use the B<-mountpoint> argument +to name the user's home directory. It is best to create a tape backup of a +volume before deleting it. Note that other mount points for the volume are +not removed, if they exist. =item * -To remove the mount point only, provide both the -mountpoint -and B<-savevolume> options. - +To remove the mount point only, provide both the B<-mountpoint> and +B<-savevolume> options. =item * -To preserve both the volume and mount point, omit the -B<-mountpoint> argument (or both it and the B<-savevolume> -flag). - +To preserve both the volume and mount point, omit the B<-mountpoint> +argument (or both it and the B<-savevolume> flag). =back @@ -51,93 +47,90 @@ flag). =over 4 -=item -user +=item B<-user> > Names the entry to delete from the Protection and Authentication Databases. -=item -mountpoint +=item B<-mountpoint> > -Specifies the pathname to the user's home directory, which is deleted -from the filespace. By default, the volume referenced by the mount -point is also removed from the file server machine that houses it, along with -its Volume Location Database (VLDB) entry. To retain the volume and -VLDB entry, include the B<-savevolume> flag. Partial pathnames -are interpreted relative to the current working directory. +Specifies the pathname to the user's home directory, which is deleted from +the filespace. By default, the volume referenced by the mount point is +also removed from the file server machine that houses it, along with its +Volume Location Database (VLDB) entry. To retain the volume and VLDB +entry, include the B<-savevolume> flag. Partial pathnames are interpreted +relative to the current working directory. Specify the read/write path to the mount point, to avoid the failure that results from attempting to remove a mount point from a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, -B). For further discussion of the -concept of read/write and read-only paths through the filespace, see the -B reference page. +F). For further discussion of the concept of read/write and +read-only paths through the filespace, see the B reference +page. -=item -savevolume +=item B<-savevolume> Preserves the user's volume and VLDB entry. -=item -verbose +=item B<-verbose> -Produces on the standard output stream a detailed trace of the -command's execution. If this argument is omitted, only warnings -and error messages appear. +Produces on the standard output stream a detailed trace of the command's +execution. If this argument is omitted, only warnings and error messages +appear. -=item -cell +=item B<-cell> > -Specifies the cell in which to run the command. For more details, -see the introductory B reference page. +Specifies the cell in which to run the command. For more details, see +L. -=item -admin +=item B<-admin> > Specifies the AFS user name under which to establish authenticated -connections to the AFS server processes that maintain the various components -of a user account. For more details, see the introductory -B reference page. +connections to the AFS server processes that maintain the various +components of a user account. For more details, see L. -=item -dryrun +=item B<-dryrun> Reports actions that the command interpreter needs to perform while -executing the command, without actually performing them. For more -details, see the introductory B reference page. +executing the command, without actually performing them. For more details, +see L. -=item -skipauth +=item B<-skipauth> Prevents authentication with the AFS Authentication Server, allowing a site using Kerberos to substitute that form of authentication. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command removes smith's user account from the -B cell. The B<-savevolume> argument -retains the C volume on its file server -machine. +The following command removes smith's user account from the C +cell. The B<-savevolume> argument retains the C volume on its +file server machine. % uss delete smith -mountpoint /afs/abc.com/usr/smith -savevolume =head1 PRIVILEGE REQUIRED -The issuer (or the user named by -admin argument) must belong to -the B group in the Protection Database, -must have the C flag turned on in his or her Authentication -Database entry, and must have at least B (B) -and B (B) permissions on the access control list -(ACL) of the mount point's parent directory. If the -B<-savevolume> flag is not included, the issuer must also be listed in -the B file. +The issuer (or the user named by B<-admin> argument) must belong to the +system:administrators group in the Protection Database, must have the +C flag turned on in his or her Authentication Database entry, and +must have at least C (administer) and C (delete) permissions on the +access control list (ACL) of the mount point's parent directory. If the +B<-savevolume> flag is not included, the issuer must also be listed in the +F file. =head1 SEE ALSO -L, +L, L, -L +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/uss_help.pod b/doc/man-pages/pod8/uss_help.pod index 19533b47e..e583a4f40 100644 --- a/doc/man-pages/pod8/uss_help.pod +++ b/doc/man-pages/pod8/uss_help.pod @@ -1,76 +1,69 @@ =head1 NAME -uss help - Displays the syntax of specified uss commands or lists -functional descriptions of all B commands +uss help - Displays help for uss commands =head1 SYNOPSIS -B [B<-topic> >+] [-help] +B [B<-topic> >+] [B<-help>] -B [B<-t> >+] [-h] +B [B<-t> >+] [B<-h>] =head1 DESCRIPTION -The uss help command displays the complete online help entry -(short description and syntax statement) for each command operation code -specified by the B<-topic> argument. If the B<-topic> -argument is omitted, the output includes the first line (name and short -description) of the online help entry for every B command. +The B command displays the complete online help entry (short +description and syntax statement) for each command operation code +specified by the B<-topic> argument. If the B<-topic> argument is omitted, +the output includes the first line (name and short description) of the +online help entry for every B command. -To list every uss command whose name or short description -includes a specified keyword, use the B command. +To list every uss command whose name or short description includes a +specified keyword, use the B command. =head1 OPTIONS =over 4 -=item -topic +=item B<-topic> >+ Indicates each command for which to display the complete online help -entry. Omit the B part of the command name, providing only -the operation code (for example, specify B, not B). If this argument is omitted, the output briefly describes -every B command. +entry. Omit the B part of the command name, providing only the +operation code (for example, specify B, not B). If this +argument is omitted, the output briefly describes every B command. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT -The online help entry for each uss command consists of the -following two or three lines: +The online help entry for each uss command consists of the following two +or three lines: =over 4 =item * -The first line names the command and briefly describes its -function. - +The first line names the command and briefly describes its function. =item * The second line lists aliases for the command, if any. - =item * -The final line, which begins with the string C, lists the -command's options in the prescribed order. Online help entries use -the same symbols (for example, brackets) as the reference pages in this -document. - +The final line, which begins with the string C, lists the command's +options in the prescribed order. Online help entries use the same symbols +(for example, brackets) as the reference pages in this document. =back =head1 EXAMPLES -The following command displays the online help entry for the uss -bulk command: +The following command displays the online help entry for the B +command: % uss help bulk uss bulk: bulk input mode @@ -86,8 +79,8 @@ None =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/vldb_check.pod b/doc/man-pages/pod8/vldb_check.pod index 7a121e1eb..e9a480d11 100644 --- a/doc/man-pages/pod8/vldb_check.pod +++ b/doc/man-pages/pod8/vldb_check.pod @@ -4,91 +4,86 @@ vldb_check - Checks the integrity of the VLDB =head1 SYNOPSIS -B > [B<-uheader>] [B<-vheader>] [-servers] -[B<-entries>] [B<-verbose>] [B<-help>] +B B<-database> > [B<-uheader>] [B<-vheader>] + [B<-servers>] [B<-entries>] [B<-verbose>] [B<-help>] -B > [B<-u>] [B<-vh>] [B<-s>] [B<-e>] [B<-ve>] [-h] +B B<-d> > [B<-u>] [B<-vh>] [B<-s>] [B<-e>] + [B<-ve>] [B<-h>] =head1 DESCRIPTION -The vldb_check command checks the integrity of the Volume -Location Database (VLDB), reporting any errors or corruption it finds. -If there are problems, do not issue any B commands until the -database is repaired. +The B command checks the integrity of the Volume Location +Database (VLDB), reporting any errors or corruption it finds. If there +are problems, do not issue any B commands until the database is +repaired. =head1 CAUTIONS The results can be unpredictable if the Volume Location (VL) Server makes -changes to the VLDB while this command is running. Use the B command to shutdown the local B process -before running this command, or before creating a second copy of the -B file (with a different name) on which to run the -command. +changes to the VLDB while this command is running. Use the B +command to shutdown the local B process before running this +command, or before creating a second copy of the F file (with a +different name) on which to run the command. =head1 OPTIONS =over 4 -=item -database +=item B<-database> > -Names the VLDB (copy of the vldb.DB0 file) to -check. If the current working directory is not the location of the -file, provide a pathname, either full or relative to the current working -directory. +Names the VLDB (copy of the F file) to check. If the current +working directory is not the location of the file, provide a pathname, +either full or relative to the current working directory. -=item -uheader +=item B<-uheader> -Displays information which Ubik maintains in the database's -header. +Displays information which Ubik maintains in the database's header. -=item -pheader +=item B<-pheader> Displays information which the VL Server maintains in the database's header. -=item -servers +=item B<-servers> >+ Outputs the server entries from the VLDB, which list the IP addresses registered for each file server machine in the cell. -=item -entries +=item B<-entries> -Outputs every volume entry in the database. The information -includes the volume's name and the volume ID number for each of its -versions. +Outputs every volume entry in the database. The information includes the +volume's name and the volume ID number for each of its versions. -=item -verbose +=item B<-verbose> Reports additional information about the database, including the number of entries for each type of volume. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 OUTPUT If there are errors in the database, the output always reports them on the -standard error stream. If any options other than B<-database> -or B<-help> are provided, the output written to the standard output -stream includes additional information as described for each option in the -preceding B section of this reference page. The output -is intended for debugging purposes and is meaningful to someone familiar with -the internal structure of the VLDB. +standard error stream. If any options other than B<-database> or B<-help> +are provided, the output written to the standard output stream includes +additional information as described for each option in L. The +output is intended for debugging purposes and is meaningful to someone +familiar with the internal structure of the VLDB. =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the local superuser root. +The issuer must be logged in as the local superuser C. =head1 SEE ALSO -L - -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/vlserver.pod b/doc/man-pages/pod8/vlserver.pod index 57bcd657b..e55ecf7d7 100644 --- a/doc/man-pages/pod8/vlserver.pod +++ b/doc/man-pages/pod8/vlserver.pod @@ -4,75 +4,72 @@ vlserver - Initializes the Volume Location Server =head1 SYNOPSIS -B [B<-p> >] [-nojumbo] -[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. +B [B<-p> >] [B<-nojumbo>] + [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>] =head1 DESCRIPTION -The vlserver command initializes the Volume Location (VL) -Server, which runs on every database server machine. In the -conventional configuration, its binary file is located in the -B directory on a file server machine. +The B command initializes the Volume Location (VL) Server, which +runs on every database server machine. In the conventional configuration, +its binary file is located in the F directory on a file +server machine. -The vlserver command is not normally issued at the command shell -prompt but rather placed into a file server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a database server machine as the local superuser -B. +The B command is not normally issued at the command shell prompt +but rather placed into a file server machine's F +file with the B command. If it is ever issued at the command +shell prompt, the issuer must be logged onto a database server machine as +the local superuser C. As it initializes, the VL Server process creates the two files that -constitute the Volume Location Database (VLDB), B and -B, in the B directory if they -do not already exist. Use the commands in the B suite to -administer the database. +constitute the Volume Location Database (VLDB), F and +F, in the F directory if they do not already +exist. Use the commands in the B suite to administer the database. The VL Server maintains the record of volume locations in the Volume -Location Database (VLDB). When the Cache Manager fills a file request -from an application program, it first contacts the VL Server to learn which +Location Database (VLDB). When the Cache Manager fills a file request from +an application program, it first contacts the VL Server to learn which file server machine currently houses the volume that contains the file. -The Cache Manager then requests the file from the File Server process running -on that file server machine. +The Cache Manager then requests the file from the File Server process +running on that file server machine. The VL Server records a trace of its activity in the -B file. Use the B -command to display the contents of the file. By default, it records on -a minimal number of messages. For instructions on increasing the amount -of logging, see the B reference page. +F file. Use the B command to display the +contents of the file. By default, it records on a minimal number of +messages. For instructions on increasing the amount of logging, see +L. By default, the VL Server runs nine lightweight processes (LWPs). To change the number, use the B<-p> argument. +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + =head1 OPTIONS =over 4 -=item -p +=item B<-p> > -Sets the number of server lightweight processes (LWPs) to run. -Provide an integer between B<4> and B<16>. The default -is 9. +Sets the number of server lightweight processes (LWPs) to run. Provide an +integer between C<4> and C<16>. The default is C<9>. -=item -nojumbo +=item B<-nojumbo> -Prohibits the server from sending or receiving jumbograms. A -jumbogram is a large-size packet composed of 2 to 4 normal Rx data packets -that share the same header. The VL Server uses jumbograms by default, -but some routers are not capable of properly breaking the jumbogram into -smaller packets and reassembling them. +Prohibits the server from sending or receiving jumbograms. A jumbogram is +a large-size packet composed of 2 to 4 normal Rx data packets that share +the same header. The VL Server uses jumbograms by default, but some +routers are not capable of properly breaking the jumbogram into smaller +packets and reassembling them. -=item -enable_peer_stats +=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. +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 -enable_process_stats +=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, @@ -80,37 +77,36 @@ 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 -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following B command creates a vlserver -process on the machine B that uses six -lightweight processes. Type the command on a single line: +The following B command creates a vlserver process on the +machine C that uses six lightweight processes. Type the +command on a single line: - % bos create -server fs2.abc.com -instance vlserver -type simple \ + % bos create -server fs2.abc.com -instance vlserver -type simple \ -cmd "/usr/afs/bin/vlserver -p 6" =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the superuser root on a file -server machine to issue the command at a command shell prompt. It is -conventional instead to create and start the process by issuing the B command. +The issuer must be logged in as the superuser C on a file server +machine to issue the command at a command shell prompt. It is conventional +instead to create and start the process by issuing the B +command. =head1 SEE ALSO -L, -L, -L - -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/volinfo.pod b/doc/man-pages/pod8/volinfo.pod index 060210e86..bf5e953a3 100644 --- a/doc/man-pages/pod8/volinfo.pod +++ b/doc/man-pages/pod8/volinfo.pod @@ -1,108 +1,103 @@ =head1 NAME -volinfo - Produces detailed statistics about one or more volume headers and the -partition that houses them +volinfo - Produces detailed statistics about AFS volume headers =head1 SYNOPSIS -B [B<-online>] [B<-vnode>] [B<-date>] [B<-inode>] [-itime] -[B<-part> >+] - [B<-volumeid> >+] [B<-header>] [B<-sizeOnly>] [-fixheader] - [B<-saveinodes>] [B<-orphaned>] [-help] +B [B<-online>] [B<-vnode>] [B<-date>] [B<-inode>] [B<-itime>] + [B<-part> >+] + [B<-volumeid> >+] [B<-header>] [B<-sizeOnly>] + [B<-fixheader>] [B<-saveinodes>] [B<-orphaned>] [B<-help>] =head1 DESCRIPTION -The volinfo command displays detailed statistics about one or -more volume headers and the partition that houses them. The command -must be issued on a file server machine and by default produces output for -every volume on every AFS server partition on the machine. To display -output for the volumes on one partition only, include the B<-part> -argument. To display output for one volume only, include the -B<-volumeid> argument. +The B command displays detailed statistics about one or more +volume headers and the partition that houses them. The command must be +issued on a file server machine and by default produces output for every +volume on every AFS server partition on the machine. To display output for +the volumes on one partition only, include the B<-part> argument. To +display output for one volume only, include the B<-volumeid> argument. =head1 OPTIONS =over 4 -=item -online +=item B<-online> Is nonoperational. -=item -vnode +=item B<-vnode> Displays a table for each volume which lists the large (directory) and small (file) vnodes in it, in addition to the default output. -=item -date +=item B<-date> -When combined with the -vnode flag, adds the -C field to each vnode entry in the large vnode and -small vnode tables, reporting its most recent modification time. +When combined with the B<-vnode> flag, adds the C field to +each vnode entry in the large vnode and small vnode tables, reporting its +most recent modification time. -=item -inode +=item B<-inode> -When combined with the -vnode flag, adds the C -field to each vnode entry in the large vnode and small vnode tables, reporting -the associated inode number. +When combined with the B<-vnode> flag, adds the C field to each +vnode entry in the large vnode and small vnode tables, reporting the +associated inode number. -=item -itime +=item B<-itime> -When combined with the -vnode flag, displays a change, -modification, and access timestamp for each of the large vnode and small vnode -tables. +When combined with the B<-vnode> flag, displays a change, modification, +and access timestamp for each of the large vnode and small vnode tables. -=item -part +=item B<-part> >+ Specifies the partition that houses each volume for which to produce -output. Use the format BI, where I -is one or two lowercase letters. This argument can be omitted if the -current working directory is the mount location for an AFS server -partition; it is not the mount location for an AFS server partition, the -command produces output for every volume on all local AFS server -partitions. +output. Use the format F>, where I is one or two lowercase +letters. This argument can be omitted if the current working directory is +the mount location for an AFS server partition; it is not the mount +location for an AFS server partition, the command produces output for +every volume on all local AFS server partitions. -=item -volumeid +=item B<-volumeid> >+ -Specifies the ID number of one volume for which to produce output. -The B<-part> argument must be provided along with this one unless the -current working directory is the mount location for the AFS server partition -that houses the volume. +Specifies the ID number of one volume for which to produce output. The +B<-part> argument must be provided along with this one unless the current +working directory is the mount location for the AFS server partition that +houses the volume. -=item -header +=item B<-header> Displays statistics about the volume header of each volume, in addition to the default output. -=item -sizeOnly +=item B<-sizeOnly> Displays a single line of output for each volume, reporting the size of various structures associated with it. The default output is suppressed and any flags that modify it (such as B<-vnode>) are ignored. -=item -fixheader +=item B<-fixheader> -Repairs damaged inodes in each volume if possible. If there are -any, it reports the action it is taking to repair them. Otherwise, it -produces no output in addition to the default output. +Repairs damaged inodes in each volume if possible. If there are any, it +reports the action it is taking to repair them. Otherwise, it produces no +output in addition to the default output. -=item -saveinodes +=item B<-saveinodes> Creates a file in the current working directory for each inode in each -volume. Each file is called -BI and contains the inode's -contents. The default output is suppressed and any flags that modify it -(such as B<-vnode>) are ignored. +volume. Each file is called F> and contains the +inode's contents. The default output is suppressed and any flags that +modify it (such as B<-vnode>) are ignored. -=item -orphaned +=item B<-orphaned> Displays a large vnode and small vnode table for each volume, which lists -only orphaned vnodes (vnodes that have no parent). If there are none, -the tables are empty (only the headers appear). +only orphaned vnodes (vnodes that have no parent). If there are none, the +tables are empty (only the headers appear). -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -110,20 +105,18 @@ are ignored. By default, the command produces several line of statistics for each volume. Adding other options produces or substitutes additional -information as described in the preceding B section of this -reference page. The output is intended for debugging purposes and is -meaningful to someone familiar with the internal structure of volume -headers. +information as described in L. The output is intended for +debugging purposes and is meaningful to someone familiar with the internal +structure of volume headers. =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the local superuser root. +The issuer must be logged in as the local superuser C. =head1 SEE ALSO -L - -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/volserver.pod b/doc/man-pages/pod8/volserver.pod index 9d01497ad..b1bc236de 100644 --- a/doc/man-pages/pod8/volserver.pod +++ b/doc/man-pages/pod8/volserver.pod @@ -4,69 +4,66 @@ volserver - Initializes the Volume Server component of the fs process =head1 SYNOPSIS -B [B<-log>] [-p >] -[B<-udpsize> >] - [B<-enable_peer_stats>] [B<-enable_process_stats>] [-help] - -This command does not use the syntax conventions of the AFS command -suites. Provide the command name and all option names in full. +B [B<-log>] [B<-p> >] + [B<-udpsize> >] + [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>] =head1 DESCRIPTION -The volserver command initializes the Volume Server component of -the B process. In the conventional configuration, its -binary file is located in the B directory on a file -server machine. +The B command initializes the Volume Server component of the +C process. In the conventional configuration, its binary file is +located in the F directory on a file server machine. -The volserver command is not normally issued at the command -shell prompt but rather placed into a file server machine's -B file with the B -command. If it is ever issued at the command shell prompt, the issuer -must be logged onto a database server machine as the local superuser -B. +The B command is not normally issued at the command shell +prompt but rather placed into a file server machine's +F file with the B command. If it is +ever issued at the command shell prompt, the issuer must be logged onto a +database server machine as the local superuser C. The Volume Server records a trace of its activity in the -B file. Use the B -command to display the contents of the file. +F file. Use the B command to display +the contents of the file. -The Volume Server processes the vos commands that administrators -use to create, delete, move, and replicate volumes, as well as prepare them -for archiving to tape or other media. +The Volume Server processes the B commands that administrators use to +create, delete, move, and replicate volumes, as well as prepare them for +archiving to tape or other media. By default, the VL Server runs nine lightweight processes (LWPs). To change the number, use the B<-p> argument. +This command does not use the syntax conventions of the AFS command +suites. Provide the command name and all option names in full. + =head1 OPTIONS =over 4 -=item -log +=item B<-log> -Records in the /usr/afs/logs/VolserLog file the names of all -users who successfully initiate a B command. The Volume -Server also records any file removals that result from issuing the B command with the B<-f> flag. +Records in the /usr/afs/logs/VolserLog file the names of all users who +successfully initiate a B command. The Volume Server also records any +file removals that result from issuing the B command with the +B<-f> flag. -=item -p +=item B<-p> > -Sets the number of server lightweight processes (LWPs) to run. -Provide an integer between B<4> and B<16>. The default -is 9. +Sets the number of server lightweight processes (LWPs) to run. Provide an +integer between C<4> and C<16>. The default is C<9>. -=item -udpsize +=item B<-udpsize> > -Sets the size of the UDP buffer, which is 64 KB by default. Provide -a positive integer, preferably larger than the default. +Sets the size of the UDP buffer in bytes, which is 64 KB by +default. Provide a positive integer, preferably larger than the default. -=item -enable_peer_stats +=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. +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 -enable_process_stats +=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, @@ -74,34 +71,34 @@ 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 -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following B command creates a volserver -process on the machine B: +The following B command creates a C process on the +machine C: - % bos create -server fs2.abc.com -instance volserver -type simple \ + % bos create -server fs2.abc.com -instance volserver -type simple \ -cmd /usr/afs/bin/volserver =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the superuser root on a file -server machine to issue the command at a command shell prompt. It is -conventional instead to create and start the process by issuing the B command. +The issuer must be logged in as the superuser C on a file server +machine to issue the command at a command shell prompt. It is conventional +instead to create and start the process by issuing the B +command. =head1 SEE ALSO -L, -L, -L, -L, +L, +L, +L, +L, L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/xfs_size_check.pod b/doc/man-pages/pod8/xfs_size_check.pod index 36f0f2a5e..5b07b4de8 100644 --- a/doc/man-pages/pod8/xfs_size_check.pod +++ b/doc/man-pages/pod8/xfs_size_check.pod @@ -1,19 +1,19 @@ =head1 NAME -xfs_size_check - Verifies proper inode configuration +xfs_size_check - Verifies proper IRIX inode configuration =head1 SYNOPSIS -xfs_size_check +B =head1 DESCRIPTION -The xfs_size_check command, when run on a file server machine -that runs IRIX version 6.2 or higher and uses XFS-formatted partitions -as server partitions (conventionally mounted at B -directories), verifies that each partition uses 512-byte inodes. AFS -stores information in the inodes on server partitions, and the 256-byte inode -size that XFS uses by default is not large enough. +The B command, when run on a file server machine that runs +IRIX version 6.2 or higher and uses XFS-formatted partitions as server +partitions (conventionally mounted at F directories), verifies +that each partition uses 512-byte inodes. AFS stores information in the +inodes on server partitions, and the 256-byte inode size that XFS uses by +default is not large enough. =head1 CAUTIONS @@ -30,15 +30,14 @@ output. Otherwise, it prints the following header: and then the following message for each partition on which to run the IRIX B command with the indicated options: - I: mkfs -t xfs -i size=512 -l size=4000b I + : mkfs -t xfs -i size=512 -l size=4000b -where I is in a format like /dev/dsk/dks0d0s0 for -a single disk partition or B for a logical -volume. +where is in a format like C for a single disk +partition or C for a logical volume. =head1 PRIVILEGE REQUIRED -The issuer must be logged in as the local superuser root. +The issuer must be logged in as the local superuser C. =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/xstat_fs_test.pod b/doc/man-pages/pod8/xstat_fs_test.pod deleted file mode 100644 index f16f64d33..000000000 --- a/doc/man-pages/pod8/xstat_fs_test.pod +++ /dev/null @@ -1,109 +0,0 @@ -=head1 NAME - -xstat_fs_test - Displays data collections from the File Server process - -=head1 SYNOPSIS - -B [B] -fsname >+ -B<-collID> >+ [B<-onceonly>] - [-frequency >] - [B<-period> >] [B<-debug>] [-help] - -B [B] -fs >+ -B<-c> >+ [B<-o>] - [-fr >] - [B<-p> >] [B<-d>] [-h] - -=head1 DESCRIPTION - -The xstat_fs_test command tests the routines in the -B library and displays the data collections -associated with the File Server (the B process). The -command executes in the foreground. - -The command produces a large volume of output; to save it for later -analysis, direct it to a file. - -=head1 OPTIONS - -=over 4 - -=item initcmd - -Accommodates the command's use of the AFS command parser, and is -optional. - -=item -fsname - -Specifies the fully qualified hostname of each file server machine for -which to monitor the File Server process. - -=item -collID - -Specifies each data collection to return, which defines the type and -amount of data the command interpreter gathers about the File Server. -Data is returned in a predefined data structure. - -There are three acceptable values: - -=over 4 - -=item 0 - -Provides profiling information about the numbers of times different -internal File Server routines were called since the File Server -started. This value is not currently implemented; it returns no -data. - -=item 1 - -Reports various internal performance statistics related to the File Server -(for example, vnode cache entries and B protocol activity). - -=item 2 - -Reports all of the internal performance statistics provided by the -B<1> setting, plus some additional, detailed performance figures about -the File Server (for example, minimum, maximum, and cumulative statistics -regarding File Server RPCs, how long they take to complete, and how many -succeed). - -=back - -=item -onceonly - -Gathers statistics just one time. Omit this flag to have the -command continue to probe the Cache Manager for statistics at the frequency -specified by the B<-frequency> argument; in this case press -> to stop the probes. - -=item -frequency - -Sets the frequency in seconds at which the program initiates probes to the -Cache Manager. The default is 30 seconds. - -=item -period - -Sets the number of minutes the program runs; at the end of this -period of time, the program exits. The default is 10 minutes. - -=item -debug - -Displays a trace on the standard output stream as the command runs. - -=item -help - -Prints the online help for this command. All other valid options -are ignored. - -=back - -=head1 SEE ALSO - -=head1 COPYRIGHT - -IBM Corporation 2000. All Rights Reserved. - -This documentation is covered by the IBM Public License Version 1.0. It was -converted from HTML to POD by software written by Chas Williams and Russ -Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. -- 2.39.5
for day, and + for year) and an optional portion ( for hours and 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. +Omit the I portion to use the default of midnight (00:00 hours), or +provide a value in 24-hour format (for example, C<20:30> is 8:30 p.m.). +Valid values for the year range from C<1970> to C<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] [Id] + [in] [y] [m] [d] -where the optional word in 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. +where the optional word in is followed by at least one of a number of +years (maximum C<9999>) followed by the letter C, a number of months +(maximum C<12>) followed by the letter C, or a number of days (maximum +C<31>) followed by the letter C. If providing more than one of the +three, list them in the indicated order. If the date that results from +adding the relative expiration value to a dump's creation time is later +than the latest possible date in the UNIX time representation, the Backup +System automatically reduces it to that date. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command defines a full dump called /1999 with a -relative expiration date of one year: +The following command defines a full dump called C with a relative +expiration date of one year: % backup adddump -dump /1999 -expires in 1y The following command defines an incremental dump called -B1 with a relative expiration date of 13 days: +C1 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. +C and C. Their parent, the full dump level +C, 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 /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_addhost.pod b/doc/man-pages/pod8/backup_addhost.pod index 879b42cea..1ecbabdd0 100644 --- a/doc/man-pages/pod8/backup_addhost.pod +++ b/doc/man-pages/pod8/backup_addhost.pod @@ -4,83 +4,78 @@ backup addhost - Adds a Tape Coordinator entry to the Backup Database =head1 SYNOPSIS -B > [-portoffset >] -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-tapehost> > + [B<-portoffset> >] + [B<-localauth>] [B<-cell> >] [B<-help>] -B > [-p >] -[B<-l>] [B<-c> >] [B<-h>] +B B<-t> > [B<-p> >] + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup addhost command creates a Tape Coordinator entry in -the Backup Database. The entry records +The B command creates a Tape Coordinator entry in the +Backup Database. The entry records =over 4 =item * The host name of the Tape Coordinator machine where the Tape Coordinator -(B) process runs, as specified with the B<-tapehost> -argument. - +(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). - +B<-portoffset> argument. An entry for the port offset must also appear in +the F 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 +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 B command. =head1 OPTIONS =over 4 -=item -tapehost +=item B<-tapehost> > 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 +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 (F or equivalent) on the machine where the command is issued. -=item -portoffset +=item B<-portoffset> > -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. +Specifies the Tape Coordinator's port offset number. Provide an integer +from the range C<0> through C<58510>, or omit this argument to use the +default value of C<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 F file on the Tape Coordinator +machine named by the B<-tapehost> argument. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -88,28 +83,27 @@ are ignored. 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: +C: % 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: +offset number 0 to a Tape Coordinator on the machine C: % backup addhost backup3.abc.com =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_addvolentry.pod b/doc/man-pages/pod8/backup_addvolentry.pod index 125170453..037b6354f 100644 --- a/doc/man-pages/pod8/backup_addvolentry.pod +++ b/doc/man-pages/pod8/backup_addvolentry.pod @@ -4,89 +4,80 @@ backup addvolentry - Defines a volume entry in a volume set =head1 SYNOPSIS -B > -server > -B<-partition> > - -volumes > - [B<-localauth>] [B<-cell> >] [-help] +B B<-name> > + B<-server> > B<-partition> > + B<-volumes> > + [B<-localauth>] [B<-cell> >] [B<-help>] -B > B<-s> > -p > -B<-v> > - [B<-l>] [B<-c> >] [-h] +B B<-n> > B<-s> > + B<-p> > B<-v> > + [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup addvolentry command adds a volume entry definition to -the existing volume set named by the B<-name> argument. A -volume entry definition can match one or more volumes, depending on the -combination of the B<-server>, B<-partition>, and -B<-volumes> arguments. +The B 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 -partition arguments, provide -either +For the B<-server> and B<-partition> arguments, provide either =over 4 =item * -The name of one machine or partition - +The name of one machine or partition. =item * -The metacharacter expression .* (period and asterisk), -which matches every machine name or partition name in the Volume Location -Database (VLDB). - +The metacharacter expression .* (period and asterisk), which matches every +machine name or partition name in the Volume Location Database (VLDB). =back -For the -volumes argument, specify a combination of alphanumeric +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. +volume name. L lists the acceptable metacharacters. =head1 CAUTIONS -It is best to issue this command in interactive mode. If issuing it -at the shell prompt, enclose any strings containing metacharacters in double +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 +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 OPTIONS =over 4 -=item -name +=item B<-name> > -Names the volume set to which to add this volume entry definition. -The volume set must already exist (use the B command -to create it). +Names the volume set to which to add this volume entry definition. The +volume set must already exist (use the B command to +create it). -=item -server +=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. +in the volume entry. Provide either one fully-qualified hostname (such as +C) or the metacharacter expression C<.*> (period and +asterisk), which matches all machine names in the VLDB. -=item -partition +=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. +C) or the metacharacter expression C<.*> (period and asterisk), +which matches all partition names. -=item -volumes +=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: -L<(1)> -L<(1)> =over 4 @@ -96,108 +87,100 @@ The period matches any single character. =item * -The asterisk matches zero or more instances of the preceding -character. Combine it with any other alphanumeric character or -metacharacter. +The asterisk matches zero or more instances of the preceding character. +Combine it with any other alphanumeric character or metacharacter. =item [ ] 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. +of the characters, but no other characters; for example, C<[abc]> matches +a single C or C or C, but not C or C. This expression can +be combined with the asterisk. =item ^ 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. +designates a match with any single character I the characters that +follow it; for example, C<[^a]> matches any single character except +lowercase C. This expression can be combined with the asterisk. =item \ 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). +match its literal value only. For example, the expression C<\.> (backslash +and period) matches a single period, C<\*> a single asterisk, and C<\\> a +single backslash. Such expressions can be combined with the asterisk (for +example, C<\.*> 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: +an asterisk (C<.*>). 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 C and +ends with C: user.*backup -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +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: +C. The entry matches all volumes on any machine or partition whose +names begin with the string C followed by a period: backup> addvolentry sys .* .* sun4x_56\..* -The following command adds a volume entry to the volume set called -B, to match all volumes on the B partition of -file server machine B. Because it is -issued at the shell prompt, double quotes surround the metacharacters in the -B<-volumes> argument. (The command is shown here on two lines -only for legibility reasons.) +The following command adds a volume entry to the volume set called C, +to match all volumes on the F partition of file server machine +C. Because it is issued at the shell prompt, double quotes +surround the metacharacters in the B<-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 I about -configuring the AFS Backup System presents additional examples as well as -advice on grouping volumes. +The chapter in the I 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 /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_addvolset.pod b/doc/man-pages/pod8/backup_addvolset.pod index cd7dfa501..e1575d244 100644 --- a/doc/man-pages/pod8/backup_addvolset.pod +++ b/doc/man-pages/pod8/backup_addvolset.pod @@ -4,101 +4,96 @@ backup addvolset - Creates a new (empty) volume set =head1 SYNOPSIS -B > [-temporary] -[B<-localauth>] [B<-cell> >] [B<-help>] +B B<-name> > [B<-temporary>] + [B<-localauth>] [B<-cell> >] [B<-help>] -B > [B<-t>] [B<-l>] [B<-c> >] [-h] +B B<-n> > [B<-t>] [B<-l>] + [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup addvolset command creates a new volume set, by -default adding it to the Backup Database. It is best that the volume -set's name indicate the volume set's contents; for example, -define the volume entries in the B volume set to match all user -volumes. The volume set name must be unique within the Backup Database -of the local cell. +The B 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 C 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 backup addvolentry command -to define the volume entries in the volume set. +After issuing this command, issue the B 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 B 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 B 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 B command to delete it before -that. - -One advantage of temporary volume sets is that the backup -addvolset command, and any B 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. +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 +B 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 +B command to delete it before that. + +One advantage of temporary volume sets is that the B +command, and any B 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 -name +=item B<-name> > -Names the new volume set. The name can include up to 31 of any -character other than the period. Avoid other metacharacters as -well. +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 -temporary +=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 -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +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: +The following command creates a volume set called C: % backup addvolset sys =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L, -L +L, +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_apropos.pod b/doc/man-pages/pod8/backup_apropos.pod index 694c98e63..5519253d0 100644 --- a/doc/man-pages/pod8/backup_apropos.pod +++ b/doc/man-pages/pod8/backup_apropos.pod @@ -4,33 +4,32 @@ backup apropos - Displays each help entry containing a keyword string =head1 SYNOPSIS -B > [-help] +B B<-topic> > [B<-help>] -B > [-h] +B B<-t> > [B<-h>] =head1 DESCRIPTION -The backup apropos command displays the first line of the online -help entry for any B command that has in its name or short -description the string specified by the B<-topic> argument. +The B command displays the first line of the online help +entry for any B 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 backup help -command. +To display the syntax for a command, use the B command. =head1 OPTIONS =over 4 -=item -topic +=item B<-topic> > -Specifies the keyword string to match, in lowercase letters only. -If the string is more than a single word, surround it with double quotes -(B<" ">) or other delimiters. +Specifies the keyword string to match, in lowercase letters only. If the +string is more than a single word, surround it with double quotes (C<" ">) +or other delimiters. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -38,13 +37,13 @@ are ignored. 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 -B command where the string specified with the -B<-topic> argument is part of the command name or first line. +B 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 backup commands that include the -word B in their names or short descriptions: +The following example lists all backup commands that include the word +C in their names or short descriptions: % backup apropos tape labeltape: label a tape @@ -58,8 +57,8 @@ None =head1 SEE ALSO -L, -L +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_dbverify.pod b/doc/man-pages/pod8/backup_dbverify.pod index 23826ddc0..4be9602fa 100644 --- a/doc/man-pages/pod8/backup_dbverify.pod +++ b/doc/man-pages/pod8/backup_dbverify.pod @@ -4,55 +4,54 @@ backup dbverify - Checks the integrity of the Backup Database =head1 SYNOPSIS -B [B<-detail>] [B<-localauth>] [B<-cell> >] [-help] +B [B<-detail>] [B<-localauth>] [B<-cell> >] + [B<-help>] -B [B<-d>] [B<-l>] [B<-c> >] [-h] +B [B<-d>] [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup dbverify command checks the integrity of the Backup -Database. The command's output indicates whether the Backup -Database is damaged (data is corrupted) or not. If the Backup Database -is undamaged, it is safe to continue using it. If it is corrupted, -discontinue any backup operations until it is repaired. +The B 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 CAUTIONS 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 B command repairs some types -of corruption. +likely to run. The B command repairs some types of +corruption. =head1 OPTIONS =over 4 -=item -detail +=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. +name of the server machine running the Backup Server that is checking its +copy of the database. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back @@ -62,49 +61,43 @@ The command displays one of the following two messages: =over 4 -=item C +=item Database OK The database is undamaged and can be used. -=item C +=item Database not OK -The database is damaged. You can use the backup savedb -command to repair many kinds of corruption as it creates a backup copy. -For more detailed instructions, see the I chapter about performing backup operations. +The database is damaged. You can use the backup savedb command to repair +many kinds of corruption as it creates a backup copy. For more detailed +instructions, see the I chapter about +performing backup operations. =back -The -detail flag provides additional information: +The B<-detail> flag provides additional information: =over 4 =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 B command, and then restore it by using the -B command. - +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 B command, and then restore it by using the B +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 C. For a detailed -trace of the verification operation, see the -B file on the indicated machine. You -can use the B command to display it. - +checked, designated as the C. For a detailed trace of +the verification operation, see the F file on the +indicated machine. You can use the B command to display it. =back @@ -117,8 +110,8 @@ The following command confirms that the Backup Database is undamaged: 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 Server running on the machine C checked its copy of +the Database. % backup dbverify -detail Database OK @@ -127,18 +120,18 @@ checked its copy of the Database. =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L, -L, -L +L, +L, +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_deldump.pod b/doc/man-pages/pod8/backup_deldump.pod index af427eb45..848052f31 100644 --- a/doc/man-pages/pod8/backup_deldump.pod +++ b/doc/man-pages/pod8/backup_deldump.pod @@ -4,67 +4,65 @@ backup deldump - Deletes a dump level from the Backup Database =head1 SYNOPSIS -B > [-localauth] -[B<-cell> >] [B<-help>] +B B<-dump> > [B<-localauth>] + [B<-cell> >] [B<-help>] -B > [B<-l>] [B<-c> >] [-h] +B B<-d> > [B<-l>] [B<-c> >] + [B<-h>] =head1 DESCRIPTION -The backup deldump command deletes the indicated dump level and -all of its child dump levels from the dump hierarchy in the Backup -Database. Use the B command to display the -dump hierarchy. +The B command deletes the indicated dump level and all of +its child dump levels from the dump hierarchy in the Backup Database. Use +the B command to display the dump hierarchy. =head1 OPTIONS =over 4 -=item -dump +=item B<-dump> > Specifies the complete pathname of the dump level to delete. -=item -localauth +=item B<-localauth> Constructs a server ticket using a key from the local -B file. The B 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 -B reference page. +F file. The B 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 L. -=item -cell +=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 B reference page. +Names the cell in which to run the command. Do not combine this argument +with the B<-localauth> flag. For more details, see L. -=item -help +=item B<-help> -Prints the online help for this command. All other valid options -are ignored. +Prints the online help for this command. All other valid options are +ignored. =back =head1 EXAMPLES -The following command deletes the dump level /sunday1/monday1 -from the dump hierarchy, along with any of its child dump levels. +The following command deletes the dump level C from the +dump hierarchy, along with any of its child dump levels. % backup deldump /sunday1/monday1 =head1 PRIVILEGE REQUIRED -The issuer must be listed in the /usr/afs/etc/UserList file on -every machine where the Backup Server is running, or must be logged onto a -server machine as the local superuser B if the -B<-localauth> flag is included. +The issuer must be listed in the F file on every +machine where the Backup Server is running, or must be logged onto a +server machine as the local superuser C if the B<-localauth> flag is +included. =head1 SEE ALSO -L, -L, -L +L, +L, +L =head1 COPYRIGHT diff --git a/doc/man-pages/pod8/backup_deletedump.pod b/doc/man-pages/pod8/backup_deletedump.pod index ba196d615..e7a1c3abe 100644 --- a/doc/man-pages/pod8/backup_deletedump.pod +++ b/doc/man-pages/pod8/backup_deletedump.pod @@ -4,19 +4,20 @@ backup deletedump - Deletes one or more dump records from the Backup Database =head1 SYNOPSIS -B [B<-dumpid> >+] [B<-from> >+] [-to >+] -[B<-localauth>] [B<-cell> >] [B<-help>] +B [B<-dumpid> >+] [B<-from> >+] + [B<-to> >+] [B<-localauth>] [B<-cell> >] + [B<-help>] -B [B<-d> >+] [B<-f> >+] [-t >+] -[B<-l>] [B<-c> >] [B<-h>] +B [B<-d> >+] [B<-f> >+] + [-t >+] [B<-l>] [B<-c> >] [B<-h>] =head1 DESCRIPTION -The backup deletedump command deletes one or more dump records -from the Backup Database. Either use the B<-dumpid> argument to -specify the dump ID number of one or more dumps, or use the B<-from> -and B<-to> arguments to delete the records for all regular dumps -created during the time period bracketed by the specified values. +The B command deletes one or more dump records from the +Backup Database. Either use the B<-dumpid> argument to specify the dump ID +number of one or more dumps, or use the B<-from> and B<-to> arguments to +delete the records for all regular dumps created during the time period +bracketed by the specified values. Use this command to remove dump records that are incorrect (possibly because a dump operation was interrupted or failed), or that correspond to @@ -25,111 +26,104 @@ dumps that are expired or otherwise no longer needed. =head1 CAUTIONS The only way to remove the dump record for an appended dump is to remove -the record for its initial dump, and doing so removes the records for all of -the initial dump's associated appended dumps. +the record for its initial dump, and doing so removes the records for all +of the initial dump's associated appended dumps. The only way to remove the record for a Backup Database dump (created with -the B command) is to specify its dump ID number with -the B<-dumpid> argument. Using the B<-from> and -B<-to> arguments never removes database dump records. +the B command) is to specify its dump ID number with the +B<-dumpid> argument. Using the B<-from> and B<-to> arguments never removes +database dump records. Removing records of a dump makes it impossible to restore data from the -corresponding tapes or from any dump that refers to the deleted dump as its -parent, directly or indirectly. That is, restore operations must begin +corresponding tapes or from any dump that refers to the deleted dump as +its parent, directly or indirectly. That is, restore operations must begin with the full dump and continue with each incremental dump in order. If the records for a specific dump are removed, it is not possible to restore -data from later incremental dumps unless the deleted records are restored by -running the B command with the B<-dbadd> -flag. +data from later incremental dumps unless the deleted records are restored +by running the B command with the B<-dbadd> flag. If a dump set contains any dumps that were created outside the time range -specified by the B<-from> and B<-to> arguments, the command -does not delete any of the records associated with the dump set, even if some -of them represent dumps created during the time range. +specified by the B<-from> and B<-to> arguments, the command does not +delete any of the records associated with the dump set, even if some of +them represent dumps created during the time range. =head1 OPTIONS =over 4 -=item -dumpid +=item B<-dumpid> >+ -Specifies the dump ID of each dump record to delete. The -corresponding dumps must be initial dumps; it is not possible to delete -appended dump records directly, but only by deleting the record of their -associated initial dump. Using this argument is the only way to delete -records of Backup Database dumps (created with the B -command). +Specifies the dump ID of each dump record to delete. The corresponding +dumps must be initial dumps; it is not possible to delete appended dump +records directly, but only by deleting the record of their associated +initial dump. Using this argument is the only way to delete records of +Backup Database dumps (created with the B command). -Provide either this argument or the -to (and optionally -B<-from>) argument. +Provide either this argument or the B<-to> (and optionally B<-from>) +argument. -=item -from +=item B<-from> >+ Specifies the beginning of a range of dates; the record for any dump created during the indicated period of time is deleted. -Omit this argument to indicate the default of midnight (00:00 hours) -on 1 January 1970 (UNIX time zero), or provide a date value in the format -I [I]. The month (I), -day (I