FS_GETSERVERPREFS(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 FS_GETSERVERPREFS 💖

okay bestie, pull up a chair, we're doing AFS command reference today — this is fs_getserverprefs, part of the AFS command reference, and it's genuinely so useful once it clicks, i promise 🫶

✨ NAME ✨

fs_getserverprefs — the lil command that shows you preference ranks for file servers or VL servers. no cap, that's the whole gig 💅

🌸 SYNOPSIS 🌸

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

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

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

three ways to say the exact same thing: getserverprefs, gets, or gp. the shorties are for when your fingers are tired. iconic.

💜 DESCRIPTION 💜

So. fs getserverprefs displays preference ranks for file server machine interfaces — and yes, "file server machines" here means machines running the fs process, iykyk — or, if you pass the -vlserver flag, for Volume Location (VL) Server machines (which are out here running the vlserver process).

For file server machines, the Cache Manager tracks up to 15 interfaces per machine, and gives each interface its own separate rank. These ranks = the order the local Cache Manager tries contacting the interfaces of machines housing a volume when it needs to fetch data from that volume. For VL Server machines, the ranks = the order the Cache Manager tries contacting a cell's VL Servers when it's requesting VLDB info.

And for both kinds of rank: lower integer values are more preferred. that's the whole vibe, lower = better, periodt ✨

The Cache Manager keeps ranks in kernel memory. Once a rank is set, it persists until the machine reboots, or until you use the fs setserverprefs command to change it. fs_setserverprefs(1) is where you go to learn 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. The Cache Manager assigns ranks to every machine listed in its copy of the /etc/openafs/CellServDB file, or found via DNS AFSDB or SRV records for the cell, when it initializes. When the Cache Manager needs to fetch VLDB info 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 it can't reach that one (server process outage, machine outage, network outage — the whole menu 😭), it tries the VL Server with the next lowest integer rank, and so on and so on. If all of a cell's VL Server machines are unavailable, the Cache Manager cannot fetch data from the cell. that's it, that's the limit, no plan B 💀

Default file server ranks range from 5,000 to 40,000, excluding the range reserved for VL Servers (10,000 to 10,126) — and 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 with the lowest integer rank. Can't reach the fileserver process via that interface (server process, machine, or network outage)? It goes to the interface with the next lowest integer rank, and so on. And if it can't reach any of the interfaces for machines housing that volume... yeah, it cannot fetch data from the volume. 💔

Here's a cute lil detail: for both file server machines and VL Server machines, it is totally possible for a machine or interface in a foreign cell to have the same rank as a machine or interface in the local cell. And that is fine, not a problem, not a bug, don't panic 🧚 — because the Cache Manager only ever compares ranks for machines belonging to one cell at a time. slay, boundaries.

🎀 OPTIONS 🎀

  • -file <output file> — Specifies the full pathname of a file to write the preference ranks to. If that file already exists, the command overwrites its contents. If the pathname is invalid, the command fails. If you don't pass this argument at all, the preference ranks just show up on the standard output stream. 🍓
  • -numeric — Displays the IP addresses of file server machine interfaces or VL Server machines instead of their hostnames. Skip this argument and the fs command interpreter translates the IP addresses to hostnames like "fs1.example.com". 🦋
  • -vlservers — Displays preference ranks for VL Server machines instead of file server machine interfaces.
  • -help — Prints the online help for this command. All other valid options are ignored. (it said what it said 💅)

🌈 OUTPUT 🌈

The output is 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 (like the Domain Name Server) or the local host table. So if an IP address shows up in your output, it's because the translation attempt failed — not your fault, it just couldn't resolve 🙈. To bypass the translation step entirely and display IP addresses instead of hostnames, include the -numeric flag. This can significantly speed the production of output, so if you're impatient (same), you know what to do ✨

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

🔥 EXAMPLES 🔥

First one: this displays the local Cache Manager's preference ranks for file server machines. The local machine belongs to the AFS cell named example.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 "example.net". It is not possible to translate the IP addresses of two machines on the 138.255 network. 😭

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

Second one: this shows how the output displays IP addresses when the -numeric flag is included, and it illustrates how network proximity determines default ranks (as described on the fs setserverprefs 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're 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

Third one: this shows how the -vlservers flag displays preference ranks for VL Server machines 👑

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

👑 PRIVILEGE REQUIRED 👑

None. you literally need zero privileges, you're welcome, go forth and check your ranks bestie 💅

🦋 SEE ALSO 🦋

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

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.

and that's the whole page, bestie!! no notes, ate, left zero crumbs 🫶✨

OpenAFS — 2026-07-27 — FS_GETSERVERPREFS(1) 💖 that's the source, the version, and the date, mwah, bye!! 🎀

📦 where this page comes from