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

   1      Table of Contents
   2 =======================================
   3 1. Introduction
   4 2. Building and Installing
   5 3. Configuration File
   6 4. Command line
   7 5. Tools
   8 6. References
   9
  10
  11
  12 1.   Introduction
  13 =======================================
  14 This application provides means to check the availability of remote hosts
  15 through pings to them.
  16
  17
  18 1.1. Rationale
  19 ---------------------------------------
  20 The application uses ICMP echo requests messages, or TCP SYN segments, to
  21 verify whether a given host is available (up) or not (down).
  22
  23 The host's address can be an IP or a DNS.
  24
  25
  26 1.2. How to use
  27 ---------------------------------------
  28 There are many ways to invoke the application, the simplest is just type:
  29   ./pingcheck
  30 which uses the configuration values from the configuration file (described in
  31 the Configuration File section).
  32
  33 Note: like the ordinary ping, pingcheck binary requires root privileges to
  34 access control packets. You can run it from sudo:
  35   sudo ./pingcheck
  36 or setuid:
  37   sudo chown root:root pingcheck
  38   sudo chmod u+s pingcheck
  39   ./pingcheck
  40 the last method is the common way to provide temporary root privileges for
  41 an executable.
  42
  43
  44 1.3. Resources
  45 ---------------------------------------
  46 Further information about the problem domain can be found in the References
  47 section.
  48
  49
  50 1.4. Legal Issues
  51 ---------------------------------------
  52 Most parts are licensed under the GPLv2 + linking exception.
  53
  54 Parts of the ICMP code are based on the ping example found in the boost Asio
  55 documentation ((c) Christopher Kohlhoff) but are now heavily modified. The DNS
  56 resolver mechanism is based on boost::net::dns and is therefore licensed under
  57 the boost license. Notes about this are included in the beginning of the source
  58 code.
  59
  60
  61 2.   Building and Installing
  62 =======================================
  63 After downloading the source code and necessary libraries (in particular boost)
  64 and tools (cmake) you should be able to do:
  65
  66 me@my_linux_host ~/some/dir/pingcheck> mkdir build
  67 me@my_linux_host ~/some/dir/pingcheck> cd build
  68 me@my_linux_host ~/some/dir/pingcheck/build> ccmake ../
  69                                                OR
  70 me@my_linux_host ~/some/dir/pingcheck/build> cmake ../
  71 me@my_linux_host ~/some/dir/pingcheck/build> make help      # show more options
  72 me@my_linux_host ~/some/dir/pingcheck/build> make
  73 me@my_linux_host ~/some/dir/pingcheck/build> make check
  74 me@my_linux_host ~/some/dir/pingcheck/build> make install
  75
  76 The default install location is /usr/local, the easiest way to change this is
  77 through ccmake
  78
  79
  80 3.   Configuration file
  81 =======================================
  82 In this section are described the configuration items, along with they possible
  83 values and meanings. This section is organized in each major configuration
  84 block. An example file is contained in the conf subdirectory.
  85
  86
  87 3.1. General
  88 ---------------------------------------
  89 This configurations are shared among and affect all the hosts.
  90 - default-source-network-interface: the local network interface from where the
  91   ping packages will originate. This option is used for those hosts that set
  92   source-network-interface=default
  93 - nameserver: the server which the hosts names will be resolved. It is the
  94   lookup server which the application will query first. If left blank or omited,
  95   it will use the /etc/resolv.conf.
  96   You can use the nslookup <host> to figure out the nameserver.
  97 - hosts-down-limit: an absolute number, which ranges from 0 to the number of
  98   hosts available. This value represents the minimum number of hosts that have
  99   to fail (i.e. do not reply to the ping) in order to alert any external system.
 100 - ping-fail-limit: percentage of pings to a host that can fail. If the
 101   percentage of failed pings to a host exceed this number, then the host is
 102   considered down.
 103 - status-notifier-cmd: the command line that is called when a host is down, or
 104   up. Accepted variables are:
 105     ${status} - down or up
 106 - link-up-interval: how long (in minutes) the pings must be returned with
 107   success in order to consider the link up, or stable.
 108 - link-down-interval: how long (in minutes) the pings must fail, in order to the
 109   application consider the link down.
 110 - ratio-random-hosts: expects a value in [0,1]; if <1 will only use the given
 111   ratio of hosts, selecting them at random
 112 - ping-reply-timeout: Amount of time to wait for an EchoReply to an Echo Request
 113   before sending the next ping
 114 - max-address-resolution-attempts: For hosts given as DNS names, will first do
 115   a DNS lookup to get corresponding IPs. This number specifies how often that is
 116   attempted before declaring the host offline
 117 - resolved-ip-ttl-threshold: When the TTL for an IP falls below this threshold,
 118   a new DNS lookup will be scheduled
 119
 120
 121 3.2. Host
 122 ---------------------------------------
 123 (All these settings must always be present!)
 124 - name: the DNS or IP of the host to ping. Take in consideration that, if a
 125   DNS is given, the application pings all IPs in the look up table, however, if
 126   IP is provide, it is the only which will be pinged.
 127 - port: when using a port based protocol, like TCP, this field specifies in
 128   which port to ping the host.
 129 - source-network-interface: the local network interface from where the ping
 130   packages for a given host will originate. To use the global network
 131   interface, specify value as "default"
 132 - interval: the host will be pinged every "interval" seconds. Can be specified
 133   as fixed number (e.g. "30") or as a range (e.g. "30..60"), from which the
 134   interval will be picked at random (e.g. 42) at startup
 135 - ping-protocol: indicates which protocol to use to ping the destination host,
 136   the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp,
 137   icmpv6).
 138
 139
 140 4.   Command line
 141 =======================================
 142 The command line accepts the general configuration file options plus the
 143 following:
 144 - config-file: command line to specify a file where the hosts and other
 145   configuration information are provided.
 146 - daemon: run the application as a daemon.
 147 - log-level: apply a filter of which log messages will be printed. The available
 148   options are the default Unix levels (e.g. debug, info, etc.).
 149 - log-output: select the place where the log messages will be printed. The
 150   available options are CONSOLE, TERMINAL and SYSLOG.
 151
 152
 153 5.   Tools
 154 =======================================
 155 Along with pingcheck, the binary feed_packet_data will be built but not copied
 156 like the pingcheck binary to the install location (you will find it in your
 157 build_directory/src/feed_packet_data). It allows direct access to the ICMP/TCP
 158 parser factories that interpret incoming network data. It can be fed data in
 159 pcap format or as raw binary data, either from file or stdin.
 160
 161
 162 6.   References
 163 =======================================
 164 [1]  http://tools.ietf.org/html/rfc792
 165 [2]  http://en.wikipedia.org/wiki/Ping
 166 [3]  http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
 167 [4]  http://en.wikipedia.org/wiki/ICMPv6
 168 [5]  http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
 169 [6]  http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html
 170 [7]  http://www.networkuptime.com/nmap/page4-5.shtml