NAME

Net::Peep - Perl extension for Peep: The Network Auralizer.

DESCRIPTION

Peep is an open source free software network monitoring tool issued under the Gnu General Public License that presents information via audio output. Network diagnosis with Peep is made not only based on single network events, but the network as a whole "sounds normal."

Although Peep has found much use as a monitoring tool, the tool has been designed to allow customized clients to be created for virtually any purpose. It could be used, for example, to create a stock ticker or to parse input from a web cam with ImageMagick and create aural output based on the nature of the image.

Please refer to the section on creating a custom client below for more information.

SYNOPSIS

This document serves as an introduction to the Peep clients and the Peep client architecture.

REQUIRES


            
              
              File::Tail
Time::HiRes
Net::Ping::External
Filesys::DiskFree
Proc::ProcessTable

INTRODUCTION

Peep is built on a client-server model in which the clients generate "events" based on user-defined criteria (e.g., whether a packet denial has been logged or a broken link on a web site was found). One or several Peep servers are then notified of the events by clients, at which time an audio signal is generated.

The clients, which include such applications as logparser and sysmonitor and for which this document constitutes introductory documentation, are written in Perl, IMHO about the coolest language ever. The bulk of the client code is composed of a set of Perl modules comprising objects and base classes for use by Peep clients and their derivatives.

The server, peepd, is written in C.

Both the client and server are available for download free of charge from the Peep homepage located at


            
              
              http://peep.sourceforge.net

The Peep client modules and executables are also available on the CPAN (Comprehensive Perl Archive Network) for installation via the time-honored


            
              
              perl -MCPAN -e "install Net::Peep"

In fact, this is the preferred method of installation of the Peep clients.

Consult the core Peep documentation for more information on installation and usage of Peep.

The Peep client library is composed of the following core modules:


            
              
              Perl Modules
------------
Net::Peep            A non-functional module.  Simply holds 
                     POD documentation for Peep; in fact, 
                     it holds the documentation that you are
                     reading right now!
Net::Peep::Conf      The Peep configuration object.  An  
                     object representation of peep.conf.
Net::Peep::Parser    The Peep configuration file parser.  Reads  
                     peep.conf and populates Peep::Conf 
                     appropriately.
Net::Peep::BC        The Peep broadcast module.  Used to notify Peep  
                     servers that an event has been generated.
Net::Peep::Log       Provides utility methods for logging, debugging,
                     and benchmarking.
Net::Peep::Client    Base and utility class for Peep clients and 
                     client modules.
Net::Peep::Client::Logparser  Utility class for the logparser client.
Net::Peep::Client::Sysmonitor Utility class for the sysmonitor client.
Net::Peep::Client::Pinger     Utility class for the pinger client.
Net::Peep::Peck      Utility class for the peck client.
Net::Peep::Notifier  A class Peep uses to send out e-mail 
                     notifications.

There are a variety of helper classes other than those mentioned above that server a variety of useful functions. Consult the individual PODs for more information.


            
              
              Clients
-------
logparser            Generates events based on matching regular
                     expressions to tailed logs (e.g., 
                     /var/log/messages).
sysmonitor           Generates events based on system events (e.g.,
                     load average exceeding 2.0).
pinger               Generates events based on whether a host
                     is responsive.
peck                 Generates ad hoc Peep events.  Primarily for 
                     testing purposes.
keytest              Generates ad hoc Peep events.  Primarily for 
                     fun.

Please refer to the individual modules of the Peep distribution (e.g., Net::Peep::BC) or the Peep client executables (e.g., logparser) for further documentation.

CREATING A CUSTOM PEEP CLIENT

One of the most powerful features of Peep is the ability to create customized clients to use Peep for whatever you like. Although Peep is used widely as a systems and network monitor because it is well suited to the task, you could do anything from creating a stock monitoring client to creating a client that will take output from a web cam, parse it with ImageMagick (see http://www.imagemagick.org and http://www.imagemagick.org/www/perl.html) and generate real-time sound effects based on what you see.

With the whole of the CPAN at your disposal, the sky is the limit.

The Net::Peep::Client module and other helper classes make constructing a custom Peep client a breeze.

It is quite formulaic, and once you have done it once, you will already feel like it is old hat. In describing the process, we will create the first example mentioned above: A client to monitor stock prices. All told, the code is only 50 lines (only 33 statements!) and took me about a half hour to write.

The client will wake up every 60 seconds, get some stock quotes over the web, and depending on whether the stock is above or below a certain price, will alert you with both a peep and an e-mail notification.

Bear in mind that you really do not need to know much Perl to create a client. If you are a newbie, just copy what is done here while using your favorite Perl book to figure out whatever you do not understand.

The full code listing is given at the end of this section for reference.

SOME PRELIMINARIES

The ticker requires a Perl module by the name of Finance::Quote.

I will assume that the reader is familiar with how to install a Perl module. For those who are unfamiliar with the process of installing a Perl module from the CPAN, a hint:


            
              
              sudo perl -MCPAN -e 'install Finance::Quote'

THE CLIENT CONFIGURATION

First, create a section in the Peep configuration file, peep.conf, for your client. (peep.conf would typically be put in your /usr/local/etc directory during install.) peep.conf is heavily commented, so you should use that as a reference as well as this document.

The section begins with a client declaration and ends with an end client declaration.

There is some window dressing you have to add, including a class and port declaration. You can just copy those from one of the other clients.

You can also put an optional default section, which specifies any defaults for command-line options. See the logparser section of peep.conf for an example.

Next (and this is where you are doing the real work), you create the config section.

Between the config and end config, you can put anything you want. You will see what this section is all about in a bit, but for now let us just create a section that lists some stock symbols and related information we will need for the client.

If you want to receive e-mail notifications, you can include an optional notification section following the config section as well which will describe who is to be sent the e-mail and some other information.

The whole thing looks like this:


            
              
              client ticker
  class morgenstern
  port 1999
  config
    # Stock symbol  Stock exchange    Event             Max      Min  
    RHAT            nasdaq            red-hat           4.0      3.6
    SUNW            nasdaq            sun-microsystems  9.0      8.0
  end config
  notification
    notification-hosts morgenstern
    notification-recipients collin.starkweather@colorado.edu
    notification-level warn
  end notification
end client ticker

Finally, you should define the events you just created. An event named red-hat is associated with the stock symbol for Red Hat (no endorsement implied) and one named sun-microsystems is associated with, you guessed it, Sun Microsystems (again, no endorsement implied).

So let us tie these events into some sounds. Going down to the events block in the configuration file, put in the following:


            
              
              events
# Event Type    | Path to Sound File               | # of sounds to load
... 
red-hat           /usr/local/share/peep/sounds/misc/events/rooster.*   1
sun-microsystems  /usr/local/share/peep/sounds/misc/events/doorbell.*  1
end events

This will cause a rooster to crow when RHAT goes out of bounds and a doorbell to chime when the same happens with SUNW.

THE CODE

Creating the client itself is really quite easy. There is going to be alot of discussion in this section, and the code is quite liberally commented. However there are actually only 50 lines (and only 33 statements - some statements span lines for clarity) of code to create the entire client. So you should not feel intimidated. There is really not much to it.

I assume that the reader has some working knowledge of Perl. If you are just starting out, I would recommend that you look up


            
              
              http://www.perlmonks.org

to supplement any other learning you are doing. It is a very helpful forum and a real boon to those just starting out.

OPEN A FILE

Open a file called ticker in your text editor of choice.

USE SOME MODULES

The first thing we will create is the use section. This will read in all of the objects we need. I will also use the strict pragma. Using strict is a habit I highly recommend:


            
              
              #!/usr/bin/perl
use strict;
use Net::Peep::BC;
use Net::Peep::Log;
use Net::Peep::Client;
use Net::Peep::Notifier;
use Net::Peep::Notification;
use Finance::Quote;
use vars qw{ %config $logger $client $quoter $conf };

After using strict, several Peep modules are used. The Net::Peep::BC module is used to send a broadcast to the server to let it know it is supposed to play a sound. Net::Peep::Log is a helpful module if you need to create some well-formatted output. (We will use it in a couple of places to let ourselves know what we are doing.)

The Net::Peep::Client module is the real workhorse. That is what will enable us to write a client in 33 statements or less. The Net::Peep::Notifier and Net::Peep::Notification modules are used to send e-mail notifications. (I want to know it if my stocks take a nosedive and I am out of my office!)

Next is the Finance::Quote module, which we will use to fetch the stock prices.

Finally we declare some global variables with the vars pragma. You will see what these are used for later.

INSTANTIATE SOME OBJECTS

We will be using three objects in the main section of the script: A logging object, a Peep client object, and the object that gets our stock quotes for us.


            
              
              $logger = new Net::Peep::Log;
$client = new Net::Peep::Client;
$quoter = new Finance::Quote;

WORKING WITH THE CLIENT OBJECT

Now we will work some magic with the client object.

The first thing we do is give the client a name. We will call our client 'ticker'.


            
              
              $client->name('ticker');

Now we need to initialize the client.


            
              
              $client->initialize();

There are a variety of command-line options that will be read and parsed during the initialization. If you would like to supply some of your own command-line options to the initialization, you can do so using the format of the Getopt::Long object with something like:


            
              
              my $foo = '';
my %options = ( 'foo=s'=>\$foo, ... );
$client->initialize(%options);

Next we will tell the client what it will use to parse the config block we defined above. We will simply pass it a reference to a subroutine which we will define later. How about we call the subroutine parse?


            
              
              $client->parser( \&parse );

Now that we have told the client what to use to parse the config block, we can tell it to read in the configuration information from the Peep configuration file:


            
              
              my $conf = $client->configure();

The return value of the configure method, $conf, is a Net::Peep::Conf object containing the information gleaned from the Peep configuration file and a variety of useful methods. See the Net::Peep::Conf PODs for more information.

After the configuration information is read, we will start the client on its way. The first thing we do is tell the client what to do every time it wakes up. We will feed it a callback (another reference to a subroutine, this one called loop) which will be run every time the client wakes up. Then we will start the client up, telling it to wake up every 60 seconds and execute the callback.


            
              
              $client->callback( \&loop );
$client->MainLoop(60);

That is all there is to it! Well, almost. We mentioned two subroutines above which we have not yet defined. So the last thing we will do is write these subroutines.

THE PARSER

The parser is given everything between the config and end config lines in the section of the configuration file we defined above.

Though you can parse it any way you like, I favor using a regular expression. They seem to intimidate people because they look so cryptic, but they were much easier for me to get the hang of than I expected.


            
              
              # This subroutine will be used to parse the following 2 lines from
# peep.conf (see above) and store the information in %config:
#   RHAT            nasdaq            red-hat           4.0      3.6
#   SUNW            nasdaq            sun-microsystems  9.0      8.0
sub parse {
  for my $line (@_) {
    if ($line =~ /^\s*([A-Z]+)\s+(\w+)\s+([\w\-]+)\s+([\d\.]+)\s+([\d\.]+)/) {
      my ($symbol,$exchange,$event,$max,$min) = ($1,$2,$3,$4,$5,$6);
        $config{$symbol} = { event=>$event, exchange=>$exchange, max=>$max, min=>$min };
     }
  }
} # end sub parse

We basically create a data structure from the %config hash. The keys of the hash are the stock symbols and the values are hash references used to describe some information about the stock symbol such as what stock exchange to look at, what event (sound) to play, and what the maximum and minimum prices that will trigger the event are.

The information that we get from the configuration file will be used in the next section to trigger the event and the e-mail notification.

THE CALLBACK

Finally, the meat of the client: The callback. I will leave it as an exercise to the reader to browse the documentation for Finance::Quote.

First the code, then the explanation:


            
              
              sub loop {
  for my $key (sort keys %config) {
    $logger->log("Checking the price of [$key] ...");
    # Fetch some information about the stock including the price
    my %results = $quoter->fetch($config{$key}->{'exchange'},$key);
    my $price = $results{$key,'price'};
    $logger->log("\tThe price of [$key] is [$price].");
    if ($price > $config{$key}->{'max'} or $price < $config{$key}->{'min'}) {
      $logger->log("\tThe price is out of bounds!  Sending notification ....");
      # The price is out of bounds!  We'll start peeping ...
      my $broadcast = Net::Peep::BC->new('ticker',$conf);
      $broadcast->send('ticker',
        type=>0, 
        sound=>$config{$key}->{'event'},
        location=>128, 
        priority=>0, 
        volume=>255);
      my $notifier = new Net::Peep::Notifier;
      my $notification = new Net::Peep::Notification;
      $notification->client('ticker');
      $notification->status('crit');
      $notification->datetime(time());
      $notification->message("The price of $key is $price!");
      $notifier->notify($notification);
    }
  }
} # end sub loop

In the callback, we loop over the stock symbols we found in the parse subroutine described above with


            
              
              for my $key (sort keys %config) {
  ...
}

For each stock symbol, we fetch the price and other information using


            
              
              my %results = $quoter->fetch($config{$key}->{'exchange'},$key);

Next, we check if the price is greater than the maximum or less than the minimum defined in the configuration file:


            
              
              if ($price > $config{$key}->{'max'} or $price < $config{$key}->{'min'}) {
      ...
}

If it is, we first send a message to the Peep server to play a sound. We do this by instantiating a Net::Peep::BC, the Peep broadcast object, and calling its send method.


            
              
              my $broadcast = Net::Peep::BC->new('ticker',$conf);
$broadcast->send('ticker',
  type=>0, 
  sound=>$config{$key}->{'event'},
  location=>128, 
  priority=>0, 
  volume=>255);

The type option indicates the type of sound (0 for an event, 1 for a state). The sound option tells it what type of sound it should play (in this case either red-hat or sun-microsystems). The remainder of the settings are described in the Net::Peep::BC documentation.

Second, we send out an e-mail notification. This is done by creating a Net::Peep::Notifier object, which will actually send the e-mail, and giving it a Net::Peep::Notification object properly populated with information that will be included in the e-mail:


            
              
              my $notifier = new Net::Peep::Notifier;
my $notification = new Net::Peep::Notification;
$notification->client('ticker');
$notification->status('crit');
$notification->datetime(time());
$notification->message("The price of $key is $price!");
$notifier->notify($notification);

For more information, consult the documentation for these objects.

It is worth noting that this does not imply that we will receive an e-mail every 60 seconds. The notification system sends out a notification when it first receives one, then sends all subsequent notifications in a bundle at regular intervals (you can set the bundling interval in peep.conf) .

We have created a Peep client from scratch! Let us see how it works ....

RUN THE CLIENT

Simply as an example, I would start the server with


            
              
              ./peepd -S /usr/local/etc/peep.conf --nodaemon

I use the --nodeamon flag so that I can watch the output.

Then


            
              
              ./ticker --noautodiscovery --server=localhost --port=2001 \ 
         --nodaemon --config=/usr/local/etc/peep.conf

DROP US A LINE

We would be interested in any clients that are created, both out of curiosity and because the code may be useful to others. Our e-mail addresses are given below.

AUTHOR

Collin Starkweather <collin.starkweather@colorado.edu>

ACKNOWLEDGEMENTS

Many thanks to the folks at SourceForge for creating a robust development environment to support open source projects such as Peep.

If you are not familiar with SourceForge, please visit their site at


            
              
              http://www.sourceforge.net

TERMS AND CONDITIONS

This software is issued under the Gnu General Public License.

For more information, write to Michael Gilfix (mgilfix@eecs.tufts.edu).

This version of Peep is open source; you can redistribute it and/or modify it under the terms listed in the file COPYING included with the full Peep distribution which can be found at


            
              
              http://peep.sourceforge.net

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

For those interested in a robust network and systems monitoring tools, your humble author has found Big Brother to be a valuable resource which is complementary to Peep. Big Brother is an open source product and there are a large number of user-contributed plug-ins which make it ideal for a variety of needs.

You can find more information on Big Brother at


            
              
              http://www.bb4.com

Those who enjoy Peep may also enjoy checking out logplay, which is similar in concept but fills a different niche.

You can find more information on logplay at


            
              
              http://projects.babblica.net/logplay

Logplay is not under active development at the time, though many ideas from the project are being incorporated into Peep with the assistance of the author, Rando Christensen, who has generously donated his time in many productive discussions.

Please contact me at


            
              
              collin.starkweather@colorado.edu

if you have any questions.

APPENDIX A: THE STOCK TICKER CONFIGURATION


            
              
              client ticker
  class morgenstern
  port 1999
  config
    # Stock symbol  Stock exchange    Event             Max      Min  
    RHAT            nasdaq            red-hat           4.0      3.6
    SUNW            nasdaq            sun-microsystems  9.0      8.0
  end config
  notification
    notification-hosts morgenstern
    notification-recipients collin.starkweather@colorado.edu
    notification-level warn
  end notification
end client ticker
events
# Event Type    | Path to Sound File               | # of sounds to load
... 
red-hat           /usr/local/share/peep/sounds/misc/events/rooster.*   1
sun-microsystems  /usr/local/share/peep/sounds/misc/events/doorbell.*  1
end events

APPENDIX B: THE STOCK TICKER

Note the PODs at the beginning of the script. When the script is run with the help flag


            
              
              ./ticker --help

the client will display whatever PODs are included with the script.


            
              
              #!/usr/bin/perl
=head1 NAME
ticker - A stock monitoring client written for Peep: The Network
Auralizer.
=head1 USAGE
  ./ticker --help
  ./ticker --noautodiscovery --server=localhost --port=2001 --nodaemon
If you have any problems, try turning on debugging output with
something like --debug=9.
=head1 CONFIGURATION
To use this client, include a section like the following in peep.conf:
  client ticker
    class home
    port 1999
    config
      # Stock symbol  Stock exchange    Event             Max      Min  
      RHAT            nasdaq            red-hat           4.0      3.6
      SUNW            nasdaq            sun-microsystems  9.0      8.0
    end config
    notification
      notification-hosts localhost
      notification-recipients bogus.user@bogusdomain.com
      notification-level warn
    end notification
  end client ticker
and another section in the events block with something like
  events
  #Event Type      |          Path to Sound File           | # of sounds to load
  ...
  red-hat            /usr/local/share/peep/sounds/misc/events/rooster.*        1
  sun-microsystems   /usr/local/share/peep/sounds/misc/events/doorbell.*       1
  end events
=head1 AUTHOR
Collin Starkweather <collin.starkweather@colorado.edu> Copyright (C) 2001
=head1 SEE ALSO 
perl(1), peepd(1), Net::Peep, Net::Peep::Client, Net::Peep::BC,
Net::Peep::Notifier, Net::Peep::Notification, Finance::Quote
http://www.sourceforge.net
=cut
# Always use strict :-)
use strict;
use Net::Peep::BC;
use Net::Peep::Log;
use Net::Peep::Client;
use Net::Peep::Notifier;
use Net::Peep::Notification;
use Finance::Quote;
use vars qw{ %config $logger $client $quoter $conf };
# The Net::Peep::Log object will allow us to print out some things in
# a nicely formatted way so we can tell ourselves what we're doing ...
$logger = new Net::Peep::Log;
# Instantiate a Peep client object.  The client object handles most of
# the dirty work for us so we don't have to worry about things such as
# forking in daemon mode or parsing the command-line options or the
# Peep configuration file.  Its a very sophisticated object with many
# useful functions.  For more information, type
#
#   perldoc Net::Peep::Client
$client = new Net::Peep::Client;
$quoter = new Finance::Quote;
# First we have to give the client a name
$client->name('ticker');
# Now we initialize the client.  If the initialization returns a false
# value, we display documentation for the script.
$client->initialize() || $client->pods();
# Now we assign a parser that will parse the 'ticker' section of the
# Peep configuration file
$client->parser( \&parse );
# Now we tell the client to get the information from the configuration
# file.  It returns a  Net::Peep::Conf, the Peep configuration object,
# which contains information from the configuration file.
$conf = $client->configure();
# Register a callback which will be executed every 60 seconds.  The
# callback is simply a function which checks the price of the stock
# and peeps every time it exceeds the maximum or minimum price that
# has been set.
$client->callback( \&loop );
# Start looping.  The callback will be executed every 60 seconds ...
$client->MainLoop(60);
sub parse {
    # Parse the config section for the ticker client in the Peep
    # configuration file
    # We'll use a regular expression to extract the ticker information
    # and stuff it into a data structure (the global variable %config)
    # This subroutine will be used to parse lines from peep.conf such
    # as the following and store the information in %config:
    #   RHAT            nasdaq            red-hat           4.0      3.6
    #   SUNW            nasdaq            sun-microsystems  9.0      8.0
    for my $line (@_) {
        if ($line =~ /^\s*([A-Z]+)\s+(\w+)\s+([\w\-]+)\s+([\d\.]+)\s+([\d\.]+)/) {
            my ($symbol,$exchange,$event,$max,$min) = ($1,$2,$3,$4,$5,$6);
            $config{$symbol} = { event=>$event, exchange=>$exchange, max=>$max, min=>$min };
        }
    }
} # end sub parse
sub loop {
    for my $key (sort keys %config) {
        $logger->log("Checking the price of [$key] ...");
        # Fetch some information about the stock including the price
        my %results = $quoter->fetch($config{$key}->{'exchange'},$key);
        my $price = $results{$key,'price'};
        $logger->log("\tThe price of [$key] is [$price].");
        if ($price > $config{$key}->{'max'} or $price < $config{$key}->{'min'}) {
            $logger->log("\tThe price is out of bounds!  Sending notification ....");
            # The price is out of bounds!  We'll start peeping ...
            my $broadcast = Net::Peep::BC->new('ticker',$conf);
            $broadcast->send('ticker',
                             type=>0, 
                             sound=>$config{$key}->{'event'},
                             location=>128, 
                             priority=>0, 
                             volume=>255);
            # In case we're away from our desk, we'll also send out an
            # e-mail notification.  Don't want to miss the action!
            my $notifier = new Net::Peep::Notifier;
            my $notification = new Net::Peep::Notification;
            $notification->client('ticker');
            $notification->status('crit');
            $notification->datetime(time());
            $notification->message("The price of $key is $price!");
            $notifier->notify($notification);
        }
    }
} # end sub loop

To install Net::Peep, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::Peep

CPAN shell

perl -MCPAN -e shell
install Net::Peep

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)