3 udebug - Reports Ubik process status for a database server process
10 B<udebug> S<<< B<-server> <I<server machine>> >>> S<<< [B<-port> <I<IP port>>] >>>
13 B<udebug> S<<< B<-s> <I<server machine>> >>> S<<< [B<-p> <I<IP port>>] >>> [B<-l>] [B<-h>]
20 The B<udebug> command displays the status of the lightweight Ubik process
21 for the database server process identified by the B<-port> argument that
22 is running on the database server machine named by the B<-server>
23 argument. The output identifies the machines where peer database server
24 processes are running, which of them is the synchronization site (Ubik
25 coordinator), and the status of the connections between them.
31 =item B<-server> <I<server machine>>
33 Names the database server machine that is running the process for which to
34 display status information. Provide the machine's IP address in dotted
35 decimal format, its fully qualified host name (for example,
36 B<fs1.example.com>), or the shortest abbreviated form of its host name that
37 distinguishes it from other machines. Successful use of an abbreviated
38 form depends on the availability of a name resolution service (such as the
39 Domain Name Service or a local host table) at the time the command is
42 =item B<-port> <I<IP port>>
44 Identifies the database server process for which to display status
45 information, either by its process name or port number. Provide one of the
50 =item B<buserver> or 7021 for the Backup Server
52 =item B<kaserver> or 7004 for the Authentication Server
54 =item B<ptserver> or 7002 for the Protection Server
56 =item B<vlserver> or 7003 for the Volume Location Server
62 Reports additional information about each peer of the machine named by the
63 B<-server> argument. The information appears by default if that machine
64 is the synchronization site.
68 Prints the online help for this command. All other valid options are
75 Several of the messages in the output provide basic status information
76 about the Ubik process on the machine specified by the B<-server>
77 argument, and the remaining messages are useful mostly for debugging
80 To check basic Ubik status, issue the command for each database server
81 machine in turn. In the output for each, one of the following messages
82 appears in the top third of the output.
84 I am sync site . . . (<#_sites> servers)
88 For the synchronization site, the following message indicates that all
89 sites have the same version of the database, which implies that Ubik is
90 functioning correctly. See the following for a description of values other
95 For correct Ubik operation, the database server machine clocks must agree
96 on the time. The following messages, which are the second and third lines
97 in the output, report the current date and time according to the database
98 server machine's clock and the clock on the machine where the B<udebug>
101 Host's <IP_addr> time is <dbserver_date/time>
102 Local time is <local_date/time> (time differential <skew> secs)
104 The <skew> is the difference between the database server machine clock and
105 the local clock. Its absolute value is not vital for Ubik functioning, but
106 a difference of more than a few seconds between the I<skew> values for the
107 database server machines indicates that their clocks are not synchronized
108 and Ubik performance is possibly hampered.
110 Following is a description of all messages in the output. As noted, it is
111 useful mostly for debugging and most meaningful to someone who understands
112 Ubik's implementation.
114 The output begins with the following messages. The first message reports
115 the IP addresses that are configured with the operating system on the
116 machine specified by the B<-server> argument. As previously noted, the
117 second and third messages report the current date and time according to
118 the clocks on the database server machine and the machine where the
119 B<udebug> command is issued, respectively. All subsequent timestamps in
120 the output are expressed in terms of the local clock rather than the
121 database server machine clock.
123 Host's addresses are: <list_of_IP_addrs>
124 Host's <IP_addr> time is <dbserver_date/time>
125 Local time is <local_date/time> (time differential <skew> secs)
127 If the <skew> is more than about 10 seconds, the following message
128 appears. As noted, it does not necessarily indicate Ubik malfunction: it
129 denotes clock skew between the database server machine and the local
130 machine, rather than among the database server machines.
134 If the udebug command is issued during the coordinator election process
135 and voting has not yet begun, the following message appears next.
137 Last yes vote not cast yet
139 Otherwise, the output continues with the following messages.
141 Last yes vote for <sync_IP_addr> was <last_vote> secs ago (sync site);
142 Last vote started <vote_start> secs ago (at <date/time>)
143 Local db version is <db_version>
145 The first indicates which peer this Ubik process last voted for as
146 coordinator (it can vote for itself) and how long ago it sent the vote.
147 The second message indicates how long ago the Ubik coordinator requested
148 confirming votes from the secondary sites. Usually, the <last_vote> and
149 <vote_start> values are the same; a difference between them can indicate
150 clock skew or a slow network connection between the two database server
151 machines. A small difference is not harmful. The third message reports the
152 current version number <db_version> of the database maintained by this
153 Ubik process. It has two fields separated by a period. The field before
154 the period is based on a timestamp that reflects when the database first
155 changed after the most recent coordinator election, and the field after
156 the period indicates the number of changes since the election.
158 The output continues with messages that differ depending on whether the
159 Ubik process is the coordinator or not.
165 If there is only one database server machine, it is always the coordinator
166 (synchronization site), as indicated by the following message.
168 I am sync site forever (1 server)
172 If there are multiple database sites, and the B<-server> argument names
173 the coordinator (synchronization site), the output continues with the
174 following two messages.
176 I am sync site until <expiration> secs from now (at <date/time>)
178 Recovery state <flags>
180 The first message (which is reported on one line) reports how much longer
181 the site remains coordinator even if the next attempt to maintain quorum
182 fails, and how many sites are participating in the quorum. The I<flags>
183 field in the second message is a hexadecimal number that indicates the
184 current state of the quorum. A value of C<1f> indicates complete database
185 synchronization, whereas a value of C<f> means that the coordinator has
186 the correct database but cannot contact all secondary sites to determine
187 if they also have it. Lesser values are acceptable if the B<udebug>
188 command is issued during coordinator election, but they denote a problem
189 if they persist. The individual flags have the following meanings:
195 This machine is the coordinator.
199 The coordinator has determined which site has the database with the
200 highest version number.
204 The coordinator has a copy of the database with the highest version
209 The database's version number has been updated correctly.
213 All sites have the database with the highest version number.
217 If the udebug command is issued while the coordinator is writing a change
218 into the database, the following additional message appears.
220 I am currently managing write transaction I<identifier>
224 If the B<-server> argument names a secondary site, the output continues
225 with the following messages.
228 Lowest host <lowest_IP_addr> was set <low_time> secs ago
229 Sync host <sync_IP_addr> was set <sync_time> secs ago
231 The <lowest_IP_addr> is the lowest IP address of any peer from which the
232 Ubik process has received a message recently, whereas the <sync_IP_addr>
233 is the IP address of the current coordinator. If they differ, the machine
234 with the lowest IP address is not currently the coordinator. The Ubik
235 process continues voting for the current coordinator as long as they
236 remain in contact, which provides for maximum stability. However, in the
237 event of another coordinator election, this Ubik process votes for the
238 <lowest_IP_addr> site instead (assuming they are in contact), because it
239 has a bias to vote in elections for the site with the lowest IP address.
243 For both the synchronization and secondary sites, the output continues
244 with the following messages. The first message reports the version number
245 of the database at the synchronization site, which needs to match the
246 <db_version> reported by the preceding C<Local db version> message. The
247 second message indicates how many VLDB records are currently locked for
248 any operation or for writing in particular. The values are nonzero if the
249 B<udebug> command is issued while an operation is in progress.
251 Sync site's db version is <db_version>
252 <locked> locked pages, <writes> of them for write
254 The following messages appear next only if there are any read or write
255 locks on database records:
257 There are read locks held
258 There are write locks held
260 Similarly, one or more of the following messages appear next only if there
261 are any read or write transactions in progress when the B<udebug> command
264 There is an active write transaction
265 There is at least one active read transaction
266 Transaction tid is <tid>
268 If the machine named by the B<-server> argument is the coordinator, the
269 next message reports when the current coordinator last updated the
272 Last time a new db version was labelled was:
273 <last_restart> secs ago (at <date/time>)
275 If the machine named by the B<-server> argument is the coordinator, the
276 output concludes with an entry for each secondary site that is
277 participating in the quorum, in the following format.
279 Server (<IP_address>): (db <db_version>)
280 last vote rcvd <last_vote> secs ago (at <date/time>),
281 last beacon sent <last_beacon> secs ago (at <date/time>),
282 last vote was { yes | no }
283 dbcurrent={ 0 | 1 }, up={ 0 | 1 } beaconSince={ 0 | 1 }
285 The first line reports the site's IP address and the version number of the
286 database it is maintaining. The <last_vote> field reports how long ago the
287 coordinator received a vote message from the Ubik process at the site, and
288 the <last_beacon> field how long ago the coordinator last requested a vote
289 message. If the B<udebug> command is issued during the coordinator
290 election process and voting has not yet begun, the following messages
294 Last beacon never sent
296 On the final line of each entry, the fields have the following meaning:
302 C<dbcurrent> is C<1> if the site has the database with the highest version
303 number, C<0> if it does not.
307 C<up> is C<1> if the Ubik process at the site is functioning correctly,
312 C<beaconSince> is C<1> if the site has responded to the coordinator's last
313 request for votes, C<0> if it has not.
317 Including the B<-long> flag produces peer entries even when the
318 B<-server> argument names a secondary site, but in that case only the
319 I<IP_address> field is guaranteed to be accurate. For example, the value
320 in the <db_version> field is usually C<0.0>, because secondary sites do
321 not poll their peers for this information. The values in the I<last_vote>
322 and I<last_beacon> fields indicate when this site last received or
323 requested a vote as coordinator; they generally indicate the time of the
324 last coordinator election.
328 This example checks the status of the Ubik process for the Volume Location
329 Server on the machine C<afs1>, which is the synchronization site.
331 % udebug afs1 vlserver
332 Host's addresses are: 192.12.107.33
333 Host's 192.12.107.33 time is Wed Oct 27 09:49:50 1999
334 Local time is Wed Oct 27 09:49:52 1999 (time differential 2 secs)
335 Last yes vote for 192.12.107.33 was 1 secs ago (sync site);
336 Last vote started 1 secs ago (at Wed Oct 27 09:49:51 1999)
337 Local db version is 940902602.674
338 I am sync site until 58 secs from now (at Wed Oct 27 09:50:50 1999) (3 servers)
340 Sync site's db version is 940902602.674
341 0 locked pages, 0 of them for write
342 Last time a new db version was labelled was:
343 129588 secs ago (at Mon Oct 25 21:50:04 1999)
345 Server( 192.12.107.35 ): (db 940902602.674)
346 last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
347 last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
348 dbcurrent=1, up=1 beaconSince=1
350 Server( 192.12.107.34 ): (db 940902602.674)
351 last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
352 last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
353 dbcurrent=1, up=1 beaconSince=1
355 This example checks the status of the Authentication Server on the machine
356 with IP address 192.12.107.34, which is a secondary site. The local clock
357 is about 4 minutes behind the database server machine's clock.
359 % udebug 192.12.107.34 7004
360 Host's addresses are: 192.12.107.34
361 Host's 192.12.107.34 time is Wed Oct 27 09:54:15 1999
362 Local time is Wed Oct 27 09:50:08 1999 (time differential -247 secs)
364 Last yes vote for 192.12.107.33 was 6 secs ago (sync site);
365 Last vote started 6 secs ago (at Wed Oct 27 09:50:02 1999)
366 Local db version is 940906574.25
368 Lowest host 192.12.107.33 was set 6 secs ago
369 Sync host 192.12.107.33 was set 6 secs ago
370 Sync site's db version is 940906574.25
371 0 locked pages, 0 of them for write
373 =head1 PRIVILEGE REQUIRED
386 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
388 This documentation is covered by the IBM Public License Version 1.0. It was
389 converted from HTML to POD by software written by Chas Williams and Russ
390 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.