From 83cd09db799277b9409eedd01286208f8bef5a8e Mon Sep 17 00:00:00 2001 From: James Elliott Date: Mon, 8 May 2023 16:02:59 +1000 Subject: [PATCH] docs: factorize (#5411) Signed-off-by: James Elliott --- .../content/en/configuration/first-factor/ldap.md | 11 +++++++---- .../en/configuration/miscellaneous/server.md | 14 ++++++++++---- .../en/configuration/notifications/smtp.md | 7 +++++-- docs/content/en/configuration/prologue/common.md | 15 +++++++++++++++ docs/content/en/configuration/session/redis.md | 8 ++++++-- docs/content/en/configuration/storage/mysql.md | 6 +++++- docs/content/en/configuration/storage/postgres.md | 6 +++++- .../content/en/configuration/telemetry/metrics.md | 14 ++++++++++---- 8 files changed, 63 insertions(+), 18 deletions(-) diff --git a/docs/content/en/configuration/first-factor/ldap.md b/docs/content/en/configuration/first-factor/ldap.md index aebd73f46..5e6a7815c 100644 --- a/docs/content/en/configuration/first-factor/ldap.md +++ b/docs/content/en/configuration/first-factor/ldap.md @@ -121,8 +121,8 @@ This section describes the individual configuration options. {{< confkey type="string" required="yes" >}} -*__Reference Note:__ This configuration option uses the [Address](../prologue/common.md#address) format. Please see the -[documentation](../prologue/common.md#address) on this format for more information.* +*__Reference Note:__ This configuration option uses the [address common syntax](../prologue/common.md#address). Please +see the [documentation](../prologue/common.md#address) on this format for more information.* The LDAP URL which consists of a scheme, hostname, and port. Format is `[://][:]`. The default scheme is `ldapi` if the path is absolute otherwise it's `ldaps`, and the permitted schemes are `ldap`, `ldaps`, or @@ -173,8 +173,11 @@ URL's are slightly more secure. ### tls -Controls the TLS connection validation process. You can see how to configure the tls -section [here](../prologue/common.md#tls-configuration). +*__Reference Note:__ This configuration option uses the +[TLS configuration common structure](../prologue/common.md#tls-configuration). Please see the +[documentation](../prologue/common.md#tls-configuration) on this structure for more information.* + +Controls the TLS connection validation parameters for either StartTLS or the TLS socket. ### base_dn diff --git a/docs/content/en/configuration/miscellaneous/server.md b/docs/content/en/configuration/miscellaneous/server.md index e0cc0a538..683590747 100644 --- a/docs/content/en/configuration/miscellaneous/server.md +++ b/docs/content/en/configuration/miscellaneous/server.md @@ -190,13 +190,19 @@ research about how browsers utilize and understand this header before attempting ### buffers -Configures the server buffers. See the [Server Buffers](../prologue/common.md#server-buffers) documentation for more -information. +*__Reference Note:__ This configuration option uses the +[Server buffers common structure](../prologue/common.md#server-buffers). Please see the +[documentation](../prologue/common.md#server-buffers) on this structure for more information.* + +Configures the server buffers. ### timeouts -Configures the server timeouts. See the [Server Timeouts](../prologue/common.md#server-timeouts) documentation for more -information. +*__Reference Note:__ This configuration option uses the +[Server timeouts common structure](../prologue/common.md#server-timeouts). Please see the +[documentation](../prologue/common.md#server-timeouts) on this structure for more information.* + +Configures the server timeouts. ### endpoints diff --git a/docs/content/en/configuration/notifications/smtp.md b/docs/content/en/configuration/notifications/smtp.md index bd879e0e5..8c537e58c 100644 --- a/docs/content/en/configuration/notifications/smtp.md +++ b/docs/content/en/configuration/notifications/smtp.md @@ -232,8 +232,11 @@ mixed emails which contain both HTML and text so this option is rarely necessary ### tls -Controls the TLS connection validation process. You can see how to configure the tls section -[here](../prologue/common.md#tls-configuration). +*__Reference Note:__ This configuration option uses the +[TLS configuration common structure](../prologue/common.md#tls-configuration). Please see the +[documentation](../prologue/common.md#tls-configuration) on this structure for more information.* + +Controls the TLS connection validation parameters for either StartTLS or the TLS socket. ## Using Gmail diff --git a/docs/content/en/configuration/prologue/common.md b/docs/content/en/configuration/prologue/common.md index 06455d23d..67446637e 100644 --- a/docs/content/en/configuration/prologue/common.md +++ b/docs/content/en/configuration/prologue/common.md @@ -205,6 +205,11 @@ guide on configuring any particular instance. Various sections of the configuration use a uniform configuration section called TLS. Notably LDAP and SMTP. This section documents the usage. +Various sections of the configuration use a uniform configuration section called `tls` which configure TLS socket and +TLS verification parameters. Notably the [LDAP](../first-factor/ldap.md#tls), [SMTP](../notifications/smtp.md#tls), +[PostgreSQL](../storage/postgres.md#tls), [MySQL](../storage/mysql.md#tls), and [Redis](../session/redis.md#tls) +sections. This section documents the common parts of this structure. + #### server_name {{< confkey type="string" required="no" >}} @@ -263,6 +268,11 @@ is provided, in top down order, each certificate must be signed by the next cert ### Server Buffers +Various sections of the configuration use a uniform configuration section called `buffers` which configure HTTP server +buffers. Notably the [server](../miscellaneous/server.md#buffers) and +[metrics telemetry](../telemetry/metrics.md#buffers) sections. This section documents the common parts of this +structure. + #### read {{< confkey type="integer" default="4096" required="no" >}} @@ -277,6 +287,11 @@ Configures the maximum response size. The default of 4096 is generally sufficien ### Server Timeouts +Various sections of the configuration use a uniform configuration section called `timeouts` which configure HTTP server +timeouts. Notably the [server](../miscellaneous/server.md#timeouts) and +[metrics telemetry](../telemetry/metrics.md#timeouts) sections. This section documents the common parts of this +structure. + #### read {{< confkey type="duration" default="6s" required="no" >}} diff --git a/docs/content/en/configuration/session/redis.md b/docs/content/en/configuration/session/redis.md index fe8a8de01..e663a4b42 100644 --- a/docs/content/en/configuration/session/redis.md +++ b/docs/content/en/configuration/session/redis.md @@ -182,8 +182,12 @@ is useful if there are long delays in establishing connections. ### tls -If defined enables [redis] over TLS, and additionally controls the TLS connection validation process. You can see how to -configure the tls section [here](../prologue/common.md#tls-configuration). +*__Reference Note:__ This configuration option uses the +[TLS configuration common structure](../prologue/common.md#tls-configuration). Please see the +[documentation](../prologue/common.md#tls-configuration) on this structure for more information.* + +If defined enables connecting to [redis] over a TLS socket, and additionally controls the TLS connection +validation parameters. ### high_availability diff --git a/docs/content/en/configuration/storage/mysql.md b/docs/content/en/configuration/storage/mysql.md index bbe02ff0a..f638d0c45 100644 --- a/docs/content/en/configuration/storage/mysql.md +++ b/docs/content/en/configuration/storage/mysql.md @@ -182,8 +182,12 @@ The SQL connection timeout. ### tls +*__Reference Note:__ This configuration option uses the +[TLS configuration common structure](../prologue/common.md#tls-configuration). Please see the +[documentation](../prologue/common.md#tls-configuration) on this structure for more information.* + If defined enables connecting to [MySQL] or [MariaDB] over a TLS socket, and additionally controls the TLS connection -validation process. You can see how to configure the tls section [here](../prologue/common.md#tls-configuration). +validation parameters. [MySQL]: https://www.mysql.com/ [MariaDB]: https://mariadb.org/ diff --git a/docs/content/en/configuration/storage/postgres.md b/docs/content/en/configuration/storage/postgres.md index f7ca07238..993f3c978 100644 --- a/docs/content/en/configuration/storage/postgres.md +++ b/docs/content/en/configuration/storage/postgres.md @@ -188,7 +188,11 @@ The SQL connection timeout. ### tls +*__Reference Note:__ This configuration option uses the +[TLS configuration common structure](../prologue/common.md#tls-configuration). Please see the +[documentation](../prologue/common.md#tls-configuration) on this structure for more information.* + If defined enables connecting to [PostgreSQL] over a TLS socket, and additionally controls the TLS connection -validation process. You can see how to configure the tls section [here](../prologue/common.md#tls-configuration). +validation parameters. [PostgreSQL]: https://www.postgresql.org/ diff --git a/docs/content/en/configuration/telemetry/metrics.md b/docs/content/en/configuration/telemetry/metrics.md index 21779ed0b..4c9b3acbf 100644 --- a/docs/content/en/configuration/telemetry/metrics.md +++ b/docs/content/en/configuration/telemetry/metrics.md @@ -69,13 +69,19 @@ This value should typically be prefixed with a `0` to ensure the relevant parser ### buffers -Configures the server buffers. See the [Server Buffers](../prologue/common.md#server-buffers) documentation for more -information. +*__Reference Note:__ This configuration option uses the +[Server buffers common structure](../prologue/common.md#server-buffers). Please see the +[documentation](../prologue/common.md#server-buffers) on this structure for more information.* + +Configures the server buffers. ### timeouts -Configures the server timeouts. See the [Server Timeouts](../prologue/common.md#server-timeouts) documentation for more -information. +*__Reference Note:__ This configuration option uses the +[Server timeouts common structure](../prologue/common.md#server-timeouts). Please see the +[documentation](../prologue/common.md#server-timeouts) on this structure for more information.* + +Configures the server timeouts. ## See More