pmping is a multiping script

Contents

Introduction

This script is intended to provide a way to ping multiple hosts, and check for their availability and responsiveness. Besides the regular "it's alive" check, we can see the amount of lost packets and average response in a given time.

The results can be displayed on the console where you called it, or can be sent to a logfile with output redirection (sorry, no syslog for now). When the output is set to the screen, it shows some verbose warning messages and even some beeps through the internal speaker (thus not needing to have a sound card, which is suitable for servers).

It has been written on order to help me in one of my tasks of monitoring routers, links and servers. So the average parameters, message and sound formats were done to suit my needs. But, since it's a script, and it's GPL, you can always help me improve it, adding new switches, parameters, messages, etc.

This is it's official site, and the complete project, along with the files, can be found at:

SourceForge.net Logo

http://sourceforge.net/projects/pmping

But, don't go now! Continue reading and know a little more about this great piece of software! :)

(Top)

Main Features

(Top)

News

-Dec/16/2006- -x.xx- - IMPORTANT: I have been informed that the beep2 site has become offline. Since this script still uses it, I've put a copy of the program here. If you are using SUSE, you may find an RPM package here. BTW, I know this is script needs some more polishing and adding some features. I'm planning a major rewriting, I just need to find the correct amount of inspiration to work on it.
-Apr/27/2005- -0.06- - Corrected dynamic config reload (wasn't really working).
- Try to catch SMTP connection errors when sending notification e-mails.
- Changed the way we check network errors (regex was not working).
-Mar/14/2005- -0.05- - Added command line option to select another config file.
- Switched from Getopt::Std to Getopt::Long (supports long options names).
- Added help message.
- Added 'verbose' mode. Show most of the 'infos'.
- Show 'warnings' on debug mode only. Show all 'infos' too.
- Documentation update.
- Other minor code cosmetic changes.
-Mar/08/2005- -0.04- Minor bug fix with unknown packets detection.
-Mar/04/2005- -0.03- New release to correct Perl taint checks on some systems.

(Top)

Installation

You need:

Either beep2 and fping must be SETUID ROOT so that everything can work. Also,pmping itself can be setuid. If you think this can break the security on your system, you can use SU or SUDO. It's just a matter of choice.

Copy the script somewhere in your PATH and give the appropriate permissions.

(Top)

Configuration

Before running for the first time, check the following $config var on the code.

By default, each user has it's own configuration stored in $HOME/.pmping. You can change it to any other location, by editing the code, or you can specify it using -c or --config when calling the script. Also, if you want to use a system-wide config, change this var to the appropriate location (like /etc/pmping.conf, for example).

There are also some global options already set inside the script. If none of those options are given in the user configuration file, it's assumed the default ones. You can change it as you like, but BE CAREFUL! If you break any options, you could break the hole script! Check for a section in the code that starts with "Loading options and defaults".

There is a hierarchy for loading the configuration options: 

  (user specific host config) -> (user global config) -> (script global config)

It means that any option can be set with specific values for each host. If it's not found, it's assumed the global one that is set in a global section of the user config. If the option is not found in the host config, neither in the global user config, it's assumed the default value stored inside the script.

The first time the script is run it tries to find the config file. If not found, a new one is created using the host's default route. After the config file is loaded, it checks if there is any global parameter that overrides the script's defaults.

(Top)

Options

For a better explanation of the configuration options, here is a configuration file sample: 

  [Global]
  # Location of the fping binary
  fpingbin = /usr/bin/fping
  # How many packets to send
  packets = 10
  # Max accepted loss of packets
  maxloss = 20
  # Max accepted average response time
  maxavgtime = 250
  # Time in seconds between each ping sequence
  wait = 10
  # To beep or not to beep?
  beep = yes
  # Location of the beep2 binary
  beepbin = /usr/bin/beep2
  # Beep when loss > maxloss
  beeploss = "C6 600|- 100|D5 500|- 100|C6 500|- 200"
  # Beep when time > maxavgtime
  beeptime = "C6 200|- 100|C6 200|- 100|C6 200|- 200"
  # Beep when loss = 100%
  beepdown = "F6 600|- 100|F5 200|- 100|F4 200|- 200"
  # Beep when loss = 0% and after loss = 100%
  beepup = "F4 400|- 100|F5 200|- 100|F6 400|- 200"
  # Run a command when a host is down
  execdown = "/usr/bin/dosomething"
  # Send a message when host is DOWN or UP
  mailto = this.email@doesnot.exist.com
  # Server to send e-mail from
  mailsrv = localhost
  
  [Host 10.0.0.254]
  # The descriptive name of this host
  name = Default Gateway

Note that the config file looks just a regular INI. But never forget that all the options are CASE SENSITIVE, which means they sould be written just like the example shown above.

The [Global] section is optional, such as all of the options inside it. The only thing that is mandatory is a section called [Host i.p.a.d], where "i.p.a.d" is the IP address of the target host. The "name" option is optional, and if it's not found it's set to a generic name defined somewhere in the code.

All other options set in the [Global] section, except "fpingbin", "beepbin" and "packets", can be set individually for each host.

The only problem you may have is about writing the how the beep sounds. This script use the SCORE INPUT MODE, where the first field is the score, constructed with a letter and number (and #), and the second field is length in milliseconds. This score uses a standard music notation. There is a | (pipe char) between each field, so you can use how many scores you want, the way you feel like to.

The beeps are sound when:

when the percentage of lost packes is greater or equal the value specified.
when the average round-trip time is greater or equal the value specified.
when the host is down (100% loss).
when the host becomes up (0% loss) after a time down.

A note about "execdown": whatever you want to run must be in /bin:/usr/bin:/usr/local/bin, or you will get errors about the Perl's taint checks.

About the e-mail notifications, they are sent only when a host comes down or up. You can specify more than one recipient by just separating then with one single white space.

(Top)

Running

  Usage: pmping [option]
  
  Running without options makes it assume defaults.
  
  Available options:
    -c, --config ...   use another config file (default: $HOME/.pmping)
    -v, --verbose      run in verbose mode (default: off)
    -d, --debug        show debug information (assume -v, default: off)
    -h, --help         show this help and exit

(Top)

Screenshots


Fig. 1
Fig. 2

Fig. 1 - Some packet loss and one link down.
Fig. 2 - Debug mode.

(Top)

Bugs

For now, there is no known bug.

(Top)

TODO

(Top)

Thanks

Thank you everyone who use this script. Please drop me a line if you find any bugs or have any suggestions. Also, if you find this script useful, share with your friends.

We also accept donations, of course. :)

(Top)

Contact

Mauricio Teixeira
mteixeira at webset dot net
http://mteixeira.webset.net

(Top)

My Personal Site - Mauricio Teixeira - Updated in Sat Dec 16 10:36:35 2006 - Created using - You are visitor