rtpmon.1

rtpmon-1.0a7.tar.gz for UNIX like

.TH rtpmon 1
.SH NAME
.B rtpmon
- A Third Party RTCP Monitor
.SH SYNOPSIS
.B rtpmon
[
.B \-C
.I conferenceName
]
.\" [
.\" .B \-K
.\" .I key
.\" ]
[
.B \-d
.I display
]
[
.B \-t
.I threshold
]
[
.B \-u
.I script
]
[
.B \-X
.I resource=value
]
.I addr/port

.SH DESCRIPTION
.B Rtpmon
is a third-party RTCP monitor.  It can be used to monitor the control
information exchanged between applications that implement RTP, the
Real-Time Transport Protocol.  Feedback from receivers, including the
loss rate and jitter, are displayed in a table that can be sorted in
various ways to help isolate and diagnose multicast distribution
problems.

.SH OPTIONS
.TP
.B \-C
Use
.I conferenceName
as the title for the main
.B rtpmon
window.  If the \-C flag is ommitted, the destination address
and port are used as the window title.
.TP
.B \-d
Connect to the X server indicated by the
.I display
argument.
.TP
.B \-t
Make
.I threshold
the default threshold for loss rate in the main display window as
described below.
.TP
.TP
.B \-u
Source
.I script,
in addition to the compiled-in script, to build the user interface.
This is only useful during development.
.TP
.B \-X
Override the X resource 
Rtpmon.\fIresource\fR
with
.I value.

.SH OPERATION
Upon startup,
.B rtpmon
starts listening for RTCP packets sent to the RTP session on the
multicast address
.I addr
and the appropriate RTPv2 control port corresponding to 
.I port.
(that is, if
.I port
is odd, it is used and if
.I port
is even, 
.I port
+ 1 is used).

The main window is a table with current senders listed across the top
and listeners along the left side.  Each row in the table displays
that listener's statistics about its reception from each sender.  The
default display shows loss rate measured over the last 4 RTCP packets
received from the listener.  Other statistics can be displayed as
described below.

Clicking on a name (either a sender or a listener) will bring up a
window that includes the latest contents of all RTCP SDES packets seen
from that source as well as their RTP synchronization source id, IP
address, and the time of their most recent control packet.

Clicking on a statistic in the main display will bring up a window with
stripcharts that display the recent history of all the statistics
available.  Three statistics are currently displayed.  
.I Packet Loss
is calculated by comparing the number of dropped packets to the number
of expected packets over the last 4 RTCP packets from a listener.
.I Filtered Packet Loss
is computed with a Moving Weighted Average over the ``fraction lost''
field of all RTCP packets from a listener.
.I Delay Jitter
is computed with a Moving Weighted Average over the ``interarrival
jitter'' field of all RTCP packets from a listener.

If mtrace(8) is installed, the stripchart window will have a button at
the bottom that will run mtrace from the sender to the listener via the
multicast group used for the session.

The button labeled ``Menu'' at the bottom of the main window brings up
a new menu window.  The statistic displayed in the main window can be
selected from this dialog.  Various other parameters (as described
below) can also be changed from the menu window.

.SH THRESHOLDS

In a large conference, there may be many listeners with very low loss
rates and jitter.  To keep the display from getting too cluttered and
to focus on interesting statistics, it is possible to display only those
listeners for which the loss rate (or another statistic) is above
some threshold.  The default threshold comes from the
.I Rtpmon.threshold
X resource or the
.I \-t
command line switch.  The threshold associated with each display
parameter can also be changed from the menu window.

To keep the display reasonably stable, if a listener is displayed in the
main window and their loss rate then falls below the threshold, they are
not immediately removed from the display.  The button labled ``Clean''
on the main window will remove those listeners that have loss rates
below the treshold.  Pressing the `c' key in the main window does the
same thing.

The display can be cleaned periodically by clicking the ``Autoclean''
button in the menu and selecting the interval (in seconds) at which
the display should be automatically cleaned.  Autoclean can be turned
on by default by setting the X resource
.I Rtpmon.autoclean
to 1 (the default is 0 which turns autoclean off).  The default autoclean
interval can be set by the X resource
.I Rtpmon.autocleanInterval.

.SH SORTING

The main display can be sorted by any of several keys.  The key to be
used can be chosen from the ``Sorting'' section of the menu.
.I Maximum Loss
sorts the rows by the maximum loss seen in all columns.
.I Average Loss
sorts the rows by the loss rate averaged over all columns.
.I IP Address
sorts the rows by the IP address from which RTCP packets are received.
IP addresses can be used for crude topographical grouping.  A single
column can be chosen by selecting
.I Sender
and then choosing a particular sender.

By default, the display is not continuously re-sorted.  It can be
explicitly sorted by pressing the ``Sort'' button on the main window
or pressing the `s' key.  The display can be sorted periodically using
the ``Autosort'' button in the menu which is analogous to ``Autoclean''.

.SH "X RESOURCES"
The following are the names and default values of X resources used by
.I rtpmon.
Any of these resources can be overridden by the -X command switch,
which may be used multiple times on the command line.
For example, "-Xautosort=1" overrides
.I Rtpmon.autosort
with 1.
.IP "\fBRtpmon.threshold\fI (1)\fP"
the default threshold for loss rate in the main display window
.IP "\fBRtpmon.autoclean\fI (0)\fP"
turns on or off autocleaning.
.IP "\fBRtpmon.autocleanInterval\fI (5)\fP"
interval (in seconds) at which the display should be cleaned if
autocleaning is on
.IP "\fBRtpmon.autosort\fI (0)\fP"
turns on or off autosorting
.IP "\fBRtpmon.autosortInterval\fI (5) \fP"
interval (in seconds) at which the display should be sorted if
autosorting is on
.IP "\fBRtpmon.refreshInterval\fI (.5)\fP"
interval (in seconds) at which values in the main display should
be refreshed
.IP "\fBRtpmon.sessbw\fI (64.)\fP"
the estimated data bandwidth for the session; used to estimate the
frequency with which RTCP packets should be expected.

.SH "SEE ALSO"
vic(1),
vat(1),
mtrace(8),
.LP
Schulzrinne, Casner, Frederick, Jacobson,
``RTP: A Transport Protocol for Real-Time Applications'',
Internet Request For Comments 1889, available via anonymous ftp
at ftp://ds.internic.net/rfc/rfc1889.txt.

.SH ACKNOWLEDGMENTS
.LP
The original design for 
.B rtpmon
was suggested by Van Jacobson.  The software architecture was
inspired by, and bits of code have been borrowed from,
.I vic
and
.I vat
written by Van Jacobson and Steve McCanne.  Bill Fenner has also
provided many useful comments, suggestions, and bug fixes.

.SH AUTHORS
David Bacher ([e-mail]) and
Andrew Swan ([e-mail])

.SH BUGS
This is an alpha release of
.B rtpmon
so there are likely to be many bugs.  A conference with multiple
simultaneous senders is not handled very well right now.  Older MBone
software may not conform to the RTP specification, leading to odd
reports for packet loss and jitter from receivers using those
programs.  Please report any other bugs to
.I [e-mail]