NAME

fs_setserverprefs - Sets the Cache Manager preference ranks for file servers or location servers

SYNOPSIS

fs setserverprefs [-servers <File server names and ranks>+] [-vlservers <Location server names and ranks>+] [-file <input from named file>] [-stdin] [-help]

DESCRIPTION

The fs setserverprefs command (alias fs sp) sets the Cache Manager's preference ranks for one or more File Server interfaces or, if the -vlserver argument is provided, for Location Servers. For File Servers, the numerical ranks determine the order in which the Cache Manager attempts to contact the interfaces of machines that are housing a volume. For Location Servers, the ranks determine the order in which the Cache Manager attempts to contact a cell's Location Servers when requesting volume location information.

The fs getserverprefs reference page explains how the Cache Manager uses preference ranks when contacting File Servers or Location Servers. The following paragraphs explain how the Cache Manager calculates default ranks, and how to use this command to change the defaults.

Calculation of Default Preference Ranks

The Cache Manager stores a preference rank as a paired IP address and numerical rank. If a File Server is multihomed, the Cache Manager assigns a distinct rank to each of the server's addresses (up to the number of addresses that the Location Server can store per File Server). Once calculated, a rank persists until the machine reboots, or until this command is used to change it.

The Cache Manager sets default Location Server preference ranks as it initializes, randomly assigning a rank from the range 10,000 to 10,126 to each of the machines listed in the local /etc/yfs/yfs-client.conf file. If DNS is used to locate Location Servers, the Cache Manager will assign a rank to every server obtained via a DNS SRV or DNS AFSDB query for that cell. Currently, the priority and weight information from SRV records is not used.

The Cache Manager sets default preference ranks for File Servers as it fetches volume location information. Each time it learns about File Server interfaces for which it has not already set ranks, it assigns a rank to each interface.

After assigning a base rank to a File Server interface, the Cache Manager adds to it a number randomly chosen from the range 0 (zero) to 14. This process reduces the number of interfaces that have exactly the same rank.

Setting Non-default Preference Ranks

Use the fs setserverprefs command to reset an existing preference rank, or to set the initial rank of a File Server or Location Server interface. To make a rank persist across a reboot of the local machine, place the appropriate fs setserverprefs command in a machine specific initialization file.

Specify each preference rank as a pair of values separated by one or more spaces:

As with default ranks, the Cache Manager adds a randomly chosen integer to a rank specified by this command. For File Server interfaces, the integer is from the range 0 (zero) to 14; for Location Servers, it is from the range 0 (zero) to 126. For example, if the administrator assigns a rank of 15,000 to a File Server interface, the Cache Manager stores an integer between 15,000 to 15,014.

There are several ways to provide ranks for File Server interfaces (but not for Location Servers):

When setting File Server preference ranks, it is legal to combine the -servers, -file, and -stdin options on a single command line. If different options specify a different rank for the same interface, the Cache Manager stores and uses the rank assigned with the -servers argument.

The -vlservers argument is the only way to assign Location Server ranks. It can be combined with one or more of the -servers, -file, and -stdin options, but the Cache Manager applies the values provided for those options to File Server ranks only.

The fs command interpreter does not verify hostnames or IP addresses, and so assigns preference ranks to invalid machine names or addresses. The Cache Manager never uses such ranks unless the same incorrect information is in the location database.

OPTIONS

-servers <file server names and ranks>+

Specifies one or more file server machine preference ranks. Each rank pairs the fully-qualified hostname or IP address (in dotted decimal format) of a File Server's interface with an integer rank, separated by one or more spaces; also separate each pair with one or more spaces. Acceptable values for the rank range from 1 through 65521; a lower value indicates a greater preference. Providing ranks outside this range can have unpredictable results. Providing a value no larger than 65521 guarantees that the rank does not exceed the maximum possible value of 65,535 even if the largest random factor (14) is added.

This argument can be combined with the -file argument, -stdin flag, or both. If more than one of the arguments sets a rank for the same interface, the rank set by this argument takes precedence. It can also be combined with the -vlservers argument, but does not interact with it.

-vlservers <Location server names and ranks>+

Specifies one or more Location Server preference ranks. Each rank pairs the fully-qualified hostname or IP address (in dotted decimal format) of a Location Server machine with an integer rank, separated by one or more spaces; also separate each pair with one or more spaces. Acceptable values for the rank range from 1 through 65521; a lower value indicates a greater preference. Providing ranks outside this range can have unpredictable results. Providing a value no larger than 65521 guarantees that the rank does not exceed the maximum possible value of 65,535 even if the largest random factor (14) is added.

This argument can be combined with the -servers argument, -file argument, -stdin flag, or any combination of the three, but does not interact with any of them. They apply only to file server machine ranks.

-file <input file>

Specifies the full pathname of a file from which to read pairs of File Server interfaces and their ranks, using the same notation and range of values as for the -servers argument. In the file, place each pair on its own line and separate the two parts of each pair with one or more spaces.

This argument can be combined with the -servers argument, -stdin flag, or both. If more than one of the arguments sets a rank for the same interface, the rank set by the -server argument takes precedence. It can also be combined with the -vlservers argument, but does not interact with it.

-stdin

Reads pairs of File Server interface and integer rank from the standard input stream. The intended use is to accept input piped in from a user-defined program or script that generates ranks in the appropriate format, but it also accepts input typed to the shell. Format the interface and rank pairs as for the -file argument. If typing at the shell, type Ctrl-D after the final newline to complete the input.

This argument can be combined with the -servers argument, the -file argument, or both. If more than one of the arguments sets a rank for the same interface, the rank set by the -server argument takes precedence. It can also be combined with the -vlservers argument, but does not interact with it.

-help

Prints the online help for this command. All other valid options are ignored.

EXAMPLES

The following command sets the Cache Manager's preference ranks for the file server machines named fs3.your-cell-name.com and fs4.your-cell-name.com, the latter of which is specified by its IP address, 172.12.105.100. To increase the Cache Manager's preference for these machines, the issuer assigns a rank of 25000, to which the Cache Manager adds an integer in the range from 0 to 15.

   # fs setserverprefs -servers fs3.your-cell-name.com 25000 172.12.105.100 25000

The following command uses the -servers argument to set the Cache Manager's preference ranks for the same two file server machines, but it also uses the -file argument to read a collection of preference ranks from a file that resides in the local file /etc/fs.prefs:

   # fs setserverprefs -servers fs3.your-cell-name.com 25000 172.12.105.100 25000 \
       -file /etc/fs.prefs

The /etc/fs.prefs file has the following contents and format:

   172.12.108.214           7500
   172.12.108.212           7500
   10.255.33.41            39000
   10.255.33.34            39000
   192.168.45.36           41000
   192.168.45.37           41000

The following command uses the -stdin flag to read preference ranks from the standard input stream. The ranks 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 | fs setserverprefs -stdin

The following command uses the -vlservers argument to set the Cache Manager's preferences for the Location Servers named fs1.your-cell-name.com, fs3.your-cell-name.com, and fs4.your-cell-name.com to base ranks of 1, 11000, and 65521, respectively:

   # fs setserverprefs -vlservers fs1.your-cell-name.com 1 \
       fs3.your-cell-name.com 11000 fs4.your-cell-name.com 65521

PRIVILEGE REQUIRED

The issuer must be logged in as the local superuser root.

SEE ALSO

fs_getserverprefs(1)

COPYRIGHT

IBM Corporation 2000. http://www.ibm.com/ 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.

ACKNOWLEDGEMENTS

"AFS" is a registered mark of International Business Machines Corporation, used under license. (USPTO Registration 1598389)

"OpenAFS" is a registered mark of International Business Machines Corporation. (USPTO Registration 4577045)

The "AuriStor" name, log 'S' brand mark, and icon are registered marks of AuriStor, Inc. (USPTO Registrations 4849419, 4849421, and 4928460) (EUIPO Registration 015539653).

"Your File System" is a registered mark of AuriStor, Inc. (USPTO Registrations 4801402 and 4849418).

"YFS" and "AuriStor File System" are trademarks of AuriStor, Inc.