Monit¶
STATE: stable
TESTS: Playbook
API Docs: Core - Monit
Service Docs: Monit
Info¶
For mail alerts to work:
Don’t forget to configure your mailing settings at the general monit page
You will also need to set your sender-mail address in the ‘format’ field using the ‘monit_alert’ module. See the examples below.
Interfaces for ‘monit_services’ must be provided as used in the network config (p.e. ‘opt1’ instead of ‘DMZ’)
per example see menu: ‘Interface - Assignments - Interface ID (in brackets)’
this brings problems if the interface-names are not the same on both nodes when using HA-setups
Definition¶
For basic parameters see: Basics
ansibleguy.opnsense.monit_alert¶
Parameter |
Type |
Required |
Default value |
Aliases |
Comment |
---|---|---|---|---|---|
recipient |
string |
true |
- |
email, mail |
Mail address to send the alert to |
not_on |
boolean |
false |
true |
not |
Do not send alerts for the following events but on all others |
events |
list |
false |
- |
- |
Filter event-types to alert on. Invertable using the ‘not_on’ parameter. One or multiple of: ‘action’, ‘checksum’, ‘bytein’, ‘byteout’, ‘connection’, ‘content’, ‘data’, ‘exec’, ‘fsflags’, ‘gid’, ‘icmp’, ‘instance’, ‘invalid’, ‘link’, ‘nonexist’, ‘packetin’, ‘packetout’, ‘permission’, ‘pid’, ‘ppid’, ‘resource’, ‘saturation’, ‘size’, ‘speed’, ‘status’, ‘timeout’, ‘timestamp’, ‘uid’, ‘uptime’ |
format |
string |
false |
- |
- |
The email format for alerts. Subject: $SERVICE on $HOST failed. “Mail format” is a newline-separated list of properties to control the mail formatting. It is also needed to correctly set the From address |
reminder |
int |
false |
10 |
- |
Send a reminder after some cycles. Integer between 0 and 86400 |
description |
string |
false |
- |
desc |
Send a reminder after some cycles |
match_fields |
string |
false |
[‘recipient’] |
- |
Fields that are used to match configured alerts with the running config - if any of those fields are changed, the module will think it’s a new entry. At least one of: ‘recipient’, ‘not_on’, ‘events’, ‘reminder’, ‘description’ |
ansibleguy.opnsense.monit_test¶
Parameter |
Type |
Required |
Default value |
Aliases |
Comment |
---|---|---|---|---|---|
name |
string |
true |
- |
- |
Unique name of the test |
type |
string |
false |
‘Custom’ |
- |
Type of test. ‘Custom’ will not be idempotent - will be translated on the server-side. See ‘list’ module output for details. One of: ‘Existence’, ‘SystemResource’, ‘ProcessResource’, ‘ProcessDiskIO’, ‘FileChecksum’, ‘Timestamp’, ‘FileSize’, ‘FileContent’, ‘FilesystemMountFlags’, ‘SpaceUsage’, ‘InodeUsage’, ‘DiskIO’, ‘Permisssion’, ‘UID’, ‘GID’, ‘PID’, ‘PPID’, ‘Uptime’, ‘ProgramStatus’, ‘NetworkInterface’, ‘NetworkPing’, ‘Connection’, ‘Custom’ |
condition |
string |
false for state changes, else true |
- |
- |
The test condition. Per example: ‘cpu is greater than 50%’ or ‘failed host 127.0.0.1 port 22 protocol ssh’ |
action |
string |
false for state changes, else true |
‘alert’ |
- |
One of: ‘alert’, ‘restart’, ‘start’, ‘stop’, ‘exec’, ‘unmonitor’ |
path |
path |
false, true if present and type is ‘execute’ |
- |
- |
The absolute path to the script to execute - if action is set to ‘execute’. Make sure the script is executable by the Monit service |
ansibleguy.opnsense.monit_service¶
Parameter |
Type |
Required |
Default value |
Aliases |
Comment |
---|---|---|---|---|---|
name |
string |
true |
- |
- |
Unique service name |
type |
string |
false for state changes, else true |
- |
- |
One of: ‘process’, ‘file’, ‘fifo’, ‘filesystem’, ‘directory’, ‘host’, ‘system’, ‘custom’, ‘network’ |
pidfile |
path |
false |
- |
- |
|
match |
string |
false |
- |
- |
|
path |
path |
false |
- |
- |
According to the service type path can be a file or a directory |
service_timeout |
path |
false |
- |
svc_timeout |
Integer between 1 and 86400 |
address |
string |
false, true if type is one of ‘network’, ‘host’ |
- |
- |
The target IP address for ‘host’ and ‘network’ checks |
interface |
string |
false, true if type is one of ‘network’ |
- |
- |
The existing Interface for ‘Network’ checks. Alternative to ‘address’ |
start |
string |
false |
- |
- |
Absolute path to the executable with its arguments to run at service-start |
stop |
string |
false |
- |
- |
Absolute path to the executable with its arguments to run at service-stop |
tests |
list |
false |
- |
- |
Name of tests to link to the service. Not all test-types are compatible with all service-types |
depends |
list |
false |
- |
- |
Optionally define a (list of) service(s) which are required before monitoring this one, if any of the dependencies are either stopped or unmonitored this service will stop/unmonitor too |
polltime |
string |
false |
- |
- |
Set the service poll time. Either as a number of cycles ‘NUMBER CYCLES’ or Cron-style ‘* 8-19 * * 1-5’ |
description |
string |
false |
- |
- |
Examples¶
Alerts¶
- hosts: localhost
gather_facts: no
module_defaults:
group/ansibleguy.opnsense.all:
firewall: 'opnsense.template.ansibleguy.net'
api_credential_file: '/home/guy/.secret/opn.key'
ansibleguy.opnsense.list:
target: 'monit_alert'
tasks:
- name: Example
ansibleguy.opnsense.monit_alert:
recipient: 'monit-alert@template.ansibleguy.net'
# not_on: false
# events: []
# format: ''
# reminder: 10
# description: 'example'
# match_fields: ['recipient']
# enabled: true
# reload: true
- name: Adding simple
ansibleguy.opnsense.monit_alert:
recipient: 'monit-alert@template.ansibleguy.net'
- name: Changing
ansibleguy.opnsense.monit_alert:
recipient: 'monit-alert@template.ansibleguy.net'
format: |
From: monit-alert@template.ansibleguy.net
Reply-To: netmaster@template.ansibleguy.net
Subject: $SERVICE at $HOST failed
not_on: true
events: ['timestamp']
description: 'alert1'
reminder: 500
- name: Disabling
ansibleguy.opnsense.monit_alert:
recipient: 'monit-alert@template.ansibleguy.net'
format: |
From: monit-alert@template.ansibleguy.net
Reply-To: netmaster@template.ansibleguy.net
Subject: $SERVICE at $HOST failed
not_on: true
events: ['timestamp']
description: 'alert1'
reminder: 500
enabled: false
- name: Removing
ansibleguy.opnsense.monit_alert:
recipient: 'monit-alert@template.ansibleguy.net'
state: 'absent'
- name: Listing
ansibleguy.opnsense.list:
# target: 'monit_alert'
register: existing_entries
- name: Printing alerts
ansible.builtin.debug:
var: existing_entries.data
Tests¶
- hosts: localhost
gather_facts: no
module_defaults:
group/ansibleguy.opnsense.all:
firewall: 'opnsense.template.ansibleguy.net'
api_credential_file: '/home/guy/.secret/opn.key'
ansibleguy.opnsense.list:
target: 'monit_test'
tasks:
- name: Example
ansibleguy.opnsense.monit_test:
name: 'example'
# type: ''
# condition: ''
# action: 'alert'
# path: ''
# enabled: true
# reload: true
- name: Adding memory tests
ansibleguy.opnsense.monit_test:
name: 'test1'
condition: 'memory usage is greater than 90%'
type: 'SystemResource'
action: 'alert'
- name: Changing
ansibleguy.opnsense.monit_test:
name: 'test1'
condition: 'memory usage is greater than 90%'
type: 'SystemResource'
action: 'exec'
path: '/usr/local/bin/test1.sh'
- name: Disabling
ansibleguy.opnsense.monit_test:
name: 'test1'
condition: 'memory usage is greater than 90%'
type: 'SystemResource'
action: 'exec'
path: '/usr/local/bin/test1.sh'
enabled: false
- name: Removing
ansibleguy.opnsense.monit_test:
name: 'test1'
state: 'absent'
- name: Adding connection tests
ansibleguy.opnsense.monit_test:
name: 'test2'
condition: 'failed host 127.0.0.1 port 22 protocol ssh'
type: 'Connection'
- name: Listing
ansibleguy.opnsense.list:
# target: 'monit_test'
register: existing_entries
- name: Printing tests
ansible.builtin.debug:
var: existing_entries.data
Services¶
- hosts: localhost
gather_facts: no
module_defaults:
group/ansibleguy.opnsense.all:
firewall: 'opnsense.template.ansibleguy.net'
api_credential_file: '/home/guy/.secret/opn.key'
ansibleguy.opnsense.list:
target: 'monit_service'
tasks:
- name: Example
ansibleguy.opnsense.monit_service:
name: 'example'
# type: ''
# pidfile: ''
# match: ''
# path: ''
# timeout: 300
# address: ''
# interface: ''
# start: ''
# stop: ''
# tests: []
# depends: []
# polltime: ''
# description: 'example'
# enabled: true
# reload: true
- name: Adding simple
ansibleguy.opnsense.monit_service:
name: 'service1'
type: 'custom'
start: '/usr/local/bin/test1_start.sh'
- name: Changing
ansibleguy.opnsense.monit_service:
name: 'service1'
type: 'custom'
start: '/usr/local/bin/service1_start.sh'
stop: '/usr/local/bin/service1_stop.sh'
tests: ['test1']
- name: Adding another
ansibleguy.opnsense.monit_service:
name: 'service2'
type: 'network'
interface: 'opt2'
depends: ['service1']
- name: Disabling
ansibleguy.opnsense.monit_service:
name: 'service2'
type: 'network'
interface: 'opt2'
depends: ['service1']
enabled: false
- name: Removing
ansibleguy.opnsense.monit_service:
name: 'service2'
state: 'absent'
- name: Listing
ansibleguy.opnsense.list:
# target: 'monit_service'
register: existing_entries
- name: Printing services
ansible.builtin.debug:
var: existing_entries.data
Practical example¶
Mail notification on IDS alert: see documentation
- hosts: localhost
gather_facts: no
module_defaults:
group/ansibleguy.opnsense.all:
firewall: 'opnsense.template.ansibleguy.net'
api_credential_file: '/home/guy/.secret/opn.key'
tasks:
- name: Adding test
ansibleguy.opnsense.monit_test:
name: 'SURICATA_EVE'
condition: 'content = "blocked"'
type: 'FileContent'
action: 'alert'
- name: Adding service
ansibleguy.opnsense.monit_service:
name: 'SURICATA_ALERT'
type: 'file'
path: '/var/log/suricata/eve.json'
tests: ['SURICATA_EVE']