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.abc.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 B<buserver> or 7021 for the Backup Server
  51
  52 =item B<kaserver> or 7004 for the Authentication Server
  53
  54 =item B<ptserver> or 7002 for the Protection Server
  55
  56 =item B<vlserver> or 7003 for the Volume Location Server
  57
  58 =back
  59
  60 =item B<-long>
  61
  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.
  65
  66 =item B<-help>
  67
  68 Prints the online help for this command. All other valid options are
  69 ignored.
  70
  71 =back
  72
  73 =head1 OUTPUT
  74
  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
  78 purposes.
  79
  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.
  83
  84    I am sync site . . . (<#_sites> servers)
  85
  86    I am not sync site
  87
  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
  91 than C<1f>.
  92
  93    Recovery state 1f
  94
  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>
  99 command is issued.
 100
 101    Host's <IP_addr> time is <dbserver_date/time>
 102    Local time is <local_date/time> (time differential <skew> secs)
 103
 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.
 109
 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.
 113
 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.
 122
 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)
 126
 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.
 131
 132    ****clock may be bad
 133
 134 If the udebug command is issued during the coordinator election process
 135 and voting has not yet begun, the following message appears next.
 136
 137    Last yes vote not cast yet
 138
 139 Otherwise, the output continues with the following messages.
 140
 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>
 144
 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.
 157
 158 The output continues with messages that differ depending on whether the
 159 Ubik process is the coordinator or not.
 160
 161 =over 4
 162
 163 =item *
 164
 165 If there is only one database server machine, it is always the coordinator
 166 (synchronization site), as indicated by the following message.
 167
 168    I am sync site forever (1 server)
 169
 170 =item *
 171
 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.
 175
 176    I am sync site until <expiration> secs from now (at <date/time>)
 177        (<#_sites> servers)
 178    Recovery state <flags>
 179
 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:
 190
 191 =over 4
 192
 193 =item 0x1
 194
 195 This machine is the coordinator.
 196
 197 =item 0x2
 198
 199 The coordinator has determined which site has the database with the
 200 highest version number.
 201
 202 =item 0x4
 203
 204 The coordinator has a copy of the database with the highest version
 205 number.
 206
 207 =item 0x8
 208
 209 The database's version number has been updated correctly.
 210
 211 =item 0x10
 212
 213 All sites have the database with the highest version number.
 214
 215 =back
 216
 217 If the udebug command is issued while the coordinator is writing a change
 218 into the database, the following additional message appears.
 219
 220    I am currently managing write transaction I<identifier>
 221
 222 =item *
 223
 224 If the B<-server> argument names a secondary site, the output continues
 225 with the following messages.
 226
 227    I am not sync site
 228    Lowest host <lowest_IP_addr> was set <low_time> secs ago
 229    Sync host <sync_IP_addr> was set <sync_time> secs ago
 230
 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.
 240
 241 =back
 242
 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.
 250
 251    Sync site's db version is <db_version>
 252    <locked> locked pages, <writes> of them for write
 253
 254 The following messages appear next only if there are any read or write
 255 locks on database records:
 256
 257    There are read locks held
 258    There are write locks held
 259
 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
 262 is issued:
 263
 264    There is an active write transaction
 265    There is at least one active read transaction
 266    Transaction tid is <tid>
 267
 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
 270 database.
 271
 272     Last time a new db version was labelled was:
 273             <last_restart> secs ago (at <date/time>)
 274
 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.
 278
 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 }
 284
 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
 291 appear instead.
 292
 293    Last vote never rcvd
 294    Last beacon never sent
 295
 296 On the final line of each entry, the fields have the following meaning:
 297
 298 =over 4
 299
 300 =item *
 301
 302 C<dbcurrent> is C<1> if the site has the database with the highest version
 303 number, C<0> if it does not.
 304
 305 =item *
 306
 307 C<up> is C<1> if the Ubik process at the site is functioning correctly,
 308 C<0> if it is not.
 309
 310 =item *
 311
 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.
 314
 315 =back
 316
 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.
 325
 326 =head1 EXAMPLES
 327
 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.
 330
 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)
 339    Recovery state 1f
 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)
 344
 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
 349
 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
 354
 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.
 358
 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)
 363    ****clock may be bad
 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
 367    I am not sync site
 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
 372
 373 =head1 PRIVILEGE REQUIRED
 374
 375 None
 376
 377 =head1 SEE ALSO
 378
 379 L<buserver(8)>,
 380 L<kaserver(8)>,
 381 L<ptserver(8)>,
 382 L<vlserver(8)>
 383
 384 =head1 COPYRIGHT
 385
 386 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 387
 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.