<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY package "cmon">
  <!ENTITY date    "April 2004">
]>

<refentry>
<refentryinfo>
    <address><email>coda@cs.cmu.edu</email></address>
    <copyright>
	<year>1990-2004</year>
	<holder>Carnegie Mellon University</holder>
    </copyright>
    <date>&date;</date>
</refentryinfo>

<refmeta>
    <refentrytitle>&package;</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Coda Distributed File System</refmiscinfo>
</refmeta>

<refnamediv>
    <refname>&package;</refname>
    <refpurpose>Coda server monitor</refpurpose>
</refnamediv>

<refsynopsisdiv>
    <cmdsynopsis>
	<command>cmon</command>
	<arg>-a</arg>
	<arg>-t <replaceable>probeinterval</replaceable></arg>
	<arg choice=req><replaceable>server</replaceable></arg>
	<arg rep=repeat><replaceable>server</replaceable></arg>
    </cmdsynopsis>
</refsynopsisdiv>

<refsect1>
    <title>DESCRIPTION</title>
    <para><command>cmon</command> probes the specified list of servers
    once every <emphasis>probeinterval</emphasis> seconds and reports on
    their status. If a server is down or unreachable,
    <command>cmon</command> tries to reestablish contact with it once
    every <emphasis>probeinterval</emphasis> seconds.  It uses the
    <citerefentry>
	<refentrytitle>curses</refentrytitle>
	<manvolnum>3</manvolnum>
    </citerefentry> package for screen management and can be used
    on dumb terminals.  Run <command>cmon</command> in a terminal
    emulator (like
    <citerefentry>
	<refentrytitle>xterm</refentrytitle>
	<manvolnum>1</manvolnum>
    </citerefentry>).
    </para>
    <para>Some <command>cmon</command> data can be displayed in relative
    or absolute modes.  In relative mode, data is reported with
    reference to the interval between the last two probes.  In absolute
    mode, the accumulated value since initialization is reported.
    <command>cmon</command> can be toggled between absolute and real
    modes of presentation from the keyboard.  Typing
    <literal>a</literal> will cause data to be presented in absolute
    mode.  Typing <literal>r</literal> will present it in relative mode.
    A mode change will only take place at the next probe.
    </para>
</refsect1>

<refsect1>
    <title>OPTIONS</title>
    <para>The command-line options are:
    </para>
    <variablelist>
	<varlistentry>
	<term><option>-a</option></term>
	<listitem>
	    <para>Report data in absolute mode.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><option>-t</option></term>
	<listitem>
	    <para>Probe servers every <replaceable>probeinterval</replaceable> seconds. Default is 60.</para>
	</listitem>
	</varlistentry>
    </variablelist>
</refsect1>

<refsect1>
    <title>OUTPUT</title>
    <para>The data reported by <command>cmon</command> is organized
    under four headings: <emphasis>TIM</emphasis>, <emphasis>CPU</emphasis>,
    <emphasis>RPC</emphasis>, and <emphasis>DSK</emphasis>.
    </para>

    <para>The <emphasis>TIM</emphasis> data is as follows:
    </para>
    <variablelist>
	<varlistentry>
	<term><emphasis>mon</emphasis></term>
	<listitem>
	    <para>time at which this <command>cmon</command> process was
	    created.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>prob</emphasis></term>
	<listitem>
	    <para>time at which the server was last probed.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>succ</emphasis></term>
	<listitem>
	    <para>time at which the server last responded to a probe.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>up</emphasis></term>
	<listitem>
	    <para>time at which the server process was started.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>bind</emphasis></term>
	<listitem>
	    <para>number of times contact was reestablished after a
	    failed probe. A probe may fail due to server or network
	    failures.
	    </para>
	</listitem>
	</varlistentry>
    </variablelist>

    <para>The <emphasis>CPU</emphasis> data is as follows:
    </para>
    <variablelist>
	<varlistentry>
	<term><emphasis>sys</emphasis></term>
	<listitem>
	    <para>Relative or absolute number of seconds of system CPU
	    time used on the server.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>user</emphasis></term>
	<listitem>
	    <para>Relative or absolute number of seconds of user CPU
	    time (regular or niced) used on the server.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>util</emphasis></term>
	<listitem>
	    <para>Relative or absolute number of system and user seconds
	    divided by corresponding time of accumulation.
	    </para>
	</listitem>
	</varlistentry>
    </variablelist>

    <para>The <emphasis>RPC</emphasis> data is as follows:
    </para>
    <variablelist>
	<varlistentry>
	<term><emphasis>conn</emphasis></term>
	<listitem>
	    <para>Number of RPC connections.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>wkst</emphasis></term>
	<listitem>
	    <para>Number of workstations connected to server.  Note that
	    each instance of <command>cmon</command> shows up as a
	    workstation.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>call</emphasis></term>
	<listitem>
	    <para>Relative or absolute number of RPC calls received.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>pki</emphasis></term>
	<listitem>
	    <para>Relative or absolute number of RPC packets received.
	    Includes duplicates and other bogus packets. Also includes
	    bulk transfer packets.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>pko</emphasis></term>
	<listitem>
	    <para>Relative or absolute number of packets sent. Includes
	    retransmissions. Also includes bulk transfer packets.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>byi</emphasis></term>
	<listitem>
	    <para>Bytes corresponding to <emphasis>pki</emphasis>.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>byo</emphasis></term>
	<listitem>
	    <para>bytes corresponding to <emphasis>pko</emphasis>.
	    </para>
	</listitem>
	</varlistentry>
    </variablelist>

    <para>The <emphasis>DSK</emphasis> data is as follows:
    </para>
    <variablelist>
	<varlistentry>
	<term><emphasis>max1</emphasis></term>
	<listitem>
	    <para>Identity and percent usage of most full disk partition
	    on server.  The identity is the name of mount point. Names
	    longer than 5 characters are truncated to the first 3
	    characters, a $ character, and the last character.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><emphasis>max2</emphasis></term>
	<listitem>
	    <para>Identity and percent usage of second most full disk.
	    </para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><emphasis>max3</emphasis></term>
	<listitem>
	    <para>Identity and percent usage of third most full disk.
	    </para>
	</listitem>
	</varlistentry>
    </variablelist>
</refsect1>

<refsect1>
    <title>DIAGNOSTICS</title>
    <para>If a server is down or unreachable, statisitics for it are
    reported as "???".
    </para>
    <para>Relative data is undefined until two or more probes have been
    made.  Such data is reported as "***" between the very first and
    second probes.
    </para>
</refsect1>

<refsect1>
    <title>BUGS</title>
    <itemizedlist>
    <listitem><para>Relative computations are just based on the
    difference between the two most recent probes.  A smarter approach
    (especially for CPU utilization) would be to use some kind of
    weighted history.</para>
    </listitem>
    <!-- <listitem><para>Camelot state and chunk usage on servers should
    also be reported. Unfortunately a bug in the Camelot node server
    causes crashes when cmon tries to probe it.</para>
    </listitem> -->
    <listitem><para>The display is optimized for maximum packing of
    information into a small screen area. It may be cryptic for a
    novice.</para>
    </listitem>
    <listitem><para>No disk information is available about the root
    partition on a server.</para>
    </listitem>
    <listitem><para>Will core dump if run in a window with fewer than 25
    lines.</para>
    </listitem>
    <listitem><para>No way to force a redisplay (eg ^L).</para>
    </listitem>
    </itemizedlist>
</refsect1>

<refsect1>
    <title>SEE ALSO</title>
    <para>
    <citerefentry>
	<refentrytitle>codacon</refentrytitle>
	<manvolnum>1</manvolnum>
    </citerefentry>,
    <citerefentry>
	<refentrytitle>vutil</refentrytitle>
	<manvolnum>8</manvolnum>
    </citerefentry>,
    <citerefentry>
	<refentrytitle>curses</refentrytitle>
	<manvolnum>3</manvolnum>
    </citerefentry>
    </para>
</refsect1>

<refsect1>
    <title>AUTHORS</title>
    <itemizedlist>
    <listitem><para>M. Satyanarayanan, 1990, Created</para>
    </listitem>
    <listitem><para>Jan Harkes, 2004, converted to DocBook 4.1</para>
    </listitem>
    </itemizedlist>
</refsect1>
</refentry>
