From 5a9613e0b17241a6e69561a55a465ff6d9503ac8 Mon Sep 17 00:00:00 2001 From: Chris Berkhout Date: Tue, 30 Jan 2024 10:55:11 +0100 Subject: [PATCH] Update SQL and Oracle module docs regarding Oracle DSNs (#37590) - Add 'oracle://' URL format. - Add note about encoding of special characters in URLs. - Align the SQL module and the Oracle module documentation. --- CHANGELOG.next.asciidoc | 1 + metricbeat/docs/modules/oracle.asciidoc | 15 ++++++++++----- metricbeat/docs/modules/sql.asciidoc | 18 +++++++++++++----- .../module/oracle/_meta/docs.asciidoc | 15 ++++++++++----- .../metricbeat/module/sql/_meta/docs.asciidoc | 19 +++++++++++++------ 5 files changed, 47 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.next.asciidoc b/CHANGELOG.next.asciidoc index b8c46fa18c5..3f06bacacb6 100644 --- a/CHANGELOG.next.asciidoc +++ b/CHANGELOG.next.asciidoc @@ -135,6 +135,7 @@ Setting environmental variable ELASTIC_NETINFO:false in Elastic Agent pod will d *Filebeat* +- Update SQL input documentation regarding Oracle DSNs {pull}37590[37590] - add documentation for decode_xml_wineventlog processor field mappings. {pull}32456[32456] - httpjson input: Add request tracing logger. {issue}32402[32402] {pull}32412[32412] - Add cloudflare R2 to provider list in AWS S3 input. {pull}32620[32620] diff --git a/metricbeat/docs/modules/oracle.asciidoc b/metricbeat/docs/modules/oracle.asciidoc index f524967cce5..3436caa9cc2 100644 --- a/metricbeat/docs/modules/oracle.asciidoc +++ b/metricbeat/docs/modules/oracle.asciidoc @@ -60,19 +60,24 @@ Then, Metricbeat can be launched. *Host Configuration* -The following two types of host configurations are supported: +The following types of host configuration are supported: -1. Old style host configuration for backwards compatibility: +1. An old-style Oracle connection string, for backwards compatibility: a. `hosts: ["user/pass@0.0.0.0:1521/ORCLPDB1.localdomain"]` b. `hosts: ["user/password@0.0.0.0:1521/ORCLPDB1.localdomain as sysdba"]` -2. DSN host configuration: +2. DSN configuration as a URL: + a. `hosts: ["oracle://user:pass@0.0.0.0:1521/ORCLPDB1.localdomain?sysdba=1"]` + +3. DSN configuration as a logfmt-encoded parameter list: a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']` b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']` -DSN host configuration is the recommended way to configure the Oracle Metricbeat Module as it supports the usage of special characters in the password. +DSN host configuration is the recommended configuration type as it supports the use of special characters in the password. + +In a URL any special characters should be URL encoded. -Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`. +In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`. [float] == Metricsets diff --git a/metricbeat/docs/modules/sql.asciidoc b/metricbeat/docs/modules/sql.asciidoc index 9c27c0bc4ba..d8e0e15b617 100644 --- a/metricbeat/docs/modules/sql.asciidoc +++ b/metricbeat/docs/modules/sql.asciidoc @@ -871,19 +871,26 @@ Then, Metricbeat can be launched. ===== Host Configuration for Oracle -The following two types of host configurations are supported: +The following types of host configuration are supported: -1. DSN host configuration as URL: +1. An old-style Oracle connection string, for backwards compatibility: a. `hosts: ["user/pass@0.0.0.0:1521/ORCLPDB1.localdomain"]` b. `hosts: ["user/password@0.0.0.0:1521/ORCLPDB1.localdomain as sysdba"]` -2. DSN host configuration: +2. DSN configuration as a URL: + a. `hosts: ["oracle://user:pass@0.0.0.0:1521/ORCLPDB1.localdomain?sysdba=1"]` + +3. DSN configuration as a logfmt-encoded parameter list: a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']` b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']` -Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`. +DSN host configuration is the recommended configuration type as it supports the use of special characters in the password. + +In a URL any special characters should be URL encoded. -The username and password to connect to the database can be provided as values to `username` and `password` keys of `sql.yml`. +In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`. + +The username and password to connect to the database can be provided as values to the `username` and `password` keys of `sql.yml`. [source,yml] ---- @@ -901,6 +908,7 @@ The username and password to connect to the database can be provided as values t response_format: variables ---- + :edit_url: [float] diff --git a/x-pack/metricbeat/module/oracle/_meta/docs.asciidoc b/x-pack/metricbeat/module/oracle/_meta/docs.asciidoc index 7a93e306981..887b0601939 100644 --- a/x-pack/metricbeat/module/oracle/_meta/docs.asciidoc +++ b/x-pack/metricbeat/module/oracle/_meta/docs.asciidoc @@ -48,19 +48,24 @@ Then, Metricbeat can be launched. *Host Configuration* -The following two types of host configurations are supported: +The following types of host configuration are supported: -1. Old style host configuration for backwards compatibility: +1. An old-style Oracle connection string, for backwards compatibility: a. `hosts: ["user/pass@0.0.0.0:1521/ORCLPDB1.localdomain"]` b. `hosts: ["user/password@0.0.0.0:1521/ORCLPDB1.localdomain as sysdba"]` -2. DSN host configuration: +2. DSN configuration as a URL: + a. `hosts: ["oracle://user:pass@0.0.0.0:1521/ORCLPDB1.localdomain?sysdba=1"]` + +3. DSN configuration as a logfmt-encoded parameter list: a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']` b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']` -DSN host configuration is the recommended way to configure the Oracle Metricbeat Module as it supports the usage of special characters in the password. +DSN host configuration is the recommended configuration type as it supports the use of special characters in the password. + +In a URL any special characters should be URL encoded. -Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`. +In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`. [float] == Metricsets diff --git a/x-pack/metricbeat/module/sql/_meta/docs.asciidoc b/x-pack/metricbeat/module/sql/_meta/docs.asciidoc index 17175cb5878..95ae9376e4d 100644 --- a/x-pack/metricbeat/module/sql/_meta/docs.asciidoc +++ b/x-pack/metricbeat/module/sql/_meta/docs.asciidoc @@ -859,19 +859,26 @@ Then, Metricbeat can be launched. ===== Host Configuration for Oracle -The following two types of host configurations are supported: +The following types of host configuration are supported: -1. DSN host configuration as URL: +1. An old-style Oracle connection string, for backwards compatibility: a. `hosts: ["user/pass@0.0.0.0:1521/ORCLPDB1.localdomain"]` b. `hosts: ["user/password@0.0.0.0:1521/ORCLPDB1.localdomain as sysdba"]` -2. DSN host configuration: +2. DSN configuration as a URL: + a. `hosts: ["oracle://user:pass@0.0.0.0:1521/ORCLPDB1.localdomain?sysdba=1"]` + +3. DSN configuration as a logfmt-encoded parameter list: a. `hosts: ['user="user" password="pass" connectString="0.0.0.0:1521/ORCLPDB1.localdomain"']` b. `hosts: ['user="user" password="password" connectString="host:port/service_name" sysdba=true']` -Note: If the password contains the backslash (`\`) character, it must be escaped with a backslash. For example, if the password is `my\_password`, it should be written as `my\\_password`. +DSN host configuration is the recommended configuration type as it supports the use of special characters in the password. + +In a URL any special characters should be URL encoded. -The username and password to connect to the database can be provided as values to `username` and `password` keys of `sql.yml`. +In the logfmt-encoded DSN format, if the password contains a backslash character (`\`), it must be escaped with another backslash. For example, if the password is `my\_password`, it must be written as `my\\_password`. + +The username and password to connect to the database can be provided as values to the `username` and `password` keys of `sql.yml`. [source,yml] ---- @@ -887,4 +894,4 @@ The username and password to connect to the database can be provided as values t sql_queries: - query: SELECT METRIC_NAME, VALUE FROM V$SYSMETRIC WHERE GROUP_ID = 2 and METRIC_NAME LIKE '%' response_format: variables ----- \ No newline at end of file +----