summaryrefslogtreecommitdiff
path: root/docs/configuration/service/md-eventhandler.md
diff options
context:
space:
mode:
authorYuriy Andamasov <yuriy@vyos.io>2026-05-02 18:59:58 +0300
committerYuriy Andamasov <yuriy@vyos.io>2026-05-06 16:18:03 +0300
commit5a35f4d30e5c16bd85e811176cffa86b721112b7 (patch)
tree8339f5c27d85b97196825e825f4139fe4827876c /docs/configuration/service/md-eventhandler.md
parent38ff65941d6cd771700480fd2e6c88dad6a01c24 (diff)
downloadvyos-documentation-5a35f4d30e5c16bd85e811176cffa86b721112b7.tar.gz
vyos-documentation-5a35f4d30e5c16bd85e811176cffa86b721112b7.zip
refactor(swap): rename imported .md files to md- prefix for swap mechanism
Restore the canary file naming convention that swap_sources.py expects: the imported MyST pages now live as docs/<dir>/md-<name>.md alongside the existing docs/<dir>/<name>.rst, so swap_sources.py --swap can rename them into place at build time. - 254 .md files renamed (every page with a matching .rst counterpart) - 2 MyST-only pages left at their final names (no .rst exists, no swap needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md All 114 stems listed in docs/_swap.txt now have a corresponding md-<name>.md source file ready to swap in. 🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/configuration/service/md-eventhandler.md')
-rw-r--r--docs/configuration/service/md-eventhandler.md130
1 files changed, 130 insertions, 0 deletions
diff --git a/docs/configuration/service/md-eventhandler.md b/docs/configuration/service/md-eventhandler.md
new file mode 100644
index 00000000..48031909
--- /dev/null
+++ b/docs/configuration/service/md-eventhandler.md
@@ -0,0 +1,130 @@
+(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](#create-an-event-handler)
+>
+> [2. Add regex to the script](#add-regex-to-the-script)
+>
+> [3. Add a full path to the script](#add-a-full-path-to-the-script)
+>
+> [4. Add optional parameters](#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 \<syslogid 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 recommend to use arguments. Using environments
+is more preferable.
+:::
+```
+
+
+## Example
+
+Event handler that monitors the state of interface eth0.
+
+```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 'eth0'
+set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py'
+```
+
+Event handler script
+
+```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)
+```
+