gs_guc

Background

Currently, the default values of parameters in MogDB configuration files (postgresql.conf and pg_hba.conf) are in single-node mode. You can set application parameters by using gs_guc.

gs_guc is executed by OS user omm.

• gs_guc-current.log

  This file records the logs generated by gs_guc.

  Default directory: $GAUSSLOG/bin/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, 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, 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 it is generated. Before using the two files, place them in the $GAUSSHOME**/bin** directory on each node and ensure that they are readable.

Syntax

• Check parameters in the configuration file.

  gs_guc check [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -c "parameter"

• Modify parameters in the configuration file.

  gs_guc set [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -c "parameter = value"

• Reset parameters to their default values.

  gs_guc [ set | reload ] [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -c "parameter"

• Modify parameters in the configuration file and send semaphore to the postgresql.conf configuration file.

  gs_guc reload [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -c parameter=value

• Modify a client authentication policy and send semaphore to pg_hba.conf.

  gs_guc [ set | reload ]  [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK AUTHMEHOD authentication-options"

  NOTE: authentication-options supports the following options:

  • trust: no authentication. Remote hosts are not allowed to access MogDB in trust mode.
  • reject: access denied.
  • md5: MD5 authentication, which is not supported by default.
  • sha256: SHA256 authentication (recommended).
  • cert: client certificate authentication.
  • gss: kerberos authentication.

• Comment out a configured client authentication policy and send semaphore to pg_hba.conf.

  gs_guc [ set | reload ] [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK AUTHMEHOD"

  NOTE: If you need to comment out a configured authentication policy, use -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK AUTHMEHOD", without specifying authentication-options.

• Display help information.

  gs_guc -? | --help

• Display version information.

  gs_guc -V | --version

• Generate an encrypted password file.

  gs_guc encrypt [-M keymode] -K password [-U username] -D DATADIR

  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.
  • -Mindicates the encryption type. Its value can be server, client or source. The default value is server.

• Generate an encrypted OBS password file.

  gs_guc generate [-o prefix] [-S cipherkey] -D DATADIR

  NOTE:

  • -o indicates a file name prefix, pertaining to output cipher and rand files of the OBS type. 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.

NOTE:

• gs_guc does not support parameter value containing the number sign (#). You can use the vi tool 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.
• Setting the environment variable PGDATA as follows: Set PGDATA to /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 you use -c "Parameter" to set a GUC parameter, this parameter will be reset to its default value. Note that the log_directory and audit_directory parameters will be reset to $GAUSSLOG/pg_audit/instance_name, instead of their default values. 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 latest configuration parameter is set and the others are ignored.
• If modification validation is delayed after the parameters in the MogDB node configuration file postgresql.conf are set or modified in reload mode, the parameter settings for instances in MogDB may be inconsistent for a short period of time.

Command Reference

• set

  Modifies only parameters in the configuration file.

• check

  Checks only the parameters in the configuration file.

• reload

  Modifies parameters in the configuration file and sends semaphores to the database process for reloading the configuration file.

• encrypt/generate

  Generates the encrypted password file.

• -N

  Specifies the name of the host to be set.

  Value range: the name of an existing host.

  When this parameter is set to ALL, all the hosts in MogDB are to be set.

• -I INSTANCE-NAME

  Specifies the name of the instance to be set.

  Value range: the name of an existing instance.

  When this parameter is set to ALL, all the instances in the host are to be set.

• -D

  Specifies the MogDB instance path of the commands to be run. When the encrypt command is used, this parameter indicates the path for storing the generated password file.

  NOTE: -D cannot be used together with -I.

• -c parameter=value

  Specifies the name and value of the MogDB 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.
  • When gs_guc reload is used to set parameters and the -N parameter is set to the primary node, the parameter values of both the primary and standby nodes will be modified. If the -N parameter is set to the standby node, the parameter values of only the standby node will be modified.
  • When gs_guc reload is used to set parameters and the -N parameter is not set, the parameter values of both the primary and standby nodes will be modified if you run the command on the primary node. If the -N parameter is not set and you run the command on the standby node, the parameter values of only the standby node will be modified.

  Value range: all the parameters in the postgresql.conf file.

• -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 value is not allowed to be empty. If it is empty, the value of "parameter" will not be restored to the default value in the database.

• -h host-auth-policy

  Specifies the 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
  • sha256
  • cert
  • gss

  For details about the parameters, see their description in the pg_hba.conf configuration file.

• -?, -help

  Displays help information.

• -V, -version

  Displays version information.

• -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

  Specifies the plaintext password to be encrypted.

  Value range: a character string. The value must meet the password complexity requirements.

• -U, -keyuser=USER

  Specifies the user to be encrypted. The user belongs to the OS user.

  NOTE: MogDB 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

  Specifies the string to be encrypted.

  Value range: a string.

• -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 (_).

• -Z NODE-TYPE

  Specifies the node type of the database instance. The default value is datanode. NODE-TYPE is used to identify configuration files.

  Value range: datanode.

  NOTE: Database instance node types include coordinator, datanode, cmserver, cmagent, and gtm. MogDB can only be set to datanode. When NODE-TYPE is set to datanode, the corresponding configuration file is postgresql.conf in the database data directory.

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 -D /gaussdb/data/dbnode -c "max_connections = 800" -N plat1

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 -D /gaussdb/data/dbnode -c "max_connections" -N plat1

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

Example 3: Set a client authentication policy.

gs_guc set -N all -I all -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 -N all -I all -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 Gauss@123 -D /data/xzg/wisequery/gaussdb
gs_guc encrypt -K ***

Example 6: Check the parameter configurations of each instance in MogDB.

gs_guc check -D /gaussdb/data/dbnode -c "max_connections" -N plat1

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 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 -N all -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 8: 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 ***