From c9842085642cc748c8817f4d7345f7d47b7c1d83 Mon Sep 17 00:00:00 2001 From: Dorian Hoxha Date: Tue, 19 Jan 2021 15:44:59 +0100 Subject: [PATCH 1/5] ysql_hba_conf -> ysql_hba_conf_csv --- .../latest/secure/authentication/trust-authentication.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/content/latest/secure/authentication/trust-authentication.md b/docs/content/latest/secure/authentication/trust-authentication.md index 0bb480f6f823..a441b4595e52 100644 --- a/docs/content/latest/secure/authentication/trust-authentication.md +++ b/docs/content/latest/secure/authentication/trust-authentication.md @@ -29,11 +29,12 @@ showAsideToc: true When `trust` authentication is specified, YugabyteDB assumes that any user trying to connect with the YB-TServer can access the database with the database user name they specify. This method is appropriate and very convenient for local connections to the YugabyteDB cluster. -By default YugabyteDB cluster uses `trust `authentication. One can explicitly specify `trust` authentication by setting with the following [--ysql_hba_conf](https://docs.yugabyte.com/latest/reference/configuration/yb-tserver/#ysql-hba-conf) flag. +By default, YugabyteDB cluster uses `trust `authentication. One can explicitly specify `trust` authentication by +setting with the following [--ysql_hba_conf_csv](https://docs.yugabyte.com/latest/reference/configuration/yb-tserver/#ysql-hba-conf-csv) flag. ``` ---ysql_hba_conf="host all all 0.0.0.0/0 trust, host all all ::0/0 trust" +--ysql_hba_conf_csv='host all all 0.0.0.0/0 trust, host all all ::0/0 trust' ``` This enables `trust` authentication for all users. From 153ba7f15348a2bb0a702fbceaf9ca48ad1f5ff3 Mon Sep 17 00:00:00 2001 From: Dorian Hoxha Date: Tue, 19 Jan 2021 15:49:32 +0100 Subject: [PATCH 2/5] deprecate ysql_hba_conf + ysql_hba_conf_csv --- .../reference/configuration/yb-tserver.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/content/latest/reference/configuration/yb-tserver.md b/docs/content/latest/reference/configuration/yb-tserver.md index 1a66e2b2c5c6..9d2615a25645 100644 --- a/docs/content/latest/reference/configuration/yb-tserver.md +++ b/docs/content/latest/reference/configuration/yb-tserver.md @@ -432,6 +432,9 @@ Specifies the web server port for YSQL metrics monitoring. Default: `13000` ##### --ysql_hba_conf +{{< note title="Note" >}} +`--ysql_hba_conf` tserver flag is deprecated. Use `--ysql_hba_conf_csv` instead. +{{< /note >}} Specifies a comma-separated list of PostgreSQL client authentication settings that is written to the `ysql_hba.conf` file. @@ -441,6 +444,30 @@ Default: `"host all all 0.0.0.0/0 trust,host all all ::0/0 trust"` To see the current values in the `ysql_hba.conf` file, run the `SHOW hba_file;` statement and then view the file. Because the file is autogenerated, direct edits are overwritten by the autogenerated content. +##### --ysql_hba_conf_csv +Specifies a comma-separated list of PostgreSQL client authentication settings that is written to the `ysql_hba.conf` file. When writing, the rules are: +1. in case text has `,` or `"` it should be quoted with `"` +2. the `"` symbol inside quoted text should be doubled (i.e. `""`) + +Example: + +Suppose we have two fields: `host all all 127.0.0.1/0 password` and `host all all 0.0.0.0/0 ldap ldapserver=***** ldapsearchattribute=cn ldapport=3268 ldapbinddn=***** ldapbindpasswd="*****"`. +The second field has the `"` symbol, so we should quote this field and double the quotes. The result will be: +``` +"host all all 0.0.0.0/0 ldap ldapserver=***** ldapsearchattribute=cn ldapport=3268 ldapbinddn=***** ldapbindpasswd=""*****""" +``` + +Now the fields can be joined with the `,` and the final flag value is set inside `'` single quotes: +``` +--ysql_hba_conf_csv='host all all 127.0.0.1/0 password,"host all all 0.0.0.0/0 ldap ldapserver=***** ldapsearchattribute=cn ldapport=3268 ldapbinddn=***** ldapbindpasswd=""*****"""' +``` + +For details on using `--ysql_hba_conf_csv` to specify client authentication, see [Fine-grained authentication](../../../secure/authentication/client-authentication). + +Default: `"host all all 0.0.0.0/0 trust,host all all ::0/0 trust"` + +To see the current values in the `ysql_hba.conf` file, run the `SHOW hba_file;` statement and then view the file. Because the file is autogenerated, direct edits are overwritten by the autogenerated content. + ##### --ysql_pg_conf Comma-separated list of PostgreSQL setting assignments. From ace4ea472172feca7ec440c43df082a08f585917 Mon Sep 17 00:00:00 2001 From: Dorian Hoxha Date: Tue, 19 Jan 2021 15:49:53 +0100 Subject: [PATCH 3/5] ysql_hba_conf -> ysql_hba_conf_csv --- .../authentication/password-authentication.md | 32 ++++++++++++------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/content/latest/secure/authentication/password-authentication.md b/docs/content/latest/secure/authentication/password-authentication.md index 05826048a97b..21e9a63b99f0 100644 --- a/docs/content/latest/secure/authentication/password-authentication.md +++ b/docs/content/latest/secure/authentication/password-authentication.md @@ -78,21 +78,24 @@ or in the `yb-tserver.conf`, add the following line: 2. Specify the rules for host-based authentication. -To specify rules for the use of the `scram-sha-256` authentication method, add the YB-TServer [`--ysql_hba_conf`](../../../reference/configuration/yb-tserver/#ysql-hba-conf) flag and specify rules that satisfy your security requirements. +To specify rules for the use of the `scram-sha-256` authentication method, add the YB-TServer [`--ysql_hba_conf_csv`](../../../reference/configuration/yb-tserver/#ysql-hba-conf-csv) +flag and specify rules that satisfy your security requirements. -In the following example, the `--ysql_hba_conf` flag modifies the default rules that use `trust` to use SCRAM-SHA-256 authentication, changing the default values of `trust` to use `scram-sha-256`: +In the following example, the `--ysql_hba_conf_csv` flag modifies the default rules that use `trust` to use +SCRAM-SHA-256 authentication, changing the default values of `trust` to use `scram-sha-256`: ``` ---ysql_hba_conf="host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256" +--ysql_hba_conf_csv='host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256' ``` or in the `yb-tserver.conf`, add the following line: ``` ---ysql_hba_conf=host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256 +--ysql_hba_conf_csv=host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256 ``` -For details on using the [--ysql_hba_conf](../../../reference/configuration/yb-tserver/#ysql-hba-conf) flag to specify rules that satisfy your security requirements, see [Fine-grained authentication](../../authentication/client-authentication). +For details on using the [--ysql_hba_conf_csv](../../../reference/configuration/yb-tserver/#ysql-hba-conf-csv) flag to +specify rules that satisfy your security requirements, see [Fine-grained authentication](../../authentication/client-authentication). ## Create a cluster that uses SCRAM-SHA-256 password authentication @@ -102,11 +105,11 @@ To use SCRAM-SHA-256 password authentication on a new YugabyteDB cluster, follow ```sh --ysql_pg_conf=password_encryption=scram-sha-256 ---ysql_hba_conf=host all all 0.0.0.0/0 md5,host all all ::0/0 md5,host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256 +--ysql_hba_conf_csv=host all all 0.0.0.0/0 md5,host all all ::0/0 md5,host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256 ``` - The first line starts your YugabyteDB cluster with password encryption set to encrypt all *new* passwords using SCRAM-SHA-256. -- The `ysql_hba_conf` flag above specifies rules that allow both MD5 and SCRAM-SHA-256 *existing* passwords to be used to connect to databases. +- The `ysql_hba_conf_csv` flag above specifies rules that allow both MD5 and SCRAM-SHA-256 *existing* passwords to be used to connect to databases. 2. Start the YugabyteDB cluster. @@ -127,7 +130,8 @@ yugabyte=# 4. Change the password for `yugabyte` to a SCRAM-SHA-256 password. -You can use either the ALTER ROLE statement or the `ysqlsh` `\password\` metacommand to change the password. The new password is encrypted using the SCRAM-SHA-256 hashing algorithm. In the following example, the `\password` metacommand is used to change the password. +You can use either the ALTER ROLE statement or the `ysqlsh` `\password\` metacommand to change the password. +The new password is encrypted using the SCRAM-SHA-256 hashing algorithm. In the following example, the `\password` metacommand is used to change the password. ```sh yugabyte=# \password @@ -143,12 +147,12 @@ yugabyte=# 5. Stop the YugabyteDB cluster. -6. Remove the MD5 rules from the `--ysql_hba_conf` flag. +6. Remove the MD5 rules from the `--ysql_hba_conf_csv` flag. In the flagfile, the updated flag should appear like this: ```sh ---ysql_hba_conf=host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256 +--ysql_hba_conf_csv=host all all 0.0.0.0/0 scram-sha-256,host all all ::0/0 scram-sha-256 ``` 7. Restart the YugabyteDB cluster. @@ -159,7 +163,8 @@ In the flagfile, the updated flag should appear like this: $ ./ysqlsh -U yugabyte -W ``` -When prompted, the changed `yugabyte` user password should get you access. Any new users or roles that you create will be encrypted using SCRAM-SHA-256. Access to the host and databases is determined by the rules you specify in the YB-TServer `--ysql_hba_conf` configuration flag. +When prompted, the changed `yugabyte` user password should get you access. Any new users or roles that you create will be encrypted using SCRAM-SHA-256. +Access to the host and databases is determined by the rules you specify in the YB-TServer `--ysql_hba_conf_csv` configuration flag. ## Migrate existing MD5 passwords to SCRAM-SHA-256 @@ -168,4 +173,7 @@ When you [enable SCRAM-SHA-256 authentication](#enable-scram-sha-256-authenticat - All new, or changed, passwords will be encrypted using the SCRAM-SHA-256 hashing algorithm. - All existing passwords were encrypted using the MD5 hashing algorithm. -Because all existing passwords must be changed, you can manage the migration of these user and role passwords from MD5 to SCRAM-SHA-256 by maintaining rules in the `--ysql_hba_conf` setting to allow both MD5 passwords and SCRAM-SHA-256 passwords to work until all passwords have been migrated to SCRAM-SHA-256. For an example, see [Create a cluster that uses SCRAM-SHA-256 password authentication](#Create-a-cluster-that-uses-scram-sha-256-password-authentication) above. If you follow a similar approach for an existing cluster, you can enhance your cluster security, track and migrate passwords, and then remove the much weaker MD5 rules after all passwords have been updated. +Because all existing passwords must be changed, you can manage the migration of these user and role passwords from MD5 to SCRAM-SHA-256 +by maintaining rules in the `--ysql_hba_conf_csv` setting to allow both MD5 passwords and SCRAM-SHA-256 passwords to work until +all passwords have been migrated to SCRAM-SHA-256. For an example, see [Create a cluster that uses SCRAM-SHA-256 password authentication](#Create-a-cluster-that-uses-scram-sha-256-password-authentication) above. +If you follow a similar approach for an existing cluster, you can enhance your cluster security, track and migrate passwords, and then remove the much weaker MD5 rules after all passwords have been updated. From 6d8bc8f1f641250eb46a2a61679b5609dc4d90e7 Mon Sep 17 00:00:00 2001 From: Dorian Hoxha Date: Tue, 19 Jan 2021 15:50:13 +0100 Subject: [PATCH 4/5] ysql_hba_conf -> ysql_hba_conf_csv keeping the same url as before --- .../ysql_hba_conf-configuration.md | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/content/latest/secure/enable-authentication/ysql_hba_conf-configuration.md b/docs/content/latest/secure/enable-authentication/ysql_hba_conf-configuration.md index 1676c4510839..74d5d27b9759 100644 --- a/docs/content/latest/secure/enable-authentication/ysql_hba_conf-configuration.md +++ b/docs/content/latest/secure/enable-authentication/ysql_hba_conf-configuration.md @@ -1,8 +1,8 @@ --- -title: Configure ysql_hba_conf -headerTitle: Configure ysql_hba_conf -linkTitle: Configure ysql_hba_conf -description: Use ysql_hba_conf configuration to setup client authentication. +title: Configure ysql_hba_conf_csv +headerTitle: Configure ysql_hba_conf_csv +linkTitle: Configure ysql_hba_conf_csv +description: Use ysql_hba_conf_csv configuration to setup client authentication. menu: latest: identifier: ysql_hba_conf-configuration @@ -21,19 +21,19 @@ showAsideToc: true -The client authentication in YugabyteDB is managed by the T-Server [--ysql_hba_conf](https://docs.yugabyte.com/latest/reference/configuration/yb-tserver/#ysql-hba-conf) configuration flag, which works similar to the pg_hba.conf file in PostgreSQL. The values include records that specify allowed connection types, users, client IP addresses, and the authentication method. - -Records in the YugabyteDB` ysql_hba.conf` file are auto generated based on the values included in the [--ysql_hba_conf](https://docs.yugabyte.com/latest/reference/configuration/yb-tserver/#ysql-hba-conf) flag. For example, starting a YB-TServer with the following [--ysql_hba_conf](https://docs.yugabyte.com/latest/reference/configuration/yb-tserver/#ysql-hba-conf) flag will enable trust authentication for all users. +The client authentication in YugabyteDB is managed by the T-Server [--ysql_hba_conf_csv](../../../reference/configuration/yb-tserver/#ysql-hba-conf-csv) +configuration flag, which works similar to the pg_hba.conf file in PostgreSQL. +The values include records that specify allowed connection types, users, client IP addresses, and the authentication method. +Records in the YugabyteDB` ysql_hba.conf` file are auto generated based on the values included in the --ysql_hba_conf_csv flag. +For example, starting a YB-TServer with the following --ysql_hba_conf_csv flag will enable trust authentication for all users. ``` ---ysql_hba_conf="host all all 0.0.0.0/0 trust, host all all ::0/0 trust" +--ysql_hba_conf_csv='host all all 0.0.0.0/0 trust, host all all ::0/0 trust' ``` - To display the current values in the` ysql_hba.conf` file, run the following `SHOW` statement to get the file location: - ``` yugabyte=# SHOW hba_file; @@ -43,10 +43,8 @@ yugabyte=# SHOW hba_file; (1 row) ``` - and then view the file. Here is an example of `ysql_hba.conf` file contents. - ``` # This is an autogenerated file, do not edit manually! host all all 0.0.0.0/0 trust From 94c0c3e52df5aa6ca34073e92522c1ceae35f8d3 Mon Sep 17 00:00:00 2001 From: Dorian Hoxha Date: Thu, 21 Jan 2021 18:07:25 +0100 Subject: [PATCH 5/5] add colon before lists --- docs/content/latest/reference/configuration/yb-tserver.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/latest/reference/configuration/yb-tserver.md b/docs/content/latest/reference/configuration/yb-tserver.md index 9d2615a25645..96c694cbfaad 100644 --- a/docs/content/latest/reference/configuration/yb-tserver.md +++ b/docs/content/latest/reference/configuration/yb-tserver.md @@ -114,7 +114,7 @@ Default: `500000` (500,000 µs = 500ms) ##### --rpc_bind_addresses -Specifies the comma-separated list of the network interface addresses to bind to for RPC connections. +Specifies the comma-separated list of the network interface addresses to bind to for RPC connections: - Typically, the value is set to the private IP address of the host on which the server is running. When using the default, or explicitly setting the value to `0.0.0.0:9100`, the server will listen on all available network interfaces.