view release on metacpan or  search on metacpan

pod/rxdebug.pod  view on Meta::CPAN

#------------------------------------------------------------------------------
# rxdebug.pod
#
# Copyright © 2004 Alf Wachsmann <alfw@slac.stanford.edu> and
#                  Elizabeth Cassell <e_a_c@mailsnare.net>
#
# This library is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.
#------------------------------------------------------------------------------

=head1 NAME

B<rxdebug> - Provides debugging trace of Rx activity

=head1 SYNOPSIS

  use AFS::Monitor qw(rxdebug);

  my $rxd = rxdebug(version => 1,
                    servers => 'hostname',
                   );
  print "AFS build level of $rxd->{address} port $rxd->{port} is:";
  print $rxd->{version};

  $rxd = rxdebug(rxstats => 1,
                 noconns => 1,
                 servers => 'hostname',
                 port    => 7001,
                );

  $rxd = rxdebug(noconns  => 1,
                 peers    => 1,
                 long     => 1,
                 servers  => 'hostname',
                 port     => 7001,
                );

  $rxd = rxdebug(allconnections => 1,
                 servers        => 'hostname',
                 port           => 7002,
                );

  $rxd = rxdebug(nodally      => 1,
                 onlyserver   => 1,
                 onlyhost     => 'host2',
                 servers      => 'hostname',
                 port         => 7001,
                );

  $rxd = rxdebug(onlyclient   => 1,
                 onlyport     => 7002,
                 onlyauth     => 'crypt',
                 servers      => 'hostname',
                 port         => 7001,
                );

=head1 DESCRIPTION

The B<rxdebug> function provides a trace of Rx activity for the
server or client machine named by the B<servers> argument. Rx
is AFS's proprietary remote procedure call (RPC) protocol,
so this function enables the issuer to check the status of
communication between the Cache Manager or an AFS server
process (as specified with the B<port> argument) on the
machine and one or more processes on other machines.

=head1 OPTIONS

=over

=item B<servers>

Specifies the machine that is running the Cache Manager or server process for
which to trace Rx activity. Provide the machine's IP address in dotted decimal
format, its fully qualified host name (for example, B<fs1.abc.com>), or the
shortest abbreviated form of its host name that distinguishes it from other
machines. 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 function is issued.

=item B<port>

Specifies the process for which to trace Rx activity. Omit this argument to
specify the File Server (B<fileserver> process), or provide one of the
following values:

=over

=item *

B<7000> for the File Server (B<fileserver> process)

=item *

B<7001> for the Cache Manager (specifically, its callback interface)

=item *

B<7002> for the Protection Server (B<ptserver> process)

=item *

B<7003> for the Volume Location (VL) Server (B<vlserver> process)

=item *

B<7004> for the Authentication Server (B<kaserver> process)

=item *

B<7005> for the Volume Server (B<volserver> process)

=item *

B<7007> for the BOS Server (B<bosserver> process)

=item *

B<7008> for the Update Server (B<upserver> process)

=item *

B<7009> for the NFS/AFS Translator's B<rmtsysd> daemon

=item *

B<7021> for the Backup Server (B<buserver> process)

=item *

B<7025> through B<65535> for the Backup Tape Coordinator (B<butc> process) that
has the port offset number derived by subtracting 7025 from this value

=back

=item B<nodally>

Produces output only for connections that are not in dally mode. Dally mode is
a state in which the connection is idle or waiting.

=item B<allconnections>

Produces output for all connections, even inactive ones. By default, the output
includes information only for connections that are active or in dally mode.

=item B<rxstats>

Produces detailed statistics about Rx history and performance (for example,
counts of the number of packets of various types the process has read and sent,
calculations of average and minimum roundtrip time, and so on).

=item B<onlyserver>

Produces output only for connections in which the process designated by the
B<port> argument is acting as the server.

=item B<onlyclient>

Produces output only for connections in which the process designated by the
B<port> argument is acting as the client.

=item B<onlyport>

Produces output only for connections between the process designated by the
B<port> argument and the specified port on any another machine. Use the same
port identifiers as for the B<port> argument.

=item B<onlyhost>

Produces output only for connections between the process designated by the
B<port> argument and any process on the specified machine. To identify the
machine, use the same notation as for the B<servers> argument.

=item B<onlyauth>

Produces output only for connections that are using the specified
authentication level. Provide one of the following values:

=over

=item *

B<auth> for connections at authentication level B<rxkad_auth>

=item *

B<clear> for connections at authentication level B<rxkad_clear>

=item *

B<crypt> for connections at authentication level B<rxkad_crypt>

=item *

B<none> for unauthenticated connections (equivalents are B<null>, B<noauth>,
and B<unauth>)

=back

=item B<version>

Reports the AFS build level of the binary file for the process designated by
the B<port> argument (or of the kernel extensions file for port 7001, the Cache
Manager's callback interface). Any other options combined with this one are
ignored.

=item B<noconns>

Produces only the standard statistics that begin the output produced by every
option (other than B<version>), and peer structure information if the B<peers>
option was selected, without reporting on any connections.

=item B<peers>

Outputs information from the I<peer structure> maintained for each port on
another machine to which the process designated by the B<port> argument has a
connection. There is information about roundtrip time and numbers of packets
sent and received, for example.

=item B<long>

Outputs additional information from the I<peer structure> maintained for each
port on another machine to which the process designated by the B<port> argument
has a connection. Only use this with the B<peers> argument.

=back

=head1 OUTPUT

The return value is a reference to a hash containing the
requested information. The keys that the hash may contain, along
with a short description of their values, are listed below:

=over

=item *

C<address>: the IP address of the machine given by the B<servers> argument.

=item *

C<port>: the port used.

=item *

C<version>: a description of the AFS build level.

=item *

C<tstats>: a reference to a hash containing standard statistics.

=item *

C<rxstats>: a reference to a hash containing detailed rx statistics.

=item *

C<connections>: a reference to an array of hash references containing information about each connection.

=item *

C<dallyCounter>: the number of dallying connections skipped.

=item *

C<peers>: a reference to an array of hash references containing information about each peer.

=back

The simplest case would be if the version flag was set.
The hash table would have only three keys in it:
C<address>, C<port>, and C<version>.

For more details about the contents of the returned hash reference,
and an example of printing its entire contents in a readable format,
refer to the B<rxdebug> script in the B<examples> directory.


=head1 AUTHORS

The code and documentation for this class were contributed by Stanford
Linear Accelerator Center, a department of Stanford University.  This
documentation was written by

=over

=item Elizabeth Cassell <e_a_c@mailsnare.net> and

=item Alf Wachsmann <alfw@slac.stanford.edu>

=back

=head1 COPYRIGHT AND DISCLAIMER

 Copyright 2004 Alf Wachsmann <alfw@slac.stanford.edu> and
                Elizabeth Cassell <e_a_c@mailsnare.net>
 All rights reserved.

 Most of the explanations in this document are taken from the original
 AFS documentation.

 AFS-3 Programmer's Reference:
 Volume Server/Volume Location Server Interface
 Edward R. Zayas
 (c) 1991 Transarc Corporation.
 All rights reserved.

 IBM AFS Administration Reference
 (c) IBM Corporation 2000.
 All rights reserved.

 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.