=head1 NAME

fs setserverprefs - Sets the Cache Manager's preference ranks for file server or VL Server
machines

=head1 SYNOPSIS

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

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

fs sp [B<-se> I<fileserver names and ranks> [I<fileserver names and ranks> ...]]  [B<-vl> I<VL server names and ranks> [I<VL server names and ranks> ...]]

[B<-f> I<input from named file>]  [B<-st>]  [B<-h>]

=head1 DESCRIPTION

The C<fs setserverprefs> command sets the local Cache Manager's
preference ranks for one or more file server machine interfaces or, if
the B<-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 L<fs_getserverprefs(1)> 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.

=head2 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, which is specified in the IBM AFS Release Notes).
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 B</usr/vice/etc/CellServDB>
file. 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.

=over

=item *

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

=item *

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

=item *

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.

=item *

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.

=back

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.

=head2 Setting Non-default Preference Ranks

Use the C<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 C<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:

=over

=item *

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

=item *

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

=back

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):

=over

=item *

On the command line, following the B<-servers> argument.

=item *

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

=item *

Via the standard input stream, by providing the B<-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.

=back

When setting file server machine preference ranks, it is legal to
combine the B<-servers>, B<-file>, and B<-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 B<-servers> argument.

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

The C<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.

=head1 OPTIONS

=over 4

=item B<-servers> I<fileserver names and ranks> [I<fileserver 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 B<1> through B<65521>; a lower value
indicates a greater preference. Providing ranks outside this
range can have unpredictable results. Providing a value no
larger than B<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 B<-file> argument, B<-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 B<-vlservers>
argument, but does not interact with it.

=item B<-vlservers> I<VL server names and ranks> [I<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 B<1>
through B<65521>; a lower value indicates a greater preference.
Providing ranks outside this range can have unpredictable
results. Providing a value no larger than B<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 B<-servers> argument, B<-file>
argument, B<-stdin> flag, or any combination of the three, but
does not interact with any of them. They apply only to file
server machine ranks.

=item B<-file> I<input from named 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 B<-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 B<-servers> argument,
B<-stdin> flag, or both. If more than one of the arguments sets a
rank for the same interface, the rank set by the B<-server>
argument takes precedence. It can also be combined with the
B<-vlservers> argument, but does not interact with it.

=item B<-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 B<-file> argument. If typing at the shell, type
B<E<lt>Ctrl-dE<gt>> after the final newline to complete the input.

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

=item B<-help>

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

=back

=head1 EXAMPLES

The following command sets the Cache Manager's preference ranks for
the file server machines named B<fs3.abc.com> and B<fs4.abc.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 B<25000>, to
which the Cache Manager adds an integer in the range from 0 to 15.

    fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000

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

    fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000  \
                      -file /etc/fs.prefs

The B</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 B<-stdin> flag to read preference ranks
from the standard input stream. The ranks are piped to the command
from a program, B<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 B<-vlservers> argument to set the Cache
Manager's preferences for the VL server machines named B<fs1.abc.com>,
B<fs3.abc.com>, and B<fs4.abc.com> to base ranks of 1, 11000, and 65521,
respectively:

    fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000  \
                      fs4.abc.com 65521

=head1 PRIVILEGE REQUIRED

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

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<fs_getserverprefs(1)>

=cut
