UDEBUG(1)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💅 UDEBUG(1) — AFS Command Reference 🌸

okay bestie, pull up a chair because udebug is one of those little commands that's lowkey iconic once you know what it's doing. It lives in the AFS Command Reference, section 1, and it's literally called udebug. Say it with me: you-debug. 💖

✨ NAME ✨

udebug — reports Ubik process status for a database server process 🦋

Like… it tells you what's going on with the lightweight Ubik process chilling inside a database server process. That's the whole vibe.

🎀 SYNOPSIS 🎀

udebug -server <server machine> [-port <IP port>]
    [-long] [-help]

udebug -s <server machine> [-p <IP port>] [-l] [-h]

so there's the long-form girlies and the short-form girlies, and they do the exact same thing. pick your fighter. 💅

🌈 DESCRIPTION 🌈

The udebug command displays the status of the lightweight Ubik process for the database server process identified by the -port argument that is running on the database server machine named by the -server argument.

The way that the output just ✨ identifies the machines where peer database server processes are running✨, tells you which of them is the synchronization site (aka the Ubik coordinator, main character energy 👑), and shows you the status of the connections between them? Obsessed.

So yeah: <pink>-server</pink> picks the machine, <pink>-port</pink> picks which process on that machine, and udebug spills the tea about who's talking to whom and who's running the show. 🫶

🔥 OPTIONS 🔥

  • -server <server machine> — Names the database server machine that is running the process for which to display status information. And bestie, you have options for how you name it: give the machine's IP address in dotted decimal format, its fully qualified host name (for example, fs1.example.com), or the shortest abbreviated form of its host name that distinguishes it from other machines. ⭐
Heads up though: successful use of an abbreviated form depends on the availability of a name resolution service (such as the Domain Name Service or a local host table) at the time the command is issued. No name service, no shortcut name. periodt. 💀
  • -port <IP port> — Identifies the database server process for which to display status information, either by its process name or port number. Provide one of the following values, and yes you gotta pick from the list:
    • buserver or 7021 for the Backup Server
    • kaserver or 7004 for the Authentication Server
    • ptserver or 7002 for the Protection Server
    • vlserver or 7003 for the Volume Location Server
  • -long — Reports additional information about each peer of the machine named by the -server argument. 👀 And here's the cute part: the information appears by default if that machine is the synchronization site. So if she's the coordinator, you get the extra deets whether you asked or not. slay.
  • -help — Prints the online help for this command. All other valid options are ignored. 🙈 yep, she does not care what else you passed, -help is a solo act.

and that's the first chunk, bestie — there's more coming, so don't go anywhere 💜

✨ OUTPUT ✨

okay so bestie, a whole bunch of these messages are just here to give you the basic tea ☕ on the Ubik process running on the machine you named with the -server argument, and the leftover ones are mostly for debugging purposes. ngl, most of it is very "iykyk" territory.

To vibe check basic Ubik status, just run the command for each database server machine one at a time, like a little tour 🦋. In the output for each one, one of these messages is gonna pop up in the top third of the output:

I am sync site . . . (<#_sites> servers)

I am not sync site

For the synchronization site, this next message means every site has the same version of the database, which implies Ubik is functioning correctly and being a good little server 👑. Peep below for what it means when that value is anything other than "1f":

Recovery state 1f

For Ubik to actually work right, the database server machine clocks have to agree on the time — no cap, this matters 💀. These next messages (they're the second and third lines of the output) report the current date and time according to the database server machine's clock, and according to the clock on the machine where you issued the udebug command:

Host's <IP_addr> time is <dbserver_date/time>
Local time is <local_date/time> (time differential <skew> secs)

The <skew> is the difference between the database server machine clock and your local clock. Its absolute value isn't vital for Ubik functioning, but listen — if there's a difference of more than a few seconds between the skew values for the database server machines, that means their clocks are not synchronized and Ubik performance is possibly getting hampered 😭.

Next up, here's a rundown of every message in the output. Like I said, it's useful mostly for debugging, and it's most meaningful to someone who actually understands Ubik's implementation (main character energy for the systems nerds 🧚).

The output kicks off with these messages. The first one reports the IP addresses configured with the operating system on the machine named by the -server argument. And as already mentioned, the second and third messages report the current date and time according to the clocks on the database server machine and the machine where udebug was issued, respectively. Pro tip: every subsequent timestamp in the output is expressed in terms of the local clock, not the database server machine clock 👀.

Host's addresses are: <list_of_IP_addrs>
Host's <IP_addr> time is <dbserver_date/time>
Local time is <local_date/time> (time differential <skew> secs)

If the <skew> is more than about 10 seconds, this message shows up. And as noted (say it with me), it does not necessarily mean Ubik is malfunctioning: it denotes clock skew between the database server machine and the local machine, not among the database server machines. So don't spiral 💅.

****clock may be bad

If you ran the udebug command during the coordinator election process and voting hasn't begun yet, this message appears next:

Last yes vote not cast yet

Otherwise? The output keeps going with these:

Last yes vote for <sync_IP_addr> was <last_vote> secs ago (sync site);
Last vote started <vote_start> secs ago (at <date/time>)
Local db version is <db_version>

The first one tells you which peer this Ubik process last voted for as coordinator (it can vote for itself, iconic 💅) and how long ago it sent that vote. The second message tells you how long ago the Ubik coordinator requested confirming votes from the secondary sites. Usually the <last_vote> and <vote_start> values are the same; if they differ, that can signal clock skew or a slow network connection between the two database server machines. A small difference is not harmful, don't stress 🫶. The third message reports the current version number <db_version> of the database maintained by this Ubik process. It's got two fields separated by a period. The field before the period is based on a timestamp that reflects when the database first changed after the most recent coordinator election, and the field after the period tells you the number of changes since that election.

Now the output branches based on whether this Ubik process is the coordinator or not 🌈.

  • If there's only one database server machine, it's always the coordinator (synchronization site), as this message shows:
I am sync site forever (1 server)
  • If there are multiple database sites, and the -server argument names the coordinator (the synchronization site), the output continues with these two messages:
I am sync site until <expiration> secs from now (at <date/time>)
    (<#_sites> servers)
Recovery state <flags>

The first message (which gets reported on one line) tells you how much longer the site stays coordinator even if the next attempt to maintain quorum fails, plus how many sites are participating in the quorum. The flags field in the second message is a hexadecimal number that indicates the current state of the quorum 🔥. A value of "1f" means complete database synchronization, whereas a value of "f" means the coordinator has the correct database but cannot contact all secondary sites to determine if they also have it. Lesser values are acceptable if you ran udebug during coordinator election, but they denote a problem if they persist 👀. The individual flags mean the following:

  • 0x1 — This machine is the coordinator.
  • 0x2 — The coordinator has determined which site has the database with the highest version number.
  • 0x4 — The coordinator has a copy of the database with the highest version number.
  • 0x8 — The database's version number has been updated correctly.
  • 0x10 — All sites have the database with the highest version number.

If you issued the udebug command while the coordinator is writing a change into the database, this extra message shows up too:

I am currently managing write transaction I<identifier>
  • If the -server argument names a secondary site, the output continues with these messages:
I am not sync site
Lowest host <lowest_IP_addr> was set <low_time> secs ago
Sync host <sync_IP_addr> was set <sync_time> secs ago

The <lowest_IP_addr> is the lowest IP address of any peer this Ubik process has received a message from recently, whereas <sync_IP_addr> is the IP address of the current coordinator. If those two differ, the machine with the lowest IP address is not currently the coordinator. The Ubik process keeps voting for the current coordinator as long as they stay in contact — which is what provides maximum stability, slay for reliability ✨. But the moment another coordinator election happens, this Ubik process votes for the <lowest_IP_addr> site instead (assuming they're in contact), because it's got a bias to vote in elections for the site with the lowest IP address. periodt.

For both the synchronization and secondary sites, the output continues with these messages. The first reports the version number of the database at the synchronization site, which needs to match the <db_version> reported by the earlier "Local db version" message (consistency queen 👑). The second tells you how many VLDB records are currently locked for any operation, or for writing in particular. Those values are nonzero if you ran udebug while an operation was in progress.

Sync site's db version is <db_version>
<locked> locked pages, <writes> of them for write

These next messages only show up if there are any read or write locks on database records:

There are read locks held
There are write locks held

Similarly, one or more of these messages show up right after, only if there are any read or write transactions in progress at the moment you issued udebug:

There is an active write transaction
There is at least one active read transaction
Transaction tid is <tid>

If the machine named by the -server argument is the coordinator, the next message reports when the current coordinator last updated the database:

Last time a new db version was labelled was:
        <last_restart> secs ago (at <date/time>)

And if the machine named by the -server argument is the coordinator, the output wraps up with an entry for every secondary site participating in the quorum, in this format:

Server (<IP_address>): (db <db_version>)
last vote rcvd <last_vote> secs ago (at <date/time>),
last beacon sent <last_beacon> secs ago (at <date/time>),
    last vote was { yes | no }
dbcurrent={ 0 | 1 }, up={ 0 | 1 } beaconSince={ 0 | 1 }

The first line reports the site's IP address and the version number of the database it's maintaining. The <last_vote> field reports how long ago the coordinator received a vote message from the Ubik process at that site, and the <last_beacon> field tells you how long ago the coordinator last requested a vote message 💜. But if you issued the udebug command during the coordinator election process and voting hasn't begun yet, these messages show up instead:

Last vote never rcvd
Last beacon never sent

On that final line of each entry, here's what those fields actually mean:

  • "dbcurrent" is 1 if the site has the database with the highest version number, 0 if it doesn't.
  • "up" is 1 if the Ubik process at the site is functioning correctly, 0 if it is not.
  • "beaconSince" is 1 if the site has responded to the coordinator's last request for votes, 0 if it hasn't.

Including the -long flag produces peer entries even when the -server argument names a secondary site — but heads up bestie, in that case only the IP_address field is guaranteed to be accurate 🙈. For example, the value in the <db_version> field is usually 0.0, because secondary sites don't poll their peers for this information. And the values in the last_vote and last_beacon fields indicate when this site last received or requested a vote as coordinator; they generally indicate the time of the last coordinator election.

🌸 EXAMPLES 🎀

okay bestie, real talk, these examples?? iconic. let's walk through them together 💖

✨ Example 1: checking the sync site ✨

So like, this one checks the status of the Ubik process for the Volume Location Server on the machine "afs1", which is literally the synchronization site. queen behavior 👑

% udebug afs1 vlserver
Host's addresses are: 192.12.107.33
Host's 192.12.107.33 time is Wed Oct 27 09:49:50 1999
Local time is Wed Oct 27 09:49:52 1999 (time differential 2 secs)
Last yes vote for 192.12.107.33 was 1 secs ago (sync site);
Last vote started 1 secs ago (at Wed Oct 27 09:49:51 1999)
Local db version is 940902602.674
I am sync site until 58 secs from now (at Wed Oct 27 09:50:50 1999) (3 servers)
Recovery state 1f
Sync site's db version is 940902602.674
0 locked pages, 0 of them for write
Last time a new db version was labelled was:
         129588 secs ago (at Mon Oct 25 21:50:04 1999)

Server( 192.12.107.35 ): (db 940902602.674)
    last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
    last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
    dbcurrent=1, up=1 beaconSince=1

Server( 192.12.107.34 ): (db 940902602.674)
    last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
    last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
    dbcurrent=1, up=1 beaconSince=1

look at that. sync site status, vote receipts, beacon gossip, every server reporting in. the vibes are immaculate 🦋

💅 Example 2: the secondary site with a clock problem 💅

This next one checks the status of the Authentication Server on the machine with IP address 192.12.107.34, which is a secondary site. and bestie? the local clock is about 4 minutes behind the database server machine's clock. yikes 😭 it literally says so.

% udebug 192.12.107.34 7004
Host's addresses are: 192.12.107.34
Host's 192.12.107.34 time is Wed Oct 27 09:54:15 1999
Local time is Wed Oct 27 09:50:08 1999 (time differential -247 secs)
****clock may be bad
Last yes vote for 192.12.107.33 was 6 secs ago (sync site);
Last vote started 6 secs ago (at Wed Oct 27 09:50:02 1999)
Local db version is 940906574.25
I am not sync site
Lowest host 192.12.107.33 was set 6 secs ago
Sync host 192.12.107.33 was set 6 secs ago
Sync site's db version is 940906574.25
0 locked pages, 0 of them for write

see that ****clock may be bad line? that's the universe clocking the tea ☕ and the time differential -247 secs is the receipt. not me and my server living in different time zones fr fr 🙈

🌈 PRIVILEGE REQUIRED 👑

None

like. zero. none. nada. you need nothing special to run this, bestie. go check your Ubik servers, you've got the clearance 💖✨

💜 SEE ALSO 🫶

go read up on your servers, it's giving ✨informed✨

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. legends only, no cap 👑

and that's the whole page, bestie!! 🦋✨ this is UDEBUG(1) from OpenAFS, dated 2026-07-27, and honestly? she ate. now go debug something and slay 💅💖🌸

📦 where this page comes from