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 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 username using the -U option, a file whose name starts with the username is generated. Taking -U test as an example, the names of the files generated are test.key.cipher and test.key.rand.

• datasource.key.cipher and 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 cluster.
  • 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 ./

Syntax

• Check parameters in the configuration file.

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

• Modify parameters in a 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 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 [-N NODE-NAME] {-I INSTANCE-NAME | -D DATADIR} -h "HOSTTYPE DATABASE USERNAME IPADDR IPMASK AUTHMEHOD authentication-options"
  gs_guc {set | reload} -Z NODE-TYPE [-N NODE-NAME] {-I INSTANCE-NAME | -D DATADIR} -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK AUTHMEHOD authentication-options"
  gs_guc {set | reload} -Z NODE-TYPE [-N NODE-NAME] {-I INSTANCE-NAME | -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 certification (national secret sm3).
• cert: Client certificate-based authentication.
• gss: Kerberos authentication, which is used only for authentication between internal nodes.
• 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 ] [-N NODE-NAME] [-I INSTANCE-NAME | -D DATADIR] -h "HOSTTYPE DATABASE USERNAME IPADDR-WITH-IPMASK AUTHMEHOD"

• Display help information.

  gs_guc -? | --help

• Display the version number.

  gs_guc -V | --version

• Use gs_guc encrypt to generate an encrypted password and encryption factor 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. 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 a prefix.

  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.
  • 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 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 last configuration parameter is set and the others are ignored.
• If modification validation is delayed after the parameters in the cluster node configuration file postgresql.conf are set or modified in reload mode, the parameter settings for instances in the cluster 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 semaphore 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: name of an existing host

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

  NOTE: It depends on the static file and is valid only when the OM is installed. The compilation and installation are invalid because there is no static file.

• -I INSTANCE-NAME

  Specifies the name of the instance to be set.

  Value range: name of an existing instance

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

  NOTE: It depends on the static file and is valid only when the OM is installed. The compilation and installation are invalid because there is no static file.

• -D

Specifies the cluster 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 cluster 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

• -lcname=LCNAME

  Specifies the 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.

• -c parameter

  Specifies the name of the parameter to be checked. When you perform the set or reload operation, the parameter value cannot be null. Otherwise, the default value of the database parameter is not restored.

• -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
• sm3
• cert
• gss

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

NOTE: If -h is specified, the system attempts to modify the pg_hba file of all nodes by default. If compilation and installation are performed without static files, the pg_hba file of the current node can be successfully modified, but a message is displayed indicating that the static file does not exist.

• -?, -help

  Display help information.

• -V, -version

  Display 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 a database instance. The default value is datanode. NODE-TYPE is used to identify a configuration file.

  Value range: datanode.

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

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 recomended.

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