=head1 NAME

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

=head1 SYNOPSIS

fs getserverprefs [B<-file> I<output to named file>]
[B<-numeric>]  [B<-vlservers>]  [B<-help>]

fs gets [B<-f> I<output to named file>]  [B<-n>]  [B<-v>]  [B<-h>]

fs gp [B<-f> I<output to named file>]  [B<-n>]  [B<-v>]  [B<-h>]

=head1 DESCRIPTION

The C<fs getserverprefs> command displays preference ranks for file
server machine interfaces (file server machines run the B<fs> process)
or, if the B<-vlserver> flag is provided, for Volume Location (VL) Server
machines (which run the B<vlserver> process). For file server machines,
the Cache Manager tracks up to 15 interfaces per machine and assigns a
separate rank to each interface. The ranks indicate the order in which
the local Cache Manager attempts to contact the interfaces of machines
that are housing a volume when it needs to fetch data from the volume.
For VL Server machines, the ranks indicate the order in which the
Cache Manager attempts to contact a cell's VL Servers when requesting
VLDB information. For both types of rank, lower integer values are
more preferred.

The Cache Manager stores ranks in kernel memory. Once set, a rank
persists until the machine reboots, or until the C<fs setserverprefs>
command is used to change it. The reference page for the C<fs
setserverprefs> command explains how the Cache Manager sets default
ranks, and how to use that command to change the default values.

Default VL Server ranks range from 10,000 to 10,126, and the Cache
Manager assigns them to every machine listed in its copy of the
B</usr/vice/etc/CellServDB> file. When the Cache Manager needs to fetch
VLDB information from a cell, it compares the ranks for the VL Server
machines belonging to that cell, and attempts to contact the VL Server
with the lowest integer rank. If the Cache Manager cannot reach the VL
Server (because of server process, machine or network outage), it
tries to contact the VL Server with the next lowest integer rank, and
so on. If all of a cell's VL Server machines are unavailable, the
Cache Manager cannot fetch data from the cell.

Default file server ranks range from 5,000 to 40,000, excluding the
range used for VL Servers (10,000 to 10,126); the maximum possible
rank is 65,534. When the Cache Manager needs to fetch data from a
volume, it compares the ranks for the interfaces of machines that
house the volume, and attempts to contact the interface that has the
lowest integer rank. If it cannot reach the B<fileserver> process via
that interface (because of server process, machine or network outage),
it tries to contact the interface with the next lowest integer rank,
and so on. If it cannot reach any of the interfaces for machines that
house the volume, it cannot fetch data from the volume.

For both file server machines and VL Server machines, it is possible
for a machine or interface in a foreign cell to have the same rank as
a machine or interface in the local cell. This does not present a
problem, because the Cache Manager only ever compares ranks for
machines belonging to one cell at a time.

=head1 OPTIONS

=over 4

=item B<-file> I<output to named file>

Specifies the full pathname of a file to which to write the
preference ranks. If the specified file already exists, the
command overwrites its contents. If the pathname is invalid,
the command fails. If this argument is not provided, the
preference ranks appear on the standard output stream.

=item B<-numeric>

Displays the IP addresses of file server machine interfaces or
VL Server machines, rather than their hostnames. If this
argument is not provided, the C<fs> command interpreter has the IP
addresses translated to hostnames such as B<fs1.abc.com>.

=item B<-vlservers>

Displays preference ranks for VL Server machines rather than
file server machine interfaces.

=item B<-help>

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

=back

=head1 OUTPUT

The output consists of a separate line for each file server machine
interface or VL Server machine, pairing the machine's hostname or IP
address with its rank. The Cache Manager stores IP addresses in its
kernel list of ranks, but the command by default identifies interfaces
by hostname, by calling a translation routine that refers to either
the cell's name service (such as the Domain Name Server) or the local
host table. If an IP address appears in the output, it is because the
translation attempt failed. To bypass the translation step and display
IP addresses rather than hostnames, include the B<-numeric> flag. This
can significantly speed the production of output.

By default, the command writes to the standard output stream. Use the
B<-file> argument to write the output to a file instead.

=head1 EXAMPLES

The following example displays the local Cache Manager's preference
ranks for file server machines. The local machine belongs to the AFS
cell named B<abc.com>, and in this example the ranks of file server
machines in its local cell are lower than the ranks of file server
machines from the foreign cell, B<def.com>. It is not possible to
translate the IP addresses of two machines on the 138.255 network.

    fs getserverprefs
   fs2.abc.com           20007
   fs3.abc.com           30002
   fs1.abc.com           20011
   fs4.abc.com           30010
   server1.def.com       40002
   138.255.33.34         40000
   server6.def.com       40012
   138.255.33.37         40005

The following example shows hows the output displays IP addresses when
the B<-numeric> flag is included, and illustrates how network proximity
determines default ranks (as described on the L<fs_setserverprefs(1)>
reference page). The local machine has IP address 192.12.107.210, and
the two file server machines on its subnetwork have ranks of 20,007
and 20,011. The two file server machines on a different subnetwork of
the local machine's network have higher ranks, 30,002 and 30,010,
whereas the ranks of the remaining machines range from 40,000 to
40,012 because they are in a completely different network.

    fs getserverprefs -numeric
   192.12.107.214          20007
   192.12.105.99           30002
   192.12.107.212          20011
   192.12.105.100          30010
   138.255.33.41           40002
   138.255.33.34           40000
   138.255.33.36           40012
   138.255.33.37           40005

The example shows how the B<-vlservers> flag displays preference ranks
for VL Server machines:

    fs getserverprefs -vlservers
   fs2.abc.com            10052
   fs3.abc.com            10113
   fs1.abc.com            10005

=head1 PRIVILEGE REQUIRED

None

=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_setserverprefs(1)>

=cut
