Sets the Cache Manager's preferences for File Server or File Location (FL) Server machines
Synopsis
cm setpreferences [-server machine rank...] [-path filename] [-stdin] [-fldb] [-help]
Options
-server machine rank
Specifies File Server or FL Server preference entries, with each entry consisting of a machine specification (a host name or IP address) and a
preference rank. Separate each machine specification and each rank with one or more spaces. By default, the -server option specifies File Server machine entries; add the -fldb
option to specify FL Server machine entries. Each server machine can have multiple preference entries, with each entry having a unique host name or IP address. Refer to the "Specifying Preferences"
topic of this reference page for information about specifying File Server or FL Server entries.
-path filename
Specifies the full pathname of a file from which the command is to read preference entries. Each entry consists of a File Server or FL Server machine
specification (a host name or IP address) and its respective rank. Separate each machine specification from its rank with one or more spaces, and include each paired machine specification and rank on
a separate line. Refer to the "Specifying Preferences" section of this reference page for information about specifying File Server or FL Server entries.
-stdin
Directs the command to read File Server or FL Server preference entries from standard input (stdin). Each entry must consist of a machine specification (either a
host name or IP address) and a ranking value. Separate each machine specification and each rank with one or more spaces. Refer to the "Specifying Preferences" topic of this reference page for
information about specifying File Server or FL Server entries.
-fldb
Directs the command to consider the servers specified in the -server option as FL Servers.
-help
Prints the online help for this command. All other valid options specified with this option are ignored.
Description
The cm setpreferences command can be used to add preference entries to a Cache Manager preference list or modify ranking values for existing preference entries. The Cache Manager preference list is created each time a Cache Manager is initialized with the dfsd command (each time the client machine is rebooted). Each Cache Manager maintains its own separate preference list. Each entry in the list consists of the IP address of an FL Server or File Server and an automatically assigned preference value. New entries are automatically added to the preference list as necessary when filesets are first referenced.
In operation, when the Cache Manager needs to contact an FL Server, it consults its list of FL Servers and attempts to contact a server at the address with the lowest-ranking value in the preference list. Similarly, when a Cache Manager needs to contact a File Server, it consults its preference list and contacts a suitable File Server at the address with the lowest-ranking value.
If the Cache Manager cannot access a server at the address with the lowest preference rank (because of a problem with either the machine or the network), the Cache Manager attempts to access a similar server at the address with the next-lowest rank. It continues in this way until it either succeeds in accessing an appropriate server or determines that all such servers are unavailable.
By default, the Cache Manager assigns preferences that make sensible choices based on the location of servers. Therefore, you should adjust the default values only if there is a compelling reason to do so. The default values force the Cache Manager to attempt to connect to servers in the following order:
1. The same machine as the client (default rank of 5000).
2. The same subnetwork as the client (default rank of 20000).
3. The same network as the client (default rank of 30000).
4. Different networks (default rank of 40000).
For example, a server on the same machine as the Cache Manager receives a rank of 5000, while a server on the same subnetwork receives a rank of 20000. The entry with the lowest-ranking value has the highest "preference." Thus, a server with a preference value of 5000 will be chosen before a server with a rank of 20000.
Should two servers be assigned the same preference value, such as two File Servers on the same subnetwork both receiving a default value of 20000, the server with the lowest round-trip value is chosen. Each server is assigned a random round-trip value when the Cache Manager is initialized. The assigned round-trip value is always higher than the upper bound for stored actual round-trip values. This ensures that an actual round-trip value will always be chosen over assigned values.
The Cache Manager stores its preferences in the kernel of the local machine. The preferences are lost each time the Cache Manager is initialized. You can include the cm setpreferences command in a machine's initialization file to load a predefined collection of server preferences when the machine is rebooted.
Specifying Preferences
Using the cm setpreferences command, you specify Cache Manager preference entries as pairs of values. The first value of the pair is the machine specification (either the host name or IP address in dotted decimal format) of a File Server or FL Server; the second value is the preference rank (an integer in the range from 1 to 65,534). The FLDB can contain up to four addresses for each server machine (although the machine can have more connections); therefore, the Cache Manager preference list will normally have up to four entries for a given server machine.
You can specify preference entries
· On the command line via the -server option. Use this option to tune the preferences manually in response to system or network adjustments.
· From a file via the -path option. Use this option to configure one or more Cache Managers with a fixed set of preferences. You can use the cm getpreferences command to generate a file of preferences that has the proper format.
· From standard input via the -stdin option. Use this option to pipe preferences to the command from a user-defined process that generates preferences in an acceptable format.
The -server, -path, and -stdin options are not mutually exclusive. You can include any combination of these options with the command to provide input from multiple sources. Note that the command does not verify host names or IP addresses specified with any of its options. You can add a preference for an invalid host name or IP address; the Cache Manager stores invalid preferences in the kernel, but it ignores them (the Cache Manager never needs to consult such preferences).
Privilege Required
The issuer must be logged in as root on the local machine.
Output
By default, the cm setpreferences command displays no output.
Examples
The following command uses the -server option to set the Cache Manager's preferences for the File Servers named fs3.abc.com and fs4.abc.com, the latter of which is specified by IP address. The two File Servers reside in a different subnetwork that is in the same network as the local machine. Therefore, the Cache Manager assigned each a default rank of 30,000. To make the Cache Manager prefer these File Servers over File Servers in other subnetworks, the cm setpreferences command is used to assign these machines ranks of 25,000.
# cm setp -se fs3.abc.com 25000 128.21.18.100 25000
The following command uses the -server option to set the Cache Manager's preferences for the same two File Servers, but it also uses the -path option to read a collection of preferences from a file that resides on the local machine at etc/cm.prefs:
# cm setp -se fs3.abc.com 25000 128.21.18.100 25000 -p
/etc/cm.prefs
The file /etc/cm.prefs has the following contents and format:
128.21.16.214 7500
128.21.16.212 7500
121.86.33.41 39000
121.86.33.34 39000
121.86.33.36 41000
121.86.33.37 41000
The following command uses the -stdin option to read preferences from standard input. The preferences are piped to the command from a program, calc_prefs, which was written by the issuer to calculate preferences based on values significant to the local cell.
# calc_prefs | cm setp -stdin
Related Information
Commands: