doc: Fix udebug -port bullet list
[openafs.git] / doc / man-pages / pod1 / udebug.pod
1 =head1 NAME
2
3 udebug - Reports Ubik process status for a database server process
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<udebug> S<<< B<-server> <I<server machine>> >>> S<<< [B<-port> <I<IP port>>] >>>
11     [B<-long>] [B<-help>]
12
13 B<udebug> S<<< B<-s> <I<server machine>> >>> S<<< [B<-p> <I<IP port>>] >>> [B<-l>] [B<-h>]
14
15 =for html
16 </div>
17
18 =head1 DESCRIPTION
19
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.
26
27 =head1 OPTIONS
28
29 =over 4
30
31 =item B<-server> <I<server machine>>
32
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
40 issued.
41
42 =item B<-port> <I<IP port>>
43
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
46 following values:
47
48 =over 4
49
50 =item
51
52 B<buserver> or 7021 for the Backup Server
53
54 =item
55
56 B<kaserver> or 7004 for the Authentication Server
57
58 =item
59
60 B<ptserver> or 7002 for the Protection Server
61
62 =item
63
64 B<vlserver> or 7003 for the Volume Location Server
65
66 =back
67
68 =item B<-long>
69
70 Reports additional information about each peer of the machine named by the
71 B<-server> argument. The information appears by default if that machine
72 is the synchronization site.
73
74 =item B<-help>
75
76 Prints the online help for this command. All other valid options are
77 ignored.
78
79 =back
80
81 =head1 OUTPUT
82
83 Several of the messages in the output provide basic status information
84 about the Ubik process on the machine specified by the B<-server>
85 argument, and the remaining messages are useful mostly for debugging
86 purposes.
87
88 To check basic Ubik status, issue the command for each database server
89 machine in turn. In the output for each, one of the following messages
90 appears in the top third of the output.
91
92    I am sync site . . . (<#_sites> servers)
93
94    I am not sync site
95
96 For the synchronization site, the following message indicates that all
97 sites have the same version of the database, which implies that Ubik is
98 functioning correctly. See the following for a description of values other
99 than C<1f>.
100
101    Recovery state 1f
102
103 For correct Ubik operation, the database server machine clocks must agree
104 on the time. The following messages, which are the second and third lines
105 in the output, report the current date and time according to the database
106 server machine's clock and the clock on the machine where the B<udebug>
107 command is issued.
108
109    Host's <IP_addr> time is <dbserver_date/time>
110    Local time is <local_date/time> (time differential <skew> secs)
111
112 The <skew> is the difference between the database server machine clock and
113 the local clock. Its absolute value is not vital for Ubik functioning, but
114 a difference of more than a few seconds between the I<skew> values for the
115 database server machines indicates that their clocks are not synchronized
116 and Ubik performance is possibly hampered.
117
118 Following is a description of all messages in the output. As noted, it is
119 useful mostly for debugging and most meaningful to someone who understands
120 Ubik's implementation.
121
122 The output begins with the following messages. The first message reports
123 the IP addresses that are configured with the operating system on the
124 machine specified by the B<-server> argument. As previously noted, the
125 second and third messages report the current date and time according to
126 the clocks on the database server machine and the machine where the
127 B<udebug> command is issued, respectively. All subsequent timestamps in
128 the output are expressed in terms of the local clock rather than the
129 database server machine clock.
130
131    Host's addresses are: <list_of_IP_addrs>
132    Host's <IP_addr> time is <dbserver_date/time>
133    Local time is <local_date/time> (time differential <skew> secs)
134
135 If the <skew> is more than about 10 seconds, the following message
136 appears. As noted, it does not necessarily indicate Ubik malfunction: it
137 denotes clock skew between the database server machine and the local
138 machine, rather than among the database server machines.
139
140    ****clock may be bad
141
142 If the udebug command is issued during the coordinator election process
143 and voting has not yet begun, the following message appears next.
144
145    Last yes vote not cast yet
146
147 Otherwise, the output continues with the following messages.
148
149    Last yes vote for <sync_IP_addr> was <last_vote> secs ago (sync site);
150    Last vote started <vote_start> secs ago (at <date/time>)
151    Local db version is <db_version>
152
153 The first indicates which peer this Ubik process last voted for as
154 coordinator (it can vote for itself) and how long ago it sent the vote.
155 The second message indicates how long ago the Ubik coordinator requested
156 confirming votes from the secondary sites. Usually, the <last_vote> and
157 <vote_start> values are the same; a difference between them can indicate
158 clock skew or a slow network connection between the two database server
159 machines. A small difference is not harmful. The third message reports the
160 current version number <db_version> of the database maintained by this
161 Ubik process. It has two fields separated by a period. The field before
162 the period is based on a timestamp that reflects when the database first
163 changed after the most recent coordinator election, and the field after
164 the period indicates the number of changes since the election.
165
166 The output continues with messages that differ depending on whether the
167 Ubik process is the coordinator or not.
168
169 =over 4
170
171 =item *
172
173 If there is only one database server machine, it is always the coordinator
174 (synchronization site), as indicated by the following message.
175
176    I am sync site forever (1 server)
177
178 =item *
179
180 If there are multiple database sites, and the B<-server> argument names
181 the coordinator (synchronization site), the output continues with the
182 following two messages.
183
184    I am sync site until <expiration> secs from now (at <date/time>)
185        (<#_sites> servers)
186    Recovery state <flags>
187
188 The first message (which is reported on one line) reports how much longer
189 the site remains coordinator even if the next attempt to maintain quorum
190 fails, and how many sites are participating in the quorum. The I<flags>
191 field in the second message is a hexadecimal number that indicates the
192 current state of the quorum. A value of C<1f> indicates complete database
193 synchronization, whereas a value of C<f> means that the coordinator has
194 the correct database but cannot contact all secondary sites to determine
195 if they also have it. Lesser values are acceptable if the B<udebug>
196 command is issued during coordinator election, but they denote a problem
197 if they persist. The individual flags have the following meanings:
198
199 =over 4
200
201 =item 0x1
202
203 This machine is the coordinator.
204
205 =item 0x2
206
207 The coordinator has determined which site has the database with the
208 highest version number.
209
210 =item 0x4
211
212 The coordinator has a copy of the database with the highest version
213 number.
214
215 =item 0x8
216
217 The database's version number has been updated correctly.
218
219 =item 0x10
220
221 All sites have the database with the highest version number.
222
223 =back
224
225 If the udebug command is issued while the coordinator is writing a change
226 into the database, the following additional message appears.
227
228    I am currently managing write transaction I<identifier>
229
230 =item *
231
232 If the B<-server> argument names a secondary site, the output continues
233 with the following messages.
234
235    I am not sync site
236    Lowest host <lowest_IP_addr> was set <low_time> secs ago
237    Sync host <sync_IP_addr> was set <sync_time> secs ago
238
239 The <lowest_IP_addr> is the lowest IP address of any peer from which the
240 Ubik process has received a message recently, whereas the <sync_IP_addr>
241 is the IP address of the current coordinator. If they differ, the machine
242 with the lowest IP address is not currently the coordinator. The Ubik
243 process continues voting for the current coordinator as long as they
244 remain in contact, which provides for maximum stability. However, in the
245 event of another coordinator election, this Ubik process votes for the
246 <lowest_IP_addr> site instead (assuming they are in contact), because it
247 has a bias to vote in elections for the site with the lowest IP address.
248
249 =back
250
251 For both the synchronization and secondary sites, the output continues
252 with the following messages. The first message reports the version number
253 of the database at the synchronization site, which needs to match the
254 <db_version> reported by the preceding C<Local db version> message. The
255 second message indicates how many VLDB records are currently locked for
256 any operation or for writing in particular. The values are nonzero if the
257 B<udebug> command is issued while an operation is in progress.
258
259    Sync site's db version is <db_version>
260    <locked> locked pages, <writes> of them for write
261
262 The following messages appear next only if there are any read or write
263 locks on database records:
264
265    There are read locks held
266    There are write locks held
267
268 Similarly, one or more of the following messages appear next only if there
269 are any read or write transactions in progress when the B<udebug> command
270 is issued:
271
272    There is an active write transaction
273    There is at least one active read transaction
274    Transaction tid is <tid>
275
276 If the machine named by the B<-server> argument is the coordinator, the
277 next message reports when the current coordinator last updated the
278 database.
279
280     Last time a new db version was labelled was:
281             <last_restart> secs ago (at <date/time>)
282
283 If the machine named by the B<-server> argument is the coordinator, the
284 output concludes with an entry for each secondary site that is
285 participating in the quorum, in the following format.
286
287    Server (<IP_address>): (db <db_version>)
288    last vote rcvd <last_vote> secs ago (at <date/time>),
289    last beacon sent <last_beacon> secs ago (at <date/time>),
290        last vote was { yes | no }
291    dbcurrent={ 0 | 1 }, up={ 0 | 1 } beaconSince={ 0 | 1 }
292
293 The first line reports the site's IP address and the version number of the
294 database it is maintaining. The <last_vote> field reports how long ago the
295 coordinator received a vote message from the Ubik process at the site, and
296 the <last_beacon> field how long ago the coordinator last requested a vote
297 message. If the B<udebug> command is issued during the coordinator
298 election process and voting has not yet begun, the following messages
299 appear instead.
300
301    Last vote never rcvd
302    Last beacon never sent
303
304 On the final line of each entry, the fields have the following meaning:
305
306 =over 4
307
308 =item *
309
310 C<dbcurrent> is C<1> if the site has the database with the highest version
311 number, C<0> if it does not.
312
313 =item *
314
315 C<up> is C<1> if the Ubik process at the site is functioning correctly,
316 C<0> if it is not.
317
318 =item *
319
320 C<beaconSince> is C<1> if the site has responded to the coordinator's last
321 request for votes, C<0> if it has not.
322
323 =back
324
325 Including the B<-long> flag produces peer entries even when the
326 B<-server> argument names a secondary site, but in that case only the
327 I<IP_address> field is guaranteed to be accurate. For example, the value
328 in the <db_version> field is usually C<0.0>, because secondary sites do
329 not poll their peers for this information.  The values in the I<last_vote>
330 and I<last_beacon> fields indicate when this site last received or
331 requested a vote as coordinator; they generally indicate the time of the
332 last coordinator election.
333
334 =head1 EXAMPLES
335
336 This example checks the status of the Ubik process for the Volume Location
337 Server on the machine C<afs1>, which is the synchronization site.
338
339    % udebug afs1 vlserver
340    Host's addresses are: 192.12.107.33
341    Host's 192.12.107.33 time is Wed Oct 27 09:49:50 1999
342    Local time is Wed Oct 27 09:49:52 1999 (time differential 2 secs)
343    Last yes vote for 192.12.107.33 was 1 secs ago (sync site);
344    Last vote started 1 secs ago (at Wed Oct 27 09:49:51 1999)
345    Local db version is 940902602.674
346    I am sync site until 58 secs from now (at Wed Oct 27 09:50:50 1999) (3 servers)
347    Recovery state 1f
348    Sync site's db version is 940902602.674
349    0 locked pages, 0 of them for write
350    Last time a new db version was labelled was:
351             129588 secs ago (at Mon Oct 25 21:50:04 1999)
352
353    Server( 192.12.107.35 ): (db 940902602.674)
354        last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
355        last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
356        dbcurrent=1, up=1 beaconSince=1
357
358    Server( 192.12.107.34 ): (db 940902602.674)
359        last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
360        last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
361        dbcurrent=1, up=1 beaconSince=1
362
363 This example checks the status of the Authentication Server on the machine
364 with IP address 192.12.107.34, which is a secondary site. The local clock
365 is about 4 minutes behind the database server machine's clock.
366
367    % udebug 192.12.107.34 7004
368    Host's addresses are: 192.12.107.34
369    Host's 192.12.107.34 time is Wed Oct 27 09:54:15 1999
370    Local time is Wed Oct 27 09:50:08 1999 (time differential -247 secs)
371    ****clock may be bad
372    Last yes vote for 192.12.107.33 was 6 secs ago (sync site);
373    Last vote started 6 secs ago (at Wed Oct 27 09:50:02 1999)
374    Local db version is 940906574.25
375    I am not sync site
376    Lowest host 192.12.107.33 was set 6 secs ago
377    Sync host 192.12.107.33 was set 6 secs ago
378    Sync site's db version is 940906574.25
379    0 locked pages, 0 of them for write
380
381 =head1 PRIVILEGE REQUIRED
382
383 None
384
385 =head1 SEE ALSO
386
387 L<buserver(8)>,
388 L<kaserver(8)>,
389 L<ptserver(8)>,
390 L<vlserver(8)>
391
392 =head1 COPYRIGHT
393
394 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
395
396 This documentation is covered by the IBM Public License Version 1.0.  It was
397 converted from HTML to POD by software written by Chas Williams and Russ
398 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.