This is an automated email from the ASF dual-hosted git repository.
riemer pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/streampipes-website.git
The following commit(s) were added to refs/heads/dev by this push:
new 0e32c10f4 Connectivity guide MQTT (#223)
0e32c10f4 is described below
commit 0e32c10f4f8558e0c618b7799cb3652332babdce
Author: Jacqueline Höllig <[email protected]>
AuthorDate: Mon Dec 15 16:08:51 2025 +0100
Connectivity guide MQTT (#223)
* env description
* text
* added introduction text
---
docs/07_connect_mqtt.md | 68 ++++++++++++++++++++++
...chitecture.md => 08_technicals-architecture.md} | 0
...als-messaging.md => 08_technicals-messaging.md} | 0
...appers.md => 08_technicals-runtime-wrappers.md} | 0
...-guidance.md => 08_technicals-user-guidance.md} | 0
docs/{08_debugging.md => 09_debugging.md} | 0
docs/{08_monitoring.md => 09_monitoring.md} | 0
docs/{09_contribute.md => 10_contribute.md} | 0
docs/{09_get-help.md => 10_get-help.md} | 0
website-v2/sidebars.json | 4 ++
10 files changed, 72 insertions(+)
diff --git a/docs/07_connect_mqtt.md b/docs/07_connect_mqtt.md
new file mode 100644
index 000000000..bee2b3177
--- /dev/null
+++ b/docs/07_connect_mqtt.md
@@ -0,0 +1,68 @@
+---
+id: connect-mqtt
+title: MQTT
+sidebar_label: MQTT
+---
+
+This document provides an overview of the MQTT connection and security
configuration options available in StreamPipes. It covers how to configure
broker connections, authentication modes, and TLS/SSL security settings —
including guidance on keystore and truststore management for secure
communication.
+
+## Notes on MQTT Settings
+
+* **Broker URL** : The URL of the MQTT broker. Specify the protocol and port,
for example:
+ * `tcp://test-server.com:1883` — for unencrypted connections
+ * `ssl://test-server.com:8883` — for secure (TLS) connections
+
+ Both the protocol (tcp:// or ssl://) and port number are required.
+* **Access Mode**: Choose between:
+ * **Unauthenticated**: No authentication required, can be used with or
without TLS
+ * **Username/Password**: Basic authentication with username and password,
can be used with or without TLS
+ * **Username**: The username for authentication
+ * **Password**: The password for authentication
+ * **Client Certificate** : Requires TLS to be enabled. Authentication is
performed using a client certificate.
+ * **Certificate PEM**: Public Key in PEM format
+ * **Private Key PEM**: Private (RSA) Key in PEM format (without password !)
+
+## TLS Configuration
+
+To enable TLS successfully, the MQTT broker’s server certificate must be
trusted by the Java Trust Store. If the certificate is **self-signed** or
issued by a **certificate authority not trusted by the Java Trust Store**, one
of the following options must be used:
+
+* **Allow self-signed certificates**: Set `SP_SECURITY_ALLOW_SELFSIGNED=true`
to permit connections using self-signed certificates.
+
+ ⚠️ Use this only in development or testing environments, as it reduces
certificate validation security.
+
+* **Provide a custom keystore**: Provide a keystore containing the MQTT
server’s certificate by setting the environment variable:
+ ```bash
+ SP_SECURITY_KEYSTORE_FILENAME=/path/to/keystore.pfx
+ ```
+
+ Depending on your keystore setup, additional environment variables may
also be required, such as:
+
+ * `SP_SECURITY_KEYSTORE_PASSWORD`
+
+ * `SP_SECURITY_KEYSTORE_TYPE`
+
+See the Security Configuration section below for more details.
+
+## Security Configuration
+
+Depending on the desired security level .env variables need to be set.
+
+| Env Variable Name | Default Value
| Description
|
+|--------------------------------|---------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
+| SP_SECURITY_KEYSTORE_FILENAME |
/streampipes-security/keystore.pfx |The file path to the keystore
containing the application's private keys and certificates used for TLS/SSL
communication. |
+| SP_SECURITY_KEYSTORE_PASSWORD | | The password
used to unlock and access the keystore file. This value must match the password
set when the keystore was created.
|
+| SP_SECURITY_KEYSTORE_TYPE | "PKCS12"
| The format or type of the keystore (e.g., PKCS12, JKS).
Determines how keys and certificates are stored and accessed.Keystore.
|
+| SP_SECURITY_KEY_PASSWORD | |
The password for the specific private key within the keystore. Required if the
key is protected by a different password than the keystore itself. |
+| SP_SECURITY_TRUSTSTORE_FILENAME| /streampipes-security/truststore.pfx
| The file path to the truststore containing trusted CA certificates used
to verify external TLS connections. |
+| SP_SECURITY_TRUSTSTORE_PASSWORD | | The
password used to unlock and access the truststore file. This must match the
password set when the truststore was created.
|
+| SP_SECURITY_TRUSTSTORE_TYPE | PKCS12
|The format or type of the truststore (e.g., PKCS12,
JKS). Defines how trusted certificates are stored and managed.
|
+| SP_SECURITY_ALLOW_SELFSIGNED | false
| If set to true, allows TLS connections using self-signed
certificates. Use only for testing or development environments, as it disables
strict certificate validation and may reduce connection security.
+
+If you do not want to accept all Selfsigned certificates (only specific ones),
you will need to mount a truststore.
+A trustore from a certificate can be build by e.g,
+
+```bash
+# Create a keystore from the private key and certificate
+openssl pkcs12 -export -in server-cert.pem -inkey server-key.pem -out
server-keystore.p12 -name mqtt
+```
+
diff --git a/docs/07_technicals-architecture.md
b/docs/08_technicals-architecture.md
similarity index 100%
rename from docs/07_technicals-architecture.md
rename to docs/08_technicals-architecture.md
diff --git a/docs/07_technicals-messaging.md b/docs/08_technicals-messaging.md
similarity index 100%
rename from docs/07_technicals-messaging.md
rename to docs/08_technicals-messaging.md
diff --git a/docs/07_technicals-runtime-wrappers.md
b/docs/08_technicals-runtime-wrappers.md
similarity index 100%
rename from docs/07_technicals-runtime-wrappers.md
rename to docs/08_technicals-runtime-wrappers.md
diff --git a/docs/07_technicals-user-guidance.md
b/docs/08_technicals-user-guidance.md
similarity index 100%
rename from docs/07_technicals-user-guidance.md
rename to docs/08_technicals-user-guidance.md
diff --git a/docs/08_debugging.md b/docs/09_debugging.md
similarity index 100%
rename from docs/08_debugging.md
rename to docs/09_debugging.md
diff --git a/docs/08_monitoring.md b/docs/09_monitoring.md
similarity index 100%
rename from docs/08_monitoring.md
rename to docs/09_monitoring.md
diff --git a/docs/09_contribute.md b/docs/10_contribute.md
similarity index 100%
rename from docs/09_contribute.md
rename to docs/10_contribute.md
diff --git a/docs/09_get-help.md b/docs/10_get-help.md
similarity index 100%
rename from docs/09_get-help.md
rename to docs/10_get-help.md
diff --git a/website-v2/sidebars.json b/website-v2/sidebars.json
index 3b8fe6552..c7265c2ef 100644
--- a/website-v2/sidebars.json
+++ b/website-v2/sidebars.json
@@ -192,6 +192,10 @@
"extend-sdk-output-strategies",
"extend-customize-ui"
],
+ "🔗 Connectivity Guide": [
+ "connect-mqtt"
+ ],
+
"🔧 Technicals": [
"technicals-architecture",
"technicals-runtime-wrappers",
