<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@
  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Stephen</firstname>">
  <!ENTITY dhsurname   "<surname>Moraco</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>August  11, 2001</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  <!ENTITY dhemail     "<email>stephen@debian.org</email>">
  <!ENTITY dhusername  "Stephen M Moraco">
  <!ENTITY dhucpackage "<refentrytitle>TKPING</refentrytitle>">
  <!ENTITY dhpackage   "tkping">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2001</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>network monitoring tool</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>

      <arg><option>options</option></arg>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para><command>&dhpackage;</command> is intended primarily for 
	  system administrators and network administrators so that they can see
	  when crucial hosts and other network nodes go down.</para>

    <para><command>&dhpackage;</command> is typically left running for
	  days.  The user can see all nodes are green meaning that all
	  are OK.  After being away from the display for a period of time,
	  the user returns and looks at the display.  If any of the nodes are
	  not green, then the user knows that those have either "gone missing" for 
	  a short period of time or have rebooted (The color tells the user
	  which).  Either way, the user knows to log onto these machines to see 
	  what happened or to look into the status of the network/subnet to 
	  which the failing machines are connected.  Overall, this saves the user
	  time, as there is no reason to check into the health of the machines
	  which remain green.</para>

  </refsect1>
  <refsect1>
    <title>DETAILS OF OPERATION</title>

    <para><command>&dhpackage;</command> is a tool that runs under 
	  the X Window System to display the status of internet nodes.</para>

    <para><command>&dhpackage;</command> displays a grid of node buttons,
	  one for each node being monitored.  The name of the node represented by
	  the button is displayed on the face of the button.</para>

	<para>This grid can be laid-out automatically by 
	  <command>&dhpackage;</command> or the layout can be controlled by the 
	  user from the command-line or by settings in a control file 
	  (See: -rows, -columns).</para>
	  
	<para><command>&dhpackage;</command> also supports additional layout
	  control interspersed within the nodes file. (See: &lt;blank&gt;,
	  &lt;message&gt;, and &lt;nextcolumn&gt;.)</para>
	  
    <para>At specified intervals, <command>&dhpackage;</command> will 
	  generate a number of ICMP echo packets (similar to the 
	  <application>ping(8)</application> program) and send them 
	  to each of the specified nodes.  <command>&dhpackage;</command> 
	  displays the results of its pings by coloring the button associated
	  with the node based on the status of the returned pings.</para>

	<para>The grid of buttons supports a couple styles of interaction.
	  The user may select a menu operation affecting all of the nodes, or
	  the user may click on one or more buttons and then select a menu
	  operation which affects only those selected.  Finally, a right-click
	  operation on a button is supported.  This pops up a list of operations
	  one can do against that specific button.</para>
	
	<para>The button color represents current status of the node.  The
	  user can recheck a node, mark it a down, or get info regarding 
	  details of the history of ping attempts against this node.</para>

	<para>To recheck a node, simply click on the button 
	  corresponding to the desired node.  The color will change,
	  indicating that the node has been selected.  Picking 
	  ``Recheck'' from the menu will then check the node again.
	  During the time that a node is being rechecked, the cursor will
	  change to an hourglass.  All button and/or keypress events sent to
	  <command>&dhpackage;</command> will be ignored until the 
	  pinging is complete and the cursor is restored.</para>

	<para>If a node is selected and ``Down'' is picked, then the node is 
	  marked as ignored and the color of the button is changed to 
	  represent this status.  When <command>&dhpackage;</command> next 
	  traverses the grid, this node will not be checked.  This is useful 
	  when the user knows a node to be down and does not want to waste 
	  any time checking it.</para>

	<para>If a node is selected and ``Info'' is picked, a pop-up dialog will 
	  display statistics about that node.  Currently, 
	  <command>&dhpackage;</command> will print out the total number of 
	  times the node returned none, some, or all of the packets sent out,
	  the total number of packets sent to and received from the node,
	  and the average packet round-trip time sampled over the last
	  5, 50, 100, and 200 grid traversals.</para>
	  
	<para>Multiple nodes may be rechecked, or marked as down.  If ``Info'' is 
	  then picked, only the first node will have its information 
	  displayed.</para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <para>The following are the command-line arguments understood 
	  by <command>&dhpackage;</command>:</para>

    <variablelist>
      <varlistentry>
        <term><option>-rows {nbr}</option>
        </term>
        <listitem>
          <para>This option is used to specify the number of rows in 
		  the host grid.  Entries in the node file will then be loaded 
		  top to bottom.  (Resource name: rows).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-columns {nbr}</option>
        </term>
        <listitem>
          <para>This option is used to specify the number of columns 
		  in the host grid.  Entries in the node file will then be 
		  loaded left to right.  (Resource name: columns)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-wintitle {titleStr}</option>
        </term>
        <listitem>
          <para>Specify the text to put on the application titlebar
		  (as opposed to the window manager's titlebar).
		  (the default is ``&dhpackage;'' followed by a version string).
		  (Resource name: wintitle)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-nodes {fspec}</option>
        </term>
        <listitem>
          <para>Specify a name of a file which contains the hosts to put on 
		    the grid.  If this option is given, the default file ~/.tkpingrc 
			will not be loaded. (No associated resource)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-xdefs {fspec}</option>
        </term>
        <listitem>
          <para>Name of the file which contains option settings.  Use in place
		    of discrete command-line options, an X resources file, or the 
			system-wide defaults file /etc/tkping/tkping.conf. 
			(No associated resource)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-logfile {fspec}</option>
        </term>
        <listitem>
          <para>Specifies the log file to which diagnostic output will
		    be sent.  ()</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-packets {nbr}</option>
        </term>
        <listitem>
          <para>Number of packets to send to each node (default 5).
		    (Resource name: numberPackets)</para>
		</listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-sleep {secs}</option>
        </term>
        <listitem>
          <para>Interval between traversals of the grid (default 
		    120 seconds).  (Resource name: sleepDelay)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-timeout {secs}</option>
        </term>
        <listitem>
          <para>How long to wait for each packet before assuming the 
		    node is not responding (default 0.5 seconds).  (Resource 
			name: timeout)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-ignore</option>
        </term>
        <listitem>
          <para>In certain circumstances, it may be preferable that
		  <command>&dhpackage;</command> not immediately attempt to 
		  ping all the nodes on the grid.  When this option is set,
		  all nodes will act as though they had been selected and the
		  ``Down'' menu item picked.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-debug</option>
        </term>
        <listitem>
          <para>Turn on debugging.  Used primarily by developer of 
		  <command>&dhpackage;</command>.
		  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-verbose</option>
        </term>
        <listitem>
          <para>Show more detailed info regarding application state.
		  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-h</option>
          <option>--help</option>
        </term>
        <listitem>
          <para>Show summary of options.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>COLORS</title>
    <para> <command>&dhpackage;</command> uses colors to indicate the status 
	of each node.  The standard color codes along with the 
	X-default codes are as follows:</para>

    <variablelist>
      <varlistentry>
        <term><option>#00C000 allPacketsBackColor</option></term>
        <listitem>
		<para>Host returned all packets sent.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>#DAFF00 somePacketsBackColor</option></term>
        <listitem>
		<para>Host returned some of the packets sent.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>#C00000 noPacketsBackColor</option></term>
        <listitem>
		<para>Host returned none of the packets sent.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>Orange ignoredColor</option></term>
        <listitem>
		<para>The node is to be ignored.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>LightGrey changedColor</option></term>
        <listitem>
		<para>The node changed its status from either returning 
		  no packets or from an error to returning all packets.  The cell 
		  will remain in this color or pattern until reset by manually 
		  checking the node (see above).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>Black errorColor</option></term>
        <listitem>
		<para>An internal error has occurred.  This should only occur if 
		  the host name cannot be found in either the name server or system 
		  host table.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term><option>~/.tkpingrc</option>
        </term>
        <listitem>
          <para>File containing nodes to check as well as labels to
		  display amongst the node buttons.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>/etc/tkping/tkping.conf</option>
        </term>
        <listitem>
          <para>File containing settings default values for timeouts,
		  ping counts, etc.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>FILE FORMATS: NODES</title>
    <para>To Be Added.  See /usr/share/doc/tkping/examples/tkping.hosts 
	  for now.</para>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>fping(8).</para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>This manual page was written by &dhusername; &dhemail; for
      the &debian; system (but may be used by others).  Permission is
      granted to copy, distribute and/or modify this document under
      the terms of the <acronym>GNU</acronym> Free Documentation
      License, Version 1.1 or any later version published by the Free
      Software Foundation; with no Invariant Sections, no Front-Cover
      Texts and no Back-Cover Texts.</para>
    <para>Excerpts are taken from the xping(1) manpage written by Jeff 
	  Okamoto of Hewlett-Packard</para>
    <para>NOTE1: (xping) From a program originally written for X10 by 
	  Mike Harris and converted to the X11 HP Widget Set and enhanced by 
	  Jeff Okamoto and Ken Stone.  Converted to run under HP-UX 8.0 and 
	  use the Motif 1.1 Widget Set by Jeff Okamoto.</para>
	<para>NOTE2: &dhpackage; is a complete rewrite of xping in perl/TK.  The
	  author had no access to original source code, only the manpage
	  accompanying the xping program.  The input file format is not the
	  same and this manpage has been written to speak to the new input
	  file format and the specific operation of &dhpackage;.</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->