summaryrefslogtreecommitdiff
path: root/docs/configuration
diff options
context:
space:
mode:
authorRobert Göhler <github@ghlr.de>2022-07-07 17:06:48 +0200
committerGitHub <noreply@github.com>2022-07-07 17:06:48 +0200
commit14edf2698d3b063a06e3964dd1bd2961711d1d81 (patch)
tree651c58c451052683b7738c9d9641d3ccf900fe84 /docs/configuration
parenta04df9e0c61fee87f297972db17fee93878016de (diff)
parente1b2a017fdca013fa4aa7e16e5c56cef8d845ba3 (diff)
downloadvyos-documentation-14edf2698d3b063a06e3964dd1bd2961711d1d81.tar.gz
vyos-documentation-14edf2698d3b063a06e3964dd1bd2961711d1d81.zip
Merge pull request #804 from aapostoliuk/eventhandlerdocs
event handler: T3083: Created documentation for the new Event Handler
Diffstat (limited to 'docs/configuration')
-rw-r--r--docs/configuration/service/eventhandler.rst127
-rw-r--r--docs/configuration/service/index.rst1
-rw-r--r--docs/configuration/system/eventhandler.rst51
-rw-r--r--docs/configuration/system/index.rst1
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