From c15a8c65ad232349b202fcf67a4f5037aaec02c8 Mon Sep 17 00:00:00 2001 From: Derrick Brashear Date: Fri, 16 Jul 2010 13:21:57 -0400 Subject: [PATCH 1/1] document dafileserver split dafileserver and fileserver documentation. remove dafs-only switches from fileserver doc. refer both ways between docs. Change-Id: Ibcac8ed3f294c18436978f3cd4e52de305130198 Reviewed-on: http://gerrit.openafs.org/2425 Reviewed-by: Derrick Brashear Tested-by: Derrick Brashear --- doc/man-pages/pod8/.gitignore | 6 + doc/man-pages/pod8/dafileserver.pod.in | 121 +++ doc/man-pages/pod8/fileserver.pod | 840 --------------------- doc/man-pages/pod8/fileserver.pod.in | 64 ++ doc/man-pages/pod8/fragments/fileserver-also.pod | 10 + .../pod8/fragments/fileserver-cautions.pod | 47 ++ .../pod8/fragments/fileserver-copyright.pod | 5 + .../pod8/fragments/fileserver-description.pod | 140 ++++ .../pod8/fragments/fileserver-options.pod | 298 ++++++++ .../pod8/fragments/fileserver-privilege.pod | 4 + .../pod8/fragments/fileserver-synopsis.pod | 46 ++ .../pod8/fragments/fileserver-troubleshooting.pod | 146 ++++ regen.sh | 1 + 13 files changed, 888 insertions(+), 840 deletions(-) create mode 100644 doc/man-pages/pod8/.gitignore create mode 100644 doc/man-pages/pod8/dafileserver.pod.in delete mode 100644 doc/man-pages/pod8/fileserver.pod create mode 100644 doc/man-pages/pod8/fileserver.pod.in create mode 100644 doc/man-pages/pod8/fragments/fileserver-also.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-cautions.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-copyright.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-description.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-options.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-privilege.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-synopsis.pod create mode 100644 doc/man-pages/pod8/fragments/fileserver-troubleshooting.pod diff --git a/doc/man-pages/pod8/.gitignore b/doc/man-pages/pod8/.gitignore new file mode 100644 index 0000000..3c6265f --- /dev/null +++ b/doc/man-pages/pod8/.gitignore @@ -0,0 +1,6 @@ +# After changing this file, please run +# git ls-files -i --exclude-standard +# to check that you haven't inadvertently ignored any tracked files. + +/dafileserver.pod +/fileserver.pod diff --git a/doc/man-pages/pod8/dafileserver.pod.in b/doc/man-pages/pod8/dafileserver.pod.in new file mode 100644 index 0000000..cc2dbd2 --- /dev/null +++ b/doc/man-pages/pod8/dafileserver.pod.in @@ -0,0 +1,121 @@ +=head1 NAME + +dafileserver - Initializes the File Server component of the dafs process + +=head1 SYNOPSIS + +=for html +
+ +=include fragments/dafileserver-synopsis.pod + +=for html +
+ +=head1 DESCRIPTION + +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 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. + +=include fragments/fileserver-description.pod + +=head1 CAUTIONS + +=include fragments/fileserver-cautions.pod + +=head1 OPTIONS + +=include fragments/fileserver-options.pod + +=item B<-fs-state-dont-save> + +When present, fileserver state will not be saved during shutdown. Default +is to save state. + +=item B<-fs-state-dont-restore> + +When present, fileserver state will not be restored during startup. +Default is to restore state on startup. + +=item B<-fs-state-verify> (none | save | restore | both) + +This argument controls the behavior of the state verification mechanism. +A value of C turns off all verification. A value of C only +performs the verification steps prior to saving state to disk. A value +of C only performs the verification steps after restoring state +from disk. A value of C performs all verifications steps both +prior to save and following a restore. + +The default is C. + +=item B<-vhashsize > + +The log(2) number of of volume hash buckets. Default is 8 (i.e., by +default, there are 2^8 = 256 volume hash buckets). + +=item B<-vlruthresh > + +The number of minutes of inactivity before a volume is eligible for soft +detachment. Default is 120 minutes. + +=item B<-vlruinterval > + +The number of seconds between VLRU candidate queue scan. The default is +120 seconds. + +=item B<-vlrumax > + +The maximum number of volumes which can be soft detached in a single pass +of the scanner. Default is 8 volumes. + +=item B<-unsafe-nosalvage> + +This option causes the fileserver to bypass the normal safety check when +attaching volumes that checks the inUse field in the volume header. With +this option, volumes that were in use at the time of an unclean shutdown +will not be salvaged immediately the next time they are accessed, and thus +risk (possibly silent and/or irrevocable) corruption. Volumes will still +be salvaged when an internal inconsistency is detected or other cases +where a salvage would normally occur. + +Due to the increased risk of data corruption, the use of this flag is +strongly discouraged. Only use it if you really know what you are doing. + +=back + +=head1 EXAMPLES + +The following B command creates a dafs process on +the file server machine C that uses the large configuration +size, and allows volumes to exceed their quota by 10%. Type the command on +a single line: + + % bos create -server fs2.abc.com -instance dafs -type dafs \ + -cmd "/usr/afs/bin/fileserver -pctspare 10 -L" \ + /usr/afs/bin/volserver \ + /usr/afs/bin/salvageserver \ + /usr/afs/bin/salvager + +=head1 TROUBLESHOOTING + +=include fragments/fileserver-troubleshooting.pod + +=head1 PRIVILEGE REQUIRED + +=include fragments/fileserver-privilege.pod + +=head1 SEE ALSO + +=include fragments/fileserver-also.pod +L, + +=head1 COPYRIGHT + +=include fragments/fileserver-copyright.pod diff --git a/doc/man-pages/pod8/fileserver.pod b/doc/man-pages/pod8/fileserver.pod deleted file mode 100644 index 31450d8..0000000 --- a/doc/man-pages/pod8/fileserver.pod +++ /dev/null @@ -1,840 +0,0 @@ -=head1 NAME - -fileserver - Initializes the File Server component of the fs process - -=head1 SYNOPSIS - -=for html -
- -B S<<< [B<-auditlog> >] >>> - S<<< [B<-audit-interface> (file | sysvmq)] >>> - S<<< [B<-d> >] >>> - S<<< [B<-p> >] >>> - S<<< [B<-spare> >] >>> - S<<< [B<-pctspare> >] >>> - S<<< [B<-b> >] >>> - S<<< [B<-l> >] >>> - S<<< [B<-s> >] >>> - S<<< [B<-vc> >] >>> - S<<< [B<-w> >] >>> - S<<< [B<-cb> >] >>> - S<<< [B<-banner>] >>> - S<<< [B<-novbc>] >>> - S<<< [B<-implicit> >] >>> - S<<< [B<-readonly>] >>> - S<<< [B<-hr> >] >>> - S<<< [B<-busyat> n >>>] >>> - S<<< [B<-nobusy>] >>> - S<<< [B<-rxpck> >] >>> - S<<< [B<-rxdbg>] >>> - S<<< [B<-rxdbge>] >>> - S<<< [B<-rxmaxmtu> >] >>> - S<<< [B<-nojumbo> >>> - S<<< [B<-jumbo> >>> - S<<< [B<-rxbind> >>> - S<<< [B<-allow-dotted-principals>] >>> - S<<< [B<-L>] >>> - S<<< [B<-S>] >>> - S<<< [B<-k> >] >>> - S<<< [B<-realm> >] >>> - S<<< [B<-udpsize> >] >>> - S<<< [B<-sendsize> >] >>> - S<<< [B<-abortthreshold> >] >>> - S<<< [B<-enable_peer_stats>] >>> - S<<< [B<-enable_process_stats>] >>> - S<<< [B<-syslog> [>]] >>> - S<<< [B<-mrafslogs>] >>> - S<<< [B<-saneacls>] >>> - S<<< [B<-help>] >>> - S<<< [B<-fs-state-dont-save>] >>> - S<<< [B<-fs-state-dont-restore>] >>> - S<<< [B<-fs-state-verify>] (none | save | restore | both)] >>> - S<<< [B<-vhandle-setaside> >] >>> - S<<< [B<-vhandle-max-cachesize> >] >>> - S<<< [B<-vhandle-initial-cachesize> >] >>> - S<<< [B<-vhashsize> >] >>> - S<<< [B<-vlrudisable>] >>> - S<<< [B<-vlruthresh> >] >>> - S<<< [B<-vlruinterval> >] >>> - S<<< [B<-vlrumax> >] >>> - S<<< [B<-unsafe-nosalvage>] >>> - S<<< [B<-vattachpar> >] >>> - S<<< [B<-m> >] >>> - S<<< [B<-lock>] >>> - -=for html -
- -=head1 DESCRIPTION - -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 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 F log file as it -initializes, if the file does not already exist. It does not write a -detailed trace by default, but the B<-d> option may be used 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 the table below summarizes the setting for each of the three -machine sizes. - -=over 4 - -=item * - -The maximum number of lightweight processes (LWPs) or pthreads -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 of -memory for these processes. - -=item * - -The maximum number of directory blocks the File Server caches in memory; -corresponds to the B<-b> argument. Each cached directory block (buffer) -consumes 2,092 bytes of memory. - -=item * - -The maximum number of large vnodes the File Server caches in memory for -tracking directory elements; corresponds to the B<-l> argument. Each large -vnode consumes 292 bytes of memory. - -=item * - -The maximum number of small vnodes the File Server caches in memory for -tracking file elements; corresponds to the B<-s> argument. Each small -vnode consumes 100 bytes of memory. - -=item * - -The maximum volume cache size, which determines how many volumes the File -Server can cache in memory before having to retrieve data from disk; -corresponds to the B<-vc> argument. - -=item * - -The maximum number of callback structures the File Server caches in -memory; corresponds to the B<-cb> argument. Each callback structure -consumes 16 bytes of memory. - -=item * - -The maximum number of Rx packets the File Server uses; corresponds to the -B<-rxpck> argument. Each packet consumes 1544 bytes of memory. - -=back - -The default values are: - - Parameter (Argument) Small (-S) Medium Large (-L) - --------------------------------------------------------------------- - Number of LWPs (-p) 6 9 128 - 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 - -To override any of the values, provide the indicated argument (which can -be combined with the B<-S> or B<-L> flag). - -The amount of memory required for the File Server varies. The approximate -default memory usage is 751 KB when the B<-S> flag is used (small -configuration), 1.1 MB when all defaults are used (medium configuration), -and 1.4 MB when the B<-L> flag is used (large configuration). If -additional memory is available, increasing the value of the B<-cb> and -B<-vc> arguments can improve File Server performance most directly. - -By default, the File Server allows a volume to exceed its quota by 1 MB -when an application is writing data to an existing file in a volume that -is full. The File Server still does not allow users to create new files in -a full volume. To change the default, use one of the following arguments: - -=over 4 - -=item * - -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 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 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 stores volumes in partitions. A partition is a -filesystem or directory on the server machine that is named C -or C where XX is "a" through "z" or "aa" though "iv". Up to -255 partitions are allowed. The File Server expects that the /vicepXX -directories are each on a dedicated filesystem. The File Server will -only use a /vicepXX if it's a mountpoint for another filesystem, -unless the file C exists. The data in the -partition is a special format that can only be access using OpenAFS -commands or an OpenAFS client. - -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 - -There are two strategies the File Server can use for attaching AFS volumes -at startup and handling volume salvages. The traditional method assumes -all volumes are salvaged before the File Server starts and attaches all -volumes at start before serving files. The newer demand-attach method -attaches volumes only on demand, salvaging them at that time as needed, -and detaches volumes that are not in use. A demand-attach File Server can -also save state to disk for faster restarts. - -The choice of traditional or demand-attach File Server must be made at -compile time, and the required setup in F is different for the -two servers. When changing from a traditional File Server to -demand-attach or vice versa, you will need to stop and remove the C or -C node in F and create a new node of the appropriate -type. See L for more information. - -Do not use the B<-k> and B<-w> arguments, which are intended for use -by the OpenAFS developers only. Changing them from their default -values can result in unpredictable File Server behavior. In any case, -on many operating systems the File Server uses native threads rather -than the LWP threads, so using the B<-k> argument to set the number of -LWP threads has no effect. - -Do not specify both the B<-spare> and B<-pctspare> arguments. Doing so -causes the File Server to exit, leaving an error message in the -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. - -Currently, the maximum size of a volume is 2 terabytes (2^31 bytes) -and the maximum size of a /vicepX partition on a fileserver is 2^64 -kilobytes. The maximum partition size in releases 1.4.7 and earlier is -2 terabytes (2^31 bytes). The maximum partition size for 1.5.x -releases 1.5.34 and earlier is 2 terabytes as well. - -The maximum number of directory entries is 64,000 if all of the entries -have names that are 15 octets or less in length. A name that is 15 octets -long requires the use of only one block in the directory. Additional -sequential blocks are required to store entries with names that are longer -than 15 octets. Each additional block provides an additional length of 32 -octets for the name of the entry. Note that if file names use an encoding -like UTF-8, a single character may be encoded into multiple octets. - -In real world use, the maximum number of objects in an AFS directory -is usually between 16,000 and 25,000, depending on the average name -length. - -=head1 OPTIONS - -=over 4 - -=item B<-auditlog> > - -Turns on audit logging, and sets the path for the audit log. The audit -log records information about RPC calls, including the name of the RPC -call, the host that submitted the call, the authenticated entity (user) -that issued the call, the parameters for the call, and if the call -succeeded or failed. - -=item B<-audit-interface> (file | sysvmq) - -Specifies what audit interface to use. The C interface writes audit -messages to the file passed to B<-auditlog>. The C interface -writes audit messages to a SYSV message (see L and -L). The message queue the C interface writes to has the -key C, where C is the path specified in the -B<-auditlog> option. - -Defaults to C. - -=item B<-d> > - -Sets the detail level for the debugging trace written to the -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 B<-p> > - -Sets the number of threads (or LWPs) 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 OpenAFS. -Consult the I for the current release. - -=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 -C<0> prevents the volume from ever exceeding its quota. Do not combine -this argument with the B<-pctspare> argument. - -=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 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<-b> > - -Sets the number of directory buffers. Provide a positive integer. - -=item B<-l> > - -Sets the number of large vnodes available in memory for caching directory -elements. Provide a positive integer. - -=item B<-s> > - -Sets the number of small vnodes available in memory for caching file -elements. Provide a positive integer. - -=item B<-vc> > - -Sets the number of volumes the File Server can cache in memory. Provide a -positive integer. - -=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. - -=item B<-cb> > - -Sets the number of callbacks the File Server can track. Provide a positive -integer. - -=item B<-banner> - -Prints the following banner to F about every 10 minutes. - - File Server is running at I (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 stores volumes in partitions. A partition is a +filesystem or directory on the server machine that is named C +or C where XX is "a" through "z" or "aa" though "iv". Up to +255 partitions are allowed. The File Server expects that the /vicepXX +directories are each on a dedicated filesystem. The File Server will +only use a /vicepXX if it's a mountpoint for another filesystem, +unless the file C exists. The data in the +partition is a special format that can only be access using OpenAFS +commands or an OpenAFS client. + +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. diff --git a/doc/man-pages/pod8/fragments/fileserver-options.pod b/doc/man-pages/pod8/fragments/fileserver-options.pod new file mode 100644 index 0000000..fa07c1f --- /dev/null +++ b/doc/man-pages/pod8/fragments/fileserver-options.pod @@ -0,0 +1,298 @@ +=over 4 + +=item B<-auditlog> > + +Turns on audit logging, and sets the path for the audit log. The audit +log records information about RPC calls, including the name of the RPC +call, the host that submitted the call, the authenticated entity (user) +that issued the call, the parameters for the call, and if the call +succeeded or failed. + +=item B<-audit-interface> (file | sysvmq) + +Specifies what audit interface to use. The C interface writes audit +messages to the file passed to B<-auditlog>. The C interface +writes audit messages to a SYSV message (see L and +L). The message queue the C interface writes to has the +key C, where C is the path specified in the +B<-auditlog> option. + +Defaults to C. + +=item B<-d> > + +Sets the detail level for the debugging trace written to the +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 B<-p> > + +Sets the number of threads (or LWPs) 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 OpenAFS. +Consult the I for the current release. + +=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 +C<0> prevents the volume from ever exceeding its quota. Do not combine +this argument with the B<-pctspare> argument. + +=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 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<-b> > + +Sets the number of directory buffers. Provide a positive integer. + +=item B<-l> > + +Sets the number of large vnodes available in memory for caching directory +elements. Provide a positive integer. + +=item B<-s> > + +Sets the number of small vnodes available in memory for caching file +elements. Provide a positive integer. + +=item B<-vc> > + +Sets the number of volumes the File Server can cache in memory. Provide a +positive integer. + +=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. + +=item B<-cb> > + +Sets the number of callbacks the File Server can track. Provide a positive +integer. + +=item B<-banner> + +Prints the following banner to F about every 10 minutes. + + File Server is running at I