Plugins

Plugins are a very powerful tool. Here you can create your own scripts, which can then be executed on hosts you choose. For example, you can use this to change the firewall settings on all systems at the same time. Currently we support the runtime environments Bash (Linux), Python 3 (Linux) and PowerShell (Windows).

What are Plugins?

Plugins are scripts that you can run on your systems on a periodic basis or in response to a system event. You can run plugins on via tags on multiple systems or just on single systems. You can write the scripts yourself, but for certain purposes there are already templates.

Parallelism in the execution of plug-ins

The agent can execute several simultaneously scheduled plugins in parallel. The default number of plugins executed in parallel is 10. This setting can be configured in the config.json file in the “override” → “plugins” section via the “concurrency” value. The following applies:

• Value 0 means that the default number of 10 plugins running in parallel is used.

• If you want to adjust the number of plugins running in parallel, you can enter a different value here.

An example of a corresponding configuration in the config.json:

{
  "override": {
    "plugins": {
      "disabled": false,
      "concurrency": 0
    }
  }
}

Please note that the system load generated by each plugin must be taken into account if plugins are planned at the same time in order to avoid overloading your systems.

Plugin templates

On the Enginsight platform you can already find some templates for plugins. Further suggestions and ideas can be found at https://github.com/enginsight.

Create Plugins

To create a new plugin, click on Add plugin.

1. Provide a name and a brief description.

2. Then set the appropriate script language. Available options are Bash (Shell), Python 3, and PowerShell.

3. Now insert your script in the selected script language.

4. Take advantage of the ability to define fields that should be extracted for visualization on the platform.

5. You can also schedule the automatic execution of your script via the corresponding setting.

6. Now assign hosts. Either select appropriate ones from the list or use the tag system for allocation. Assign your plugin to a host and maintain an overview in the chosen host's Custom Metrics overview.
7. Finally, add your plugin using the button.

Example: MySQL database backup

A popular use for regularly executed plugins is to perform backups of, for example, a MySQL database.

1. First create a new plugin as described. Use the following bash script as a template:

#!/bin/bash
# Shell script to backup MySQL database
#==============================================
# Author       : Name
# Organisation : Unternehmen
# Created      : xx.xx.xxx, xx:xx:xx
#==============================================

# Set these variables
MyUSER=""	# DB_USERNAME
MyPASS=""	# DB_PASSWORD
MyHOST=""	# DB_HOSTNAME

# Backup Dest directory
DEST="" # /home/username/backups/DB

# Email for notifications
EMAIL=""

# How many days old files must be to be removed
DAYS=3

# Linux bin paths
MYSQL="$(which mysql)"
MYSQLDUMP="$(which mysqldump)"
GZIP="$(which gzip)"

# Get date in dd-mm-yyyy format
NOW="$(date +"%d-%m-%Y_%s")"

# Create Backup sub-directories
MBD="$DEST/$NOW/mysql"
install -d $MBD

# DB skip list
SKIP="information_schema
another_one_db"

# Get all databases
DBS="$($MYSQL -h $MyHOST -u $MyUSER -p$MyPASS -Bse 'show databases')"

# Archive database dumps
for db in $DBS
do
    skipdb=-1
    if [ "$SKIP" != "" ];
    then
		for i in $SKIP
		do
			[ "$db" == "$i" ] && skipdb=1 || :
		done
    fi
 
    if [ "$skipdb" == "-1" ] ; then
    	FILE="$MBD/$db.sql"
	$MYSQLDUMP -h $MyHOST -u $MyUSER -p$MyPASS $db > $FILE
    fi
done

# Archive the directory, send mail and cleanup
cd $DEST
tar -cf $NOW.tar $NOW
$GZIP -9 $NOW.tar

echo "MySQL backup is completed! Backup name is $NOW.tar.gz" | mail -s "MySQL backup" $EMAIL
rm -rf $NOW

# Remove old files
find $DEST -mtime +$DAYS -exec rm -f {} \;

1. Enter your username, password and hostname of the MySQL database into the script. Also modify the path to the backup directory. Please note that further adjustments may be necessary for your database systems.

2. Now go to 'Cronjob' and select 'Scheduled execution' and the appropriate host. You can also switch the plugin to multiple hosts at the same time via tags.

3. Assign a cron expression to specify when the backup should be executed. For example * 2 * * 3 for every Wednesday at 2am.

4. Click on 'Create new plugin' to create the new plugin. If you want, you can test the plugin. To do this, click on 'Test' and select a desired host.

Autonomous reaction to system event: via alerting

1. Erstellen Sie dazu unter Alarme einen neuen Alarm. Wählen Sie unter Referenz denjenigen Host, Endpunkt oder diejenige agentlose Überwachung (Observation), auf dessen Verhalten mit dem Plugin reagiert werden soll.

2. Legen Sie eine Bedingung für die Ausführung des Plugins fest.

3. Vergeben Sie eine Beschreibung.

4. Legen Sie fest, wer über die Ausführung des Plugins benachrichtigt werden soll.

5. Wählen Sie unter Plugins den Host, auf dem das Plugin ausgeführt werden soll und das von Ihnen erstellte Plugin aus.

6. Speichern Sie Ihren Alarm, indem Sie auf Alarm hinzufügen klicken.

Example: Restart Apache web server

Create a new plugin as described. Use the following bash script as a template:

#!/bin/bash
#==============================================
# Author       : Name
# Organisation : Unternehmen
# Created      : xx.xx.xxx, xx:xx:xx
#==============================================

ps auxw | grep apache2 | grep -v grep > /dev/null

if [ $? != 0 ]
then
        /etc/init.d/apache2 start > /dev/null
fi

Now create an alarm. In this case, there are two scenarios that can trigger the plugin to run. One is that the Apache web server process is not running, the other is that the web page is not available.

Process is not executed

1. Select the Host alarm type and the corresponding server as a reference.

2. Set the 'Process is not running' requirement and select the Apache process from the list that opens.

3. Assign a description and specify who should be notified.

4. Select the host on which the plugin should be executed, in this case it is identical to the reference.

5. Select the created plugin and add the alert.

Website not available

1. Select the alarm type Endpoint and as a reference a web page running on the Apache web server. If you have several websites hosted on the corresponding web server, it makes sense to switch the alarm to all of them via Tag.

2. Select the 'Web page unavailable' requirement.

3. Enter a description and specify who should be notified.

4. Select the host where the plugin should run, meaning where Apache is located.

5. Select the created plugin and add the alert.