gs_guc

Background

All the current default values for parameters in the openGauss configuration files (postgresql.conf and pg_hba.conf) are applied in single-server configuration mode. You can set application parameters by using gs_guc.

gs_guc-current.log
This file records the logs generated by gs_guc.
gs_guc-Year-Month-Day_HHMMSS.log
A backup file is generated based on the current time when the size of the gs_guc-current.log file reaches 16 MB.
server.key.cipher and server.key.rand
When you encrypt a user password using the gs_guc encrypt command and the -M option is set to server, the server.key.cipher and server.key.rand files are generated. server.key.cipher stores the encrypted password. server.key.rand stores the encryption factor.
client.key.cipher and client.key.rand
When you encrypt a user password using the gs_guc encrypt command and the -M option is set to client, the client.key.cipher and** client.key.rand** files are generated. client.key.cipher stores the encrypted password. client.key.rand stores the encryption factor.
NOTE: client.key.cipher and client.key.rand indicate the ciphertext file and encryption factor files generated when the -U option is not specified. When you specify the user name using the -U option, a file whose name starts with the user name is generated. Take -U test as an example, the names of the files generated are test.key.cipher and test.key.rand.
datasource.key.cipher, datasource.key.rand
When you encrypt a user password using the gs_guc encrypt command and the -M option is set to source, the datasource.key.cipher and datasource.key.rand files are generated. datasource.key.cipher stores the encrypted password. datasource.key.rand stores the encryption factor.
NOTE:
- datasource.key.cipher and datasource.key.rand are key files invoked during data source creation. gs_guc has the read permission when the files are generated. Before using the two files, place them in the $GAUSSHOME/bin directory on each node and ensure that they are readable. gs_ssh helps you quickly place files in the specified directory of each node in the database instance.
- You can also run the gs_guc generate command to generate the two files using either of the following methods and enter the password as prompted. Method 1: gs_guc encrypt -M source -D ./ Method 2: gs_guc generate -o datasource -D ./
obsserver.key.cipher and obsserver.key.rand
When you run the gs_guc generate command to encrypt the entered password, the two files are generated. obsserver.key.cipher indicates the ciphertext of the password, and obsserver.key.rand indicates the encryption factor.
NOTE: obsserver.key.cipher and obsserver.key.rand are the key files invoked when OBS objects are created.

Syntax

-Z indicates the data node.
- Check parameters in the configuration file (only DNs are supported).
```
gs_guc check {-Z datanode} [-D DATADIR] -c "parameter"
```
- Check parameters in the configuration file of the logical database (only DNs are supported).
```
gs_guc check {-Z datanode} [-D DATADIR] -c "parameter" --lcname=LCNAME
```
- Modify parameters in a configuration file.
```
gs_guc set {-Z datanode} [-D DATADIR] -c "parameter = value"
```
- Modify parameters in the configuration file of a logical database (only DNs are supported)
```
gs_guc set {-Z datanode} [-D DATADIR] -c "parameter = value" --lcname=LCNAME
```
- Reset parameters to their default kernel values.
```
gs_guc [ set | reload ] {-Z datanode} [-D DATADIR] -c "parameter"
```
- Change the parameter values that have been set in the logical database to the default values when the database is started.
```
gs_guc [ set | reload ] {-Z datanode} [-D DATADIR] -c "parameter" --lcname=LCNAME
```
- Modify parameters in the configuration file and send semaphore to the postgresql.conf configuration file.
```
gs_guc reload {-Z datanode} [-D DATADIR] -c parameter=value
```
- Modify the client authentication policy. If reload is set, semaphores are sent to pg_hba.conf at the same time. That is, the configuration takes effect without restart.
```
gs_guc {set | reload} {-Z NODE-TYPE} -D DATADIR -h "HOSTTYPE DATABASE USERNAME IPADDR IPMASK AUTHMEHOD authentication-options"
gs_guc {set | reload} {-Z NODE-TYPE} -D DATADIR -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK AUTHMEHOD authentication-options"
gs_guc {set | reload} {-Z NODE-TYPE} -D DATADIR -h "HOSTTYPE DATABASE USERNAME HOSTNAME AUTHMEHOD authentication-options"
```
  NOTE:
  - The authentication-options parameter following AUTHMEHOD is optional. AUTHMEHOD supports the following options:
  - trust: No authentication is required. Remote hosts are not allowed to access the database in trust mode.
  - reject: access denied.
  - md5: MD5 authentication, which is not supported by default. (The MD5 encryption algorithm is not recommended because it has lower security and poses security risks.)
  - sha256: SHA256 authentication (recommended).
  - sm3: SM3 authentication.
  - cert: Client certificate-based authentication.
  - The authentication policy in the pg_hba.conf file has a higher priority. When the gs_guc tool is used for configuration, new policies are inserted into the original authentication policy based on a certain rule. The field comparison sequence is as follows: IPADDR/HOSTNAME > HOSTTYPE > DATABASE > USERNAME. That is, the IP addresses or host names are compared first. If the priorities cannot be distinguished, the host types are compared. For each configuration field, a stricter configuration parameter has a higher priority and a looser configuration parameter has a lower priority. The details are as follows:
  - IPADDR: An IP address of all zeros is not restricted and will be placed after the policy for specifying an IP address.
  - DATABASE: The value all indicates that the database is not restricted and is placed after the policy for specifying a database. The value replication indicates that the database is placed after other policies.
  - USERNAME: The value all indicates that the user is not restricted and is placed after the policy for specifying a user.
  - HOSTTYPE: local > hostssl > hostnossl > host
- Comment out the configured client authentication policy. If reload is set, semaphores are sent to pg_hba.conf at the same time. That is, the configuration takes effect without restart.
```
gs_guc {set | reload} {-Z NODE-TYPE} -D DATADIR -h "HOSTTYPE DATABASE USERNAME IPADDR IPMASK"
gs_guc {set | reload} {-Z NODE-TYPE} -D DATADIR -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK"
gs_guc {set | reload} {-Z NODE-TYPE} -D DATADIR -h "HOSTTYPE DATABASE USERNAME HOSTNAME"
```
- Display help information.
```
gs_guc -? | --help
```
- Display version number.
```
gs_guc -V | --version
```
Generate the encrypted ciphertext file and encryption factor file.
- Use gs_guc encrypt to generate an encrypted password and encryption factor file.
```
gs_guc encrypt [-M keymode] [-K password] [-U username] -D DATADIR
Or
gs_guc encrypt [-M keymode] [-K password] [-U username] -C [cipher_dir] -R [rand_dir]
```
  NOTE:
  - -K indicates a user-specified password. gs_guc specifies the requirements of the password length (ranging from 8 to 16) and complexity. If the requirements are not meet, an error is reported. If the -K parameter is not specified, the system prompts you to enter the password in interactive mode. To ensure system security, you are advised to enter the password in interactive mode. This password is used to ensure the security and uniqueness of the generated password file. You do not need to save or memorize the password.
  - -M indicates the encryption type. Its value can be server, client or source. The default value is server.
- gs_guc generate generates the encrypted password and encryption factor file with the prefix obsserver or other prefixes.
```
gs_guc generate [-o prefix] [-S cipherkey] -D DATADIR
```
  NOTE:
  - -o indicates a file name prefix, pertaining to output cipher and rand files. The default prefix is obsserver. The value can contain only digits, letters, and underscores (_).
  - -S indicates the password specified by the user. The password must meet the length (8 ≤ len ≤ 16) and complexity requirements. If the password does not meet the requirements, an error is reported. If the value is default, a randomly generated string will be used as the password, and the password length is 13 characters. If the -S parameter is not specified, the system prompts you to enter the password in interactive mode. To ensure system security, you are advised to enter the password in interactive mode. This password is used to ensure the security and uniqueness of the generated password file. You do not need to save or memorize the password.
  - Only the parameters are different when the gs_guc encrypt or gs_guc generate command is used to generate the encrypted password and encryption factor file. During the generation, a random number is used as the encryption key material and salt. Therefore, the file generated each time is different. The encryption password and encryption factor file generated each time must be used in pairs and cannot be changed or used alternately. The same encryption password and encryption factor file must be used for encryption and decryption.

NOTE:
Parameter values set using gs_guc cannot contain the number sign (#). To set such values, you can use vi to manually modify the configuration file.
If the environment variable PGDATA has been set, the -D parameter can be omitted. Otherwise, a parameter setting failure will be reported.
Set the environment variable PGDATA as follows: Set /gaussdb/data, and then execute export PGDATA to make the setting effective.
authpolicy contains a series of authentication parameters: HOSTTYPE DATABASE USERNAME IPADDR IPMASK, HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK, or HOSTTYPE DATABASE USERNAME HOSTNAME.
If -c “parameter” is used to set the GUC parameter, the GUC parameter value will be set to the default value of the parameter upon database startup (the value of the boot_val field in the system view PG_SETTINGS). Note that log_directory and audit_directory are set to $GAUSSLOG/pg_audit/instance_name instead of the default values when the database is started. GUC parameters are dependent on each other. Therefore, exercise caution when using -c " Parameter".
When setting the -c parameter, the double quotation marks can be omitted.
If the value contains special characters, such as $, escape the character first.
If a configuration parameter occurs in multiple rows of a configuration file and two or more rows take effect at the same time (which means that the configuration parameter is not commented out using “#”), only the last configuration parameter is set and the others are ignored.
If you set or modify parameters in the configuration file (postgresql.conf) of a database node in reload mode, the settings may take effect with a short delay. As a result, the parameters of each database instance may be inconsistent for a short period of time after the configuration.
When gs_guc is used to set floating-point parameters, floating-point numbers cannot be accurately represented in the computer. Therefore, parameter values can be successfully set within the error range of 1e-9.
When gs_guc is used to set parameters of the integer type, the decimal, hexadecimal, and octal data can be accepted. The value starting with 0x indicates hexadecimal and 0 indicates octal, and other values indicate decimal.

Command Reference

set
Modifies only parameters in the configuration file.
check
Checks only the parameters in the configuration file.
NOTE: If the check result contains parameter=NULL, this parameter is not configured in the configuration file.
reload
Modifies parameters in the configuration file and sends semaphore to the database process for reloading the configuration file.
encrypt/generate
Generates the encrypted password file.
-D
Path of the database instance where the command needs to be executed. When the encrypt command is used, this parameter indicates the path for storing the generated password file.
-C
Path for generating the plaintext key file when the encrypt command is used.
-R
Path for generating the random number key file when the encrypt command is used.
-c parameter=value
Name and value of the database configuration parameter to be set.
NOTE:
- If the parameter is a string variable, use -c parameter=value or -c parameter = value.
- When gs_guc set or reload is set to log_directory, the default value is restored and set to a specific data directory.
Value range: all the parameters in the postgresql.conf file
--lcname=LCNAME
Name of the logical database to be set.
NOTE:
- This parameter must be used together with -Z datanode. That is, gs_guc can be used only for logical database instances of DNs.
- The parameters that can be operated on a logical database are different from those on a complete database. For details, see $GAUSSHOME/bin/cluster_guc.conf.
Value range: name of an existing logical database.
--ignore-node=NODES
Specifies the name of the host to be ignored.
NOTE:
- This parameter must be used together with set or reload, and** -Z** supports only datanode or coordinator.
- This parameter cannot be used together with -D.
- When the reload command is used together with the --ignore-node command, if no primary node is specified for the --ignore-node command, the parameters of all nodes in the cluster are modified synchronously.
-c parameter
When the check operation is performed, “parameter” indicates the name of the parameter to be checked. When the set or reload operation is performed, “parameter” indicates the name of the parameter whose value needs to be restored to the default value in the database.
-h host-auth-policy
Client authentication policy added to the pg_hba.conf configuration file
Value range:
- HOSTTYPE DATABASE USERNAME IPADDR IPMASK [authmehod-options]
- HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK [authmehod-options ]
- HOSTTYPE DATABASE USERNAME HOSTNAME [authmehod-options ]
HOSTTYPE is a mandatory parameter. Value range:
- local
- host
- hostssl
- hostnossl
local is a Unix domain socket. host is a common or SSL-encrypted TCP/IP socket. hostssl is an SSL-encrypted TCP/IP socket. hostnossl is a TCP/IP-only socket.
authmehod-options is an optional parameter. Value range:
- trust
- reject
- md5 (The MD5 encryption algorithm is not recommended because it has lower security and poses security risks.)
- sha256
- cert
For details about the parameters, see their description in the pg_hba.conf configuration file.
-?, --help
Display help information.
-V, --version
Display version information.
-Z NODE_TYPE
Indicates the instance type.
Value range:
- datanode
-M, --keymode=MODE
Specifies that the password is invoked to create which object. Its value can be server, client or source.
NOTE: Using the SSL function involves the encrypted passwords of the server certificates and private key files as well as those of the client certificates and private key files. When these passwords are stored in encrypted mode, this parameter must be specified. Otherwise, a server password file will be generated.
Value range:
- server (default value)
- client
- source
-K PASSWORD
gs_guc encrypt specifies the password to be encrypted. If this parameter is not specified, the system prompts you to enter the password in interactive mode. To ensure system security, you are advised to enter the password in interactive mode.
Value range: a character string. The value must meet the password length (ranging from 8 to 16) and complexity requirements. If the value is default, a randomly generated string will be used as the password, and the password length is 13 characters.
-U, --keyuser=USER
Specifies the user to be encrypted. The user belongs to the OS user.
NOTE: For example, openGauss can configure different SSL licenses and private files for each user. When this option is specified, user-specific password files can be generated.
-S CIPHERKEY
gs_guc generate specifies the string to be encrypted. If this parameter is not specified, the system prompts you to enter the password in interactive mode. To ensure system security, you are advised to enter the password in interactive mode.
Value range: a character string. The value must meet the password length (ranging from 8 to 16) and complexity requirements.
-o PREFIX
Specifies the file name prefix for output cipher and rand files of the OBS type. The default prefix is obsserver.
Value range: a string containing only digits, letters, and underscores (_)

Example

Example 1: Change the maximum number of connections allowed by a database to 800. The database must be restarted to make the change take effect.

gs_guc set -Z datanode -D /gaussdb/data/datanode -c "max_connections = 800" 

Total instances: 1. Failed instances: 0.
Success to perform gs_guc!

Example 2: Change the maximum number of connections allowed by a database to the default value. The database must be restarted to make the change take effect.

gs_guc set -Z datanode -D /gaussdb/data/datanode -c "max_connections"

Total instances: 1. Failed instances: 0.
Success to perform gs_guc!

Example 3: Set a client authentication policy.

gs_guc set -Z datanode -D /gaussdb/data/datanode -h "host replication testuser 10.252.95.191/32 sha256"

Total instances: 2. Failed instances: 0.
Success to perform gs_guc!

Example 4: Comment out a configured client authentication policy.

gs_guc set -Z datanode -D /gaussdb/data/datanode -h "host replication testuser 10.252.95.191/32"

Total instances: 2. Failed instances: 0.
Success to perform gs_guc!

Example 5: Encrypt a plaintext user password stored on a server to avoid password leakage.

gs_guc encrypt -K XXXXXXXXX -D /data/xzg/wisequery/gaussdb
gs_guc encrypt -K ***

Example 6: Check the parameter configurations of each instance.

gs_guc check -Z datanode -D /gaussdb/data/datanode -c "max_connections"

Total GUC values: 1. Failed GUC values: 0.
The value of parameter max_connections is same on all instances.
    max_connections=800

Example 7: Modify the DN parameters. For example, change the maximum number of connections allowed by the database to 800. The database must be restarted to make the change take effect.

gs_guc set -Z datanode -D /gaussdb/data/datanode -c "max_connections = 800"
Begin to perform gs_guc for all coordinators.

Total instances: 3. Failed instances: 0.
Success to perform gs_guc!

Begin to perform gs_guc for all datanodes.

Total instances: 9. Failed instances: 0.
Success to perform gs_guc!

Example 8: Modify DN parameters. For example, modify archive_command to ensure the validity of the archiving path. The database must be restarted to make the change take effect. This method is recommended.

gs_guc set -Z datanode -D /data/datanode  -c "archive_command= 'cp %p /data/datanode/pg_xlog/archive_status/%f'"
Total instances: 3. Failed instances: 0.
Success to perform gs_guc!

Example 9: Modify DN parameters. For example, modify archive_command to ensure the validity of the archiving path. The database must be restarted to make the change take effect. This method is not recommended.

gs_guc set -Z datanode -D /gaussdb/data/datanode -c "archive_command= 'cp %p pg_xlog/archive_status/%f'"
Total instances: 3. Failed instances: 0.
Success to perform gs_guc!

Example 10: Use an entered plaintext password to customize and generate the test.key.cipher and test.key.rand files.

gs_guc generate -S Mppdb@123 -D /data/xzg/wisequery/gaussdb -o test
gs_guc encrypt -S ***