--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
+<HTML><HEAD>
+<TITLE>Administration Reference</TITLE>
+<!-- Begin Header Records ========================================== -->
+<!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID -->
+<!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30 -->
+<META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
+<META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
+<META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
+</HEAD><BODY>
+<!-- (C) IBM Corporation 2000. All Rights Reserved -->
+<BODY bgcolor="ffffff">
+<!-- End Header Records ============================================ -->
+<A NAME="Top_Of_Page"></A>
+<H1>Administration Reference</H1>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf161.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf163.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<P>
+<H2><A NAME="HDRFS_SETSERVERPREFS" HREF="auarf002.htm#ToC_176">fs setserverprefs</A></H2>
+<A NAME="IDX4971"></A>
+<A NAME="IDX4972"></A>
+<A NAME="IDX4973"></A>
+<A NAME="IDX4974"></A>
+<A NAME="IDX4975"></A>
+<A NAME="IDX4976"></A>
+<A NAME="IDX4977"></A>
+<P><STRONG>Purpose</STRONG>
+<P>Sets the Cache Manager's preference ranks for file server or VL Server
+machines
+<P><STRONG>Synopsis</STRONG>
+<PRE><B>fs setserverprefs</B> [<B>-servers</B> <<VAR>fileserver names and ranks</VAR>><SUP>+</SUP>]
+ [<B>-vlservers</B> <<VAR>VL server names and ranks</VAR>><SUP>+</SUP>]
+ [<B>-file</B> <<VAR>input from named file</VAR>>] [<B>-stdin</B>] [<B>-help</B>]
+
+<B>fs sets</B> [<B>-se</B> <<VAR>fileserver names and ranks</VAR>><SUP>+</SUP>] [<B>-vl</B> <<VAR>VL server names and ranks</VAR>><SUP>+</SUP>]
+ [<B>-f</B> <<VAR>input from named file</VAR>>] [<B>-st</B>] [<B>-h</B>]
+
+<B>fs sp</B> [<B>-se</B> <<VAR>fileserver names and ranks</VAR>><SUP>+</SUP>] [<B>-vl</B> <<VAR>VL server names and ranks></VAR><SUP>+</SUP>]
+ [<B>-f</B> <<VAR>input from named file</VAR>>] [<B>-st</B>] [<B>-h</B>]
+</PRE>
+<P><STRONG>Description</STRONG>
+<P>The <B>fs setserverprefs</B> command sets the local Cache
+Manager's preference ranks for one or more file server machine interfaces
+or, if the <B>-vlserver</B> 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.
+<P>The <B>fs getserverprefs</B> 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.
+<P><B>Calculation of Default Preference Ranks</B>
+<P>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 <I>IBM AFS Release Notes</I>). Once calculated, a
+rank persists until the machine reboots, or until this command is used to
+change it.
+<P>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</B>
+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.
+<P>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.
+<UL>
+<P><LI>If the local machine is a file server machine, the base rank for each of
+its interfaces is 5,000.
+<P><LI>If the file server machine interface is on the same subnetwork as the
+client interface, its base rank is 20,000.
+<P><LI>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.
+<P><LI>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.
+</UL>
+<P>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.
+<P><B>Setting Non-default Preference Ranks</B>
+<P>Use the <B>fs setserverprefs</B> 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
+<B>fs setserverprefs</B> command in the machine's AFS initialization
+file.
+<P>Specify each preference rank as a pair of values separated by one or more
+spaces:
+<UL>
+<P><LI>The first member of the pair is the fully-qualified hostname (for example,
+<B>fs1.abc.com</B>), or the IP address in dotted decimal
+format, of a file server machine interface or VL Server machine
+<P><LI>The second member of the pair is an integer. The possible ranks
+range from <B>1</B> through <B>65535</B>.
+</UL>
+<P>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.
+<P>There are several ways to provide ranks for file server machine interfaces
+(but not for VL Server machines):
+<UL>
+<P><LI>On the command line, following the <B>-servers</B> argument.
+<P><LI>In a file named by the <B>-file</B> argument. Place each pair
+on its own line in the file. Directing the output from the <B>fs
+getserverprefs</B> command to a file automatically generates a file with the
+proper format.
+<P><LI>Via the standard input stream, by providing the <B>-stdin</B>
+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.
+</UL>
+<P>When setting file server machine preference ranks, it is legal to combine
+the <B>-servers</B>, <B>-file</B>, and <B>-stdin</B> 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</B> argument.
+<P>The <B>-vlservers</B> argument is the only way to assign VL Server
+machine ranks. It can be combined with one or more of the
+<B>-servers</B>, <B>-file</B>, and <B>-stdin</B> options, but the
+Cache Manager applies the values provided for those options to file server
+machine ranks only.
+<P>The <B>fs</B> 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.
+<P><STRONG>Options</STRONG>
+<DL>
+<P><DT><B>-servers
+</B><DD>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</B> through
+<B>65521</B>; a lower value indicates a greater preference.
+Providing ranks outside this range can have unpredictable results.
+Providing a value no larger than <B>65521</B> guarantees that the rank
+does not exceed the maximum possible value of 65,535 even if the largest
+random factor (14) is added.
+<P>This argument can be combined with the <B>-file</B> argument,
+<B>-stdin</B> 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</B>
+argument, but does not interact with it.
+<P><DT><B>-vlservers
+</B><DD>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</B> through <B>65521</B>; a lower value
+indicates a greater preference. Providing ranks outside this range can
+have unpredictable results. Providing a value no larger than
+<B>65521</B> guarantees that the rank does not exceed the maximum possible
+value of 65,535 even if the largest random factor (14) is added.
+<P>This argument can be combined with the <B>-servers</B> argument,
+<B>-file</B> argument, <B>-stdin</B> flag, or any combination of the
+three, but does not interact with any of them. They apply only to file
+server machine ranks.
+<P><DT><B>-file
+</B><DD>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</B> argument. In the file, place
+each pair on its own line and separate the two parts of each pair with one or
+more spaces.
+<P>This argument can be combined with the <B>-servers</B> argument,
+<B>-stdin</B> flag, or both. If more than one of the arguments sets
+a rank for the same interface, the rank set by the <B>-server</B> argument
+takes precedence. It can also be combined with the
+<B>-vlservers</B> argument, but does not interact with it.
+<P><DT><B>-stdin
+</B><DD>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</B> argument. If
+typing at the shell, type <B><Ctrl-d></B> after the final newline to
+complete the input.
+<P>This argument can be combined with the <B>-servers</B> argument, the
+<B>-file</B> argument, or both. If more than one of the arguments
+sets a rank for the same interface, the rank set by the <B>-server</B>
+argument takes precedence. It can also be combined with the
+<B>-vlservers</B> argument, but does not interact with it.
+<P><DT><B>-help
+</B><DD>Prints the online help for this command. All other valid options
+are ignored.
+</DL>
+<P><STRONG>Examples</STRONG>
+<P>The following command sets the Cache Manager's preference ranks for
+the file server machines named <B>fs3.abc.com</B> and
+<B>fs4.abc.com</B>, 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</B>, to which the
+Cache Manager adds an integer in the range from 0 to 15.
+<PRE> # <B>fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000</B>
+
+</PRE>
+<P>The following command uses the <B>-servers</B> argument to set the
+Cache Manager's preference ranks for the same two file server machines,
+but it also uses the <B>-file</B> argument to read a collection of
+preference ranks from a file that resides in the local file
+<B>/etc/fs.prefs</B>:
+<PRE> # <B>fs setserverprefs -servers fs3.abc.com 25000 192.12.105.100 25000</B> \
+ <B>-file /etc/fs.prefs</B>
+
+</PRE>
+<P>The <B>/etc/fs.prefs</B> file has the following contents and
+format:
+<PRE> 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
+
+</PRE>
+<P>The following command uses the <B>-stdin</B> flag to read preference
+ranks from the standard input stream. The ranks are piped to the
+command from a program, <B>calc_prefs</B>, which was written by the issuer
+to calculate preferences based on values significant to the local cell.
+<PRE> # <B>calc_prefs | fs setserverprefs -stdin</B>
+
+</PRE>
+<P>The following command uses the <B>-vlservers</B> argument to set the
+Cache Manager's preferences for the VL server machines named
+<B>fs1.abc.com</B>, <B>fs3.abc.com</B>,
+and <B>fs4.abc.com</B> to base ranks of 1, 11000, and 65521,
+respectively:
+<PRE> # <B>fs setserverprefs -vlservers fs1.abc.com 1 fs3.abc.com 11000</B> \
+ <B>fs4.abc.com 65521</B>
+
+</PRE>
+<P><STRONG>Privilege Required</STRONG>
+<P>The issuer must be logged in as the local superuser <B>root</B>.
+<P><STRONG>Related Information</STRONG>
+<P><A HREF="auarf146.htm#HDRFS_GETSERVERPREFS">fs getserverprefs</A>
+<P>
+<HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf161.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf163.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
+<!-- Begin Footer Records ========================================== -->
+<P><HR><B>
+<br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
+</B>
+<!-- End Footer Records ============================================ -->
+<A NAME="Bot_Of_Page"></A>
+</BODY></HTML>
git://git.openafs.org / openafs.git / blobdiff