AFSMONITOR(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

👑 afsmonitor(1) — AFS Command Reference 👑

Bestie, welcome to the stat-watching group chat. This is the manual page for afsmonitor, and it is iconic in a very "I watch servers for fun" way. 💖

🌸 NAME 🌸

afsmonitor — Monitors File Servers and Cache Managers

✨ SYNOPSIS ✨

afsmonitor [initcmd] [-config <configuration file>]
    [-frequency <poll frequency, in seconds>]
    [-output <storage file name>] [-detailed]
    [-debug <debug output file>]
    [-fshosts <list of file servers to monitor>+]
    [-cmhosts <list of cache managers to monitor>+]
    [-buffers <number of buffer slots>] [-version] [-help]

afsmonitor [i]  [-co <configuration file>]
    [-fr <poll frequency, in seconds>]
    [-o <storage file name>] [-det]
    [-deb <debug output file>]
    [-fs <list of file servers to monitor>+]
    [-cm <list of cache managers to monitor>+]
    [-b <number of buffer slots>] [-version] [-h]

💖 DESCRIPTION 💖

So the afsmonitor command initializes a program that gathers and displays statistics about specified File Server and Cache Manager operations. It lets the issuer monitor, from a single location, a wide range of File Server and Cache Manager operations on any number of machines in both local and foreign cells. That's main character energy for infrastructure.

There are 271 available File Server statistics and 571 available Cache Manager statistics, listed in the appendix about afsmonitor statistics in the OpenAFS Administration Guide. By default, the command displays all of the relevant statistics for the file server machines named by the -fshosts argument and the client machines named by the -cmhosts argument. To limit the display to only the statistics of interest, list them in the configuration file specified by the -config argument. In addition, use the configuration file for the following purposes:

  • To set threshold values for any monitored statistic. When the value of a statistic exceeds the threshold, the afsmonitor command displays it in reverse video. There are no default threshold values.
  • To invoke a program or script automatically when a statistic exceeds its threshold. The AFS distribution does not include any such scripts.
  • To list the file server and client machines to monitor, instead of using the -fshosts and -cmhosts arguments.

For a description of the configuration file, see afsmonitor(5).

⚠️ CAUTIONS ⚠️

Bestie, read this part before you go goblin mode. It's giving "your terminal is now a dedicated altar" and that's on purpose. 🫶

The following software must be accessible to a machine where the afsmonitor program is running:

  • The AFS xstat libraries, which the afsmonitor program uses to gather data.
  • The curses graphics package, which most UNIX distributions provide as a standard utility.

The afsmonitor screens format successfully both on so-called dumb terminals and in windowing systems that emulate terminals. For the output to look its best, the display environment needs to support reverse video and cursor addressing. Set the TERM environment variable to the correct terminal type, or to a value that has characteristics similar to the actual terminal type. The display window or terminal must be at least 80 columns wide and 12 lines long.

The afsmonitor program must run in the foreground, and in its own separate, dedicated window or terminal. The window or terminal is unavailable for any other activity as long as the afsmonitor program is running. Any number of instances of the afsmonitor program can run on a single machine, as long as each instance runs in its own dedicated window or terminal. Note that it can take up to three minutes to start an additional instance.

💅 OPTIONS 💅

  • initcmd — Accommodates the command's use of the AFS command parser, and is optional. The short synopsis line writes this slot as [i].
  • -config <file>, -co <configuration file> — Names the configuration file which lists the machines to monitor, statistics to display, and threshold values, if any. A partial pathname is interpreted relative to the current working directory. Provide this argument if not providing the -fshosts argument, -cmhosts argument, or neither. For instructions on creating this file, see the preceding DESCRIPTION section, and the section on the afsmonitor program in the OpenAFS Administration Guide.
  • -frequency <poll frequency>, -fr <poll frequency, in seconds> — Specifies in seconds how often the afsmonitor program probes the File Servers and Cache Managers. Valid values range from 1 to 86400 (which is 24 hours); the default value is 60. This frequency applies to both File Servers and Cache Managers, but the afsmonitor program initiates the two types of probes, and processes their results, separately. The actual interval between probes to a host is the probe frequency plus the time required for all hosts to respond.
  • -output <file>, -o <storage file name> — Names the file to which the afsmonitor program writes all of the statistics that it collects. By default, no output file is created. See the section on the afsmonitor command in the OpenAFS Administration Guide for information on this file.
  • -detailed, -det — Formats the information in the output file named by -output argument in a maximally readable format. Provide the -output argument along with this one.
  • -fshosts <host>+, -fs <list of file servers to monitor>+ — Names one or more machines from which to gather File Server statistics. For each machine, provide either a fully qualified host name, or an unambiguous abbreviation (the ability to resolve an abbreviation depends on the state of the cell's name service at the time the command is issued). This argument can be combined with the -cmhosts argument, but not with the -config argument.
  • -cmhosts <host>+, -cm <list of cache managers to monitor>+ — Names one or more machines from which to gather Cache Manager statistics. For each machine, provide either a fully qualified host name, or an unambiguous abbreviation (the ability to resolve an abbreviation depends on the state of the cell's name service at the time the command is issued). This argument can be combined with the -fshosts argument, but not with the -config argument.
  • -buffers <slots>, -b <number of buffer slots> — Is nonoperational and provided to accommodate potential future enhancements to the program.
  • -debug <debut output file>, -deb <debug output file> — Turns on debugging output, and writes debugging information to the specified file. The synopsis also writes this as -debug <debug output file>.
  • -help, -h — Prints the online help for this command. All other valid options are ignored.
  • -version — Prints the program version and then exits. All other valid options are ignored.

🖥️ OUTPUT ✨

okay bestie, the afsmonitor program shows you its data across three whole screens, and they're all gorgeous in their own way:

  • System Overview — this one just appears the second afsmonitor initializes, like it's the main character or whatever. It sums up, separately for File Servers and Cache Managers, how many machines are being monitored and how many of those have alerts (an alert = a statistic that went past its threshold). Then it lists the hostname and the number of alerts for every machine it's watching, and it'll flag if a process failed to respond to the last probe. 💅
  • File Server — this screen shows File Server statistics for each file server machine being monitored. Threshold-breaking stats get highlighted, and machines that ghosted the last probe get called out.
  • Cache Managers — same energy, but for Cache Manager statistics on each client machine being monitored. Thresholds highlighted, probe-ghosters identified. 🦋

The corners of every screen are giving information, and you need to know all four:

  • Top left corner: the program name and version number. hi hello, it's me. 👑
  • Top right corner: the screen name, current and total page numbers, and current and total column numbers. The page number (for example, p. 1 of 3) tells you the index of the current page and the total number of (vertical) pages that data is spread over. The column number (for example, c. 1 of 235) gives you the index of the current leftmost column plus the total number of columns where data appears. Oh and — the symbol >>> means there's more data to the right, and <<< means there's more data to the left. peekaboo.
  • Bottom left corner: the list of available commands, bestie. Type the first letter of a command name to run it. Only the currently possible options show up — like, if there's only one page of data, the next and prev commands (which scroll the screen up and down) just don't appear, because why would they. For the full breakdown of the commands, scroll to the next section about navigating the display screens. 🧚
  • Bottom right corner: the probes field tells you how many times the program has probed File Servers (fs), Cache Managers (cm), or both. And yes, the counts for File Servers and Cache Managers can differ. The freq field reports how often the program sends probes. ⭐

as mentioned, the lower left hand corner of every display screen shows the names of the commands you currently have for bouncing between screens — whether that's a whole different screen type, or just more statistics/machines of the type you're already on. To run a command, press the lowercase version of the first letter in its name. Some commands also have an uppercase version with a slightly different effect, and I'm listing all of those below:

  • cm — switches you to the Cache Managers screen. Only available on the System Overview and File Servers screens.
  • fs — switches you to the File Servers screen. Only available on the System Overview and the Cache Managers screens.
  • left — scrolls horizontally to the left, so you can access the data columns sitting to the left of the current set. Available when the <<< symbol shows up at the top left of the screen. Press uppercase L to scroll horizontally alllll the way to the left, showing the very first set of data columns. 👈
  • next — scrolls down vertically to the next page of machine names. Available when there are two or more pages of machines and you're not already on the final page. Press uppercase N to jump straight to the final page.
  • oview — switches you to the System Overview screen. Only available on the Cache Managers and File Servers screens.
  • prev — scrolls up vertically to the previous page of machine names. Available when there are two or more pages of machines and you're not currently on the first page. Press uppercase N to scroll to the first page.
  • right — scrolls horizontally to the right, to access the data columns sitting to the right of the current set. This command is available when the >>> symbol appears at the upper right of the screen. Press uppercase R to scroll horizontally all the way to the right, showing the final set of data columns. 👉

🌸 The System Overview Screen 🌸

The System Overview screen pops up automatically as the afsmonitor program initializes — no asking, it just shows up. It displays the status of as many File Server and Cache Manager processes as can actually fit in the current window, so scroll down if you want the rest of the tea. 🍓

This screen is split — File Server info on the left, Cache Manager info on the right. The header for each grouping reports two things for you:

  • How many machines the program is monitoring the indicated process on.
  • How many alerts there are, and how many machines are affected by them. (An alert means a statistic exceeded its threshold, or a process failed to respond to the last probe. both count!)

Then comes the list of machines being monitored. If a machine has any alerts, the number of them shows up in square brackets to the left of the hostname. And if a process failed to respond to the last probe, the letters PF (probe failure 💀) appear in square brackets to the left of the hostname.

🔥 The File Servers Screen 🔥

The File Servers screen displays the values collected at the most recent probe for File Server statistics.

A summary line at the top of the screen — just below the standard program version and screen title blocks — spells out the number of monitored File Servers, the number of alerts, and the number of machines affected by those alerts.

The first column always shows the hostnames of the machines running the monitored File Servers. Periodt.

To the right of the hostname column, you get as many columns of statistics as can fit within the current width of the display screen or window — each column takes up space for 10 characters. The name of the statistic sits at the top of each column. If the File Server on a machine didn't respond to the most recent probe, a pair of dashes (--) appears in every column. If a value exceeds its configured threshold, it gets highlighted in reverse video. And if a value is too big to fit in the allotted column width, it overflows into the next row in the same column. no cap. 🌈

🦋 The Cache Managers Screen 🦋

The Cache Managers screen displays the values collected at the most recent probe for Cache Manager statistics.

A summary line at the top of the screen — just below the standard program version and screen title blocks — spells out the number of monitored Cache Managers, the number of alerts, and the number of machines affected by those alerts.

The first column always shows the hostnames of the machines running the monitored Cache Managers. iconic behavior.

To the right of the hostname column you get as many columns of statistics as fit within the current width of the display screen or window — each column needs space for 10 characters. The statistic's name appears at the top of each column. If the Cache Manager on a machine didn't respond to the most recent probe, a pair of dashes (--) appears in each column. If a value exceeds its configured threshold, it's highlighted in reverse video. If a value is too large for the allotted column width, it overflows into the next row in the same column. 💜

📝 Writing to an Output File 📝

Throw in the -output argument to name the file where afsmonitor writes all of the statistics it collects. This output file is lowkey amazing for tracking performance over long periods of time, and it lets the administrator apply post-processing techniques that reveal system trends. (heads up bestie: the AFS distribution does not include any post-processing programs. you'd be on your own for those.)

The output file is in ASCII format and records the same information as the File Server and Cache Manager display screens. Every line in the file uses this format to record the time at which afsmonitor gathered the indicated statistic from the Cache Manager (CM) or File Server (FS) running on the machine called host_name. If a probe failed, the error code -1 appears in the statistic field:

   <time>  <host_name>  CM|FS   <statistic>

And if the administrator usually reviews the output file by hand rather than feeding it to an automated analysis program or script, including the -detail flag formats the data in a much more readable form. your eyes will thank you. 🙈

💖 EXAMPLES 💖

For examples of commands, display screens, and configuration files, see the section about the afsmonitor program in the OpenAFS Administration Guide.

👑 PRIVILEGE REQUIRED 👑

None. that's right, zero, nothing, free. slay.

🌟 SEE ALSO 🌟

afsmonitor(5) fstrace(8), scout(1)

The OpenAFS Administration Guide at <http://docs.openafs.org/AdminGuide/>.

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 🫶 this one is from the OpenAFS era, dated 2026-07-27 — go forth and monitor those File Servers and Cache Managers, you've got this 💅✨

📦 where this page comes from