diff options
| -rw-r--r-- | docs/configuration/service/eventhandler.rst | 127 | ||||
| -rw-r--r-- | docs/configuration/service/index.rst | 1 | ||||
| -rw-r--r-- | docs/configuration/system/eventhandler.rst | 51 | ||||
| -rw-r--r-- | docs/configuration/system/index.rst | 1 |
4 files changed, 128 insertions, 52 deletions
diff --git a/docs/configuration/service/eventhandler.rst b/docs/configuration/service/eventhandler.rst new file mode 100644 index 00000000..15f08239 --- /dev/null +++ b/docs/configuration/service/eventhandler.rst @@ -0,0 +1,127 @@ +.. _event-handler: + +############# +Event Handler +############# + +********************************* +Event Handler Technology Overview +********************************* + +Event handler allows you to execute scripts when a string that matches a regex or a regex with +a service name appears in journald logs. You can pass variables, arguments, and a full matching string to the script. + + +****************************** +How to configure Event Handler +****************************** + + `1. Create an event handler`_ + + `2. Add regex to the script`_ + + `3. Add a full path to the script`_ + + `4. Add optional parameters`_ + +********************************* +Event Handler Configuration Steps +********************************* + +1. Create an event handler +========================== + + .. cfgcmd:: set service event-handler event <event-handler name> + + This is an optional command because the event handler will be automatically created after any of the next commands. + + +2. Add regex to the script +=========================================== + + .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> + + This is a mandatory command. Sets regular expression to match against log string message. + + .. note:: The regular expression matches if and only if the entire string matches the pattern. + + + +3. Add a full path to the script +================================ + + .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script> + + This is a mandatory command. Sets the full path to the script. The script file must be executable. + + + +4. Add optional parameters +========================== + + .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <sylogid name> + + This is an optional command. Filters log messages by syslog-identifier. + + .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value> + + This is an optional command. Adds environment and its value to the script. Use separate commands for each environment. + + One implicit environment exists. + + * ``message``: Full message that has triggered the script. + + .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments> + + This is an optional command. Adds arguments to the script. Arguments must be separated by spaces. + + .. note:: We don't recomend to use arguments. Using environments is more preffereble. + + +******* +Example +******* + + Event handler that monitors the state of interface eth0. + + .. code-block:: none + + set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' + set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' + set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth2' + set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' + + Event handler script + + .. code-block:: none + + #!/usr/bin/env python3 + # + # VyOS event-handler script example + from os import environ + import subprocess + from sys import exit + + # Perform actions according to requirements + def process_event() -> None: + # Get variables + message_text = environ.get('message') + interface_name = environ.get('interface_name') + interface_action = environ.get('interface_action') + # Print the message that triggered this script + print(f'Logged message: {message_text}') + # Prepare a command to run + command = f'sudo ip link set {interface_name} {interface_action}'.split() + # Execute a command + subprocess.run(command) + + if __name__ == '__main__': + try: + # Run script actions and exit + process_event() + exit(0) + except Exception as err: + # Exit properly in case if something in the script goes wrong + print(f'Error running script: {err}') + exit(1) diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 11a1a118..8607490d 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -25,3 +25,4 @@ Service ssh tftp-server webproxy + eventhandler diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst deleted file mode 100644 index 3eab4e2c..00000000 --- a/docs/configuration/system/eventhandler.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _event-handler: - -Event Handler -------------- - -Event handler allows you to execute scripts when a string that matches a regex -appears in a text stream (e.g. log file). - -It uses "feeds" (output of commands, or a named pipes) and "policies" that -define what to execute if a regex is matched. - -.. code-block:: none - - system - event-handler - feed <name> - description <feed description> - policy <policy name> - source - preset - syslog # Use the syslog logs for feed - custom - command <command to execute> # E.g. "tail -f /var/log/somelogfile" - named-pipe <path to a names pipe> - policy <policy name> - description <policy description> - event <event name> - description <event description> - pattern <regex> - run <command to run> - -In this small example a script runs every time a login failed and an interface -goes down - -.. code-block:: none - - vyos@vyos# show system event-handler - feed Syslog { - policy MyPolicy - source { - preset syslog - } - } - policy MyPolicy { - description "Test policy" - event BadThingsHappened { - pattern "authentication failure" - pattern "interface \.* index \d+ .* DOWN.*" - run /config/scripts/email-to-admin - } - }
\ No newline at end of file diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst index 9791ddb1..5bf781af 100644 --- a/docs/configuration/system/index.rst +++ b/docs/configuration/system/index.rst @@ -30,4 +30,3 @@ System :includehidden: default-route - eventhandler |