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 "Hosts", then click on "Plugins" in the left side menu and then on "Create new plugin".

Run plugins

Plugins can either be executed regularly, e.g. to execute routine tasks. Or they can react autonomously to system events.

Shedulded execution: Using Cronjob

1. To do this, either select a special host under 'Cronjob' or select all devices that you have tagged with a special tag.

2. By using the cron-expression you define the time for the regular execution. Do not forget to check the box 'Scheduled execution'.

3. Set the desired time zone for the automatic execution.

4. You can finish the creation of the plugin by clicking on 'Create new plugin' in the upper right corner.

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 {} \;

2. 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.

3. 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.

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

5. 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. Go to alerts and create a new alert. Select the reference to whose behavior the plugin should react. You can use either a host, endpoint or agentless monitoring (Observation).

2. Specify a requirement for the execution of the plugin. Assign a description.

3. Specify who should be notified about the execution of the plugin.

4. Under Automation → Plugins, select the host on which the plugin should be executed.

5. Save your alert by clicking on 'Add alert'.

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.