doc/html/AdminReference/auarf237.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf236.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf238.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRUDEBUG" HREF="auarf002.htm#ToC_251">udebug</A></H2>
  19 <A NAME="IDX5484"></A>
  20 <A NAME="IDX5485"></A>
  21 <A NAME="IDX5486"></A>
  22 <P><STRONG>Purpose</STRONG>
  23 <P>Reports status of Ubik process associated with a database server process
  24 <P><STRONG>Synopsis</STRONG>
  25 <PRE><B>udebug -servers</B>  &lt;<VAR>server&nbsp;machine</VAR>>  [<B>-port</B> &lt;<VAR>IP&nbsp;port</VAR>>]  [<B>-long</B>]  [<B>-help</B>]
  26
  27 <B>udebug -s</B>  &lt;<VAR>server&nbsp;machine</VAR>>  [<B>-p</B> &lt;<VAR>IP&nbsp;port</VAR>>]  [<B>-l</B>]  [<B>-h</B>]
  28
  29 </PRE>
  30 <P><STRONG>Description</STRONG>
  31 <P>The <B>udebug</B> command displays the status of the lightweight Ubik
  32 process for the database server process identified by the <B>-port</B>
  33 argument that is running on the database server machine named by the
  34 <B>-servers</B> argument. The output identifies the machines where
  35 peer database server processes are running, which of them is the
  36 synchronization site (Ubik coordinator), and the status of the connections
  37 between them.
  38 <P><STRONG>Options</STRONG>
  39 <DL>
  40 <P><DT><B>-servers
  41 </B><DD>Names the database server machine that is running the process for which to
  42 display status information. Provide the machine's IP address in
  43 dotted decimal format, its fully qualified host name (for example,
  44 <B>fs1.abc.com</B>), or the shortest abbreviated form of its
  45 host name that distinguishes it from other machines. Successful use of
  46 an abbreviated form depends on the availability of a name resolution service
  47 (such as the Domain Name Service or a local host table) at the time the
  48 command is issued.
  49 <P><DT><B>-port
  50 </B><DD>Identifies the database server process for which to display status
  51 information, either by its process name or port number. Provide one of
  52 the following values.
  53 <DL>
  54 <DD><P><B>buserver</B> or <B>7021</B> for the Backup Server
  55 <DD><P><B>kaserver</B> or <B>7004</B> for the Authentication Server
  56 <DD><P><B>ptserver</B> or <B>7002</B> for the Protection Server
  57 <DD><P><B>vlserver</B> or <B>7003</B> for the Volume Location Server
  58 </DL>
  59 <P><DT><B>-long
  60 </B><DD>Reports additional information about each peer of the machine named by the
  61 <B>-servers</B> argument. The information appears by default if
  62 that machine is the synchronization site.
  63 <P><DT><B>-help
  64 </B><DD>Prints the online help for this command. All other valid options
  65 are ignored.
  66 </DL>
  67 <P><STRONG>Output</STRONG>
  68 <P>Several of the messages in the output provide basic status information
  69 about the Ubik process on the machine specified by the <B>-servers</B>
  70 argument, and the remaining messages are useful mostly for debugging
  71 purposes.
  72 <P>To check basic Ubik status, issue the command for each database server
  73 machine in turn. In the output for each, one of the following messages
  74 appears in the top third of the output.
  75 <PRE>   I am sync site . . . (<VAR>#_sites</VAR> servers)
  76
  77    I am not sync site
  78 </PRE>
  79 <P>For the synchronization site, the following message indicates that all
  80 sites have the same version of the database, which implies that Ubik is
  81 functioning correctly. See the following for a description of values
  82 other than <TT>1f</TT>.
  83 <PRE>   Recovery state 1f
  84 </PRE>
  85 <P>For correct Ubik operation, the database server machine clocks must agree
  86 on the time. The following messages, which are the second and third
  87 lines in the output, report the current date and time according to the
  88 database server machine's clock and the clock on the machine where the
  89 <B>udebug</B> command is issued.
  90 <PRE>   Host's <VAR>IP_addr</VAR> time is <VAR>dbserver_date/time</VAR>
  91    Local time is <VAR>local_date/time</VAR> (time differential <VAR>skew</VAR> secs)
  92 </PRE>
  93 <P>The <VAR>skew</VAR> is the difference between the database server machine
  94 clock and the local clock. Its absolute value is not vital for Ubik
  95 functioning, but a difference of more than a few seconds between the
  96 <VAR>skew</VAR> values for the database server machines indicates that their
  97 clocks are not synchronized and Ubik performance is possibly hampered.
  98 <P>Following is a description of all messages in the output. As noted,
  99 it is useful mostly for debugging and most meaningful to someone who
 100 understands Ubik's implementation.
 101 <P>The output begins with the following messages. The first message
 102 reports the IP addresses that are configured with the operating system on the
 103 machine specified by the <B>-servers</B> argument. As previously
 104 noted, the second and third messages report the current date and time
 105 according to the clocks on the database server machine and the machine where
 106 the <B>udebug</B> command is issued, respectively. All subsequent
 107 timestamps in the output are expressed in terms of the local clock rather than
 108 the database server machine clock.
 109 <PRE>   Host's addresses are: <VAR>list_of_IP_addrs</VAR>
 110    Host's <VAR>IP_addr</VAR> time is <VAR>dbserver_date/time</VAR>
 111    Local time is <VAR>local_date/time</VAR> (time differential <VAR>skew</VAR> secs)
 112 </PRE>
 113 <P>If the <VAR>skew</VAR> is more than about 10 seconds, the following message
 114 appears. As noted, it does not necessarily indicate Ubik
 115 malfunction: it denotes clock skew between the database server machine
 116 and the local machine, rather than among the database server machines.
 117 <PRE>   ****clock may be bad
 118 </PRE>
 119 <P>If the <B>udebug</B> command is issued during the coordinator election
 120 process and voting has not yet begun, the following message appears
 121 next.
 122 <PRE>   Last yes vote not cast yet
 123 </PRE>
 124 <P>Otherwise, the output continues with the following messages.
 125 <PRE>   Last yes vote for <VAR>sync_IP_addr</VAR> was <VAR>last_vote</VAR> secs ago (sync site);
 126    Last vote started <VAR>vote_start</VAR> secs ago (at <VAR>date/time</VAR>)
 127    Local db version is <VAR>db_version</VAR>
 128 </PRE>
 129 <P>The first indicates which peer this Ubik process last voted for as
 130 coordinator (it can vote for itself) and how long ago it sent the vote.
 131 The second message indicates how long ago the Ubik coordinator requested
 132 confirming votes from the secondary sites. Usually, the
 133 <VAR>last_vote</VAR> and <VAR>vote_start</VAR> values are the same; a
 134 difference between them can indicate clock skew or a slow network connection
 135 between the two database server machines. A small difference is not
 136 harmful. The third message reports the current version number
 137 <VAR>db_version</VAR> of the database maintained by this Ubik process. It
 138 has two fields separated by a period. The field before the period is
 139 based on a timestamp that reflects when the database first changed after the
 140 most recent coordinator election, and the field after the period indicates the
 141 number of changes since the election.
 142 <P>The output continues with messages that differ depending on whether the
 143 Ubik process is the coordinator or not.
 144 <UL>
 145 <P><LI>If there is only one database server machine, it is always the coordinator
 146 (synchronization site), as indicated by the following message.
 147 <PRE>   I am sync site forever (1 server)
 148 </PRE>
 149 <P><LI>If there are multiple database sites, and the <B>-servers</B> argument
 150 names the coordinator (synchronization site), the output continues with the
 151 following two messages.
 152 <PRE>   I am sync site until <VAR>expiration</VAR> secs from now (at <VAR>date/time</VAR>) (<VAR>#_sites</VAR> servers)
 153    Recovery state <VAR>flags</VAR>
 154 </PRE>
 155 <P>The first message reports how much longer the site remains coordinator even
 156 if the next attempt to maintain quorum fails, and how many sites are
 157 participating in the quorum. The <VAR>flags</VAR> field in the second
 158 message is a hexadecimal number that indicates the current state of the
 159 quorum. A value of <TT>1f</TT> indicates complete database
 160 synchronization, whereas a value of <TT>f</TT> means that the coordinator
 161 has the correct database but cannot contact all secondary sites to determine
 162 if they also have it. Lesser values are acceptable if the
 163 <B>udebug</B> command is issued during coordinator election, but they
 164 denote a problem if they persist. The individual flags have the
 165 following meanings:
 166 <DL>
 167 <P><DT><B><TT>0x1</TT>
 168 </B><DD>This machine is the coordinator
 169 <P><DT><B><TT>0x2</TT>
 170 </B><DD>The coordinator has determined which site has the database with the
 171 highest version number
 172 <P><DT><B><TT>0x4</TT>
 173 </B><DD>The coordinator has a copy of the database with the highest version number
 174 <P><DT><B><TT>0x8</TT>
 175 </B><DD>The database's version number has been updated correctly
 176 <P><DT><B><TT>0x10</TT>
 177 </B><DD>All sites have the database with the highest version number
 178 </DL>
 179 <P>If the <B>udebug</B> command is issued while the coordinator is writing
 180 a change into the database, the following additional message appears.
 181 <PRE>   I am currently managing write transaction <VAR>identifier</VAR>
 182 </PRE>
 183 <P><LI>If the <B>-servers</B> argument names a secondary site, the output
 184 continues with the following messages.
 185 <PRE>   I am not sync site
 186    Lowest host <VAR>lowest_IP_addr</VAR> was set <VAR>low_time</VAR> secs ago
 187    Sync host <VAR>sync_IP_addr</VAR>  was set <VAR>sync_time</VAR> secs ago
 188 </PRE>
 189 <P>The <VAR>lowest_IP_addr</VAR> is the lowest IP address of any peer from which
 190 the Ubik process has received a message recently, whereas the
 191 <VAR>sync_IP_addr</VAR> is the IP address of the current coordinator. If
 192 they differ, the machine with the lowest IP address is not currently the
 193 coordinator. The Ubik process continues voting for the current
 194 coordinator as long as they remain in contact, which provides for maximum
 195 stability. However, in the event of another coordinator election, this
 196 Ubik process votes for the <VAR>lowest_IP_addr</VAR> site instead (assuming they
 197 are in contact), because it has a bias to vote in elections for the site with
 198 the lowest IP address.
 199 </UL>
 200 <P>For both the synchronization and secondary sites, the output continues with
 201 the following messages. The first message reports the version number of
 202 the database at the synchronization site, which needs to match the
 203 <VAR>db_version</VAR> reported by the preceding <TT>Local db version</TT>
 204 message. The second message indicates how many VLDB records are
 205 currently locked for any operation or for writing in particular. The
 206 values are nonzero if the <B>udebug</B> command is issued while an
 207 operation is in progress.
 208 <PRE>     Sync site's db version is <VAR>db_version</VAR>
 209    <VAR>locked</VAR> locked pages, <VAR>writes</VAR> of them for write
 210 </PRE>
 211 <P>The following messages appear next only if there are any read or write
 212 locks on database records:
 213 <PRE>   There are read locks held
 214    There are write locks held
 215 </PRE>
 216 <P>Similarly, one or more of the following messages appear next only if there
 217 are any read or write transactions in progress when the <B>udebug</B>
 218 command is issued:
 219 <PRE>   There is an active write transaction
 220    There is at least one active read transaction
 221    Transaction tid is <VAR>tid</VAR>
 222 </PRE>
 223 <P>If the machine named by the <B>-servers</B> argument is the
 224 coordinator, the next message reports when the current coordinator last
 225 updated the database.
 226 <PRE>    Last time a new db version was labelled was:
 227             <VAR>last_restart</VAR> secs ago (at <VAR>date/time</VAR>)
 228 </PRE>
 229 <P>If the machine named by the <B>-servers</B> argument is the
 230 coordinator, the output concludes with an entry for each secondary site that
 231 is participating in the quorum, in the following format.
 232 <PRE>   Server( <VAR>IP_address</VAR> ): (db <VAR>db_version</VAR>)
 233    last vote rcvd <VAR>last_vote</VAR> secs ago (at <VAR>date/time</VAR>),
 234    last beacon sent <VAR>last_beacon</VAR> secs ago (at <VAR>date/time</VAR>), last vote was { yes | no }
 235    dbcurrent={ 0 | 1 }, up={ 0 | 1 } beaconSince={ 0 | 1 }
 236 </PRE>
 237 <P>The first line reports the site's IP address and the version number of
 238 the database it is maintaining. The <VAR>last_vote</VAR> field reports
 239 how long ago the coordinator received a vote message from the Ubik process at
 240 the site, and the <VAR>last_beacon</VAR> field how long ago the coordinator last
 241 requested a vote message. If the <B>udebug</B> command is issued
 242 during the coordinator election process and voting has not yet begun, the
 243 following messages appear instead.
 244 <PRE>   Last vote never rcvd
 245    Last beacon never sent
 246 </PRE>
 247 <P>On the final line of each entry, the fields have the following
 248 meaning:
 249 <UL>
 250 <P><LI><TT>dbcurrent</TT> is <TT>1</TT> if the site has the database with the
 251 highest version number, <TT>0</TT> if it does not
 252 <P><LI><TT>up</TT> is <TT>1</TT> if the Ubik process at the site is
 253 functioning correctly, <TT>0</TT> if it is not
 254 <P><LI><TT>beaconSince</TT> is <TT>1</TT> if the site has responded to the
 255 coordinator's last request for votes, <TT>0</TT> if it has not
 256 </UL>
 257 <P>Including the <B>-long</B> flag produces peer entries even when the
 258 <B>-servers</B> argument names a secondary site, but in that case only the
 259 <VAR>IP_address</VAR> field is guaranteed to be accurate. For example,
 260 the value in the <VAR>db_version</VAR> field is usually <TT>0.0</TT>,
 261 because secondary sites do not poll their peers for this information.
 262 The values in the <VAR>last_vote</VAR> and <VAR>last_beacon</VAR> fields indicate
 263 when this site last received or requested a vote as coordinator; they
 264 generally indicate the time of the last coordinator election.
 265 <P><STRONG>Examples</STRONG>
 266 <P>This example checks the status of the Ubik process for the Volume Location
 267 Server on the machine <B>afs1</B>, which is the synchronization
 268 site.
 269 <PRE>   % <B>udebug afs1 vlserver</B>
 270    Host's addresses are: 192.12.107.33
 271    Host's 192.12.107.33 time is Wed Oct 27 09:49:50 1999
 272    Local time is Wed Oct 27 09:49:52 1999 (time differential 2 secs)
 273    Last yes vote for 192.12.107.33 was 1 secs ago (sync site);
 274    Last vote started 1 secs ago (at Wed Oct 27 09:49:51 1999)
 275    Local db version is 940902602.674
 276    I am sync site until 58 secs from now (at Wed Oct 27 09:50:50 1999) (3 servers)
 277    Recovery state 1f
 278    Sync site's db version is 940902602.674
 279    0 locked pages, 0 of them for write
 280    Last time a new db version was labelled was:
 281             129588 secs ago (at Mon Oct 25 21:50:04 1999)
 282
 283    Server( 192.12.107.35 ): (db 940902602.674)
 284        last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
 285        last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
 286        dbcurrent=1, up=1 beaconSince=1
 287
 288    Server( 192.12.107.34 ): (db 940902602.674)
 289        last vote rcvd 2 secs ago (at Wed Oct 27 09:49:50 1999),
 290        last beacon sent 1 secs ago (at Wed Oct 27 09:49:51 1999), last vote was yes
 291        dbcurrent=1, up=1 beaconSince=1
 292 </PRE>
 293 <P>This example checks the status of the Authentication Server on the machine
 294 with IP address 192.12.107.34, which is a secondary
 295 site. The local clock is about 4 minutes behind the database server
 296 machine's clock.
 297 <PRE>   % <B>udebug 192.12.107.34 7004</B>
 298    Host's addresses are: 192.12.107.34
 299    Host's 192.12.107.34 time is Wed Oct 27 09:54:15 1999
 300    Local time is Wed Oct 27 09:50:08 1999 (time differential -247 secs)
 301    ****clock may be bad
 302    Last yes vote for 192.12.107.33 was 6 secs ago (sync site);
 303    Last vote started 6 secs ago (at Wed Oct 27 09:50:02 1999)
 304    Local db version is 940906574.25
 305    I am not sync site
 306    Lowest host 192.12.107.33 was set 6 secs ago
 307    Sync host 192.12.107.33 was set 6 secs ago
 308    Sync site's db version is 940906574.25
 309    0 locked pages, 0 of them for write
 310 </PRE>
 311 <P><STRONG>Privilege Required</STRONG>
 312 <P><STRONG>Related Information</STRONG>
 313 <P><A HREF="auarf125.htm#HDRBUSERVER">buserver</A>
 314 <P><A HREF="auarf198.htm#HDRKASERVER">kaserver</A>
 315 <P><A HREF="auarf227.htm#HDRPTSERVER">ptserver</A>
 316 <P><A HREF="auarf249.htm#HDRVLSERVER">vlserver</A>
 317 <P>
 318 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf236.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf238.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 319 <!-- Begin Footer Records  ========================================== -->
 320 <P><HR><B>
 321 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 322 </B>
 323 <!-- End Footer Records  ============================================ -->
 324 <A NAME="Bot_Of_Page"></A>
 325 </BODY></HTML>