From a24db2e995b29ea749b298e522ce7ef1de798541 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Fri, 21 Aug 2026 12:29:35 +0100 Subject: [PATCH] docs: Document the [telemetry] TLS path readability check Bring the three documentation surfaces in line with the new parse-time check: - The @throws clause on makeTelemetrySetup now names the third failure condition and records that an empty path is skipped. - cfg/xrpld-example.cfg states, under all three TLS keys, that with enabled=1 and use_tls=1 a path that does not exist or cannot be read stops startup. The tls_ca_cert wording still says that empty selects the system CA store, since only a path that is set is checked. - The runbook troubleshooting entry gains a third bullet for the "cannot be read" message, whose remedy is the path or its permissions rather than the certificate and key pairing. Documentation only; no behaviour change. --- cfg/xrpld-example.cfg | 19 ++++++++++++++----- docs/telemetry-runbook.md | 21 ++++++++++++++------- include/xrpl/telemetry/Telemetry.h | 5 ++++- 3 files changed, 32 insertions(+), 13 deletions(-) diff --git a/cfg/xrpld-example.cfg b/cfg/xrpld-example.cfg index a3bd8673ce..9f74c99c82 100644 --- a/cfg/xrpld-example.cfg +++ b/cfg/xrpld-example.cfg @@ -1714,6 +1714,11 @@ validators.txt # Path to a PEM-encoded CA certificate bundle for TLS verification. # Only used when use_tls=1. Default: empty (system CA store). # +# Leaving this empty stays valid and selects the system CA store. A path +# that is set is checked like the client paths below: with enabled=1 and +# use_tls=1, one that does not exist or cannot be read makes xrpld fail +# to start. +# # tls_client_cert= # # Path to this node's PEM-encoded client certificate, presented to the @@ -1723,15 +1728,19 @@ validators.txt # To enable mTLS, both tls_client_cert and tls_client_key must be # specified. If only one is provided, xrpld will fail to start. Providing # them while use_tls=0 also fails to start, rather than being ignored. -# Both checks apply only when enabled=1; with telemetry disabled these -# settings are read but never validated. +# With use_tls=1 each path is opened at startup, so one that does not +# exist or cannot be read fails to start too, rather than failing later +# as an opaque TLS handshake error. All three checks apply only when +# enabled=1; with telemetry disabled these settings are read but never +# validated. # # tls_client_key= # # Path to the PEM-encoded private key for tls_client_cert. Required -# whenever tls_client_cert is set. Requires use_tls=1. Both conditions -# are enforced exactly as described under tls_client_cert above: when -# enabled=1, breaking either one makes xrpld fail to start. +# whenever tls_client_cert is set. Requires use_tls=1, and must be +# readable. All three conditions are enforced exactly as described under +# tls_client_cert above: when enabled=1, breaking any one of them makes +# xrpld fail to start. # Default: empty. # # Head sampling is intentionally fixed at 1.0 (sample everything) and is diff --git a/docs/telemetry-runbook.md b/docs/telemetry-runbook.md index f30b87eaea..eb3a6e9c28 100644 --- a/docs/telemetry-runbook.md +++ b/docs/telemetry-runbook.md @@ -612,12 +612,13 @@ Three dashboards are pre-provisioned in `docker/telemetry/grafana/dashboards/`: exception thrown while the `Application` object is constructed prints the same `Unable to start` prefix, so confirm the text after the colon begins with `[telemetry]` before using this entry -- Cause: the `[telemetry]` mTLS keys (`tls_client_cert` and `tls_client_key`) - contradict each other. Only these two mTLS checks are gated on `enabled=1`; - the rest of the section is still read when telemetry is off, so a malformed - value in any key — including `enabled` itself, which is read before the gate - — still fails startup with a different message -- Fix: the two checks need different remedies, and the printed message says +- Cause: either the `[telemetry]` mTLS keys (`tls_client_cert` and + `tls_client_key`) contradict each other, or one of the TLS certificate paths + cannot be read. Only these three checks are gated on `enabled=1`; the rest of + the section is still read when telemetry is off, so a malformed value in any + key — including `enabled` itself, which is read before the gate — still fails + startup with a different message +- Fix: the three checks need different remedies, and the printed message says which one fired - `tls_client_cert and tls_client_key must be set together` — exactly one of the two paths is set. Either delete the one that is set, or add the missing @@ -626,8 +627,14 @@ Three dashboards are pre-provisioned in `docker/telemetry/grafana/dashboards/`: - `tls_client_cert/tls_client_key require use_tls=1` — both paths are set but TLS is off. Either set `use_tls=1`, or delete **both** paths. Deleting only one of them trips the first check + - ` cannot be read` — the named key (`tls_ca_cert`, `tls_client_cert` or + `tls_client_key`) points at a file the node cannot open; the message also + prints the path and the OS error. Fix the path or its permissions — the + pairing is not what is wrong here. This check runs only when `use_tls=1`, + and an empty `tls_ca_cert` is always accepted (it selects the system CA + store) - If you did not mean to enable telemetry at all, set `enabled=0` — that - clears both checks whichever one fired + clears all three checks whichever one fired ## Performance Tuning diff --git a/include/xrpl/telemetry/Telemetry.h b/include/xrpl/telemetry/Telemetry.h index a34e3cf19b..bf5af0156c 100644 --- a/include/xrpl/telemetry/Telemetry.h +++ b/include/xrpl/telemetry/Telemetry.h @@ -431,7 +431,10 @@ makeTelemetry(Telemetry::Setup const& setup, beast::Journal journal); * @return A populated Setup struct with defaults for missing values. * @throws std::runtime_error If `enabled` is set and the mutual TLS (mTLS) * settings contradict each other: only one of `tls_client_cert`/`tls_client_key` - * is given, or a client certificate is given while `use_tls` is 0. Those two + * is given, or a client certificate is given while `use_tls` is 0. Also if + * `enabled` and `use_tls` are both set and a non-empty `tls_ca_cert`, + * `tls_client_cert` or `tls_client_key` cannot be read; an empty path is skipped, + * so an empty `tls_ca_cert` still means "use the system CA store". All three * checks are skipped when `enabled` is 0. * @throws boost::bad_lexical_cast If any numeric key (`enabled`, `use_tls`, * `batch_size`, the trace switches, ...) holds a value Section::valueOr cannot