.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "FS_SETSERVERPREFS 1" .TH FS_SETSERVERPREFS 1 "2012-01-23" "OpenAFS" "AFS Command Reference" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" fs_setserverprefs \- Sets the preference ranks for file servers or VL servers .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBfs setserverprefs\fR [\fB\-servers\fR\ <\fIfileserver\ names\ and\ ranks\fR>+] [\fB\-vlservers\fR\ <\fI\s-1VL\s0\ server\ names\ and\ ranks\fR>+] [\fB\-file\fR\ <\fIinput\ from\ named\ file\fR>] [\fB\-stdin\fR] [\fB\-help\fR] .PP \&\fBfs sets\fR [\fB\-se\fR\ <\fIfileserver\ names\ and\ ranks\fR>+] [\fB\-vl\fR\ <\fI\s-1VL\s0\ server\ names\ and\ ranks\fR>+] [\fB\-f\fR\ <\fIinput\ from\ named\ file\fR>] [\fB\-st\fR] [\fB\-h\fR] .PP \&\fBfs sp\fR [\fB\-se\fR\ <\fIfileserver\ names\ and\ ranks\fR>+] [\fB\-vl\fR\ <\fI\s-1VL\s0\ server\ names\ and\ ranks\fR>+] [\fB\-f\fR\ <\fIinput\ from\ named\ file\fR>] [\fB\-st\fR] [\fB\-h\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fBfs setserverprefs\fR command sets the local Cache Manager's preference ranks for one or more file server machine interfaces or, if the \&\fB\-vlserver\fR argument is provided, for Volume Location (\s-1VL\s0) 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 \s-1VL\s0 Server machines, the ranks determine the order in which the Cache Manager attempts to contact a cell's \s-1VL\s0 Servers when requesting \s-1VLDB\s0 information. .PP The \fBfs getserverprefs\fR reference page explains how the Cache Manager uses preference ranks when contacting file server machines or \s-1VL\s0 Server machines. The following paragraphs explain how the Cache Manager calculates default ranks, and how to use this command to change the defaults. .SS "Calculation of Default Preference Ranks" .IX Subsection "Calculation of Default Preference Ranks" The Cache Manager stores a preference rank in kernel memory as a paired \s-1IP\s0 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 \s-1VLDB\s0 can store per machine). Once calculated, a rank persists until the machine reboots, or until this command is used to change it. .PP The Cache Manager sets default \s-1VL\s0 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 \fI/usr/vice/etc/CellServDB\fR file. If \s-1DNS\s0 is used to locate \s-1VL\s0 Servers, the Cache Manager will assign a rank to every server configured in an \s-1AFSDB\s0 or \s-1SRV\s0 record for that cell. Currently, the priority and weight information from \s-1SRV\s0 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. .PP The Cache Manager sets default preference ranks for file server machine as it fetches volume location information from the \s-1VLDB\s0. 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 \s-1IP\s0 address, the Cache Manager compares it to the server interface's \s-1IP\s0 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. .IP "\(bu" 4 If the local machine is a file server machine, the base rank for each of its interfaces is 5,000. .IP "\(bu" 4 If the file server machine interface is on the same subnetwork as the client interface, its base rank is 20,000. .IP "\(bu" 4 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. .IP "\(bu" 4 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. .PP 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 \s-1VL\s0 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 \s-1AFS\s0 only supports storage of a volume in one cell at a time. .SS "Setting Non-default Preference Ranks" .IX Subsection "Setting Non-default Preference Ranks" Use the \fBfs setserverprefs\fR command to reset an existing preference rank, or to set the initial rank of a file server machine interface or \s-1VL\s0 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 \fBfs setserverprefs\fR command in the machine's \s-1AFS\s0 initialization file. .PP Specify each preference rank as a pair of values separated by one or more spaces: .IP "\(bu" 4 The first member of the pair is the fully-qualified hostname (for example, \&\f(CW\*(C`fs1.abc.com\*(C'\fR), or the \s-1IP\s0 address in dotted decimal format, of a file server machine interface or \s-1VL\s0 Server machine .IP "\(bu" 4 The second member of the pair is an integer. The possible ranks range from \&\f(CW1\fR through \f(CW65535\fR. .PP 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 \s-1VL\s0 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. .PP There are several ways to provide ranks for file server machine interfaces (but not for \s-1VL\s0 Server machines): .IP "\(bu" 4 On the command line, following the \fB\-servers\fR argument. .IP "\(bu" 4 In a file named by the \fB\-file\fR argument. Place each pair on its own line in the file. Directing the output from the \fBfs getserverprefs\fR command to a file automatically generates a file with the proper format. .IP "\(bu" 4 Via the standard input stream, by providing the \fB\-stdin\fR 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 \s-1AFS\s0 distribution does not include such programs or scripts. .PP When setting file server machine preference ranks, it is legal to combine the \fB\-servers\fR, \fB\-file\fR, and \fB\-stdin\fR 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 \&\fB\-servers\fR argument. .PP The \fB\-vlservers\fR argument is the only way to assign \s-1VL\s0 Server machine ranks. It can be combined with one or more of the \fB\-servers\fR, \fB\-file\fR, and \fB\-stdin\fR options, but the Cache Manager applies the values provided for those options to file server machine ranks only. .PP The fs command interpreter does not verify hostnames or \s-1IP\s0 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 \s-1VLDB\s0. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-servers\fR <\fIfile server names and ranks\fR>+" 4 .IX Item "-servers +" Specifies one or more file server machine preference ranks. Each rank pairs the fully-qualified hostname or \s-1IP\s0 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 \f(CW1\fR through \f(CW65521\fR; a lower value indicates a greater preference. Providing ranks outside this range can have unpredictable results. Providing a value no larger than \&\f(CW65521\fR guarantees that the rank does not exceed the maximum possible value of 65,535 even if the largest random factor (14) is added. .Sp This argument can be combined with the \fB\-file\fR argument, \fB\-stdin\fR 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 \fB\-vlservers\fR argument, but does not interact with it. .IP "\fB\-vlservers\fR <\fI\s-1VL\s0 server names and ranks\fR>+" 4 .IX Item "-vlservers +" Specifies one or more \s-1VL\s0 Server preference ranks. Each rank pairs the fully-qualified hostname or \s-1IP\s0 address (in dotted decimal format) of a \s-1VL\s0 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 \f(CW1\fR through \f(CW65521\fR; a lower value indicates a greater preference. Providing ranks outside this range can have unpredictable results. Providing a value no larger than \f(CW65521\fR guarantees that the rank does not exceed the maximum possible value of 65,535 even if the largest random factor (14) is added. .Sp This argument can be combined with the \fB\-servers\fR argument, \fB\-file\fR argument, \fB\-stdin\fR flag, or any combination of the three, but does not interact with any of them. They apply only to file server machine ranks. .IP "\fB\-file\fR <\fIinput file\fR>" 4 .IX Item "-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 \fB\-servers\fR argument. In the file, place each pair on its own line and separate the two parts of each pair with one or more spaces. .Sp This argument can be combined with the \fB\-servers\fR argument, \fB\-stdin\fR flag, or both. If more than one of the arguments sets a rank for the same interface, the rank set by the \fB\-server\fR argument takes precedence. It can also be combined with the \fB\-vlservers\fR argument, but does not interact with it. .IP "\fB\-stdin\fR" 4 .IX Item "-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 \fB\-file\fR argument. If typing at the shell, type Ctrl-D after the final newline to complete the input. .Sp This argument can be combined with the \fB\-servers\fR argument, the \fB\-file\fR argument, or both. If more than one of the arguments sets a rank for the same interface, the rank set by the \fB\-server\fR argument takes precedence. It can also be combined with the \fB\-vlservers\fR argument, but does not interact with it. .IP "\fB\-help\fR" 4 .IX Item "-help" Prints the online help for this command. All other valid options are ignored. .SH "EXAMPLES" .IX Header "EXAMPLES" The following command sets the Cache Manager's preference ranks for the file server machines named \f(CW\*(C`fs3.abc.com\*(C'\fR and \f(CW\*(C`fs4.abc.com\*(C'\fR, the latter of which is specified by its \s-1IP\s0 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 \f(CW25000\fR, to which the Cache Manager adds an integer in the range from 0 to 15. .PP .Vb 1 \& # fs setserverprefs \-servers fs3.abc.com 25000 192.12.105.100 25000 .Ve .PP The following command uses the \fB\-servers\fR argument to set the Cache Manager's preference ranks for the same two file server machines, but it also uses the \fB\-file\fR argument to read a collection of preference ranks from a file that resides in the local file \fI/etc/fs.prefs\fR: .PP .Vb 2 \& # fs setserverprefs \-servers fs3.abc.com 25000 192.12.105.100 25000 \e \& \-file /etc/fs.prefs .Ve .PP The /etc/fs.prefs file has the following contents and format: .PP .Vb 6 \& 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 .Ve .PP The following command uses the \fB\-stdin\fR flag to read preference ranks from the standard input stream. The ranks are piped to the command from a program, \fBcalc_prefs\fR, which was written by the issuer to calculate preferences based on values significant to the local cell. .PP .Vb 1 \& # calc_prefs | fs setserverprefs \-stdin .Ve .PP The following command uses the \fB\-vlservers\fR argument to set the Cache Manager's preferences for the \s-1VL\s0 server machines named \f(CW\*(C`fs1.abc.com\*(C'\fR, \&\f(CW\*(C`fs3.abc.com\*(C'\fR, and \f(CW\*(C`fs4.abc.com\*(C'\fR to base ranks of 1, 11000, and 65521, respectively: .PP .Vb 2 \& # fs setserverprefs \-vlservers fs1.abc.com 1 fs3.abc.com 11000 \e \& fs4.abc.com 65521 .Ve .SH "PRIVILEGE REQUIRED" .IX Header "PRIVILEGE REQUIRED" The issuer must be logged in as the local superuser root. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIfs_getserverprefs\fR\|(1) .SH "COPYRIGHT" .IX Header "COPYRIGHT" \&\s-1IBM\s0 Corporation 2000. All Rights Reserved. .PP This documentation is covered by the \s-1IBM\s0 Public License Version 1.0. It was converted from \s-1HTML\s0 to \s-1POD\s0 by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.