[pingcheck] / Readme

     Table of Contents
=======================================
1. Introduction
2. Building and Installing
3. Configuration File
4. Command line
5. Tools
6. References


1.   Introduction
=======================================
This application provides means to check the availability of remote hosts
through pings to them.


1.1. Rationale
---------------------------------------
The application uses ICMP echo requests messages, or TCP SYN segments, to
verify whether a given host is available (up) or not (down).

The host's address can be an IP or a DNS.


1.2. How to use
---------------------------------------
There are many ways to invoke the application, the simplest is just type:
  ./pingcheck
which uses the configuration values from the configuration file (described in
the Configuration File section).

Note: like the ordinary ping, pingcheck binary requires root privileges to
access control packets. You can run it from sudo:
  sudo ./pingcheck
or setuid:
  sudo chown root:root pingcheck
  sudo chmod u+s pingcheck
  ./pingcheck
the last method is the common way to provide temporary root privileges for
an executable.


1.3. Resources
---------------------------------------
Further information about the problem domain can be found in the References
section.


1.4. Legal Issues
---------------------------------------
Most parts are licensed under the GPLv2 + linking exception.

Parts of the ICMP code are based on the ping example found in the boost Asio
documentation ((c) Christopher Kohlhoff) but are now heavily modified. The DNS
resolver mechanism is based on boost::net::dns and is therefore licensed under
the boost license. Notes about this are included in the beginning of the source
code.


2.   Building and Installing
=======================================
After downloading the source code and necessary libraries (in particular boost)
and tools (cmake) you should be able to do:

me@my_linux_host ~/some/dir/pingcheck> mkdir build
me@my_linux_host ~/some/dir/pingcheck> cd build
me@my_linux_host ~/some/dir/pingcheck/build> ccmake ../
                                               OR
me@my_linux_host ~/some/dir/pingcheck/build> cmake ../
me@my_linux_host ~/some/dir/pingcheck/build> make help      # show more options
me@my_linux_host ~/some/dir/pingcheck/build> make
me@my_linux_host ~/some/dir/pingcheck/build> make check
me@my_linux_host ~/some/dir/pingcheck/build> make install

The default install location is /usr/local, the easiest way to change this is
through ccmake


3.   Configuration file
=======================================
In this section are described the configuration items, along with they possible
values and meanings. This section is organized in each major configuration
block. An example file is contained in the conf subdirectory.


3.1. General
---------------------------------------
This configurations are shared among and affect all the hosts.
- default-source-network-interface: the local network interface from where the
  ping packages will originate. This option is used for those hosts that set
  source-network-interface=default
- nameserver: the server which the hosts names will be resolved. It is the
  lookup server which the application will query first. If left blank or omited,
  it will use the /etc/resolv.conf.
  You can use the nslookup <host> to figure out the nameserver.
- hosts-down-limit: an absolute number, which ranges from 0 to the number of
  hosts available. This value represents the minimum number of hosts that have
  to fail (i.e. do not reply to the ping) in order to alert any external system.
- ping-fail-limit: percentage of pings to a host that can fail. If the
  percentage of failed pings to a host exceed this number, then the host is
  considered down.
- status-notifier-cmd: the command line that is called when a host is down, or
  up. Accepted variables are:
    ${status} - down or up
- link-up-interval: how long (in minutes) the pings must be returned with
  success in order to consider the link up, or stable.
- link-down-interval: how long (in minutes) the pings must fail, in order to the
  application consider the link down.
- ratio-random-hosts: expects a value in [0,1]; if <1 will only use the given
  ratio of hosts, selecting them at random
- ping-reply-timeout: Amount of time to wait for an EchoReply to an Echo Request
  before sending the next ping
- max-address-resolution-attempts: For hosts given as DNS names, will first do
  a DNS lookup to get corresponding IPs. This number specifies how often that is
  attempted before declaring the host offline
- resolved-ip-ttl-threshold: When the TTL for an IP falls below this threshold,
  a new DNS lookup will be scheduled


3.2. Host
---------------------------------------
(All these settings must always be present!)
- name: the DNS or IP of the host to ping. Take in consideration that, if a
  DNS is given, the application pings all IPs in the look up table, however, if
  IP is provide, it is the only which will be pinged.
- port: when using a port based protocol, like TCP, this field specifies in
  which port to ping the host.
- source-network-interface: the local network interface from where the ping
  packages for a given host will originate. To use the global network
  interface, specify value as "default"
- interval: the host will be pinged every "interval" seconds. Can be specified
  as fixed number (e.g. "30") or as a range (e.g. "30..60"), from which the
  interval will be picked at random (e.g. 42) at startup
- ping-protocol: indicates which protocol to use to ping the destination host,
  the currently supported protocols are TCP (tcp, tcp_ipv6) and ICMP (icmp,
  icmpv6).


4.   Command line
=======================================
The command line accepts the general configuration file options plus the
following:
- config-file: command line to specify a file where the hosts and other
  configuration information are provided.
- daemon: run the application as a daemon.
- log-level: apply a filter of which log messages will be printed. The available
  options are the default Unix levels (e.g. debug, info, etc.).
- log-output: select the place where the log messages will be printed. The
  available options are CONSOLE, TERMINAL and SYSLOG.


5.   Tools
=======================================
Along with pingcheck, the binary feed_packet_data will be built but not copied
like the pingcheck binary to the install location (you will find it in your
build_directory/src/feed_packet_data). It allows direct access to the ICMP/TCP
parser factories that interpret incoming network data. It can be fed data in
pcap format or as raw binary data, either from file or stdin.


6.   References
=======================================
[1]  http://tools.ietf.org/html/rfc792
[2]  http://en.wikipedia.org/wiki/Ping
[3]  http://en.wikipedia.org/wiki/Internet_Control_Message_Protocol
[4]  http://en.wikipedia.org/wiki/ICMPv6
[5]  http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html
[6]  http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html
[7]  http://www.networkuptime.com/nmap/page4-5.shtml
Commit	Line	Data
	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