+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<refentry id="fs_setserverprefs1">
- <refmeta>
- <refentrytitle>fs setserverprefs</refentrytitle>
- <manvolnum>1</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>fs setserverprefs</refname>
- <refpurpose>Sets the preference ranks for file servers or VL servers</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Synopsis</title>
- <para><emphasis role="bold">fs setserverprefs</emphasis> [<emphasis role="bold">-servers</emphasis> <<emphasis>fileserver names and ranks</emphasis>>+]
- [<emphasis role="bold">-vlservers</emphasis> <<emphasis>VL server names and ranks</emphasis>>+]
- [<emphasis role="bold">-file</emphasis> <<emphasis>input from named file</emphasis>>] [<emphasis role="bold">-stdin</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
-
- <para><emphasis role="bold">fs sets</emphasis> [<emphasis role="bold">-se</emphasis> <<emphasis>fileserver names and ranks</emphasis>>+]
- [<emphasis role="bold">-vl</emphasis> <<emphasis>VL server names and ranks</emphasis>>+]
- [<emphasis role="bold">-f</emphasis> <<emphasis>input from named file</emphasis>>] [<emphasis role="bold">-st</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
-
- <para><emphasis role="bold">fs sp</emphasis> [<emphasis role="bold">-se</emphasis> <<emphasis>fileserver names and ranks</emphasis>>+]
- [<emphasis role="bold">-vl</emphasis> <<emphasis>VL server names and ranks</emphasis>>+]
- [<emphasis role="bold">-f</emphasis> <<emphasis>input from named file</emphasis>>] [<emphasis role="bold">-st</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
-
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>The <emphasis role="bold">fs setserverprefs</emphasis> command sets the local Cache Manager's preference
- ranks for one or more file server machine interfaces or, if the
- <emphasis role="bold">-vlserver</emphasis> 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.</para>
-
- <para>The <emphasis role="bold">fs getserverprefs</emphasis> 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.</para>
-
- <refsect2>
- <title>Calculation of Default Preference Ranks</title>
- <para>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 <emphasis>IBM AFS Release Notes</emphasis>). Once calculated, a rank
- persists until the machine reboots, or until this command is used to
- change it.</para>
-
- <para>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 <replaceable>/usr/vice/etc/CellServDB</replaceable>
- 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.</para>
-
- <para>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.</para>
-
- <itemizedlist>
- <listitem>
- <para>If the local machine is a file server machine, the base rank for each of
- its interfaces is 5,000.</para>
-
- </listitem>
- <listitem>
- <para>If the file server machine interface is on the same subnetwork as the
- client interface, its base rank is 20,000.</para>
-
- </listitem>
- <listitem>
- <para>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.</para>
-
- </listitem>
- <listitem>
- <para>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.</para>
-
- </listitem>
- </itemizedlist>
- <para>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.</para>
-
- </refsect2>
- <refsect2>
- <title>Setting Non-default Preference Ranks</title>
- <para>Use the <emphasis role="bold">fs setserverprefs</emphasis> 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 <emphasis role="bold">fs
- setserverprefs</emphasis> command in the machine's AFS initialization file.</para>
-
- <para>Specify each preference rank as a pair of values separated by one or more
- spaces:</para>
-
- <itemizedlist>
- <listitem>
- <para>The first member of the pair is the fully-qualified hostname (for example,
- <computeroutput>fs1.abc.com</computeroutput>), or the IP address in dotted decimal format, of a file
- server machine interface or VL Server machine</para>
-
- </listitem>
- <listitem>
- <para>The second member of the pair is an integer. The possible ranks range from
- <computeroutput>1</computeroutput> through <computeroutput>65535</computeroutput>.</para>
-
- </listitem>
- </itemizedlist>
- <para>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.</para>
-
- <para>There are several ways to provide ranks for file server machine interfaces
- (but not for VL Server machines):</para>
-
- <itemizedlist>
- <listitem>
- <para>On the command line, following the <emphasis role="bold">-servers</emphasis> argument.</para>
-
- </listitem>
- <listitem>
- <para>In a file named by the <emphasis role="bold">-file</emphasis> argument. Place each pair on its own line
- in the file. Directing the output from the <emphasis role="bold">fs getserverprefs</emphasis> command to
- a file automatically generates a file with the proper format.</para>
-
- </listitem>
- <listitem>
- <para>Via the standard input stream, by providing the <emphasis role="bold">-stdin</emphasis> 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.</para>
-
- </listitem>
- </itemizedlist>
- <para>When setting file server machine preference ranks, it is legal to combine
- the <emphasis role="bold">-servers</emphasis>, <emphasis role="bold">-file</emphasis>, and <emphasis role="bold">-stdin</emphasis> 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
- <emphasis role="bold">-servers</emphasis> argument.</para>
-
- <para>The <emphasis role="bold">-vlservers</emphasis> argument is the only way to assign VL Server machine
- ranks. It can be combined with one or more of the <emphasis role="bold">-servers</emphasis>, <emphasis role="bold">-file</emphasis>,
- and <emphasis role="bold">-stdin</emphasis> options, but the Cache Manager applies the values provided
- for those options to file server machine ranks only.</para>
-
- <para>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.</para>
-
- </refsect2>
- </refsect1>
- <refsect1>
- <title>Options</title>
- <variablelist>
- <varlistentry>
- <term><emphasis role="bold">-servers</emphasis> <<emphasis>file server names and ranks</emphasis>>+</term>
- <listitem>
- <para>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 <computeroutput>1</computeroutput> through <computeroutput>65521</computeroutput>; a
- lower value indicates a greater preference. Providing ranks outside this
- range can have unpredictable results. Providing a value no larger than
- <computeroutput>65521</computeroutput> guarantees that the rank does not exceed the maximum possible
- value of 65,535 even if the largest random factor (14) is added.</para>
-
- <para>This argument can be combined with the <emphasis role="bold">-file</emphasis> argument, <emphasis role="bold">-stdin</emphasis> 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 <emphasis role="bold">-vlservers</emphasis> argument, but does not interact with it.</para>
-
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="bold">-vlservers</emphasis> <<emphasis>VL server names and ranks</emphasis>>+</term>
- <listitem>
- <para>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 <computeroutput>1</computeroutput> through <computeroutput>65521</computeroutput>; a lower value indicates a greater
- preference. Providing ranks outside this range can have unpredictable
- results. Providing a value no larger than <computeroutput>65521</computeroutput> guarantees that the
- rank does not exceed the maximum possible value of 65,535 even if the
- largest random factor (14) is added.</para>
-
- <para>This argument can be combined with the <emphasis role="bold">-servers</emphasis> argument, <emphasis role="bold">-file</emphasis>
- argument, <emphasis role="bold">-stdin</emphasis> flag, or any combination of the three, but does not
- interact with any of them. They apply only to file server machine ranks.</para>
-
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="bold">-file</emphasis> <<emphasis>input file</emphasis>></term>
- <listitem>
- <para>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 <emphasis role="bold">-servers</emphasis> argument. In the file, place each
- pair on its own line and separate the two parts of each pair with one or
- more spaces.</para>
-
- <para>This argument can be combined with the <emphasis role="bold">-servers</emphasis> argument, <emphasis role="bold">-stdin</emphasis>
- flag, or both. If more than one of the arguments sets a rank for the same
- interface, the rank set by the <emphasis role="bold">-server</emphasis> argument takes precedence. It
- can also be combined with the <emphasis role="bold">-vlservers</emphasis> argument, but does not
- interact with it.</para>
-
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="bold">-stdin</emphasis></term>
- <listitem>
- <para>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 <emphasis role="bold">-file</emphasis> argument. If typing at the shell, type
- Ctrl-D after the final newline to complete the input.</para>
-
- <para>This argument can be combined with the <emphasis role="bold">-servers</emphasis> argument, the <emphasis role="bold">-file</emphasis>
- argument, or both. If more than one of the arguments sets a rank for the
- same interface, the rank set by the <emphasis role="bold">-server</emphasis> argument takes
- precedence. It can also be combined with the <emphasis role="bold">-vlservers</emphasis> argument, but
- does not interact with it.</para>
-
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis role="bold">-help</emphasis></term>
- <listitem>
- <para>Prints the online help for this command. All other valid options are
- ignored.</para>
-
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <para>The following command sets the Cache Manager's preference ranks for the
- file server machines named <computeroutput>fs3.abc.com</computeroutput> and <computeroutput>fs4.abc.com</computeroutput>, 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 <computeroutput>25000</computeroutput>, to which the
- Cache Manager adds an integer in the range from 0 to 15.</para>
-
-<programlisting>
- # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000
-
-</programlisting>
- <para>The following command uses the <emphasis role="bold">-servers</emphasis> argument to set the Cache
- Manager's preference ranks for the same two file server machines, but it
- also uses the <emphasis role="bold">-file</emphasis> argument to read a collection of preference ranks
- from a file that resides in the local file <replaceable>/etc/fs.prefs</replaceable>:</para>
-
-<programlisting>
- # fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000 \
- -file /etc/fs.prefs
-
-</programlisting>
- <para>The /etc/fs.prefs file has the following contents and format:</para>
-
-<programlisting>
- 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
-
-</programlisting>
- <para>The following command uses the <emphasis role="bold">-stdin</emphasis> flag to read preference ranks
- from the standard input stream. The ranks are piped to the command from a
- program, <emphasis role="bold">calc_prefs</emphasis>, which was written by the issuer to calculate
- preferences based on values significant to the local cell.</para>
-
-<programlisting>
- # calc_prefs | fs setserverprefs -stdin
-
-</programlisting>
- <para>The following command uses the <emphasis role="bold">-vlservers</emphasis> argument to set the Cache
- Manager's preferences for the VL server machines named <computeroutput>fs1.abc.com</computeroutput>,
- <computeroutput>fs3.abc.com</computeroutput>, and <computeroutput>fs4.abc.com</computeroutput> to base ranks of 1, 11000, and 65521,
- respectively:</para>
-
-<programlisting>
- # fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000 \
- fs4.abc.com 65521
-
-</programlisting>
- </refsect1>
- <refsect1>
- <title>Privilege Required</title>
- <para>The issuer must be logged in as the local superuser root.</para>
-
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para><link linkend="fs_getserverprefs1">fs_getserverprefs(1)</link></para>
-
- </refsect1>
- <refsect1>
- <title>Copyright</title>
- <para>IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.</para>
-
- <para>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.</para>
-
- </refsect1>
- </refentry>