Plugin:check smsfinder.pl

$ perldoc check_smsfinder.pl
NAME
    smsfinder.pl
             the Nagios 
             - check plugin, 
             - notification handler / sendSMS and 
             - ACKnowledgement addon / CGI handler
             for the MultitechSMSFinder

DESCRIPTION
    Depending on how it is called,
             - Checks a Multitech SMSFinder and returns if it is connected 
                     to the GSM Network and the level of signal strength.
             - send an SMS via a Multitech SMSFinder
             - handles a received SMS and sets the ACKnowledgement in Nagios

             *THIS script should be symlinked/copied according to your needs*
             If you symlink it, make the CGI handler the original. Your http
             server may not accept symlinked CGIs.
             So once more - this script is all three in one.

SYNOPSIS
    check_smsfinder.pl
             -H hostaddress
             [-t|--timeout=<timeout in seconds>]
             [-v|--verbose]
             [-h|--help] [-V|--version]
             [-u|--user=<user>]
             [-p|--password=<password>]

    sendsms.pl
             -H hostaddress
             [-t|--timeout=<timeout in seconds>]
             [-v|--verbose]
             [-h|--help] [-V|--version]
             [-u|--user=<user>]
             [-p|--password=<password>]
             -n|--number=<telephone number of the recipient>
             -m|--message=<message text>

    smsack.cgi
             [-v|--verbose]
             [-h|--help] [-V|--version]
             CONTENT_LENGTH via ENVIRONMENT
             SMS data       via STDIN (from http post)

OPTIONS
    -H <hostaddress>
        Hostaddress of the SMSFinder

    -t|--timeout=<timeout in seconds>
        Time in seconds to wait before script stops.

    -v|--verbose
        Enable verbose mode and show whats going on.

    -V|--version
        Print version an exit.

    -h|--help
        Print help message and exit.

    -n|--number
        Telephone number of the SMS recipient

    -m|--message
        SMS message text

    -w|--warning
        Warning level for signal strength in procent. (Default = 40)

    -c|--critical
        Critical level for signal strength in procent. (Default = 20)

    --noma
        NoMa switch - try to check if the send SMS is send, not just queued.

HOWTO integrate with Nagios
    *
     Prepare your system as described below, be well informed and (sort of)
     remote control your Nagios via your mobile and a Multitech SMSFinder.

  How to reset/overrule a host/service state?
    Just prepend the notification SMS with "OK " and send it back to your
    SMSFinder.

    The host/service state will be set to OK and notifications enabled
    again.

  How to acknowledge a notified outage?
    Just prepend the notification SMS with "ACK " and send it back to your
    SMSFinder.

    The host/service state will be acknowledged and notifications disabled
    until the host/service is fine again.

  How to prepare your system for acknowledgements?
    1. Configure the SMSFinder to use the HTTP API to send and receive SMS.

    Configure the following in the web interface of your SMSFinder:

    1.a. Access for your Nagios server(s) on the "Administration > Admin
    Access > Allowed Networks" page.

    1.b. define a SMS user on the "SMS Services > Send SMS Users" page.

    1.c. switch on the HTTP send API on the "SMS Services > SMS API > Send
    API" page.

    1.d. configure the HTTP receive API on the "SMS Services > SMS API >
    Receive API" page. (do not enable authentication, and be sure to set the
    POST Interval to 0)

    2. Configure the notifications (via sendsms.pl) in Nagios as shown in
    the examples.

    3. Configure the web server to handle the acknowledgements (via
    smsack.cgi).

    4. Alter the paths in the congfig section on top of this script to match
    your system setup.

    5. Ensure that the logfile is writable by the Nagios and the web server
    user: chown nagios:www-data /usr/local/nagios/var/smsfinder.log && chmod
    664 /usr/local/nagios/var/smsfinder.log

    6. Add the passwords to the /usr/local/nagios/etc/resource.cfg
    $USER13$=smsuser $USER14$=smspass $USER15$=adminuser $USER16$=adminpass

EXAMPLE for Nagios check configuration
     # command definition to check SMSFinder via HTTP
     define command {
            command_name            check_smsfinder
            command_line            $USER1$/check_smsfinder.pl -H $HOSTADDRESS$ -u $USER15$ -p $USER16$ -w $ARG1$ -c $ARG2$
     }

     # service definition to check the SMSFinder
     define service {
            use                                     generic-service
            host_name                       smsfinder
            service_description     smsfinder
            check_command           check_smsfinder!40!20    # warning and critical in percent
            ## maybe it's whise to alter the service/host template
            #contact_groups         smsfinders
      }
 
EXAMPLE for Nagios notification configuration
     define command {
            command_name    notify-host-by-sms
            command_line    /usr/local/nagios/smsack/sendsms.pl -H $HOSTADDRESS:smsfinder$ -u $USER13$ -p $USER14$ -n $CONTACTPAGER$ -m '$NOTIFICATIONTYPE$ $HOSTNAME$> is $HOSTSTATE$ /$SHORTDATETIME$/ $HOSTOUTPUT$'
     }

     define command {
            command_name    notify-service-by-sms
            command_line    /usr/local/nagios/smsack/sendsms.pl -H $HOSTADDRESS:smsfinder$ -u $USER13$ -p $USER14$ -n $CONTACTPAGER$ -m '$NOTIFICATIONTYPE$ $HOSTNAME$,$SERVICEDESC$> is $SERVICESTATE$ /$SHORTDATETIME$/ $SERVICEOUTPUT$'
     }

     # contact definition - maybe it's wise to alter the contact template
     define contact {
            contact_name                    smsfinder
            use                             generic-contact
            alias                           SMS Nagios Admin
            # send notifications via email and SMS
            service_notification_commands   notify-service-by-email,notify-service-by-sms
            host_notification_commands      notify-host-by-email,notify-host-by-sms
            email                           nagios@localhost
            pager                           +491725555555           # alter this please!
     }

     # contact definition - maybe it's wise to alter the contact template
     define contactgroup {
            contactgroup_name       smsfinders
            alias                   SMS Nagios Administrators
            members                 smsfinder
     }

EXAMPLE for Apache configuraion
     ScriptAlias /nagios/smsack "/usr/local/nagios/smsack"
     <Directory "/usr/local/nagios/smsack">
            Options ExecCGI
            AllowOverride None
            Order allow,deny
            Allow from 10.0.10.57   # SMS Finder
     </Directory>