gpinitsystem
Initializes a Apache Cloudberry system using configuration parameters specified in the gpinitsystem_config
file.
Synopsis
gpinitsystem -c <cluster_configuration_file>
[-h <hostfile_gpinitsystem>]
[-B <parallel_processes>]
[-p <postgresql_conf_param_file>]
[-s <standby_coordinator_host>
[-P <standby_coordinator_port>]
[-S <standby_coordinator_datadir> | --standby_datadir=<standby_coordinator_datadir>]]
[-m <number> | --max_connections=number>]
[-b <size> | --shared_buffers=<size>]
[-n <locale> | --locale=<locale>] [--lc-collate=<locale>]
[--lc-ctype=<locale>] [--lc-messages=<locale>]
[--lc-monetary=<locale>] [--lc-numeric=<locale>]
[--lc-time=<locale>] [-e <password> | --su_password=<password>]
[--mirror-mode={group|spread}] [-a] [-q] [-l <logfile_directory>] [-D]
[-I <input_configuration_file>]
[-O <output_configuration_file>]
gpinitsystem -v | --version
gpinitsystem -? | --help
Description
The gpinitsystem
utility creates a Apache Cloudberry instance or writes an input configuration file using the values defined in a cluster configuration file and any command-line options that you provide. See Initialization Configuration File Format for more information about the configuration file. Before running this utility, make sure that you have installed the Apache Cloudberry software on all the hosts in the array.
With the <-O output_configuration_file>
option, gpinitsystem
writes all provided configuration information to the specified output file. This file can be used with the -I
option to create a new cluster or re-create a cluster from a backed up configuration. See Initialization Configuration File Format for more information.
In a Apache Cloudberry DBMS, each database instance (the coordinator instance and all segment instances) must be initialized across all of the hosts in the system in such a way that they can all work together as a unified DBMS. The gpinitsystem
utility takes care of initializing the Cloudberry coordinator and each segment instance, and configuring the system as a whole.
Before running gpinitsystem
, you must set the $GPHOME
environment variable to point to the location of your Apache Cloudberry installation on the coordinator host and exchange SSH keys between all host addresses in the array using gpssh-exkeys
.
This utility performs the following tasks:
- Verifies that the parameters in the configuration file are correct.
- Ensures that a connection can be established to each host address. If a host address cannot be reached, the utility will exit.
- Verifies the locale settings.
- Displays the configuration that will be used and prompts the user for confirmation.
- Initializes the coordinator instance.
- Initializes the standby coordinator instance (if specified).
- Initializes the primary segment instances.
- Initializes the mirror segment instances (if mirroring is configured).
- Configures the Apache Cloudberry system and checks for errors.
- Starts the Apache Cloudberry system.
Note This utility uses secure shell (SSH) connections between systems to perform its tasks. In large Apache Cloudberry deployments, cloud deployments, or deployments with a large number of segments per host, this utility may exceed the host's maximum threshold for unauthenticated connections. Consider updating the SSH
MaxStartups
andMaxSessions
configuration parameters to increase this threshold. For more information about SSH configuration options, refer to the SSH documentation for your Linux distribution.
Options
-a
Do not prompt the user for confirmation.
-B parallel_processes
The number of segments to create in parallel. If not specified, the utility will start up to 4 parallel processes at a time.
-c cluster_configuration_file
Required. The full path and filename of the configuration file, which contains all of the defined parameters to configure and initialize a new Apache Cloudberry system. See Initialization Configuration File Format for a description of this file. You must provide either the -c <cluster_configuration_file>
option or the -I <input_configuration_file>
option to gpinitsystem
.
-D
Sets log output level to debug.
-h hostfile_gpinitsystem
Optional. The full path and filename of a file that contains the host addresses of your segment hosts. If not specified on the command line, you can specify the host file using the MACHINE_LIST_FILE
parameter in the gpinitsystem_config file.
-I input_configuration_file
The full path and filename of an input configuration file, which defines the Apache Cloudberry host systems, the coordinator instance and segment instances on the hosts, using the QD_PRIMARY_ARRAY
, PRIMARY_ARRAY
, and MIRROR_ARRAY
parameters. The input configuration file is typically created by using gpinitsystem
with the -O output_configuration_file
option. Edit those parameters in order to initialize a new cluster or re-create a cluster from a backed up configuration. You must provide either the -c <cluster_configuration_file>
option or the -I <input_configuration_file>
option to gpinitsystem
.
-n locale | --locale=locale
Sets the default locale used by Apache Cloudberry. If not specified, the default locale is en_US.utf8
. A locale identifier consists of a language identifier and a region identifier, and optionally a character set encoding. For example, sv_SE
is Swedish as spoken in Sweden, en_US
is U.S. English, and fr_CA
is French Canadian. If more than one character set can be useful for a locale, then the specifications look like this: en_US.UTF-8
(locale specification and character set encoding). On most systems, the command locale
will show the locale environment settings and locale -a
will show a list of all available locales.
--lc-collate=locale
Similar to --locale
, but sets the locale used for collation (sorting data). The sort order cannot be changed after Apache Cloudberry is initialized, so it is important to choose a collation locale that is compatible with the character set encodings that you plan to use for your data. There is a special collation name of C
or POSIX
(byte-order sorting as opposed to dictionary-order sorting). The C
collation can be used with any character encoding.
--lc-ctype=locale
Similar to --locale
, but sets the locale used for character classification (what character sequences are valid and how they are interpreted). This cannot be changed after Apache Cloudberry is initialized, so it is important to choose a character classification locale that is compatible with the data you plan to store in Apache Cloudberry.
--lc-messages=locale
Similar to --locale
, but sets the locale used for messages output by Apache Cloudberry. The current version of Apache Cloudberry does not support multiple locales for output messages (all messages are in English), so changing this setting will not have any effect.
--lc-monetary=locale
Similar to --locale
, but sets the locale used for formatting currency amounts.
--lc-numeric=locale
Similar to --locale
, but sets the locale used for formatting numbers.
--lc-time=locale
Similar to --locale
, but sets the locale used for formatting dates and times.
-l logfile_directory
The directory to write the log file. Defaults to ~/gpAdminLogs
.
-m number | --max_connections=number
Sets the maximum number of client connections allowed to the coordinator. The default is 250.
-O output_configuration_file
Optional, used during new cluster initialization. This option writes the cluster_configuration_file
information (used with -c) to the specified output_configuration_file
. This file defines the Apache Cloudberry members using the QD_PRIMARY_ARRAY
, PRIMARY_ARRAY
, and MIRROR_ARRAY
parameters. Use this file as a template for the -I
input_configuration_file
option. See Examples for more information.
-p postgresql_conf_param_file
Optional. The name of a file that contains postgresql.conf
parameter settings that you want to set for Apache Cloudberry. These settings will be used when the individual coordinator and segment instances are initialized. You can also set parameters after initialization using the gpconfig
utility.
-q
Run in quiet mode. Command output is not displayed on the screen, but is still written to the log file.
-b size | --shared_buffers=size
Sets the amount of memory a Cloudberry server instance uses for shared memory buffers. You can specify sizing in kilobytes (kB), megabytes (MB) or gigabytes (GB). The default is 125MB.
-s standby_coordinator_host
Optional. If you wish to configure a backup coordinator instance, specify the host name using this option. The Apache Cloudberry software must already be installed and configured on this host.
-P standby_coordinator_port
If you configure a standby coordinator instance with -s
, specify its port number using this option. The default port is the same as the coordinator port. To run the standby and coordinator on the same host, you must use this option to specify a different port for the standby. The Apache Cloudberry software must already be installed and configured on the standby host.
-S standby_coordinator_datadir | --standby_dir=standby_coordinator_datadir
If you configure a standby coordinator host with -s
, use this option to specify its data directory. If you configure a standby on the same host as the coordinator instance, the coordinator and standby must have separate data directories.
-e superuser_password | --su_password=superuser_password
Use this option to specify the password to set for the Apache Cloudberry superuser account (such as gpadmin
). If this option is not specified, the default password gparray
is assigned to the superuser account. You can use the ALTER ROLE
command to change the password at a later time.
Recommended security best practices:
- Do not use the default password option for production environments.
- Change the password immediately after installation.
--mirror-mode={group|spread}
Use this option to specify the placement of mirror segment instances on the segment hosts. The default, group
, groups the mirror segments for all of a host's primary segments on a single alternate host. spread
spreads mirror segments for the primary segments on a host across different hosts in the Apache Cloudberry array. Spreading is only allowed if the number of hosts is greater than the number of segment instances per host.
-v | --version
Print the gpinitsystem
version and exit.
-? | --help
Show help about gpinitsystem
command line arguments, and exit.