README.md
author Mahlon E. Smith <mahlon@martini.nu>
Wed, 24 Aug 2016 15:28:08 -0700
changeset 0 d99e1dffbc72
child 4 1801334b8dc4
permissions -rw-r--r--
Initial commit.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     1
# Arborist-fping
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     2
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     3
home
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     4
: http://bitbucket.org/mahlon/Arborist-fping
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     5
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     6
code
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     7
: http://code.martini.nu/Arborist-fping
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     8
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
     9
fping
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    10
: http://fping.org/
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    11
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    12
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    13
## Description
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    14
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    15
Arborist is a monitoring toolkit that follows the UNIX philosophy
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    16
of small parts and loose coupling for stability, reliability, and
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    17
customizability.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    18
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    19
This adds fping sweeping support to Arborist monitoring, which is an
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    20
efficient means to check the ICMP reachability of many, many hosts
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    21
simultaneously.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    22
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    23
It requires the fping binary to be installed in your path.  Use your
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    24
package manager of choice.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    25
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    26
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    27
## Prerequisites
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    28
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    29
* Ruby 2.2 or better
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    30
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    31
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    32
## Installation
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    33
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    34
    $ gem install arborist-fping
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    35
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    36
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    37
## Usage
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    38
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    39
In this example, we're using ICMP reachability as the method to
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    40
determine if a host node is available/present on network.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    41
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    42
	Arborist::Host( 'example' ) do
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    43
		description "Example host"
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    44
		address     '10.6.0.169'
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    45
	end
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    46
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    47
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    48
From a monitor file, require this library, and exec() to fping.  We'll
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    49
record RTT per node in this example with the -e flag, and lower the
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    50
timeout-per-host:
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    51
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    52
	require 'arborist/monitor/fping'
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    53
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    54
	Arborist::Monitor 'ping check' do
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    55
		every 10.seconds
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    56
		match type: 'host'
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    57
		include_down true
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    58
		use :addresses
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    59
		exec 'fping', '-e', '-t', '150'
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    60
		exec_callbacks( Arborist::Monitor::FPing )
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    61
	end
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    62
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    63
That's it.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    64
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    65
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    66
## License
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    67
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    68
Copyright (c) 2016, Michael Granger and Mahlon E. Smith
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    69
All rights reserved.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    70
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    71
Redistribution and use in source and binary forms, with or without
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    72
modification, are permitted provided that the following conditions are met:
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    73
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    74
* Redistributions of source code must retain the above copyright notice,
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    75
  this list of conditions and the following disclaimer.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    76
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    77
* Redistributions in binary form must reproduce the above copyright notice,
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    78
  this list of conditions and the following disclaimer in the documentation
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    79
  and/or other materials provided with the distribution.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    80
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    81
* Neither the name of the author/s, nor the names of the project's
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    82
  contributors may be used to endorse or promote products derived from this
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    83
  software without specific prior written permission.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    84
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    85
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    86
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    87
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    88
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    89
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    90
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    91
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    92
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    93
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    94
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    95
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    96