README.md
author Mahlon E. Smith <mahlon@martini.nu>
Wed, 13 Jun 2018 09:28:18 -0700
changeset 8 4f397a05dcdf
parent 4 1801334b8dc4
child 10 e738ef5f8742
permissions -rw-r--r--
Fix versioning and dependencies for release.
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
4
1801334b8dc4 Fix documentation, bump copyright.
Mahlon E. Smith <mahlon@laika.com>
parents: 0
diff changeset
    19
This adds fping sweeping support to Arborist monitoring, providing an
1801334b8dc4 Fix documentation, bump copyright.
Mahlon E. Smith <mahlon@laika.com>
parents: 0
diff changeset
    20
efficient method to check the ICMP reachability of many, many hosts
0
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
4
1801334b8dc4 Fix documentation, bump copyright.
Mahlon E. Smith <mahlon@laika.com>
parents: 0
diff changeset
    29
* Ruby 2.4 or better
0
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
		exec 'fping', '-e', '-t', '150'
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    58
		exec_callbacks( Arborist::Monitor::FPing )
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    59
	end
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    60
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    61
That's it.
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
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    64
## License
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    65
4
1801334b8dc4 Fix documentation, bump copyright.
Mahlon E. Smith <mahlon@laika.com>
parents: 0
diff changeset
    66
Copyright (c) 2016-2018, Michael Granger and Mahlon E. Smith
0
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    67
All rights reserved.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    68
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    69
Redistribution and use in source and binary forms, with or without
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    70
modification, are permitted provided that the following conditions are met:
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    71
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    72
* Redistributions of source code must retain the above copyright notice,
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    73
  this list of conditions and the following disclaimer.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    74
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    75
* Redistributions in binary form must reproduce the above copyright notice,
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    76
  this list of conditions and the following disclaimer in the documentation
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    77
  and/or other materials provided with the distribution.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    78
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    79
* 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
    80
  contributors may be used to endorse or promote products derived from this
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    81
  software without specific prior written permission.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    82
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    83
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    84
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    85
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    86
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    87
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    88
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    89
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    90
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    91
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
    92
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    93
d99e1dffbc72 Initial commit.
Mahlon E. Smith <mahlon@martini.nu>
parents:
diff changeset
    94