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

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. To do this, create a new alert under Alerts.

2. Under Reference, select the host, endpoint, or agentless monitoring (observation) whose behavior should be responded to with the plugin.

3. Define a condition for executing the plugin.

4. Enter a description.

5. Specify who should be notified when the plugin is executed.

6. Under Plugins, select the host on which the plugin should be executed and the plugin you have created.

7. Save your alert by clicking 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 alert. 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 alert 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 alert 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 alert 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.