How-to use SMS/Texto alerting system

Posted 2021-03-16 - Updated 2021-05-05

Supported on Linux

Configuring the SMS alerting system

1. Get a ‘Textbelt’ key from the Textbelt web site
2. Setup Textbelt in SADMIN configuration file
3. Defining cellular number and sms alert group
4. Set default alerting group
5. Changing the default alerting group
6. Override the default alert group and type in a script.
7. Override the default alert group in SADMIN System Monitor.
8. Testing SMS/Texto alert

Getting a ‘Textbelt’ key

Go to the Textbelt web site.
To get a Textbelt key, click on the “Generate my key” button.

Textbelt key is associated with your email address, you need to enter it at this point.

Price is reasonable, for $20 you can send up to 600 SMS messages.
You can using your credit card or use Paypal to checkout.

Setup Textbelt in SADMIN configuration file

• Now that we have our ‘Textbelt’ key, we need to record it in the SADMIN configuration file.
• Using your favorite editor open ‘$SADMIN/cfg/sadmin.cfg’ and update the two Textbelt fields.

# vi $SADMIN/cfg/sadmin.cfg
#----------------------------------------------------------------------------
# TEXTBELT SMS TEXT MESSAGE VARIABLE
# This is the key generated by TextBelt and the URL to use the SMS Service
# Go to https://textbelt.com/ and press the 'Generate my key' button.
# Enter your email address and decide what is the right plan for you.
# It's $10 for 250 Text Messages, $20 for 600, $40 for 1200.
#----------------------------------------------------------------------------
SADM_TEXTBELT_KEY = 12b0f573dfc4e1377471dc930684dfbcdded045eiSw1swtuyrUyRxHTJX2vAFhdxs
SADM_TEXTBELT_URL = https://textbelt.com/text

SADM_TEXTBELT_KEY:
This field contain the textbelt key that was previously generated for you.
To eliminate any typo error, use the clipboard copy/paste to enter the key.

SADM_TEXTBELT_URL:
It’s the URL use by SADMIN to send the SMS request to Textbelt web site.
SADMIN is using the ‘curl’ linux command to issue the request to textbelt.

Defining cellular number and sms alert group

Cellular group definition

First give a name to the cellular number owner or cellular purpose (like support,on_call).
Then the second column is a ‘c’ for Cellular definition group and finally the telephone number.

SMS/Texto group definition

If you need to alert more than one person (cellular) when an alert is issue, you can use the SMS/Texto group to do so. You declare the SMS/Texto group name, like ‘webteam’, ‘emergency’, ‘sysadmin’, that include multiple cellular definition. In the example above, the SMS/Texto group ‘emergency’, will send the alert to four cellulars.

Open the ‘alert-group.cfg’ file with your favorite editor and define your own cellular and SMS/Texto group.
# vi $SADMIN/cfg/alert_group.cfg

Setting default alerting group

• When an alert is issue from a script or from the SADMIM System Monitor, it’s sent to an alert group.
• The ‘default’ alert group name used is the one specified in the SADMIN configuration file (See image below).
• The ‘SADM_ALERT_GROUP’ name doesn’t have to be ‘default’, it could be any of the group define in the alert group file.
• You can change the ‘SADM_ALERT_GROUP’ name with your favorite editor whenever you need to.
• The group name you specify, MUST exist in the alert Group file ($SADMIN/cfg/alert_group.cfg).
• You may also leave it to ‘default’ and change the definition of the ‘default’ group in the alert group file.

Changing the default alerting group

• Let’s say SMS (Texto) is your preferred way to get alerted
  • We must make sure the ‘default’ alert group have a type ‘t’ (texto).
  • We have chosen to send alert to the ‘sysadmin_sms’ SMS alert group.
  • All alert will now be sent by default to group ‘sysadmin_sms’ that contain one cellular definition ‘john_doe’.
  • We will see later on, how to override this default within your script and in the system monitor.
  • Remember, group name must begin in column one, be unique and shouldn’t contain any space.

With your favorite editor open the alert group file.

# vi $SADMIN/cfg/alert_group.cfg

# Default Alert Group (It should not be changed or deleted).
default              t   sysadmin_sms
 
# Cellular number of individual 
john_doe            c   5147577706
robert_smith        c   4187570067
support_cell        c   5147570068
jerry_calder        c   5147779302
diane_watson        c   5147779303

# SMS(Text) Alert Group
sysadmin_sms        t   john_doe  
emergency_sms       t   john_doe,support_cell,robert_smith,diane_watson
webteam_sms         t   diane_watson

Override the default alert group and type in a script

Here, we assume that you have created a script using our Shell script template (cp $SADMIN/bin/sadm_template.sh $SADMIN/usr/bin/helloWorld.sh) or Python template (cp $SADMIN/bin/sadm_template.py $SADMIN/usr/bin/helloWorld.py). To override ‘SADM_ALERT_GROUP’ and/or ‘SADM_ALERT_TYPE’ default value, remove the ‘#’ in front of the variable and change it to the value of your choice. Remember, that the alert group name you assign to ‘SADM_ALERT_GROUP’ variable, must be define in the alert group file, if not the ‘default’ alert group will be used. We have an override example, later on this page.

These lines are located in the SADMIN section near the top of the script.

Shell Script (See sadm_template.sh) :

#export SADM_ALERT_TYPE=1            # 0=None 1=AlertOnErr 2=AlertOnOK 3=Always  
#export SADM_ALERT_GROUP="default"   # AlertGroup define in alert_group.cfg  

Python Script (See sadm_template.py) :

#inst.cfg_alert_type  = 1            # 0=None 1=AlertOnErr 2=AlertOnOK 3=Always  
#inst.cfg_alert_group = "default"    # AlertGroup define in alert_group.cfg  

The script default alert type (SADM_ALERT_TYPE)

• Alert type is use at the end of the script execution, to determine whether or not to send an alert.
• The default alert type is set at installation time and is set to ‘1’ by default. You can view the actual value by looking at the value of the variable ‘SADM_ALERT_TYPE’ in the SADMIN configuration file ($SADMIN/cfg/sadmin.cfg). When you run a Python or a Shell script using the SADMIN Tools, by default it use this value.

The Alert type have four possible values :

• 0 Don’t ever send an alert, either if the script finish with success or failure.
• 1 Send an alert only if the script finish with an error (exit code not equal to 0).
• 2 Send an alert only when the script finish with success (Exit code = 0).
• 3 Always send an alert, whether the script terminate with failure or success.

Override default alert group in SADMIN System Monitor

The alert group used by the SADMIN System Monitor are specify in the configuration file ($SADMIN/cfg/hostname.smon).

• If none are specified, the ‘default’ alert group is use.
• The alert group is specified near the end of each configuration lines.
• The columns are labelled as column J for Warning and column K for Error.
• If the Alert group used in SysMon configuration don’t exist in the alert group file, the group ‘default’ is use.

Here is an example to check filesystem space usage in SysMon configuration file (hostname.smon).

#Column
#  1     2  3  4  5   6   7    8  9 A B C D E F G    H       I     J          K              L
FS/opt  49 >= 85 90 000 0000 0000 Y Y Y Y Y Y Y Y 00000000 0000 default sysadmin_sms sadm_fs_incr.sh

In the example above ;

• If the filesystem /opt percentage usage become greater or equal to 85%, a warning alert will be send to ‘default’ alertgroup.
• If the filesystem /opt percentage usage become greater or equal to 90%, an error alert will be send to ‘sysadmin_sms’alert group.

Note:
If a script (‘sadm_fs_incr.sh’) is specified in the last column of a filesystem check line, the script is executed. The script is executed when the warning level is reach (here, if the filesystem usage is greater or equal to 85%). If the filesystem is a LVM created in a volume group that have more that 10% free, the filesystem is increase by 10% (Max.2 time a day). The last column can contain a script name (placed in $SADMIN/usr/bin), nothing or a ‘-‘ (place holder).

Testing SMS/Texto alert

Let’s make a copy of the shell template script to create our test script.
Let’s begin by typing the following command to create our test script ‘sadm_test_alert.sh’ ;

# cd $SADMIN/usr/bin
/sadmin/usr/bin # cp $SADMIN/bin/sadm_template.sh sadm_test_alert.sh
/sadmin/usr/bin # nano sadm_test_alert.sh

Before we change anything
Let’s see what we have by default, for our global alert variables in our script.
Variable ‘SADM_ALERT_TYPE’ is set to ‘1’, meaning that alert is send when the script terminate with error.
Alert group that is alerted is ‘default’, as define by the content of global variable ‘SADM_ALERT_GROUP’.
We will change these variables later on.

The ‘default’ Alert Group is currently set to send email to ‘linternux@gmail.com’.

In the alert group file, we have the following group defined, we’ll use the ‘sms_sysadmin’ group for our test.

Let’s execute our test script before we make any change to it, to see what the output look like.
We can see that it run without error ‘(Script return code is 0’) and that it ran in 4 seconds.
That it ‘Requested alert only if script fail’ and that it ‘Won’t send alert’, since the script terminate with success.

Everything seem normal, so let’s modify our script to test the SMS/Texto alerting system.

Making change to test SMS/Texto alert

Let’s change the script and simulate an error, so an alert is send.

# nano sadm_test_alert.sh

Let’s provoke an error by adding a line to our test script that make ‘SADM_EXIT_CODE’ equal to ‘1’.

First change : Original code

First change : Modified code

Let’s see what we have by default, for our global alert variables in our script. The ‘SADM_ALERT_TYPE’ variable is set to ‘1’, this means that alert will be send only when the script terminate with error. The alert group that would get alerted is ‘default’, as define by the content of global variable ‘SADM_ALERT_GROUP’.
For our test, we would like to send the alert (if any) to the ‘sms_sysadmin’ alert group, so let’s change that.

Second change : Original code

Second change : Modified code

Running our test script

We are now ready to execute our test script and see if we receive this alert.

Alert that we received on our cellular

Note: It can take a few seconds up to 4-5 minutes to receive the alert. This is due to the fact that SADMIN collect clients info every 5 minutes. This is something that will be enhance in the future version.

We hope you have a better understanding of how the alarm system work in SADMIN. We could have done the same test using the Python template ($SADMIN/bin/sadm_template.py) script.