Index: openafs/doc/man-pages/pod8/afsd.pod diff -c openafs/doc/man-pages/pod8/afsd.pod:1.6.2.5 openafs/doc/man-pages/pod8/afsd.pod:1.6.2.6 *** openafs/doc/man-pages/pod8/afsd.pod:1.6.2.5 Tue Feb 19 10:28:57 2008 --- openafs/doc/man-pages/pod8/afsd.pod Sun Mar 9 01:08:47 2008 *************** *** 393,404 **** =item B<-afsdb> ! Enable afsdb support. This will use DNS to lookup the AFSDB record and use ! that for the database servers for each cell instead of the values in the ! F file. This has the advantage of only needing to update one ! DNS record to reconfigure the AFS clients for a new database server as ! opposed to touching all of the clients, and also allows one to access a ! cell without preconfiguring its database servers in F. =item B<-backuptree> --- 393,406 ---- =item B<-afsdb> ! Enable afsdb support. This will use DNS to lookup the AFSDB record and ! use that for the database servers for each cell instead of the values ! in the F file. This has the advantage of only needing to ! update one DNS record to reconfigure the AFS clients for a new ! database server as opposed to touching all of the clients, and also ! allows one to access a cell without preconfiguring its database ! servers in F. The format of AFSDB records is defined in ! RFC 1183. =item B<-backuptree> *************** *** 705,710 **** --- 707,714 ---- L, L + RFC 1183 L + =head1 COPYRIGHT IBM Corporation 2000. All Rights Reserved. Index: openafs/doc/man-pages/pod8/bos_create.pod diff -c openafs/doc/man-pages/pod8/bos_create.pod:1.3.2.2 openafs/doc/man-pages/pod8/bos_create.pod:1.3.2.3 *** openafs/doc/man-pages/pod8/bos_create.pod:1.3.2.2 Sun Nov 11 18:51:06 2007 --- openafs/doc/man-pages/pod8/bos_create.pod Fri Mar 14 14:49:54 2008 *************** *** 45,52 **** 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 --- 45,53 ---- 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 (or the instance type for B and B), and to ! use the same name on every server machine. The conventional names, as used ! in all AFS documentation, are: =over 4 *************** *** 54,59 **** --- 55,66 ---- The Backup Server process. + =item dafs + + The process that combines the Demand Attach File Server, Volume Server, + Salvageserver and Salvager processes (B, B, + B, and B). + =item fs The process that combines the File Server, Volume Server, and Salvager *************** *** 69,75 **** =item runntp ! The controller process for the Network Time Protocol Daemon. =item upclientbin --- 76,82 ---- =item runntp ! The controller process for the Network Time Protocol Daemon (obsolete). =item upclientbin *************** *** 113,123 **** =item dafs ! Use this value only for the dafs process, which combines the ! File Server, Volume Server, Salvageserver, and Salvager processes in ! order to operate as a Demand Attach File Server. If one of the ! component processes terminates, the BOS Server shuts down ! and restarts the process in the appropriate order. =item fs --- 120,130 ---- =item dafs ! Use this value only for the dafs process, which combines the File Server, ! Volume Server, Salvageserver, and Salvager processes in order to operate ! as a Demand Attach File Server. If one of the component processes ! terminates, the BOS Server shuts down and restarts the process in the ! appropriate order. =item fs *************** *** 129,137 **** =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. =back --- 136,144 ---- =item simple Use this value for all processes listed as acceptable values to the ! B<-instance> argument, except for the B and B processes. ! There are no interdependencies between simple processes, so the ! BOS Server can stop and start them independently as necessary. =back *************** *** 258,263 **** --- 265,277 ---- -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \ /usr/afs/bin/salvager + The following command creates the dafs process dafs on the machine + C. Type the command on a single line. + + % bos create -server fs4.abc.com -instance dafs -type dafs \ + -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \ + /usr/afs/bin/salvageserver /usr/afs/bin/salvager + 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 *************** *** 383,388 **** --- 397,403 ---- L, L, L, + L, L, L, L, Index: openafs/doc/man-pages/pod8/fileserver.pod diff -c openafs/doc/man-pages/pod8/fileserver.pod:1.5.2.6 openafs/doc/man-pages/pod8/fileserver.pod:1.5.2.8 *** openafs/doc/man-pages/pod8/fileserver.pod:1.5.2.6 Tue Jan 22 23:18:10 2008 --- openafs/doc/man-pages/pod8/fileserver.pod Fri Mar 14 14:49:54 2008 *************** *** 11,35 **** 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> >] >>> [B<-banner>] [B<-novbc>] ! S<<< [B<-implicit> >] >>> [B<-readonly>] S<<< [B<-hr> >] >>> S<<< [B<-busyat> n >>>] >>> ! [B<-nobusy>] S<<< [B<-rxpck> >] >>> ! [B<-rxdbg>] [B<-rxdbge>] S<<< [B<-rxmaxmtu> >] >>> ! [B<-allow-dotted-principal>] ! S<<< [B<-rxbind> >] >>> ! S<<< [B<-vattachpar> >] >>> ! S<<< [B<-m> >] >>> ! [B<-lock>] [B<-L>] [B<-S>] S<<< [B<-k> >] >>> S<<< [B<-realm> >] >>> S<<< [B<-udpsize> >] >>> S<<< [B<-sendsize> >] >>> S<<< [B<-abortthreshold> >] >>> ! [B<-enable_peer_stats>] [B<-enable_process_stats>] [B<-help>] =for html --- 11,61 ---- 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<-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<-vhashsize> >] >>> ! S<<< [B<-vlrudisable>] >>> ! S<<< [B<-vlruthresh> >] >>> ! S<<< [B<-vlruinterval> >] >>> ! S<<< [B<-vlrumax> >] >>> ! S<<< [B<-vattachpar> >] >>> ! S<<< [B<-m> >] >>> ! S<<< [B<-lock>] >>> =for html *************** *** 66,74 **** =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 of memory for these processes. =item * --- 92,101 ---- =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 * *************** *** 204,216 **** 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 also 2 ! terabytes. The fileserver will not report an error when it has access ! to a partition larger than 2 terabytes, but it will probably fail if ! the administrator attempts to use more than 2 terabytes of space. In addition, there are reports of erroneous disk usage numbers when B or other OpenAFS disk reporting tools are used with ! partitions larger than 2 terabytes. The maximum number of directory entries is 64,000 if all of the entries have names that are 15 characters or less in length. A name --- 231,243 ---- 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 fileserver will not report an error when it has access ! to a partition larger than 2^64 kilobytes, but it will probably fail if ! the administrator attempts to use more than 2^64 kilobytes of space. In addition, there are reports of erroneous disk usage numbers when B or other OpenAFS disk reporting tools are used with ! partitions larger than 2^64 kilobytes. The maximum number of directory entries is 64,000 if all of the entries have names that are 15 characters or less in length. A name *************** *** 241,251 **** =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). The maximum number of threads can differ in each release of AFS. Consult the I for the current release. --- 268,278 ---- =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 AFS. Consult the I for the current release. *************** *** 317,322 **** --- 344,353 ---- (C, C, C, and C). To review the meaning of the permissions, see the B reference page. + =item B<-readonly> + + Don't allow writes to this fileserver. + =item B<-hr> > Specifies how often the File Server refreshes its knowledge of the *************** *** 347,357 **** Writes a trace of the File Server's operations on Rx packets to the file F. ! =item F<-rxdbge> Writes a trace of the File Server's operations on Rx events (such as retransmissions) to the file F. =item B<-allow-dotted-principal> By default, the RXKAD security layer will disallow access by Kerberos --- 378,401 ---- Writes a trace of the File Server's operations on Rx packets to the file F. ! =item B<-rxdbge> Writes a trace of the File Server's operations on Rx events (such as retransmissions) to the file F. + =item B<-rxmaxmtu> > + + Defines the maximum size of an MTU. The value must be between the + minimum and maximum packet data sizes for Rx. + + =item B<-nojumbo> + + Do not send, and do not accept, jumbograms. + + =item B<-rxbind> + + Force the fileserver to only bind to one IP address. + =item B<-allow-dotted-principal> By default, the RXKAD security layer will disallow access by Kerberos *************** *** 361,379 **** between principal names may disable this check by starting the server with this option. - =item F<-m> > - - Specifies the percentage of each AFS server partition that the AIX version - of the File Server creates as a reserve. Specify an integer value between - C<0> and C<30>; the default is 8%. A value of C<0> means that the - partition can become completely full, which can have serious negative - consequences. - - =item B<-lock> - - Prevents any portion of the fileserver binary from being paged (swapped) - out of memory on a file server machine running the IRIX operating system. - =item B<-L> Sets values for many arguments in a manner suitable for a large file --- 405,410 ---- *************** *** 404,424 **** Sets the size of the UDP buffer, which is 64 KB by default. Provide a positive integer, preferably larger than the default. ! =item B<-enable_peer_stats> ! ! Activates the collection of Rx statistics and allocates memory for their ! storage. For each connection with a specific UDP port on another machine, ! a separate record is kept for each type of RPC (FetchFile, GetStatus, and ! so on) sent or received. To display or otherwise access the records, use ! the Rx Monitoring API. ! ! =item B<-enable_process_stats> ! Activates the collection of Rx statistics and allocates memory for their ! storage. A separate record is kept for each type of RPC (FetchFile, ! GetStatus, and so on) sent or received, aggregated over all connections to ! other machines. To display or otherwise access the records, use the Rx ! Monitoring API. =item B<-abortthreshold> > --- 435,443 ---- Sets the size of the UDP buffer, which is 64 KB by default. Provide a positive integer, preferably larger than the default. ! =item B<-sendsize> > ! Sets the size of the send buffer, which is 16384 bytes by default. =item B<-abortthreshold> > *************** *** 438,448 **** --- 457,577 ---- Setting the threshold to 0 disables the throttling behavior. This option is available in OpenAFS versions 1.4.1 and later. + =item B<-enable_peer_stats> + + Activates the collection of Rx statistics and allocates memory for their + storage. For each connection with a specific UDP port on another machine, + a separate record is kept for each type of RPC (FetchFile, GetStatus, and + so on) sent or received. To display or otherwise access the records, use + the Rx Monitoring API. + + =item B<-enable_process_stats> + + Activates the collection of Rx statistics and allocates memory for their + storage. A separate record is kept for each type of RPC (FetchFile, + GetStatus, and so on) sent or received, aggregated over all connections to + other machines. To display or otherwise access the records, use the Rx + Monitoring API. + + =item B<-syslog [] + + Use syslog instead of the normal logging location for the fileserver + process. If provided, log messages are at instead of the + default LOG_USER. + + =item B<-mrafslogs> + + Use MR-AFS (Multi-Resident) style logging. This option is deprecated. + + =item B<-saneacls> + + Offer the SANEACLS capability for the fileserver. This option is + currently unimplemented. + =item B<-help> Prints the online help for this command. All other valid options are ignored. + =item B<-fs-state-dont-save> + + When present, fileserver state will not be saved during shutdown. Default + is to save state. + + This option is only supported by the demand-attach file server. + + =item B<-fs-state-dont-restore> + + When present, fileserver state will not be restored during startup. + Default is to restore state on startup. + + This option is only supported by the demand-attach file server. + + =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. + + This option is only supported by the demand-attach file server. + + =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). + + This option is only supported by the demand-attach file server. + + =item B<-vlruthresh > + + The number of minutes of inactivity before a volume is eligible for soft + detachment. Default is 120 minutes. + + This option is only supported by the demand-attach file server. + + =item B<-vlruinterval > + + The number of seconds between VLRU candidate queue scan. The default is + 120 seconds. + + This option is only supported by the demand-attach file server. + + =item B<-vlrumax > + + The maximum number of volumes which can be soft detached in a single pass + of the scanner. Default is 8 volumes. + + This option is only supported by the demand-attach file server. + + =item B<-vattachpar> > + + The number of threads assigned to attach and detach volumes. The default + is 1. Warning: many of the I/O parallism features of Demand-Attach + Fileserver are turned off when the number of volume attach threads is only + 1. + + This option is only meaningful for a file server built with pthreads + support. + + =item B<-m> > + + Specifies the percentage of each AFS server partition that the AIX version + of the File Server creates as a reserve. Specify an integer value between + C<0> and C<30>; the default is 8%. A value of C<0> means that the + partition can become completely full, which can have serious negative + consequences. This option is not supported on platforms other than AIX. + + =item B<-lock> + + Prevents any portion of the fileserver binary from being paged (swapped) + out of memory on a file server machine running the IRIX operating system. + This option is not supported on platforms other than IRIX. + =back =head1 EXAMPLES Index: openafs/doc/man-pages/pod8/salvageserver.pod diff -c /dev/null openafs/doc/man-pages/pod8/salvageserver.pod:1.1.2.2 *** /dev/null Sat Mar 22 21:01:23 2008 --- openafs/doc/man-pages/pod8/salvageserver.pod Fri Mar 14 14:49:55 2008 *************** *** 0 **** --- 1,328 ---- + =head1 NAME + + salvageserver - Initializes the Salvageserver component of the dafs process + + =head1 SYNOPSIS + + =for html +
+ + B [I] S<<< [B<-partition> >] >>> + S<<< [B<-volumeid> >] >>> [B<-debug>] [B<-nowrite>] + [B<-inodes>] [B<-force>] [B<-oktozap>] [B<-rootinodes>] + [B<-salvagedirs>] [B<-blockreads>] + S<<< [B<-parallel> >] >>> + S<<< [B<-tmpdir> >] >>> + [B<-showlog>] [B<-showsuid>] [B<-showmounts>] + S<<< [B<-orphans> (ignore | remove | attach)] >>> + [B<-client>] [B<-help>] + + =for html +
+ + =head1 DESCRIPTION + + In its typical mode of operation, the B is a daemon process + responsible for salvaging volumes. It is a component of the C + process type. In the conventional configuration, its binary file is + located in the F directory on a file server machine. + + The Salvageserver daemon is responsible for scheduling and executing + volume salvage operations on behalf of client processes. The fileserver + acts as the primary salvageserver client: any failed volume attach + operation results in a salvageserver scheduling request. The + salvageserver also accepts periodic volume activity messages in order to + update its salvage request priority queue. Other clients of the + salvageserver daemon include the B utility, and the + salvageserver command itself by passing the B<-client> flag. + + The salvage operations performed on vice partition data are nearly + identical to those performed by the standalone Salvager command. The + key differences between the two commands are: + + =over 4 + + =item * + + The Salvageserver is a daemon process which runs concurrently with the + fileserver. In contrast, the Salvager is a stand-alone application which + is invoked when the fileserver and volserver are not running. + + =item * + + The Salvageserver is incapable of performing whole partition salvage + operations; it operates at volume group granularity. + + =back + + The Salvageserver 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 Salvageserver needs to create new inodes. + + By default, multiple Salvageserver subprocesses run in parallel: one for each + volume group. By default, four concurrent salvage operations are + permitted. You may alter this default by providing a positive integer + value for the B<-parallel> argument. The maximum permitted value is 32 + concurrent salvageserver subprocesses. + + By default, the salvageserver enables a heuristic which attempts to stop + disk head thrashing by concurrent salvageserver subprocesses. Unfortunately, + this heuristic significantly degrades performance in many cases. In at least + the following environments, passing the C string to the B<-parallel> + argument is strongly encouraged: + + =over 4 + + =item * + + On NAMEI fileservers + + =item * + + When a vice partition is backed by multiple disks (e.g. RAID) + + =item * + + When a vice partition is backed by SAN-attached storage, LVM, or some other + form of storage virtualization which would cause unix device id numbers to + be unpredictable. + + =back + + The Salvageserver 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 Salvageserver + terminates without completing the salvage operation (it always removes the + temporary files before exiting). Other Salvageserver 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 Salvageserver 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. + + 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 [I] + + Accommodates the command's use of the AFS command parser, and is optional. + + =item B<-partition> > + + 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 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. + + =item B<-debug> + + This flag should be considered deprecated. Its primary purpose was to disable + forking and parallelization of the Salvager so that log messages were not + interleaved. Due to the manner in which F is + written, log messages from subprocesses are never interleaved; the entire log + for a volume group salvage is appended to the master log as one atomic + transaction. + + =item B<-nowrite> + + Brings all undamaged volumes online without attempting to salvage any + damaged volumes. + + =item B<-inodes> + + Records in the F file a list of all AFS inodes + that the Salvageserver modified. + + =item B<-force> + + Inspects all volumes for corruption, not just those that are marked as + having been active when a crash occurred. + + =item B<-oktozap> + + 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 B<-rootinodes> + + Records in the F file a list of all AFS inodes + owned by the local superuser C. + + =item B<-salvagedirs> + + Salvages entire directory structures, even if they do not appear to be + damaged. By default, the Salvageserver salvages a directory only if it is + flagged as corrupted. + + =item B<-blockreads> + + Forces the Salvageserver 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 + Salvageserver 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 B<-parallel> > + + Specifies the maximum number of Salvageserver subprocesses to run in parallel. + Provide one of three values: + + =over 4 + + =item * + + An integer from the range C<1> to C<32>. A value of C<1> means that a + single Salvageserver subprocess salvages the volume groups sequentially. + The disk partition heuristic (see above) based upon unix device ids is + enabled. + + =item * + + The disk partition heuristic (see above) based upon unix device ids is + disabled. + + =item * + + 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 + Salvageserver subprocesses in parallel on volume groups. The disk partition + heuristic (see above) based upon unix device ids is disabled. + + =back + + If this argument is omitted, up to four Salvageserver subprocesses run + in parallel. + + =item B<-tmpdir> > + + Names a local disk directory in which the Salvageserver places the temporary + files it creates during a salvage operation, instead of writing them to + the partition being salvaged (the default). If the Salvageserver cannot write + to the specified directory, it attempts to write to the partition being + salvaged. + + =item B<-showlog> + + Displays on the standard output stream all log data that is being written + to the F file. + + =item B<-showsuid> + + Displays a list of the pathnames for all files that have the setuid or + setgid mode bit set. + + =item B<-showmounts> + + Records in the F file all mount points found in + each volume. The Salvageserver does not repair corruption in the volumes, if + any exists. + + =item B<-orphans> (ignore | remove | attach) + + Controls how the Salvageserver 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 + 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 + 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 Salvageserver assigns each one a name of the following form: + + =over 4 + + =item C<__ORPHANFILE__.I> for files. + + =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. + + =back + + =item B<-client> + + Salvageserver runs in client Mode. The requested volume on the requested + partition will be scheduled for salvaging by the Salvageserver daemon. + + =item B<-help> + + Prints the online help for this command. All other valid options are + ignored. + + =back + + =head1 EXAMPLES + + The following command instructs the Salvageserver to schedule the salvage + of the volume with volume ID 258347486 on F on the local machine. + + % /usr/afs/bin/salvageserver -partition /vicepg -volumeid 258347486 -client + + =head1 PRIVILEGE REQUIRED + + To issue the command at the shell prompt, the issuer must be logged in as + the local superuser C. + + =head1 SEE ALSO + + L, + L, + L, + L, + L, + L, + L + + =head1 COPYRIGHT + + IBM Corporation 2000. All Rights Reserved. + Sine Nomine Associates 2008. 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. This document + was adapted from the Salvager POD documentation. Index: openafs/doc/txt/README.linux-nfstrans diff -c /dev/null openafs/doc/txt/README.linux-nfstrans:1.1.2.2 *** /dev/null Sat Mar 22 21:01:24 2008 --- openafs/doc/txt/README.linux-nfstrans Mon Mar 17 13:48:53 2008 *************** *** 0 **** --- 1,268 ---- + ## Introduction + + This version works on Linux 2.6, and provides the following features: + + - Basic AFS/NFS translator functionality, similar to other platforms + - Ability to distinguish PAG's assigned within each NFS client + - A new 'afspag' kernel module, which provides PAG management on + NFS client systems, and forwards AFS system calls to the translator + system via the remote AFS system call (rmtsys) protocol. + - Support for transparent migration of an NFS client from one translator + server to another, without loss of credentials or sysnames. + - The ability to force the translator to discard all credentials + belonging to a specified NFS client host. + + + The patch applies to OpenAFS 1.4.1, and has been tested against the + kernel-2.6.9-22.0.2.EL kernel binaries as provided by the CentOS project + (essentially these are rebuilds from source of Red Hat Enterprise Linux). + This patch is not expected to apply cleanly to newer versions of OpenAFS, + due to conflicting changes in parts of the kernel module source. To apply + this patch, use 'patch -p0'. + + It has been integrated into OpenAFS 1.5.x. + + ## New in Version 1.4 + + - There was no version 1.3 + - Define a "sysname generation number" which changes any time the sysname + list is changed for the translator or any client. This number is used + as the nanoseconds part of the mtime of directories, which forces NFS + clients to reevaluate directory lookups any time the sysname changes. + - Fixed several bugs related to sysname handling + - Fixed a bug preventing 'fs exportafs' from changing the flag which + controlls whether callbacks are made to NFS clients to obtain tokens + and sysname lists. + - Starting in this version, when the PAG manager starts up, it makes a + call to the translator to discard any tokens belonging to that client. + This fixes a problem where newly-created PAG's on the client would + inherit tokens owned by an unrelated process from an earlier boot. + - Enabled the PAG manager to forward non-V-series pioctl's. + - Forward ported to OpenAFS 1.4.1 final + - Added a file, /proc/fs/openafs/unixusers, which reports information + about "unixuser" structures, which are used to record tokens and to + bind translator-side PAG's to NFS client data and sysname lists. + + + ## Finding the RPC server authtab + + In order to correctly detect NFS clients and distinguish between them, + the translator must insert itself into the RPC authentication process. + This requires knowing the address of the RPC server authentication dispatch + table, which is not exported from standard kernels. To address this, the + kernel must be patched such that net/sunrpc/svcauth.c exports the 'authtab' + symbol, or this symbol's address must be provided when the OpenAFS kernel + module is loaded, using the option "authtab_addr=0xXXXXXXXX" where XXXXXXXX + is the address of the authtab symbol as obtained from /proc/kallsyms. The + latter may be accomplished by adding the following three lines to the + openafs-client init script in place of 'modprobe openafs': + + modprobe sunrpc + authtab=`awk '/[ \t]authtab[ \t]/ { print $1 }' < /proc/kallsyms` + modprobe openafs ${authtab:+authtab_addr=0x$authtab} + + + ## Exporting the NFS filesystem + + In order for the translator to work correctly, /afs must be exported with + specific options. Specifically, the 'no_subtree_check' option is needed + in order to prevent the common NFS server code from performing unwanted + access checks, and an fsid option must be provided to set the filesystem + identifier to be used in NFS filehandles. Note that for live migration + to work, a consistent filesystem id must be used on all translator systems. + The export may be accomplised with a line in /etc/exports: + + /afs (rw,no_subtree_check,fsid=42) + + Or with a command: + + exportfs -o rw,no_subtree_check,fsid=42 :/afs + + The AFS/NFS translator code is enabled by default; no additional command + is required to activate it. However, the 'fs exportafs nfs' command can + be used to disable or re-enable the translator and to set options. Note + that support for client-assigned PAG's is not enabled by default, and + must be enabled with the following command: + + fs exportafs nfs -clipags on + + Support for making callbacks to obtain credentials and sysnames from + newly-discovered NFS clients is also not enabled by default, because this + would result in long timeouts on requests from NFS clients which do not + support this feature. To enable this feature, use the following command: + + fs exportafs nfs -pagcb on + + + ## Client-Side PAG Management + + Management of PAG's on individual NFS clients is provided by the kernel + module afspag.ko, which is automatically built alongside the libafs.ko + module on Linux 2.6 systems. This component is not currently supported + on any other platform. + + To activate the client PAG manager, simply load the module; no additional + parameters or commands are required. Once the module is loaded, PAG's + may be acquired using the setpag() call, exactly as on systems running the + full cache manager. Both the traditional system call and new-style ioctl + entry points are supported. + + In addition, the PAG manager can forward pioctl() calls to an AFS/NFS + translator system via the remote AFS system call service (rmtsys). To + enable this feature, the kernel module must be loaded with a parameter + specifying the location of the translator system: + + insmod afspag.ko nfs_server_addr=0xAABBCCDD + + In this example, 0xAABBCCDD is the IP address of the translator system, + in network byte order. For example, if the translator has the IP address + 192.168.42.100, the nfs_server_addr parameter should be set to 0xc0a82a64. + + The PAG manager can be shut down using 'afsd -shutdown' (ironically, this + is the only circumstance in which that command is useful). Once the + shutdown is complete, the kernel module can be removed using rmmod. + + + ## Remote System Calls + + The NFS translator supports the ability of NFS clients to perform various + AFS-specific operations via the remote system call interface (rmtsys). + To enable this feature, afsd must be run with the -rmtsys switch. OpenAFS + client utilities will use this feature automatically if the AFSSERVER + environment variable is set to the address or hostname of the translator + system, or if the file ~/.AFSSERVER or /.AFSSERVER exists and contains the + translator's address or hostname. + + On systems running the client PAG manager (afspag.ko), AFS system calls + made via the traditional methods will be automatically forwarded to the + NFS translator system, if the PAG manager is configured to do so. This + feature must be enabled, as described above. + + + ## Credential Caching + + The client PAG manager maintains a cache of credentials belonging to each + PAG. When an application makes a system call to set or remove AFS tokens, + the PAG manager updates its cache in addition to forwarding the request + to the NFS server. + + When the translator hears from a previously-unknown client, it makes a + callback to the client to retrieve a copy of any cached credentials. + This means that credentials belonging to an NFS client are not lost if + the translator is rebooted, or if the client's location on the network + changes such that it is talking to a different translator. + + This feature is automatically supported by the PAG manager if it has + been configured to forward system calls to an NFS translator. However, + requests will be honored only if they come from port 7001 on the NFS + translator host. In addition, this feature must be enabld on the NFS + translator system as described above. + + + ## System Name List + + When the NFS translator hears from a new NFS client whose system name + list it does not know, it can make a callback to the client to discover + the correct system name list. This ability is enabled automatically + with credential caching and retrieval is enabled as described above. + + The PAG manager maintains a system-wide sysname list, which is used to + satisfy callback requests from the NFS translator. This list is set + intially to contain only the compiled-in default sysname, but can be + changed by the superuser using the VIOC_AFS_SYSNAME pioctl or the + 'fs sysname' command. Any changes are automatically propagated to the + NFS translator. + + + ## Dynamic Mount Points + + This patch introduces a special directory ".:mount", which can be found + directly below the AFS root directory. This directory always appears to + be empty, but any name of the form "cell:volume" will resolve to a mount + point for the specified volume. The resulting mount points are always + RW-path mount points, and so will resolve to an RW volume even if the + specified name refers to a replicated volume. However, the ".readonly" + and ".backup" suffixes can be used to refer to volumes of those types, + and a numeric volume ID will always be used as-is. + + This feature is required to enable the NFS translator to reconstruct a + reachable path for any valid filehandle presented by an NFS client. + Specifically, when the path reconstruction algorithm is walking upward + from a client-provided filehandle and encounters the root directory of + a volume which is no longer in the cache (and thus has no known mount + point), it will complete the path to the AFS root using the dynamic + mount directory. + + This feature is available whenever the dynamic AFS root is enabled. + On Linux systems, it is also available even when dynroot is not enabled, + to support the NFS translator. It is presently not possible to disable + this feature, though that ability may be added in the future. It would + be difficult to make this feature unavailble to users and still make the + Linux NFS translator work, since the point of the check being performed + by the NFS server is to ensure the requested file would be reachable by + the client. + + + ## Security + + The security of the NFS translator depends heavily on the underlying + network. Proper configuration is required to prevent unauthorized + access to files, theft of credentials, or other forms of attack. + + NFS, remote syscall, and PAG callback traffic between an NFS client host + and translator may contain sensitive file data and/or credentials, and + should be protected from snooping by unprivileged users or other hosts. + + Both the NFS translator and remote system call service authorize requests + in part based on the IP address of the requesting client. To prevent an + attacker from making requests on behalf of another host, the network must + be configured such that it is impossible for one client to spoof the IP + address of another. + + In addition, both the NFS translator and remote system call service + associate requests with specific users based on user and group ID data + contained within the request. In order to prevent users on the same client + from making filesystem access requests as each other, the NFS server must + be configured to accept requests only from privileged ports. In order to + prevent users from making AFS system calls on each other's behalf, possibly + including retrieving credentials, the network must be configured such that + requests to the remote system call service (port 7009) are accepted only + from port 7001 on NFS clients. + + When a client is migrated away from a translator, any credentials held + on behalf of that client must be discarded before that client's IP address + can safely be reused. The VIOC_NFS_NUKE_CREDS pioctl and 'fs nukenfscreds' + command are provided for this purpose. Both take a single argument, which + is the IP address of the NFS client whose credentials should be discarded. + + + ## Known Issues + + + Because NFS clients do not maintain active references on every inode + they are using, it is possible that portions of the directory tree + in use by an NFS client will expire from the translator's AFS and + Linux dentry cache's. When this happens, the NFS server attempts to + reconstruct the missing portion of the directory tree, but may fail + if the client does not have sufficient access (for example, if his + tokens have expired). In these cases, a "stale NFS filehandle" error + will be generated. This behavior is similar to that found on other + translator platforms, but is triggered under a slightly different set + of circumstances due to differences in the architecture of the Linux + NFS server. + + + Due to limitations of the rmtsys protocol, some pioctl calls require + large (several KB) transfers between the client and rmtsys server. + Correcting this issues would require extensions to the rmtsys protocol + outside the scope of this project. + + + The rmtsys interface requires that AFS be mounted in the same place + on both the NFS client and translator system, or at least that the + translator be able to correctly resolve absolute paths provided by + the client. + + + If a client is migrated or an NFS translator host is unexpectedly + rebooted while AFS filesystem access is in progress, there may be + a short delay before the client recovers. This is because the NFS + client must time out any request it made to the old server before + it can retransmit the request, which will then be handled by the + new server. The same applies to remote system call requests. Index: openafs/doc/txt/winnotes/afs-changes-since-1.2.txt diff -c openafs/doc/txt/winnotes/afs-changes-since-1.2.txt:1.72.2.48 openafs/doc/txt/winnotes/afs-changes-since-1.2.txt:1.72.2.50 *** openafs/doc/txt/winnotes/afs-changes-since-1.2.txt:1.72.2.48 Mon Feb 25 20:08:19 2008 --- openafs/doc/txt/winnotes/afs-changes-since-1.2.txt Fri Mar 21 13:17:41 2008 *************** *** 1,3 **** --- 1,117 ---- + Since 1.5.33 + * Optimize the DNLC by applying Interlocked incrementing for + statistics gathering and enabling greater use of read + locks instead of write locks + + * Further optimize osi_Log operations when logging is disabled + by removing the need for the function call overhead. + + * Add a new lock operation, Convert Read to Write, and apply + it throughout the cache manager. This function provides a + fast transition from a read lock to a write lock when the + caller is the only reader. + + * Fix a timeout problem when opening files or request locks + when the file in question is already write-locked by another + machine. + + * Fix a deadlock that can occur if "fs flushall" is executed + while applications are writing to AFS. + + * The cache manager would re-read data from the file server + after file truncation when obtaining buffers to write to the + same file until the first StoreData RPC completes. + + * Fixes error handling in cm_NTCheckDelete() + + * Replaces cm_scache_t mutex with a read-write lock permitting + additional parallel access. + + * Prevent an cm_scache_t reference undercount when evaluating + symlinks containing @sys when none of the active sysnames + match any of the available targets. + + * Prevent the leak of a cm_scache_t rwlock if associated symlink + is too long. + + * Set RxMaxMTU registry value to 0 which is the equivalent of + it not being set at all. + + * Reduce contention between BkgDaemon threads + + * Prevent CM_SCACHEFLAG_ASYNCSTORE from being reset on a write + failure + + * Convert reference counts on cm_volume_t, cm_conn_t, cm_server_t + objects to use the faster Interlocked operations which avoid + the need to hold write locks. + + * Permit rxkad errors other than RXKADEXPIRED to be treated as a + non-fatal error that forces a retry against another service + (if available.) + + * Fix a crash in smb_WriteData that would occur if an application + opened the file as read-only and then sent a write request anyway. + (RT 88731) + + * Respond to VL_NOENT errors by removing cm_volume_t object and + setting it to be the first object to be recycled. This is not + only a more efficient use of resources but it also prevents + repeated attempts to query the VLDB server for the volume from + the CheckOfflineVolumes routine. + + * Change the defaults for RxEnablePeerStats and RxEnableProcessStats + back to "on". + + * A first cut at a cache manager statistics monitor that can be used + to determine the necessary cache parameters to support the + application working set. + + Off by default, the performance package can be activated by setting + "daemonPerformanceTuningInterval" in the service Parameters key. + As with the other daemon interval values the unit is in seconds. + + At service start and each succeeding interval the cache manager + will write statistics to %TEMP%\afsd_performance.txt showing the + relative usage of cm_scache_t, cm_volume_t and cm_buf_t objects. + The FID statistics keep track of all FIDs seen by the cache manager + during the service session whether or not they are backed by any + live object in the cache. + + These statistics are not stored in the cache file. + + * Fix windows event logging broken in 1.5.33. + + * Eliminate multiple calls to syscfg_GetIFInfo() which is used to + populate the IP address list for WhoAreYou/TellMeAboutYourself RPCs + as well as when computing the server preference list. + + * When merging status after a StoreData operation prevent data + buffers from being discarded that we would prefer to keep. + (Bug introduced in 1.5.33.) + + * Modify installers the set RxMaxMTU to 0. + + * In the AFS Configuration Panel on the Advanced->Miscellaneous + dialog, the Background Daemons and Service Threads fields were + swapped. + + * Increase default number of Background Daemons to 4. + + * Remove cm_volume_t reference from the cm_scache_t object. Permit + cm_volume_t objects to be recycled. + + * Windows Error Reporting has shown a number of previously unseen + stack corruption errors in the Explorer Shell extension. The + minidump appeared to indicate the problem was in ParseAcl(). + Reviewing the function it appears that numerous things could go + wrong if invalid input was provided. Added error checking and + data validation. Hopefully this will address the problem. + + * Windows Error Reporting has shown crashes in aklog as a result + of krb5_cc_get_default() failures not being handled. They are + now handled. + Since 1.5.32 * The Rx library used a 32-bit type for sockets which was truncating the socket value on 64-bit Windows. This