Initializes the File Exporter and starts associated kernel daemons
Synopsis
fxd -admingroup group [-mainprocs number_of_background_daemons]
[-tokenprocs number_of_token_daemons] [-hostlife client_timeout]
[-hostrpc client_rpc_timeout] [-pollinterval server_poll_period]
[-maxlife max_hostlife] [-maxrpc max_hostrpc] [-notsr] [-minlocalprotect level
level] [-maxlocalprotectlevel level] [-minremoteprotectlevel level] [-maxremoteprotectlevel level] [-verbose] [-help]
Options
-admingroup group
Specifies the name of the group that can administer the File Exporter on this machine. Members of the specified group can effectively change the
permissions, owner, and owning group of any file system object exported from the machine. A group from the local cell can be specified by a full or abbreviated group name (for example,
/.../cellname/group_name or just group_name); a group from a foreign cell can be specified only by a full group name. The -admingroup option performs a function
similar to that of the administrative lists associated with DFS server processes, such as the Fileset Server and the Fileset Location Server, that run in the user space.
-mainprocs number_of_background_daemons
Specifies the number of main kernel processes (File Exporter kernel daemons) to run on the machine. These File Exporter kernel
daemons are responsible for receiving and servicing RPC requests for data and tokens from DFS clients. Specify an integer greater than 0 (zero) to indicate the number of main kernel daemons to
perform these services. If this option is omitted, four main kernel daemons perform these services.
-tokenprocs number_of_token_daemons
Specifies the number of token-revocation kernel processes (File Exporter kernel daemons) to run on the machine. These File Exporter
kernel daemons are responsible for responding to RPCs from DFS clients that are themselves responding to token revocation requests. Specify an integer greater than 0 (zero) to indicate the number of
kernel daemons to perform these services. If this option is omitted, two kernel daemons perform these services.
-hostlife client_timeout
Specifies the host lifetime the File Exporter assigns to each client that contacts it. The host lifetime is the length of time for which the
File Exporter considers a client to be alive. Each client must contact the File Exporter within this amount of time to renew its host lifetime. As long as a client's host lifetime has not expired,
the File Exporter cannot revoke its tokens without its permission.
By default, the File Exporter assigns each client a host lifetime of 2 minutes. Specify an integer to indicate a number of seconds to serve as the host lifetime. The host lifetime must be greater than 0 (zero) and less than or equal to the maximum host lifetime (specified with the -maxlife option) and the host RPC lifetime (specified with the -hostrpc option).
-hostrpc client_rpc_timeout
Specifies the host RPC lifetime the File Exporter assigns to each client that contacts it. The host RPC lifetime is the length of time for
which the File Exporter guarantees to attempt an RPC to a client before it revokes its tokens. The File Exporter can revoke the tokens of any client whose host RPC lifetime has expired without
contacting the client.
By default, the File Exporter assigns each client a host RPC lifetime of 2 minutes. Specify an integer to indicate a number of seconds to serve as the host RPC lifetime. The host RPC lifetime must be greater than or equal to the host lifetime (specified with the -hostlife option) and less than or equal to the maximum host RPC lifetime (specified with the -maxrpc option).
-pollinterval server_poll_period
Specifies the polling interval the File Exporter assigns to each client that contacts it. The polling interval is the frequency with
which each client that has tokens from the File Exporter is to poll it in the event that it cannot be reached. Each client sends an RPC to the File Exporter with this frequency until it can again
contact it.
By default, the File Exporter assigns each client a polling interval of 3 minutes. Specify an integer greater than 0 (zero) to indicate a number of seconds to serve as the
polling interval.
-maxlife max_hostlife
Specifies the maximum host lifetime the File Exporter can grant a client. A client can request a host lifetime larger than that specified with the
-hostlife option, but the File Exporter will not grant a host lifetime greater than the value specified with this option.
By default, the File Exporter uses a value of 2 minutes as the maximum host lifetime. Specify an integer to indicate a number of seconds to serve as the maximum host lifetime. The maximum host lifetime must be greater than or equal to the host lifetime (specified with the -hostlife option) and less than or equal to the maximum host RPC lifetime (specified with the -maxrpc option).
-maxrpc max_hostrpc
Specifies the maximum host RPC lifetime the File Exporter can grant a client. A client can ask for a host RPC lifetime larger than that specified
with the -hostrpc option, but the File Exporter will not grant a host RPC lifetime greater than the value specified with this option.
By default, the File Exporter uses a value of 2 minutes as the maximum host RPC lifetime. Specify an integer to indicate a number of seconds to serve as the maximum host RPC lifetime. The maximum host RPC lifetime must be greater than or equal to the host RPC lifetime (specified with the -hostrpc option) and the maximum host lifetime (specified with the -maxlife option).
-notsr
Specifies that the File Exporter is to forego token state recovery when it is restarted. If this option is specified, the File Exporter accepts requests for new tokens
as soon as it can again be contacted by clients. By default, it provides a brief token state recovery period during which it accepts requests only to reestablish tokens from clients that held them
before it was restarted. (It bases the duration of its period of token state recovery on the greater of its -pollinterval or -maxlife, plus 20 seconds.)
This option is useful primarily for debugging purposes. Use it sparingly, as it prevents the File Exporter from maintaining consistent token state across File Server machine restarts.
-minlocalprotectlevel level
Specifies the minimum acceptable DCE RPC authentication level for communications between the File Exporter and clients within the same cell.
The level is set either as an integer value between 0 and 6, the complete string defining the authentication level, or an abbreviation of that string. For a description of the various DCE
RPC levels, see the Security subtopic in the Description topic.
-maxlocalprotectlevel level
Specifies the maximum acceptable DCE RPC authentication level for communications between the File Exporter and clients in the local cell.
The level is set either as an integer value between 0 and 6, the complete string defining the authentication level, or an abbreviation of that string. For a description of the various DCE
RPC levels, see the Security subtopic in the Description topic.
-minremoteprotectlevel level
Specifies the minimum acceptable DCE RPC authentication level for communications between the File Exporter and clients in foreign cells.
The level is set either as an integer value between 0 and 6, the complete string defining the authentication level, or an abbreviation of that string. For a description of the various DCE
RPC levels, see the Security subtopic in the Description topic.
-maxremoteprotectlevel level
Specifies the maximum acceptable DCE RPC authentication level for communications between the File Exporter and clients in foreign cells.
The level is set either as an integer value between 0 and 6, the complete string defining the authentication level, or an abbreviation of that string. For a description of the various DCE
RPC levels, see the Security subtopic in the Description topic.
-verbose
Directs fxd to produce more detailed information about its actions during initialization and as it creates kernel daemons.
-help
Prints the online help for this command. All other valid options specified with this option are ignored.
The help and apropos commands available with all command suites are also available with the fxd command. See the bos help and bos apropos reference pages for examples using these commands.
Description
The fxd command initializes the File Exporter on a File Server machine and starts all kernel daemons, such as those for garbage collection, required by the File Exporter. During initialization, it also passes the File Exporter such information as the name of the local cell, information about the local Fileset Database machines, and the identity of the group that can administer the File Exporter. The File Exporter uses this information to communicate with other processes, such as the Fileset Location (FL) Servers on Fileset Database machines, and to ensure that only privileged users administer data in filesets exported from the machine.
The File Exporter must be run on all machines that export data for use in the global namespace. A machine that runs the File Exporter, the Fileset Server (ftserver process), and the dfsbind process is considered to be a DFS File Server machine. The File Exporter is typically run by adding the fxd command to the proper start-up file (/etc/rc or its equivalent). The dfsbind process must be run before the fxd process in a start-up file. The binary file for the fxd process resides in dcelocal/bin/fxd. The process automatically places itself in the background once its initialization is complete.
The -mainprocs and -tokenprocs options can be used to alter the default number of kernel daemons running on the server machine, as follows:
· The -mainprocs option specifies the number of main kernel daemons that run on the machine to service RPC requests for data and tokens from DFS clients. The default number of main kernel daemons is four, which is usually sufficient to handle RPC requests from many DFS client machines. Use the -mainprocs option to increase the number of main kernel daemons dedicated to servicing RPC requests if the machine is to support a large number of DFS clients.
· The -tokenprocs option specifies the number of kernel daemons dedicated to responding to RPCs from DFS clients that are themselves responding to token revocation requests from the File Exporter. The default number of kernel daemons dedicated to this task is two. If the -mainprocs option is used to increase the number of main kernel daemons, use the -tokenprocs option to increase the number of kernel daemons dedicated to handling responses to token revocation requests accordingly.
On most system types, these kernel daemons appear as nameless entries in the output of the ps command (or its equivalent). However, because some of the kernel daemons run as threads rather than processes, not all of them show up in the output of the ps command.
The -admingroup option is used to associate system administrators with the fxd process. Members of the group specified with the -admingroup option have the necessary ACL and UNIX permissions to change the permissions of any file or directory object exported from the machine. They have the equivalent of the ACL c permission on the objects in each exported DCE LFS fileset, and they can effectively change the mode bits on the objects in each exported non-LFS fileset. (To change the permissions on an object that resides in a lower-level directory of an exported fileset, a member of the group may need to provide the group with the necessary permissions on directories in the path that leads to the object.) Members of the group can also change the owner and owning group of any object exported from the machine. Note that, while similar in many respects, inclusion in the group specified with the -admingroup option and being logged in as root are not equivalent.
Place only highly trusted users in the group associated with the fxd process. Members of the group generally constitute a subset of the users in other DFS administrative lists such as the admin.bos file. For simplified administration, the same group can be specified with the -admingroup options of all fxd commands issued in a domain.
The fxd command includes a number of options that affect the File Exporter's management of tokens. The following two sections describe only those token-related issues germane to the fxd command's options. Tokens, their management by the File Exporter, and their benefits and implications are described in Part 1.
Token Management
Token management refers to the File Exporter's use of tokens to synchronize access to data and metadata on a File Server machine. The File Exporter uses tokens to track the clients that have accessed data from the machine and the types of operations they are permitted to perform on the data. When a client wants to access or change data on a File Server machine, it contacts the File Exporter on the machine to request the necessary tokens for the data. If the File Exporter can grant the client the requested tokens, the client in turn can use the tokens to access the data from the File Exporter.
Many factors affect the File Exporter's ability to grant a client's request for tokens. The File Exporter can always grant requests for tokens that do not conflict with those already held by another client. If requested tokens do conflict with existing tokens held by another client, the File Exporter tries to revoke the existing tokens. If it can revoke the existing tokens, it grants those requested; if it cannot, it either places the request in a queue or refuses it. (The choice is the client's.)
When its tokens are revoked, a client such as the Cache Manager flushes cached data for which the tokens applied, writing any modified data back to the File Server machine. Among the factors that affect the File Exporter's ability to revoke existing tokens are the various lifetimes it associates with the tokens it grants and the clients to which it grants them. The following list briefly introduces these values, of which the latter two can be modified with options of the fxd command:
Token lifetime
Specifies the length of time for which a token is valid. The File Exporter needs to revoke only valid tokens. Once a token has expired, the File Exporter does
not need to revoke it; it can simply grant new tokens as if the expired token did not exist.
Host lifetime
Specifies the length of time for which the File Exporter considers a client to be alive. A client must contact the File Exporter to renew its host lifetime before
it expires. As long as a client's host lifetime has not expired, the File Exporter cannot revoke its tokens without its permission.
Host RPC lifetime
Specifies the length of time for which the File Exporter agrees to attempt to make an RPC to a client before it revokes its tokens. The client's response to
the RPC renews its host lifetime, meaning the File Exporter cannot revoke its tokens without its permission. If the client fails to respond to the RPC but its host lifetime has not expired, the File
Exporter cannot revoke its tokens; if it fails to respond and its host lifetime has expired, the File Exporter can revoke any tokens it holds without contacting it further. The File Exporter can
revoke a client's tokens without contacting it once its host RPC lifetime has expired. A client's host RPC lifetime must be at least as long as its host lifetime.
In general, the following rules apply to the File Exporter's revocation of valid tokens:
1. If the client's host lifetime has not expired, the File Exporter tries to contact the client; it must have the client's permission to revoke its tokens.
2. If the client's host lifetime has expired but its host RPC lifetime has not, the File Exporter tries to contact the client one time. If the client responds, the File Exporter cannot revoke its tokens without its permission; otherwise, the File Exporter can revoke any tokens held by the client without contacting it further.
3. If the client's host RPC lifetime has expired, the File Exporter can revoke its tokens without contacting it.
The following options of the fxd command can be used to modify the lifetimes the File Exporter assigns to its clients. By default, the File Exporter use values of 2 minutes for each of these lifetimes.
-hostlife
Specifies each client's default host lifetime. The -hostlife must be greater than 0 (zero) and less than or equal to both the -maxlife and the
-hostrpc.
-maxlife
Specifies the maximum host lifetime the File Exporter will grant to a client that asks for one larger than the default specified with the -hostlife option.
The -maxlife must be greater than or equal to the -hostlife and less than or equal to the -maxrpc.
-hostrpc
Specifies each client's default host RPC lifetime. The -hostrpc must be greater than or equal to the -hostlife and less then or equal to the
-maxrpc.
-maxrpc
Specifies the maximum host RPC lifetime the File Exporter will grant to a client that asks for one larger than the default specified with the -hostrpc option.
The -maxrpc must be greater than or equal to both the -maxlife and the -hostrpc.
If you use one of these options to modify a default lifetime value, be careful not to violate any of the dependency rules described in the previous list. In some cases, the command can adjust values not modified by the user to ensure that the dependencies are not violated, as follows:
· If you increase the value of -hostlife without specifying -maxlife, -hostrpc, or -maxrpc, the command increases the other three values as necessary.
· If you increase the value of -maxlife without specifying -maxrpc, the command increases the value of -maxrpc as necessary.
· If you increase the value of -hostrpc without specifying -maxrpc, the command increases the value of -maxrpc as necessary.
· If you decrease the value of -maxlife without specifying -hostlife, the command decreases the value of -hostlife as necessary.
· If you decrease the value of -maxrpc without specifying -hostrpc, the command decreases the value of -hostrpc as necessary.
· If you specify multiple values that explicitly violate one or more of the dependency rules, the command fails.
· If you specify a value that implicitly violates one or more of the dependency rules and the command cannot adjust other values to compensate for the violation, the command fails.
The command displays an appropriate message if it adjusts a value that was not specified or if it fails because specified values violate the previously defined rules.
Token State Recovery
Token state recovery refers to clients regaining their tokens following a network failure or File Server machine restart. In either of these situations, each client that cannot contact the File Exporter polls the File Exporter at regular intervals. When it can again reach the File Exporter, the client attempts to recover tokens it had before it lost contact. The frequency with which each client tries to contact the File Exporter in these cases is defined with the -pollinterval option of the fxd command; by default, each client polls the File Exporter every 3 minutes.
In the case of a network failure, a client may be unable to prevent its host lifetime from expiring before it can again contact the File Exporter. Once communication is restored, the client must either reclaim its tokens or request new ones, as necessary. The client may need to compete for its tokens with other clients to which the tokens were granted while it could not reach the File Exporter.
In the case of a File Exporter restart, the File Exporter loses all knowledge of tokens it granted. For a brief period after it restarts, it refuses all requests for new tokens from all clients. During this period, it accepts requests only to reestablish tokens from those clients that held them before it was restarted. The File Exporter gives those clients that held tokens before it was restarted the chance to recover their tokens without having to compete with other clients that could request the same tokens.
The File Exporter bases the length of its period of token state recovery after a restart on the -maxlife or the -pollinterval, whichever is greater (it adds 20 seconds to the value it chooses to compensate for its own initialization time). The larger of these two values ensures that each client that had tokens has an opportunity to contact the File Exporter before the File Exporter accepts requests for new tokens from all clients. (Within this time, each client will contact the File Exporter either to renew its host lifetime or to poll the File Exporter.)
If the File Exporter receives many requests to reestablish tokens just prior to the end of its token state recovery period, it dynamically extends the original length of the period. If many clients continue to contact it during the extension, the File Exporter continues to extend the period incrementally, to a maximum of twice its original length.
(Note that, if a client is restarted for any reason, it loses all knowledge of the tokens it possessed prior to the restart; recovery of its tokens is not possible.)
Security
The -minlocalprotectlevel, -maxlocalprotectlevel, -minremoteprotectlevel, and -maxremoteprotectlevel options set the minimum and maximum RPC authentication bounds for communications between the File Exporter and clients. These bounds are used in negotiating an RPC authentication level for communications with clients. Two sets of bounds are maintained: a set that governs communications with clients within the same cell, and a second set that governs communications with clients in foreign cells.
In operation, the File Exporter and client (Cache Manager) interact to arrive at a mutually acceptable authentication level for communications. The negotiation starts with an RPC using the initial authentication level sent from the Cache Manager to the File Exporter. If the initial authentication level is outside the minimum or maximum bounds set through the fxd command, the File Exporter returns a response to the Cache Manager specifying that the authentication level is either too low or too high. The Cache Manager then decreases or increases its authentication level accordingly and retries the RPC. This process continues until the Cache Manager either adjusts its RPCs to an acceptable security level or the File Exporter requests a security level below the minimum set at the Cache Manager (causing the Cache Manager to refuse communications with the File Exporter). Once the Cache Manager and File Exporter have negotiated a security level, the Cache Manager stores this information so that it does not need to renegotiate this level for further communications with the File Exporter.
In addition, administrators can also set advisory bounds on a per-fileset basis. At present, these advisory levels serve only to bias the Cache Manager's selection of an initial authentication level (they may be enforced in a future version of DFS). Advisory bounds are set through the fts setprotectlevels command and are stored in the FLDB record for that fileset.
Note that the use of this command does not preclude communications with File Servers running earlier versions of DFS.
The various authentication levels are set by specifying either an integer value between 0 and 6, a complete string specifying the authentication level, or an abbreviation of that string as the level argument for the various command options. The following lists the various authentication levels:
· rpc_protect_level_default or default or 0
Use the DCE default authentication level.
· rpc_protect_level_none or none or 1
Perform no authentication.
· rpc_protect_level_connect or connect or 2
Authenticate only when the Cache Manager establishes a connection with the File Server.
· rpc_protect_level_call or call or 3
Authenticate only at the beginning of each RPC received.
· rpc_protect_level_pkt or pkt or 4
Ensure that all data received is from the expected host.
· rpc_protect_level_pkt_integrity or pkt_integrity or 5
Authenticate and verify that none of the data transferred has been modified.
· rpc_protect_level_pkt_privacy or pkt_privacy or 6
Perform authentication as specified by all of the previous levels and also encrypt
each RPC argument value.
Note that there is a trade-off between selecting higher security and performance. The higher levels of security require more overhead and increase the response time in file operations with File Servers.
The default values of the File Exporter and Cache Manager are such that, if they are not changed, the File Exporter and Cache Manager will negotiate to the packet integrity level. The default File Exporter values are as follows:
· The default minimum authentication level for communications with clients in the local cell is set to none.
· The default maximum authenticationn level for communications with clients in the local cell is set to packet privacy.
· The default minimum authentication level for communications with clients in foreign cells is set to none.
· The default maximum authentication level for communications with clients in foreign cells is set to packet privacy.
The default Cache Manager settings are as follows:
· The default initial authentication level for communications with File Exporters in the local cell is set to packet integrity.
· The default minimum authentication level for communications with File Exporters in the local cell is set to none.
· The default initial authentication level for communications with File Exporters in foreign cells is set to packet integrity.
· The default minimum authentication level for communications with File Exporters in foreign cells is set to packet.
Given that both Cache Manager default initial authentication levels are set to packet integrity and that this level is within the default bounds set at the File Exporter, the default authentication level is therefore packet integrity. If you set the minimum bound at the File Exporter higher than packet integrity, any Cache Managers from a version of DFS previous to 1.2.2 will not be able to communicate with that File Exporter.
Privilege Required
The issuer must be logged in as root on the local machine.
Cautions
If you restart the File Exporter with the fxd command's -notsr option, the File Exporter does not enter token state recovery; clients do not have a protected opportunity to reestablish their tokens after the restart. Similarly, if you restart the File Exporter using different values for the command's lifetime or polling interval values, the File Exporter may not remain in token state recovery long enough to provide all clients an opportunity to reestablish their tokens after it is restarted. (Until they reestablish contact with the File Exporter, clients continue to use the previous lifetime and polling interval values, which may be too long if the File Exporter is directed to use shorter values when it is restarted.)
If you set the minimum RPC authentication level for communications with clients in either local or foreign cells to higher than packet integrity, the affected clients that are running a version of DFS previous to 1.2.2 will not be able to communicate with the File Exporter.
Output
The command sends error messages to standard error output (stderr) if problems are encountered during initialization. It also displays error messages if you specify values for its lifetime-related options that violate the dependencies mentioned in the section on Token Management. Finally, it displays warning messages if it adjusts one or more of its lifetime values to compensate for an option you specify.
Examples
The following line, entered in the appropriate initialization file (/etc/rc or its equivalent) on a File Server machine, starts the fxd process on the local machine. The cell_fileset group is specified as the administrative group for the File Exporter on the machine. The dfsbind process must be run before the fxd process in a start-up file.
fxd -admin cell_fileset
The previous command line can be modified as follows to increase the host RPC lifetime, maximum host lifetime, and maximum host RPC lifetime associated with the File Exporter:
fxd -admin cell_fileset -hostrpc 180 -maxlife 240
These options change the File Exporter's lifetime values, as follows:
· The -hostrpc option explicitly increases the host RPC lifetime to 3 minutes.
· The -maxlife option explicitly increases the maximum host lifetime to 4 minutes. It also causes the command to implicitly increase the maximum host RPC lifetime to 4 minutes. (Note that, had the -maxlife option been omitted, the command would have implicitly increased the maximum host RPC lifetime to 3 minutes to match the increase to the host RPC lifetime.)
Related Information
Commands: