check_gnokii_modem, check_gnokii_network, check_gnokii_recievesms
When I was given the task to make a Nagios installation send notifications by SMS, I found three Nagios FAQs about the topic, one even mentioning gnokii, but no ready-to-use software. NagiosGnokii is what I came up with.
We use a T-Mobile Web'n'Walk Stick IV, but thanks to the abstraction layer provided by gnokii, I'm confident that NagiosGnokii will work across a much wider range of models. In particular, the WnW IV is controlled through the standard AT command set, which is also supported by many other GSM modems.
NagiosGnokii provides scripts to:
-
Detect, config-finalize, and monitor the actual device (autocreated by udev)
-
Monitor the cell network you're booked into, and alert if none or not your home network
-
Send SMS (duh!)
-
Monitor for and prefetch incoming SMS, in case your staff sends reply SMSes, or your cell provider disseminates important information through this channel
0. CHECK PREREQUISITES
This software was developed and tested in the following environment:
a) Run-of-the-mill PC with a recent Linux installed and a free USB port. In particular, check_gnokii_modem assumes that udev is running and will create character devices (with an owner that it needs to change) as soon as the GSM modem is plugged in. Non-Linux Unices that provide udev should work as well, but your devices will be named differently. Unices without udev can probably been made to work, but you'll likely have to patch check_gnokii_modem for that.
b) T-Mobile Web'n'Walk Surf Stick IV. This device actually is a re-branded Huawei E220 HSDPA Modem. gnokii is able to control its relevant functions via the AT command set. If gnokii works with your GSM modem, in particular its SMS-related functions, chances are that NagiosGnokii will work as well.
c) gnokii 0.6.28. If you install(ed) executables from some repository or distrib, run "gnokii --help | grep security" and verify that support for the "--getsecuritycodestatus" (and "--entersecuritycode PIN") option(s) has been compiled in. If not, reinstall from the source tarball and make sure to start with "./configure --enable-security".
d) sshpass 1.04 (optional). This software is only needed if:
- You can't, or don't want to, disable the SIM card asking for the PIN on reinitialization (see e) below) and
- You can't, or don't want to, assume that your operations staff will have the PIN handy when it needs to be re-entered.
e) minicom (optional). gnokii currently cannot change a SIM card's setting whether or not to require entry of the PIN upon startup. In our case, I used minicom to throw the proper AT command at the SIM card myself.
1. GNOKII CONFIGURATION
1.1. Make up your mind whether you'll ever want to use gnokii for purpo- ses other than NagiosGnokii on the machine in question.
If not, you can put the configuration for NagiosGnokii's purposes
into the default gnokii config file /etc/gnokiirc .
Otherwise, create a separate copy (say, /etc/NagiosGnokiirc ), edit
all four scripts (check_gnokii_modem, check_gnokii_network,
check_gnokii_receivesms, and notify-by-sms), and change the line
NG_CONF=""
to point to the separate copy, e.g.,
NG_CONF="/etc/NagiosGnokiirc"
(Only check_gnokii_modem and notify-by-sms need any configuration
*beyond* that.)1.2. In the chosen file, set up the gnokii configuration for the device. For our hardware, the relevant lines were: [global] port = /dev/ttyUSB0 model = AT connection = serial serial_baudrate = 19200 (I.e., leave the rest at the default values, unless instructed otherwise below.)
The traditional method to lock a modem device is to put a lockfile
*directly* into the /var/lock directory. Check whether your Nagios
user can do that (permissions on /var/lock).
If yes, have your gnokii configuration say:
use_locking = yes
If not, you'll have to choose between two evils:
a) Change the permissions on /var/lock (e.g., chmod 1777) and make
gnokii do locking as above
b) Configure gnokii *not* to lock (use_locking = no) and run the
risk of conflicting accesses
Finally disable all debug output, as NagiosGnokii won't look at it,
anyway:
[logging]
debug = off
rlpdebug = off
xdebug = off1.3. Test it. NagiosGnokii will use some or all of the following gnokii incantations:
gnokii --getsecuritycodestatus
gnokii --entersecuritycode PIN
gnokii --getnetworkinfo
echo "$SMS_CONTENT" | gnokii --sendsms $PHONENUMBER
gnokii --showsmsfolderstatus
gnokii --getsms SM 0 end
gnokii --getsms SM 0 end -a $MBOX_FILE -d
Note that instead of parsing the output of "--showssmsfolderstatus"
in detail, we request transfer of *all* slots ("SM 0 end") and
ignore gnokii's exit status (which will indicate an error if slots
didn't contain an SMS).1.4. If you install gnokii from a source tarball (into /usr/local ) and your OS does not include /usr/local/lib into the default library path, gnokii may refuse to run, reporting a missing libgnokii.so.* (for gnokii 0.6.28, libgnokii.so.5). Rather than manhandling your OSes' dynamic library setup, I'd advise that you put a symlink into /usr/lib by hand to solve the problem.
2. INSTALL THE NAGIOSGNOKII SCRIPTS
2.1. Work through the configuration sections of check_gnokii_modem and notify-by-sms.
2.2. Create a pseudo mailbox file for a (new) "user" of your choice. (The examples below use "nagios-sms-in" as the username.)
This needs to be a *local* mailbox, i.e., reside in /var/spool/mail
or /var/mail or $HOME/mbox .
Create the file empty, and change owner and permissions so that
Nagios has read and write rights. (Normally, Nagios will *not* be
able to *create* a file in the OSes' mail spool directory.)
If your system puts mailboxes in $HOME/mbox , you'll also need to
create $HOME, an entry in /etc/passwd etc. etc..
NagiosGnokii will put incoming SMSes into this mail spool file and
check_gnokii_receivesms will stay in WARNING state as long as there
is an SMS in it, but choosing a method how the SMSes will ever
*leave* the inbox is up to you. Just make sure that the file will
stay behind, be empty, and continue to grant Nagios r/w rights.
(I haven't thought this out much because I don't expect our opera-
tions staff to send reply SMSes, ever. check_gnokii_receivesms just
deals with a loose end, and the op manual says to empty the file
with an editor when necessary.)
You can find an example of what will appear in this mailbox in the
file example-incoming-sms included with this software. Note the
invalid sender address, the absence of any recipient address, and
the general non-MIME format.2.3. Install check_gnokii_network and check_gnokii_receivesms as normal Nagios plugins.
Here are the relevant parts from our Nagios config:
# check_gsm - Check that the GSM modem is booked in,
# and into the proper network
# Arguments: net_id - The network ID of the proper
# GSM network (e.g., "262 01" for T-Mobile D1)
define command{
command_name check_gsm
command_line $USER1$/check_gnokii_network '$ARG1$'
}
# check_sms_inbox - Check the GSM modem for *incoming*
# messages (in case anyone sends us some)
# Arguments: mailboxname - The name of the machine mailbox
# (file in mbox format) to move incoming SMS to
define command{
command_name check_sms_inbox
command_line $USER1$/check_gnokii_receivesms '$ARG1$'
}
define service{
use some-template
host_name localhost
service_description GSM modem reception
check_command check_gsm!262 01
}
define service{
use some-template
host_name localhost
service_description GSM modem incoming SMS
check_command check_sms_inbox!nagios-sms-in
}
If you don't know the network ID for your GSM modem's home network,
you can use "gnokii --getnetworkinfo" to look it up - provided, of
course, that your modem is operational and booked into its home GSM
network right now.2.4. Install check_gnokii_modem in a location of your choice (we keep it mixed in with the actual Nagios plugins) and have cron execute it as root (without parameters) in an interval of your liking.
Make sure that it is owned by root and mode 0700, to prevent others
from seeing the SIM card's PIN in its configuration.
Run it manually with the --debug option and follow the directions
until you get an OK state in return.2.5. In your Nagios config, add the service that check_gnokii_modem does send its results to.
Example from our config:
define service{
use some-template
host_name localhost
service_description GSM modem status
active_checks_enabled 0
check_command do-nothing
}
(where "do-nothing" is essentially /bin/false, to generate a *non*-
OK state, should it ever be executed).2.6. Install notify-by-sms wherever you put your nonplugin Nagios helper software (we keep it mixed into the plugins, too) and add matching commands to your Nagios config.
Example from our config:
# notify-host-by-sms and notify-service-by-sms - The SMS
# counterparts of notify-...-by-email
# Arguments: none (all parameters taken from macros)
define command{
command_name notify-host-by-sms
command_line /usr/bin/printf "%b" \
"$NOTIFICATIONTYPE$: $HOSTNAME$ is \
$HOSTSTATE$ ($HOSTOUTPUT$)" | \
$USER1$/notify-by-sms "$CONTACTPAGER$"
}
define command{
command_name notify-service-by-sms
command_line /usr/bin/printf "%b" \
"$NOTIFICATIONTYPE$: $HOSTNAME$: \
$SERVICEDESCR$ is $SERVICESTATE$ \
($SERVICEOUTPUT$)" | \
$USER1$/notify-by-sms "$CONTACTPAGER$"
}
(Note: Extra linebreaks, with '\' markers, added for legibility.
Remove these from *your* config!)2.7. Configure contacts, contact groups, etc. etc. to send SMSes to.
Contacts to send SMSes to need to have:
-- A "pager" statement (in addition to, or instead of "email")
giving the phone number to send SMSes to. I recommend that you
strictly stick to international notation ("+491712345678"), even
though notify-by-sms accepts a wider syntax.
-- service_notification_commands and/or host_notification_commands
set to the newly defined "notify-...-by-sms" command, instead
of the usual "notify-...-by-email" one.3. OPTIONAL SETTINGS AND SOFTWARE
See the comments at the beginning of this file to decide which you might want under what circumstances.
3.1. Disabling / re-enabling the SIM card requiring input of the PIN
If your GSM modem can be talked to through the AT command set, you can control this setting as follows:
a) Make sure that the SIM card does not ask for the PIN right now. (Use "gnokii --getsecuritycodestatus" and "gnokii --entersecuritycode PIN" as appropriate.) b) Install minicom, or another program that allows you to talk directly to a serial interface. c) Configure it to use the same device, serial settings, etc. as gnokii. d) Connect, then enter the following AT command to disable the PIN- entry-on-startup requirement: AT+CLCK="SC",0,"0000" (where "0000" is your current PIN). To re-enable it, instead enter: AT+CLCK="SC",1,"0000" If you get an error instead of "OK" in reply, doublecheck that you got a) right. If you still get an error, it is possible that your SIM card doesn't let you change this setting.
3.2. Install a special version of sshpass to pass the PIN automatically
sshpass is hardcoded to expect the string "assword:" (ssh's prompt when asking the user to enter a login password) for a signal when to send the secret data (the password). gnokii, at least when running with LANG=C (nonlocalized/English UI), uses "Enter your code:" instead.
a) Obtain and untar the sshpass source code.
b) Edit main.c and change the line:
static const char compare1[]="assword:"; // Asking for a password
to instead read:
static const char compare1[]="Enter your code:"; // Asking for a password
c) Do "configure" and "make", but NOT "make install".
d) Copy the compiled executable "sshpass" into the exact same directory
you installed check_gnokii_modem in, changing the filename to
"gnokii_pass".
e) Doublecheck ownership+permissions; Nagios needs to be able to run the
executable.
f) Doublecheck that you correctly set the PIN in check_gnokii_modem .
(SIM cards are supposed to lock you out if you repeatedly enter a
wrong PIN!)
