docs: administration: transport-security: add tls.verify_client_cert parameter

[eschabell]

• Documents new input-only TLS option for server-side client certificate verification (mutual TLS), added in commits 0b0118b9a and 04f6b5493

Summary by CodeRabbit

• Documentation
  • Transport security documentation extended with mutual TLS (mTLS) support for input plugins. New tls.verify_client_cert configuration option (default: off) enables verification of client TLS certificates. Existing transport security options have been reformatted and realigned for improved clarity and consistency.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation update to the TLS configuration properties table in the transport security guide. A new tls.verify_client_cert property was added (default off) to enable mutual TLS for input plugins. Minor formatting adjustments were applied to existing table rows.

Changes

Cohort / File(s)	Summary
TLS Documentation administration/transport-security.md	Added tls.verify_client_cert property (default off) to enable mutual TLS verification for input plugins. Minor formatting realignment applied to existing TLS configuration rows.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• patrick-stephens

Poem

🐰 A rabbit hops through security's gate,
With client cert checks—how truly great!
mTLS now blooms in the input plugin's care,
Trust flows both ways through the transport's air! 🔐

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the main change: adding documentation for the tls.verify_client_cert parameter to the transport-security documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

administration/transport-security.md (3)

30-30: Consider adding a usage example for the new parameter.

The new tls.verify_client_cert parameter enables an important security feature (mutual TLS), but no example demonstrates how to use it. Consider adding an example showing how to configure an input plugin with both tls.verify_client_cert and tls.ca_file to enable client certificate verification.

Example location suggestion: After line 111 or in a new subsection under "Example: enable TLS on HTTP input" showing how to extend it with client certificate verification.

💡 Example snippet to consider

pipeline:
  inputs:
    - name: http
      port: 9999
      tls: on
      tls.verify: off
      tls.crt_file: server.crt
      tls.key_file: server.key
      tls.verify_client_cert: on
      tls.ca_file: client_ca.crt

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@administration/transport-security.md` at line 30, Add a usage example
demonstrating how to enable mutual TLS by showing `tls.verify_client_cert` set
to on together with `tls.ca_file` and the existing server TLS fields; update the
"Example: enable TLS on HTTP input" section (or add a new subsection immediately
after it) to include an extended YAML snippet that shows `tls: on`,
`tls.crt_file`, `tls.key_file`, `tls.verify_client_cert: on` and `tls.ca_file:
client_ca.crt` so readers can see how to configure the HTTP input plugin for
client certificate verification using the `tls.verify_client_cert` and
`tls.ca_file` parameters.

---

32-32: Consider clarifying certificate requirements for mutual TLS.

Line 32 correctly states that input plugins require a certificate and private key for TLS. However, with the new tls.verify_client_cert parameter, mutual TLS also requires a CA certificate (tls.ca_file) to validate client certificates. Consider adding a note to clarify this distinction.

📝 Proposed clarification

 To use TLS on input plugins, you must provide both a certificate and a private key.
+For mutual TLS (mTLS) using `tls.verify_client_cert`, you must also provide a CA certificate via `tls.ca_file` to validate connecting client certificates.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@administration/transport-security.md` at line 32, Update the sentence about
TLS for input plugins to clarify mutual TLS requirements: when using
tls.verify_client_cert, in addition to the certificate and private key you must
provide a CA certificate (tls.ca_file) to validate client certificates;
reference the tls.verify_client_cert and tls.ca_file parameters and add a short
note explaining this distinction so users know both server cert/key and the CA
file are required for mutual TLS.

---

30-30: Simplify description to reduce redundancy.

The description mentions the input plugin scope twice ("for input plugins" and "Only applies to input plugins"). Consider consolidating for better clarity.

✏️ Proposed simplification

-| `tls.verify_client_cert`  | Require and verify the TLS certificate presented by a connecting client. Enables mutual TLS (mTLS) for input plugins. Only applies to input plugins. | `off`   |
+| `tls.verify_client_cert`  | Require and verify the TLS certificate presented by a connecting client. Enables mutual TLS (mTLS). Only applies to input plugins. | `off`   |

Alternatively, for even more conciseness:

-| `tls.verify_client_cert`  | Require and verify the TLS certificate presented by a connecting client. Enables mutual TLS (mTLS) for input plugins. Only applies to input plugins. | `off`   |
+| `tls.verify_client_cert`  | Require and verify the TLS certificate presented by a connecting client for mutual TLS (mTLS). Only applies to input plugins. | `off`   |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@administration/transport-security.md` at line 30, The description for
tls.verify_client_cert is redundant; update the text to a single concise
sentence that conveys it enables mutual TLS and only applies to input plugins.
Replace the current wording with either "Require and verify the TLS certificate
presented by a connecting client (enables mutual TLS for input plugins)." or the
shorter "Require and verify client TLS certificates to enable mutual TLS for
input plugins." Ensure the setting name tls.verify_client_cert remains
unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@administration/transport-security.md`:
- Line 30: Add the tls.verify_client_cert parameter to the input plugin docs:
update elasticsearch.md to explicitly document support for
tls.verify_client_cert (show the boolean option and default `off`, demonstrate
enabling it for mTLS on input plugins and mention required client cert/key
locations), and add the same parameter note to the TLS sections of
kubernetes-events.md and opentelemetry.md so they reference
tls.verify_client_cert alongside existing TLS settings; ensure the description
matches transport-security.md (only applies to input plugins, enables mTLS) and
include a short usage example and default value.

---

Nitpick comments:
In `@administration/transport-security.md`:
- Line 30: Add a usage example demonstrating how to enable mutual TLS by showing
`tls.verify_client_cert` set to on together with `tls.ca_file` and the existing
server TLS fields; update the "Example: enable TLS on HTTP input" section (or
add a new subsection immediately after it) to include an extended YAML snippet
that shows `tls: on`, `tls.crt_file`, `tls.key_file`, `tls.verify_client_cert:
on` and `tls.ca_file: client_ca.crt` so readers can see how to configure the
HTTP input plugin for client certificate verification using the
`tls.verify_client_cert` and `tls.ca_file` parameters.
- Line 32: Update the sentence about TLS for input plugins to clarify mutual TLS
requirements: when using tls.verify_client_cert, in addition to the certificate
and private key you must provide a CA certificate (tls.ca_file) to validate
client certificates; reference the tls.verify_client_cert and tls.ca_file
parameters and add a short note explaining this distinction so users know both
server cert/key and the CA file are required for mutual TLS.
- Line 30: The description for tls.verify_client_cert is redundant; update the
text to a single concise sentence that conveys it enables mutual TLS and only
applies to input plugins. Replace the current wording with either "Require and
verify the TLS certificate presented by a connecting client (enables mutual TLS
for input plugins)." or the shorter "Require and verify client TLS certificates
to enable mutual TLS for input plugins." Ensure the setting name
tls.verify_client_cert remains unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 71600758-d41e-4f2d-9158-26bedc8a80e9

📥 Commits

Reviewing files that changed from the base of the PR and between d1a3a63 and 6301e5a.

📒 Files selected for processing (1)

• administration/transport-security.md

[eschabell]

@patrick-stephens ready for review!