gs_guc

Background

Currently, the default values of parameters in openGauss 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 option" 
    

    NOTE: authmehod-options supports the following options:

    • trust: no authentication. Remote hosts are not allowed to access cluster 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 authmehod-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. **-M **indicates the encryption type. Its value can be server, client or source. The default value is server.

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 openGauss node configuration file postgresql.conf are set or modified in reload mode, the parameter settings for instances in openGauss 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 openGauss 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 openGauss 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 openGauss 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” indicates the name of the parameter whose value needs to 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: 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

    Specifies the string to be encrypted.

    Value range: a string.

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

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 ***
Feedback
编组 3备份
    openGauss 2024-05-25 00:42:51
    cancel