From 8f70f662f01c5d2af7f3c7682e55c8928d5e42e4 Mon Sep 17 00:00:00 2001
From: Timo Sirainen <timo.sirainen@open-xchange.com>
Date: Fri, 30 Aug 2024 20:32:27 +0300
Subject: [PATCH] Add execute settings

---
 data/settings.js            | 87 +++++++++++++++++++++++++++++++++++
 docs/core/config/execute.md | 92 +++++++++++++++++++++++++++++++++++++
 2 files changed, 179 insertions(+)
 create mode 100644 docs/core/config/execute.md

diff --git a/data/settings.js b/data/settings.js
index 19ec4137f..1247b22d3 100644
--- a/data/settings.js
+++ b/data/settings.js
@@ -4909,6 +4909,93 @@ Format used for serializing the event.`
 Format-specific arguments used for serializing the event.`
 	},
 
+	execute: {
+		tags: [ 'execute' ],
+		values: setting_types.NAMED_LIST_FILTER,
+		seealso: [ '[[link,execute_scripts]]' ],
+		text: `
+Configure external execution script. Used by various different features, such
+as [[link,welcome]]. Currently only a single execute block (per feature) is
+allowed.`
+	},
+
+	execute_args: {
+		tags: [ 'execute' ],
+		values: setting_types.STRING,
+		text: `
+External execution script arguments. The parameters are split by space
+characters. Currently escape characters are not supported.`
+	},
+
+	execute_driver: {
+		tags: [ 'execute' ],
+		values: setting_types.ENUM,
+		values_enum: [ 'unix', 'fork', 'tcp' ],
+		seealso: [ '[[link,execute_scripts]]' ],
+		text: `
+How to execute the external script:
+
+\`unix\`
+:   Use UNIX socket connection to a \`script\` service listening in
+    [[setting,execute_unix_socket_path]].
+
+\`fork\`
+:   Fork and execute the [[setting,execute_fork_path]] binary directly.
+
+\`tcp\`
+:   Use TCP connection to a \`script\` service listening in
+    [[setting,execute_tcp_host]]:[[setting,execute_tcp_port]].`
+	},
+
+	execute_fork_path: {
+		tags: [ 'execute' ],
+		values: setting_types.STRING,
+		default: '[[setting,execute_name]]',
+		text: `
+Path to the binary that is executed with [[setting,execute_driver,fork]].`
+	},
+
+	execute_name: {
+		tags: [ 'execute' ],
+		values: setting_types.STRING,
+		text: `
+Name of the execution script. This is the [[setting,execute]] named filter
+name. It is also used to provide a default driver-specific settings:
+
+\`unix\`
+:   Used as the default for [[setting,execute_unix_socket_path]].
+
+\`fork\`
+:   Used as the default for [[setting,execute_fork_path]].
+
+\`tcp\`
+:   Used as the default for [[setting,execute_tcp_host]]:[[setting,execute_tcp_port]].`
+	},
+
+	execute_tcp_host: {
+		tags: [ 'execute' ],
+		values: setting_types.STRING,
+		default: '[[setting,execute_name,host:]]',
+		text: `
+TCP host where to connect to with [[setting,execute_driver,tcp]].`
+	},
+
+	execute_tcp_port: {
+		tags: [ 'execute' ],
+		values: setting_types.STRING,
+		default: '[[setting,execute_name,:port]]',
+		text: `
+TCP port where to connect to with [[setting,execute_driver,tcp]].`
+	},
+
+	execute_unix_socket_path: {
+		tags: [ 'execute' ],
+		values: setting_types.STRING,
+		default: '[[setting,execute_name]]',
+		text: `
+UNIX socket path where to connect to with [[setting,execute_driver,unix]].`
+	},
+
 	fifo_listener: {
 		tags: [ 'service' ],
 		values: setting_types.NAMED_LIST_FILTER,
diff --git a/docs/core/config/execute.md b/docs/core/config/execute.md
new file mode 100644
index 000000000..fce809e04
--- /dev/null
+++ b/docs/core/config/execute.md
@@ -0,0 +1,92 @@
+---
+layout: doc
+title: Execute Scripts
+dovecotlinks:
+  execute_scripts: Execute Scripts
+  execute_unix:
+    hash: execute-unix
+    text: "execute: UNIX Sockets"
+  execute_tcp:
+    hash: execute-tcp
+    text: "execute: TCP Sockets"
+  execute_fork:
+    hash: execute-fork
+    text: "execute: Fork and Execute"
+---
+
+# Execute Scripts
+
+Some features, e.g. [[link,welcome]] execute an external script.
+This is configured with the [[setting,execute]] settings. Currently only
+a single script execution at a time is supported.
+
+Supported script execution drivers are:
+
+| Name | Description |
+| --- | --- |
+| [[link,execute_unix,unix]] | Connect to UNIX socket. |
+| [[link,execute_tcp,tcp]] | Connect to TCP socket. |
+| [[link,execute_fork,fork]] | Fork and execute the script directly. |
+
+## UNIX Sockets
+
+Execute the script via a script service listening on a UNIX socket. The service
+must execute the `script` binary to provide the proper communication API.
+
+Example:
+
+```[dovecot.conf]
+execute test-script {
+  #driver = unix # default
+  args = hello %{user}
+}
+service test-script-service {
+  execute = script /usr/local/bin/test-script.sh one
+  unix_listener test-script {
+    path = 0666
+  }
+}
+```
+
+The `test-script.sh` is executed with parameters `one hello <username>`.
+
+## TCP sockets
+
+Execute the script via a script service listening on a TCP socket. The service
+must execute the `script` binary to provide the proper communication API.
+
+Example:
+
+```[dovecot.conf]
+execute localhost:12345 {
+  driver = tcp # default
+  args = hello %{user}
+}
+service test-script-service {
+  execute = script /usr/local/bin/test-script.sh one
+  inet_listener {
+    port = 12345
+  }
+}
+```
+
+The `test-script.sh` is executed with parameters `one hello <username>`.
+
+## Fork and Execute
+
+Fork the process and execute the script directly.
+
+Example:
+
+```[dovecot.conf]
+execute /usr/local/bin/test-script.sh {
+  driver = fork
+  args = hello %{user}
+}
+```
+
+The `test-script.sh` is executed with parameters `hello <username>`.
+
+## Execute Settings
+
+<SettingsComponent tag="execute" />