gpMgmt/doc/gpaddmirrors_help - cloudberry - Git at Google

 COMMAND NAME: gpaddmirrors

 Adds mirror segments to a Apache Cloudberry system that was
 initially configured without mirroring.


 *****************************************************
 SYNOPSIS
 *****************************************************


 gpaddmirrors [-p <port_offset>] [-m <datadir_config_file> [-a]] [-s]
              [-d <coordinator_data_directory>] [-B <parallel_processes>]
              [-l <logfile_directory>] [-v]

 gpaddmirrors -i <mirror_config_file> [-s] [-a]
              [-d <coordinator_data_directory>]
              [-B <batch_size>] [-b <segment_batch_size>]
              [-l <logfile_directory>] [-v]

 gpaddmirrors -o <output_sample_mirror_config> [-m <datadir_config_file>]

 gpaddmirrors -?

 gpaddmirrors --version


 *****************************************************
 DESCRIPTION
 *****************************************************
 The gpaddmirrors utility configures mirror segment instances for an
 existing Apache Cloudberry system that was initially configured with
 primary segment instances only. The utility will create the mirror
 instances and begin the online replication process between the primary
 and mirror segment instances. Once all mirrors are synchronized with
 their primaries, your Apache Cloudberry system is fully data redundant.

 IMPORTANT: During the online replication process, Apache Cloudberry
 should be in a quiescent state, workloads and other queries should not
 be running.

 By default, the utility will prompt you for the file system location(s)
 where it will create the mirror segment data directories. If you do not
 want to be prompted, you can pass in a file containing the file system
 locations using the -m option.

 The mirror locations and ports must be different than your primary
 segment data locations and ports.

 The utility will create a unique data directory for each mirror segment
 instance in the specified location using the predefined naming convention.
 There must be the same number of file system locations declared for mirror
 segment instances as for primary segment instances. It is OK to specify
 the same directory name multiple times if you want your mirror data
 directories created in the same location, or you can enter a different
 data location for each mirror. Enter the absolute path. For example:

 Enter mirror segment data directory location 1 of 2 > /gpdb/mirror
 Enter mirror segment data directory location 2 of 2 > /gpdb/mirror
 OR
 Enter mirror segment data directory location 1 of 2 > /gpdb/m1
 Enter mirror segment data directory location 2 of 2 > /gpdb/m2

 Alternatively, you can run the gpaddmirrors utility and supply a
 detailed configuration file using the -i option. This is useful if
 you want your mirror segments on a completely different set of hosts
 than your primary segments. The format of the mirror configuration file is:

 <content>|<address>|<port>|<datadir>

 For example:

 0|sdw1-1|60000|/gpdata/mirror1/gp0
 1|sdw1-1|60001|/gpdata/mirror2/gp1

 The gp_segment_configuration system catalog tables can help you determine
 your current primary segment configuration so that you can plan your
 mirror segment configuration. For example, run the following query:

 =# SELECT dbid, content, address as host_address, port, datadir
    FROM gp_segment_configuration
    ORDER BY dbid;

 If creating your mirrors on alternate mirror hosts, the new
 mirror segment hosts must be pre-installed with the Cloudberry
 Database software and configured exactly the same as the
 existing primary segment hosts.

 You must make sure that the user who runs gpaddmirrors (the
 gpadmin user) has permissions to write to the data directory
 locations specified. You may want to create these directories
 on the segment hosts and chown them to the appropriate user
 before running gpaddmirrors.


 *****************************************************
 OPTIONS
 *****************************************************

 -a

  Run in quiet mode - do not prompt for information. Must supply
  a configuration file with either -m or -i if this option is used.


 -B <batch_size>

 The number of hosts to work on in parallel. If not specified, the
 utility will start working on up to 16 hosts in parallel.
 Valid values: 1-64


 -b <segment_batch_size>

 The number of segments per host to work on in parallel. If not
 specified, the utility will start working on up to 64 segments
 in parallel on each host it is working on.
 Valid values: 1-128


 -d <coordinator_data_directory>

  The coordinator data directory. If not specified, the value set for
  $COORDINATOR_DATA_DIRECTORY will be used.


 -i <mirror_config_file>

  A configuration file containing one line for each mirror segment
  you want to create. You must have one mirror segment listed for
  each primary segment in the system. The format of this file is as
  follows (as per attributes in the gp_segment_configuration catalog
  table):

    <content>|<address>|<port>|<datadir>


 -l <logfile_directory>

  The directory to write the log file. Defaults to ~/gpAdminLogs.


 -m <datadir_config_file>

  A configuration file containing a list of file system locations where
  the mirror data directories will be created. If not supplied, the
  utility will prompt you for locations. Each line in the file specifies
  a mirror data directory location. For example:
    /gpdata/m1
    /gpdata/m2
    /gpdata/m3
    /gpdata/m4


 -o <output_sample_mirror_config>

  If you are not sure how to lay out the mirror configuration file
  used by the -i option, you can run gpaddmirrors with this option
  to generate a sample mirror configuration file based on your
  primary segment configuration. The utility will prompt you for
  your mirror segment data directory locations (unless you provide
  these in a file using -m). You can then edit this file to change
  the host names to alternate mirror hosts if necessary.


 -p <port_offset>

  Optional. This number is used to calculate the database ports
  used for mirror segments. The default offset is 1000. Mirror
  port assignments are calculated as follows:
 	primary port + offset = mirror database port
  For example, if a primary segment has port 50001, then its mirror
  will use a database port of 51001 by default.


 -s

  Spreads the mirror segments across the available hosts. The
  default is to group a set of mirror segments together on an
  alternate host from their primary segment set. Mirror spreading
  will place each mirror on a different host within the Cloudberry
  Database array. Spreading is only allowed if there is a sufficient
  number of hosts in the array (number of hosts is greater than
  or equal to the number of segment instances per host).


 --hba-hostnames

  Optional. use hostnames instead of CIDR in pg_hba.conf


 -v

  Sets logging output to verbose.


 --version

  Displays the version of this utility.


 -?

  Displays the online help.


 *****************************************************
 EXAMPLES
 *****************************************************

 Add mirroring to an existing Apache Cloudberry system using
 the same set of hosts as your primary data. Calculate the mirror
 database ports by adding 100 to the current primary segment port
 numbers:

   $ gpaddmirrors -p 100


 Add mirroring to an existing Apache Cloudberry system using a
 different set of hosts from your primary data:

 $ gpaddmirrors -i mirror_config_file

 Where the mirror_config_file looks something like this:

 0|sdw1-1|52001|53001|54001|/gpdata/mir1/gp0
 1|sdw1-2|52002|53002|54002|/gpdata/mir2/gp1
 2|sdw2-1|52001|53001|54001|/gpdata/mir1/gp2
 3|sdw2-2|52002|53002|54002|/gpdata/mir2/gp3


 Output a sample mirror configuration file to use with gpaddmirrors -i:

   $ gpaddmirrors -o /home/gpadmin/sample_mirror_config


 *****************************************************
 SEE ALSO
 *****************************************************

 gpinitsystem, gpinitstandby, gpactivatestandby
	COMMAND NAME: gpaddmirrors

	Adds mirror segments to a Apache Cloudberry system that was
	initially configured without mirroring.


	*****************************************************
	SYNOPSIS
	*****************************************************


	gpaddmirrors [-p <port_offset>] [-m <datadir_config_file> [-a]] [-s]
	[-d <coordinator_data_directory>] [-B <parallel_processes>]
	[-l <logfile_directory>] [-v]

	gpaddmirrors -i <mirror_config_file> [-s] [-a]
	[-d <coordinator_data_directory>]
	[-B <batch_size>] [-b <segment_batch_size>]
	[-l <logfile_directory>] [-v]

	gpaddmirrors -o <output_sample_mirror_config> [-m <datadir_config_file>]

	gpaddmirrors -?

	gpaddmirrors --version


	*****************************************************
	DESCRIPTION
	*****************************************************
	The gpaddmirrors utility configures mirror segment instances for an
	existing Apache Cloudberry system that was initially configured with
	primary segment instances only. The utility will create the mirror
	instances and begin the online replication process between the primary
	and mirror segment instances. Once all mirrors are synchronized with
	their primaries, your Apache Cloudberry system is fully data redundant.

	IMPORTANT: During the online replication process, Apache Cloudberry
	should be in a quiescent state, workloads and other queries should not
	be running.

	By default, the utility will prompt you for the file system location(s)
	where it will create the mirror segment data directories. If you do not
	want to be prompted, you can pass in a file containing the file system
	locations using the -m option.

	The mirror locations and ports must be different than your primary
	segment data locations and ports.

	The utility will create a unique data directory for each mirror segment
	instance in the specified location using the predefined naming convention.
	There must be the same number of file system locations declared for mirror
	segment instances as for primary segment instances. It is OK to specify
	the same directory name multiple times if you want your mirror data
	directories created in the same location, or you can enter a different
	data location for each mirror. Enter the absolute path. For example:

	Enter mirror segment data directory location 1 of 2 > /gpdb/mirror
	Enter mirror segment data directory location 2 of 2 > /gpdb/mirror
	OR
	Enter mirror segment data directory location 1 of 2 > /gpdb/m1
	Enter mirror segment data directory location 2 of 2 > /gpdb/m2

	Alternatively, you can run the gpaddmirrors utility and supply a
	detailed configuration file using the -i option. This is useful if
	you want your mirror segments on a completely different set of hosts
	than your primary segments. The format of the mirror configuration file is:

	<content>\|<address>\|<port>\|<datadir>

	For example:

	0\|sdw1-1\|60000\|/gpdata/mirror1/gp0
	1\|sdw1-1\|60001\|/gpdata/mirror2/gp1

	The gp_segment_configuration system catalog tables can help you determine
	your current primary segment configuration so that you can plan your
	mirror segment configuration. For example, run the following query:

	=# SELECT dbid, content, address as host_address, port, datadir
	FROM gp_segment_configuration
	ORDER BY dbid;

	If creating your mirrors on alternate mirror hosts, the new
	mirror segment hosts must be pre-installed with the Cloudberry
	Database software and configured exactly the same as the
	existing primary segment hosts.

	You must make sure that the user who runs gpaddmirrors (the
	gpadmin user) has permissions to write to the data directory
	locations specified. You may want to create these directories
	on the segment hosts and chown them to the appropriate user
	before running gpaddmirrors.


	*****************************************************
	OPTIONS
	*****************************************************

	-a

	Run in quiet mode - do not prompt for information. Must supply
	a configuration file with either -m or -i if this option is used.


	-B <batch_size>

	The number of hosts to work on in parallel. If not specified, the
	utility will start working on up to 16 hosts in parallel.
	Valid values: 1-64


	-b <segment_batch_size>

	The number of segments per host to work on in parallel. If not
	specified, the utility will start working on up to 64 segments
	in parallel on each host it is working on.
	Valid values: 1-128


	-d <coordinator_data_directory>

	The coordinator data directory. If not specified, the value set for
	$COORDINATOR_DATA_DIRECTORY will be used.


	-i <mirror_config_file>

	A configuration file containing one line for each mirror segment
	you want to create. You must have one mirror segment listed for
	each primary segment in the system. The format of this file is as
	follows (as per attributes in the gp_segment_configuration catalog
	table):

	<content>\|<address>\|<port>\|<datadir>


	-l <logfile_directory>

	The directory to write the log file. Defaults to ~/gpAdminLogs.


	-m <datadir_config_file>

	A configuration file containing a list of file system locations where
	the mirror data directories will be created. If not supplied, the
	utility will prompt you for locations. Each line in the file specifies
	a mirror data directory location. For example:
	/gpdata/m1
	/gpdata/m2
	/gpdata/m3
	/gpdata/m4


	-o <output_sample_mirror_config>

	If you are not sure how to lay out the mirror configuration file
	used by the -i option, you can run gpaddmirrors with this option
	to generate a sample mirror configuration file based on your
	primary segment configuration. The utility will prompt you for
	your mirror segment data directory locations (unless you provide
	these in a file using -m). You can then edit this file to change
	the host names to alternate mirror hosts if necessary.


	-p <port_offset>

	Optional. This number is used to calculate the database ports
	used for mirror segments. The default offset is 1000. Mirror
	port assignments are calculated as follows:
	primary port + offset = mirror database port
	For example, if a primary segment has port 50001, then its mirror
	will use a database port of 51001 by default.


	-s

	Spreads the mirror segments across the available hosts. The
	default is to group a set of mirror segments together on an
	alternate host from their primary segment set. Mirror spreading
	will place each mirror on a different host within the Cloudberry
	Database array. Spreading is only allowed if there is a sufficient
	number of hosts in the array (number of hosts is greater than
	or equal to the number of segment instances per host).


	--hba-hostnames

	Optional. use hostnames instead of CIDR in pg_hba.conf


	-v

	Sets logging output to verbose.


	--version

	Displays the version of this utility.


	-?

	Displays the online help.


	*****************************************************
	EXAMPLES
	*****************************************************

	Add mirroring to an existing Apache Cloudberry system using
	the same set of hosts as your primary data. Calculate the mirror
	database ports by adding 100 to the current primary segment port
	numbers:

	$ gpaddmirrors -p 100


	Add mirroring to an existing Apache Cloudberry system using a
	different set of hosts from your primary data:

	$ gpaddmirrors -i mirror_config_file

	Where the mirror_config_file looks something like this:

	0\|sdw1-1\|52001\|53001\|54001\|/gpdata/mir1/gp0
	1\|sdw1-2\|52002\|53002\|54002\|/gpdata/mir2/gp1
	2\|sdw2-1\|52001\|53001\|54001\|/gpdata/mir1/gp2
	3\|sdw2-2\|52002\|53002\|54002\|/gpdata/mir2/gp3


	Output a sample mirror configuration file to use with gpaddmirrors -i:

	$ gpaddmirrors -o /home/gpadmin/sample_mirror_config


	*****************************************************
	SEE ALSO
	*****************************************************

	gpinitsystem, gpinitstandby, gpactivatestandby