NAME

       fs_setserverprefs - Sets the preference ranks for file servers or VL servers

SYNOPSIS

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

       fs sets [-se <fileserver names and ranks>+]
           [-vl <VL server names and ranks>+]
           [-f <input from named file>] [-st] [-h]

       fs sp [-se <fileserver names and ranks>+]
           [-vl <VL server names and ranks>+]
           [-f <input from named file>] [-st] [-h]

DESCRIPTION

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

       The fs getserverprefs reference page explains how the Cache Manager uses preference ranks
       when contacting file server machines or VL Server machines. 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 in kernel memory as a paired IP address and
       numerical rank. If a file server machine is multihomed, the Cache Manager assigns a
       distinct rank to each of the machine's addresses (up to the number of addresses that the
       VLDB can store per machine). Once calculated, a rank persists until the machine reboots,
       or until this command is used to change it.

       The Cache Manager sets default VL 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/openafs/CellServDB file. If DNS is used to locate VL Servers, the Cache Manager
       will assign a rank to every server configured in an AFSDB or SRV record for that cell.
       Currently, the priority and weight information from SRV records is not used. Machines from
       different cells can have the same rank, but this does not present a problem because the
       Cache Manager consults only one cell's ranks at a time.

       The Cache Manager sets default preference ranks for file server machine as it fetches
       volume location information from the VLDB. Each time it learns about file server machine
       interfaces for which it has not already set ranks, it assigns a rank to each interface. If
       the local client machine has only one IP address, the Cache Manager compares it to the
       server interface's IP address and sets a rank according to the following algorithm. If the
       client machine is multihomed, the Cache Manager applies the algorithm to each of the
       client machine's addresses and assigns to the file server machine interface the lowest
       rank that results.

       •   If the local machine is a file server machine, the base rank for each of its
           interfaces is 5,000.

       •   If the file server machine interface is on the same subnetwork as the client
           interface, its base rank is 20,000.

       •   If the file server machine interface is on the same network as the client interface,
           or is at the distant end of a point-to-point link with the client interface, its base
           rank is 30,000.

       •   If the file server machine interface is on a different network than the client
           interface, or the Cache Manager cannot obtain network information about it, its base
           rank is 40,000.

       After assigning a base rank to a file server machine interface, the Cache Manager adds to
       it a number randomly chosen from the range 0 (zero) to 14. As an example, a file server
       machine interface in the same subnetwork as the local machine receives a base rank of
       20,000, but the Cache Manager records the actual rank as an integer between 20,000 and
       20,014. This process reduces the number of interfaces that have exactly the same rank. As
       with VL Server machine ranks, it is possible for file server machine interfaces from
       foreign cells to have the same rank as interfaces in the local cell, but this does not
       present a problem. Only the relative ranks of the interfaces that house a given volume are
       relevant, and AFS only supports storage of a volume in one cell at a time.

   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 machine interface or VL Server machine for which the Cache
       Manager has no rank. To make a rank persist across a reboot of the local machine, place
       the appropriate fs setserverprefs command in the machine's AFS initialization file.

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

       •   The first member of the pair is the fully-qualified hostname (for example,
           "fs1.example.com"), or the IP address in dotted decimal format, of a file server
           machine interface or VL Server machine

       •   The second member of the pair is an integer. The possible ranks range from 1 through
           65535.

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

       There are several ways to provide ranks for file server machine interfaces (but not for VL
       Server machines):

       •   On the command line, following the -servers argument.

       •   In a file named by the -file argument. Place each pair on its own line in the file.
           Directing the output from the fs getserverprefs command to a file automatically
           generates a file with the proper format.

       •   Via the standard input stream, by providing the -stdin flag. This method enables the
           issuer to feed in values directly from a program or script that generates preference
           ranks by using an algorithm appropriate to the local cell. The AFS distribution does
           not include such programs or scripts.

       When setting file server machine 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 VL Server machine 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 machine 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 VLDB.

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 machine'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 <VL server names and ranks>+
           Specifies one or more VL Server preference ranks. Each rank pairs the fully-qualified
           hostname or IP address (in dotted decimal format) of a VL 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 machine
           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 machine 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.example.com" and "fs4.example.com", the latter of which is specified
       by its IP address, 192.12.105.100. The machines reside in another subnetwork of the local
       machine's network, so their default base rank is 30,000. 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.example.com 25000 192.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.example.com 25000 192.12.105.100 25000 \
              -file /etc/fs.prefs

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

          192.12.108.214        7500
          192.12.108.212        7500
          138.255.33.41         39000
          138.255.33.34         39000
          128.0.45.36           41000
          128.0.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 VL server machines named "fs1.example.com", "fs3.example.com", and
       "fs4.example.com" to base ranks of 1, 11000, and 65521, respectively:

          # fs setserverprefs -vlservers fs1.example.com 1 fs3.example.com 11000 \
              fs4.example.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.