Skip to content

Trigger Scripts

Script Types

LogZilla can execute various types of scripts, including:

  • Python
  • Perl
  • sh, bash, zsh, csh, etc.
  • Compiled Executables

Script Environment

All triggers passed to a script contain the matched message information as
environment variables. To manipulate any of the data, simply reference the
corresponding environment variable.

The following list of variables is automatically passed into each script:

# EVENT_ID                      =   <int>
# EVENT_SEVERITY                =   <integer>
# EVENT_FACILITY                =   <integer>
# EVENT_TRIGGER_IDS             =   <list of integers>
# EVENT_MESSAGE                 =   <string>
# EVENT_HOST                    =   <string>
# EVENT_PROGRAM                 =   <string>
# EVENT_CISCO_MNEMONIC          =   <string>
# EVENT_USER_TAGS               =   <string>
# EVENT_EXTRA_FIELDS            =   <string>
# EVENT_STATUS                  =   <integer>
# EVENT_FIRST_OCCURRENCE        =   <float>
# EVENT_LAST_OCCURRENCE         =   <float>
# EVENT_COUNTER                 =   <integer>
# EVENT_TRIGGER_ID              =   <integer>
# EVENT_TRIGGER_AUTHOR          =   <string>
# EVENT_TRIGGER_AUTHOR_EMAIL    =   <string>

Script Execution

Scripts may be executed directly or within dedicated Docker containers,
depending on your script's requirements:

Simple Scripts

For simple scripts that do not require anything beyond what is available in a
standard Linux install, simply place your script in the /etc/logzilla/scripts
directory and select it in the UI when creating a trigger.

Here's an example of a simple shell script that logs the environment variables
to the logzilla.log:

  1. Create a test.sh file in /etc/logzilla/scripts/:

    cat << EOF > /etc/logzilla/scripts/test.sh
#!/bin/bash
# Print all environment variables matching '^EVENT_' to the log
echo "Test script env vars" >> /var/log/logzilla/logzilla.log
env | grep '^EVENT_' >> /var/log/logzilla/logzilla.log
EOF

  2. Make sure the script is executable:

    chmod 755 /etc/logzilla/scripts/test.sh

Once the script is in place and executable, you can select it from the LogZilla
UI when creating a trigger.

Custom Scripts

For scripts that require additional libraries or programs, such as Python
packages, you may use your own Docker image containing all required modules.
You can also use any images available on Docker Hub.

Working Example: Custom Docker Container

In this example, we will create a container that brings up an interface on a Cisco device after it is shut down, then send a notification to Slack. The script uses Python and Netmiko to SSH into the device and apply the necessary configuration changes.

Note: All of the files below are also available on our GitHub Repo

Dockerfile

Create a new file named Dockerfile with the following content:

# Use a minimal Python base image
FROM python:3-slim

# Copy the requirements.txt file to the container
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

Requirements.txt

Create a requirements.txt file with the following content:

paramiko
requests
pyyaml
netmiko

Python Script

NOTE: The following sample code is user-contributed and should be reviewed prior to using it verbatim in production.

Yaml and Slack Key

Create a compliance.yaml file and update your Slack webhook key. Edit the
YAML configuration to fit your environment by updating the following
variables:

# Cisco credentials
ciscoUsername: "cisco"
ciscoPassword: "cisco"

# Slack settings
# Replace the value below with your actual post URL
posturl: "https://hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX"
default_channel: "#demo"
slack_user: "logzilla-bot"

# Logging and debug settings
log_file: "/var/log/logzilla/logzilla.log"

# Change to 0 in production:
debug_level: 2  # 0, 1, or 2

bring_interface_up: true

# Execution timeout for device connection and Slack:
timeout: 10

Your directory should contain:

  • Dockerfile
  • compliance.py
  • compliance.yaml
  • requirements.txt

Docker Build

Build the Docker image using the following command:

docker build -t custom-trigger-cisco-compliance .

Verify Image Build

Verify that the image was successfully built:

# docker image ls
REPOSITORY                        TAG             IMAGE ID       CREATED          SIZE
custom-trigger-cisco-compliance   latest          36188b2516db   19 minutes ago   189MB

Copy Files

After building the Docker image manually copy the necessary files to /etc/logzilla/scripts and make the script executable.

TIP: To prevent files from appearing in the selection menu in the UI, precede the filename with a ., for example: .compliance.yaml.

cp compliance.py /etc/logzilla/scripts/compliance
cp compliance.yaml /etc/logzilla/scripts/.compliance.yaml
chmod 755 /etc/logzilla/scripts/compliance

Edit the compliance.yaml file for your environment.

LogZilla UI

Log into the LogZilla Web Interface and:

  • Create a new trigger from the trigger menu.
  • Select the execute script option.
  • From the dropdown menu, select compliance.py.

Any patterns matching this trigger will now execute the script.

Execute Script