event handler: T3083: Created documentation for the new Event Handler

Created documentation for the new Event Handler module

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 9b4bf2e3..5a6cb7b1 100644
--- a/docs/configuration/system/index.rst
+++ b/docs/configuration/system/index.rst
@@ -29,4 +29,3 @@ System
    :includehidden:
 
    default-route
-   eventhandler