This section describes each of the parameters that you can edit and assign in the gpupgrade utility configuration file, /usr/local/bin/greenplum/gpupgrade/gpupgrade_config. This file is required for the gpupgrade initialize command.


The gpupgrade configuration file includes the following:

# ----------------------------
# gpupgrade configuration file
# ----------------------------

# The master port for the source Greenplum installation.
source_master_port =

# The installation path for the source Greenplum Database.
# For example, /usr/local/<source-greenplum-version>.
source_gphome =

# The installation path for the target Greenplum Database.
# For example, /usr/local/<target-greenplum-version>.
target_gphome =

# The mode is the upgrade method. The choices are “link” or “copy”.
# The copy method creates a copy of the primary segments and performs the
# upgrade on the copies.
# The link method directly upgrades the primary segments.
# mode = copy

# For extensions installed outside of target_gphome include the extension’s
# path in the dynamic_library_path value. For example, for pxf set
# dynamic_library_path to /usr/local/pxf-gp6/gpextable.
# dynamic_library_path = $libdir

# The disk free ratio specifies what fraction of disk space must be free on
# every host in order for gpupgrade to run. The ratio ranges from 0.0 to 1.0.
# Recommended values are 0.6 [60%] for copy mode, and 0.2 [20%] for link mode.
# disk_free_ratio = 0.6

# Whether to populate pg_hba.conf with hostnames or IP addresses during
# execution of gpinitsystem and other utilities.
# Choose "true" to use host names, or "false" to use IP addresses.
# use_hba_hostnames = false

# The temporary port range for the target Greenplum installation.
# The temporary port range should be reserved prior to initializaton.
# The format is a comma separated list of ports and port ranges, e.g.
# “6000,6002-6005,6012.” The ports will be reconfigured to use the source
# Greenplum installation port range once upgrade is complete.
# temp_port_range = 50432-65535

# The port where the gpupgrade process will be running.
# hub_port = 7527

# The port where the agent process will be running on all hosts.
# agent_port = 6416


You specify the gpupgrade initialize configuration file parameters via a INI-formatted file. A sample configuration file is provided in the directory where you extracted the downloaded gpupgrade utility. The file has required and optional parameters:


  • source_master_port
  • source_gphome
  • target_gphome
  • dynamic_library_path - required if upgrading with extensions whose install location is outside of target_gphome.


  • mode
  • disk_free_ratio
  • use_hba_hostnames
  • temp_port_range
  • hub_port
  • agent_port
  • parent_backup_dirs

See also Prepare for gpupgrade initialize for information about using the configuration file.

Keywords and Values

source_master_port = <port>
(Required) Identifies the master port number of the source cluster. For example: 5432.

source_gphome = <path>
(Required) Sets the location of the source cluster. For example: /usr/local/greenplum-db-5.29.10.

target_gphome = <path>
(Required) Sets the location of the target cluster.

mode = <copy | link>
(Optional) By default set to copy. Sets the mode for gpupgrade. See Review Link vs Copy Mode and Disk Space Requirements for more information.

dynamic_library_path = <path>
Sets the dynamic_library_path configuration parameter on the target Greenplum cluster to specify the location for extensions. This setting is required for extensions that are installed outside of target_gphome, such as GPText, MADlib, and PXF. The default value is $libdir. This table shows the install location for each extension:

Extension Default Install Location
GPText /usr/local/greenplum-text-{GPTEXT_VERSION}/lib/gpdb6 (for example, /usr/local/greenplum-text-3.9.0/lib/gpdb6)
MADlib $GPHOME_TARGET/madlib/Current/ports/greenplum/6/lib
PXF /usr/local/pxf-gp6/gpextable

If you are specifying more than one install location because you are upgrading with multiple extensions, delimit the paths with a colon.

disk_free_ratio = <float>
(Optional) Indicates the free space requirement for the upgrade, with a range of 0.0 to 1.0. It is set by default to 0.6 - for copy mode, which requires 60% free storage space. Uncomment this value and set to 0.2 (20%) if you have specified link mode. Uncomment and set to 0.0 to skip this check. See Review Link vs Copy Mode and Disk Space Requirements for more information.

use_hba_hostnames = <true | false>
(Optional) Indicates whether to use host names or IP addresses during Greenplum Database initialization, in gpinitsystem and other utilities. The value of use_hba_hostnames should match the value of HBA_HOSTNAMES parameter in the Greenplum 5.x gpinitsystem_config configuration file. For more information about HBA_HOSTNAMES, see gpinitsystem.

temp_port_range = <port range>
(Optional) Specifies the range of ports to use when initializing the target cluster. Default is 50432-65535 and allocation starts from 50432 onwards.

hub_port = <int>
(Optional) Sets the port for the gpupgrade hub process running on the master; 7527 by default. If you have an existing application running on the default hub port, change this value accordingly.

agent_port = <path>
(Optional) Sets the port for the gpupgrade agent process running on all hosts; set to 6416 by default. If you have an existing application running on the default agent port, change this value accordingly.

parent_backup_dirs = <path>
(Optional) Sets the file system location to store the backup of the master data directory and user defined master tablespaces that the utility takes during upgrade process. The default value is the parent directory of each primary data directory on each host. For example, /data/master if using /data/master/gpseg-1, or /data1/primaries if using /data1/primaries/gpseg1. Specify a directory to set the same path for all hosts, or use the form “host1:/dir1, host2:dir2” to set different paths for different hosts, where the first host must be the master.


See an example gpupgrade_config configuration file in the directory where you extracted the downloaded gpupgrade utility.

See Also

Run gpupgrade initialize, Review Link vs Copy Mode and Disk Space Requirements.

check-circle-line exclamation-circle-line close-line
Scroll to top icon