developer.intra2net.com Git - pingcheck/blob - Readme

   1      Table of Contents
   2 =======================================
   3 1. Introduction
   4 2. Configuration File
   5 3. Command line
   6 4. References
   7
   8
   9
  10 1.   Introduction
  11 =======================================
  12 This application provides means to check the availability of remote hosts
  13 through pings to them.
  14
  15
  16 1.1. Rationale
  17 ---------------------------------------
  18 The application uses ICMP echo requests messages, or TCP segments to verify
  19 whether a given host is available (up) or not (down).
  20
  21 The host's address can be an IP or a DNS.
  22
  23
  24 1.2. How to use
  25 ---------------------------------------
  26 There are many ways to invoke the application, the simplest is just type:
  27   ./pingcheck
  28 which uses the configuration values from the configuration file (described in
  29 the Configuration File section).
  30
  31
  32 1.3. Resources
  33 ---------------------------------------
  34 Further information about the problem domain can be found in the References
  35 section.
  36
  37
  38 1.4. Legal Issues
  39 ---------------------------------------
  40 Most parts are licensed under the GPLv2 + linking exception.
  41
  42 The ICMP code, bost::net::dns and the "boost pinger" are licensed under the
  43 boost license and include a note about this in the beginning of the source code.
  44
  45
  46 2.   Configuration file
  47 =======================================
  48 In this section are described the configuration items, along with they possible
  49 values and meanings. This section is organized in each major configuration
  50 block.
  51
  52
  53 2.1. General
  54 ---------------------------------------
  55 This configurations are shared among and affect all the hosts.
  56 - source-network-interface: the local network interface from where the ping
  57   packages with originate.
  58 - nameserver: the server which the hosts names will be resolved. It is the
  59   lookup server which the application will query first. If left blank or omited,
  60   it will use the /etc/resolv.conf.
  61   You can use the nslookup <host> to figure out the nameserver.
  62 - hosts-down-limit: an absolute number, which ranges from 0 to the number of
  63   hosts available. This value represents the minimum number of hosts that have
  64   to fail (i.e. do not reply to the ping) in order to alert any external system.
  65 - ping-fail-limit: percentage of pings to a host that can fail. If the
  66   percentage of failed pings to a host exceed this number, then the host is
  67   considered down.
  68 - status-notifier-cmd: the command line that is called when a host is down, or
  69   up. Accepted variables are:
  70     ${status} - down or up
  71 - link-up-interval: how long (in minutes) the pings must be returned with
  72   success in order to consider the link up, or stable.
  73 - link-down-interval: how long (in minutes) the pings must fail, in order to the
  74   application consider the link down.
  75
  76
  77 2.2. Host
  78 ---------------------------------------
  79 - name: the DNS or IP of the host to ping. Take in consideration that, if a
  80   DNS is given, the application pings all IPs in the look up table, however, if
  81   IP is provide, it is the only which will be pinged.
  82 - port: when using a port based protocol, like TCP, this field specifies in
  83   which port to ping the host.
  84 - interval: the host will be pinged every "interval" seconds.
  85 - ping-protocol: indicates which protocol to use to ping the destination host,
  86   the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp, icmpv6).
  87   This configuration can be used to perform a protocol fallback, in which N pings
  88   are performed with one protocol, and then after those N attempts, a second protocol
  89   is used. For example, with the given configuration:
  90     ping-protocol=ICMPv6,42,ICMP
  91   the program will ping a host 42 times using the ICMP over IPv6, and then it will
  92   use the ICMP over IPv4 after those 42 attempts.
  93
  94
  95
  96 3.   Command line
  97 =======================================
  98 The command line accepts the general configuration file options plus the
  99 following:
 100 - config-file: command line to specify a file where the hosts and other
 101   configuration information are provided.
 102 - daemon: run the application as a daemon.
 103 - log-level: apply a filter of which log messages will be printed. The available
 104   options are the default Unix levels (e.g. debug, info, etc.).
 105
 106
 107
 108 4.   References
 109 =======================================
 110 [1]  http://tools.ietf.org/html/rfc792
 111 [2]  http://en.wikipedia.org/wiki/Ping
 112 [3]  http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
 113 [4]  http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
 114 [5]  http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html
 115 [6]  http://www.networkuptime.com/nmap/page4-4.shtml