Installing VMware Tanzu Greenplum Command Center

The VMware Tanzu Greenplum Command Center installation utility installs the Command Center files on all hosts in the Greenplum Database cluster, creates the gpperfmon database and gpmon user, if needed, and creates the gp_metrics schema in the gpperfmon database.

Note: Run the Greenplum Command Center installer on the Greenplum Database master host. The installer installs the Command Center software on every host in your Greenplum Database cluster. It retrieves the list of hosts in your Greenplum Database cluster from the gp_segment_configuration system table.

After you have run the installer you can start Greenplum Command Center on the master host (recommended) or on the standby master host.

Prerequisites

Before installing Greenplum Command Center, ensure the following requirements are met:

Greenplum Database must be installed and running. See the VMware Tanzu Greenplum Command Center release notes for compatible Greenplum Database versions.
The Greenplum Database MASTER_DATA_DIRECTORY environment variable must be set.
The directory where Greenplum Command Center will be installed, /usr/local/ by default, must be writable by the gpadmin user on all Greenplum Database hosts. See Selecting and Preparing an Installation Directory for Command Center.
Port 28080 (default) must be open to TCP connections from Web clients to the HTTP server on the master and standby master hosts. Greenplum Command Center web browser clients connect to this port to access the Command Center Console. Browser connections use HTTP/HTTPS and WebSocket (WS)/Secure WebSocket (WSS) protocols. A different port number can be specified when Command Center is installed. To access the Command Center web server through a proxy, the proxy must have WebSocket support.
Port 8899 must be open on all hosts in the Greenplum Database cluster for TCP connections. This is an RPC port, used by the metrics collection agents on the segment hosts to send metrics to the backend.
If you choose to have Command Center server support SSL/TLS encryption for browser connections – the default behavior – you need a combined SSL certificate file containing the server certificate and private key. See SSL/TLS Encryption for more information.

Important! If you upgraded to VMware Tanzu Greenplum Database release 5.7 or later from an earlier Greenplum Database 5.x release, you must follow steps at Set Up the Metrics Collection and Workload Management Extensions before you start Greenplum Command Center.

Selecting and Preparing an Installation Directory for Command Center

The Command Center installation directory (default /usr/local) must exist and be writable by the gpadmin user on every host in the Greenplum Database cluster. The Command Center installer creates a directory named greenplum-cc-<version> in this directory on every host. When Command Center installation is complete the greenplum-cc-<version> directory and all of its contents must be owned by the gpadmin user. If Command Center creates the greenplum-cc-<version> directory, it also creates a greenplum-cc symbolic link to it, providing the gpadmin user has permission to create the link. You can use the greenplum-cc link in your shell startup script to source the gpcc_path.sh file.

In a standard Linux system, the /usr/local directory is owned by root and is only writable by root. If you choose the default installation directory or another directory where gpadmin does not have write permission, the root user can create the Command Center directory and the symbolic link in the installation directory on each host and make gpadmin the owner. Then the gpadmin user can run the installer without error.

If the gpadmin user has sudo access, you can use the gpssh utility to create the directory and set the owner to gpadmin on all hosts with these commands:

$ source /usr/local/greenplum-db-<version>/greenplum_path.sh
$ gpssh -f <hostfile> 'sudo mkdir -p /usr/local/greenplum-cc-4.11.0; chown -R gpadmin:gpadmin /usr/local/greenplum-cc-4.11.0'
$ gpssh -f <hostfile> 'sudo ln -s /usr/local/greenplum-cc-4.11.0 /usr/local/greenplum-cc'

The <hostfile> text file contains a list of all Greenplum host names, including the master, standby master, and segment hosts.

See Installing the Greenplum Database Software for information about setting up passwordless SSH.

Install the Greenplum Command Center Software

Run the Greenplum Command Center installer on the Greenplum Database master host. The installer copies the software to all other hosts in the cluster.

Download the Greenplum Command Center distribution file for your VMware Greenplum version from Broadcom Support Portal and copy it to the gpadmin user’s home directory on the master host.

Note
For more information about download prerequisites, troubleshooting, and instructions, see Download Broadcom products and software.
Extract the installer from the zip file.
```
$ unzip greenplum-cc-web-gp6-<version>-<platform>.zip
```
Extracting the installer creates a greenplum-web-<version> directory containing the gpccinstall-<version> installation utility.

There are four ways to run the Greenplum Command Center installer:

Interactive – the installer prompts you for the installation parameters.
Scripted – you run the installer with a configuration file containing installation parameters.
Upgrade – the installer uses the installation parameters from the current Command Center installation.
Auto – the installer uses default installation parameters.

Note: The Command Center installer uses HTTPS as the default protocol for the Command Center web server. If you choose HTTP instead, Command Center issues a warning message. The only exception is if you install with the -auto option, for which the default protocol is HTTP.

Interactive Installation

Source the greenplum_path.sh script in the Greenplum Database installation directory to ensure the GPHOME environment variable is set.
```
$ source /usr/local/greenplum-db/greenplum_path.sh
```
Run the Greenplum Command Center installer.
```
$ cd greenplum-cc-<version>
$ ./gpccinstall-<version> 
```
You can add the following options to the gpccinstall command-line. - The -W option instructs the installer to prompt for the gpmon database user’s password. - If the gpmon user does not yet exist, the installer creates it using the password you enter at the prompt. The password is not saved anywhere, so be sure to remember the password you enter.
- If the gpmon user already exists, the installer uses the password you enter at the prompt for the gpmon user. It ignores any password set in the PGPASSWORD environment variable or in the .pgpass file (~gpadmin/.pgpass, or the file specified in the PGPASSFILE environment variable). - If the gpmon user already exists, but you do not specify the -W option, the installer uses the password set in the PGPASSWORD environment variable or in the .pgpass file.
- If the gpmon user does not yet exist and you do not specify -W (or if you specify the -W option but enter no password at the prompt) the installer creates the gpmon user with a default password. See the .pgpass file to find the password. - The -ssh_path option allows you to specify the full path to a custom SSH program. If you do not supply this option, the installer uses the ssh command on the path. Example:
```
$ ./gpccinstall-<version> --ssh_path /usr/local/bin/ssh -W
```
- The -ipv6 option installs a version of Command Center with support for running on IPv6 networks. To enable IPv6, you must set the HTTPAddr configuration parameter in the $GPCC_HOME/conf/app.conf file to the IPv6 address of the host that runs Command Center.
- The -krbenable option includes prompts to configure Command Center Kerberos authentication. The Kerberos prompts are omitted from the installation dialog by default.
Where would you like to install Greenplum Command Center? (Default=/usr/local)

Press Enter to accept the default or enter the desired path. The directory must exist on all hosts in the Greenplum Database cluster and must be writable by the gpadmin user. See Selecting and Preparing an Installation Directory for Command Center for more information.
What would you like to name this installation of Greenplum Command Center? (Default=gpcc)

Enter a name to display on Command Center web pages to identify this Greenplum Command Center installation.
What port would you like the gpcc webserver to use? (Default=28080)

The default Command Center listen port is 28080. Press Enter to accept the default or enter another port number.
Would you like to enable Kerberos?

Enter y if you want to enable client authentication with Kerberos. Kerberos must already be enabled for Greenplum Database. (If you enter n, you can set up Kerberos authentication later using the gpcc krbenable command.) The installer prompts for information about your Kerberos installation.

Choose Kerberos mode (1.normal/2.strict/3.gpmon_only)

Greenplum Command Center supports three different Kerberos authentication schemes.

1 - normal mode (default) – The Command Center Kerberos keytab file contains the Command Center principal and may contain principals for Command Center users. If the principal in the client’s connection request is in the Command Center’s keytab file, Command Center uses the client’s principal for database connections. Otherwise, Command Center uses the gpmon user for database connections.
2 - strict mode – Command Center has a Kerberos keytab file containing the Command Center service principal and a principal for every Command Center user. If the principal in the client’s connection request is in the keytab file, the web server grants the client access and the web server connects to Greenplum Database using the client’s principal name. If the principal is not in the keytab file, the connection request fails.
3 - gpmon_only mode – Command Center uses the gpmon database role for all Greenplum Database connections. No client principals are needed in the Command Center’s keytab file.

Enter path to the keytab file

Provide the path to the keytab file

Enter the path to the keytab file containing the Kerberos principal for the Command Center web server and, optionally, Command Center user principals.

What is the name of the GPDB Kerberos service?

The Kerberos service name for Greenplum Database is postgres.

With Greenplum Database versions earlier than 6.0, a different Kerberos service name can be specified by setting the krb_srvname server configuration parameter. You can find the service name for your pre-6.0 Greenplum Database cluster using the gpconfig utility:
```
$ gpconfig -s krb_srvname
```
What is the URL of the Command Center web server?

The Kerberos keytab file must contain a principal for the Command Center web server. The principal name is of the format HTTP/<gpcc-host>@<realm>, where <gpcc-host> is the host name clients use in URLs when connecting to the Command Center web server.
Would you like to enable SSL?

Enter y if you want to enable SSL/TLS (HTTPS) encryption for client connections to the Command Center web server. The installation utility prompts for the location of the SSL certificate.

Please enter the full path for the SSL certificate file, including file name

Enter the path to the combined SSL certificate file installed on the Command Center host. This file contains a certificate and a private key for the web server. The file must be readable by the gpadmin user. See SSL/TLS Encryption for information about creating this file and installing it on your server.
Choose a display language (Default=English)
1. English
2. Chinese
3. Korean
4. Russian
5. Japanese

Enter a number to choose a language for the Command Center user interface.

The installer saves a log of the installation session in the current directory in a file named gpccinstall.<timestamp>.log.

Updating the Metrics Collector Extension

If a new Greenplum Database metrics_collector extension is required, the installer displays the following message:

********************************************************************************
*                                                                              *
* INSTALLATION IS ALMOST COMPLETED                                             *
*                                                                              *
* The last step is to update the metrics_collector extension, which needs to   *
* restart the Greenplum Database cluster. Please proceed to $GPCC_HOME and     *
* follow the instructions in this file:                                        *
*                                                                              *
*                            update-extension.txt                              *
*                                                                              *
* Some new features may not be available before the update is done.            *
*                                                                              *
* To use GPCC with the old metrics_collector extension, source gpcc_path.sh    *
* and run 'gpcc start'.                                                        *
*                                                                              *
********************************************************************************

If you are unable to restart Greenplum Database at this time, you can source the gpcc_path.sh file in the newly installed Command Center directory and then restart Command Center. New Command Center features may not be available until you update the metrics collector extension and restart Greenplum Database.

Follow these steps to upgrade the metrics_collector extension.

Source the gpcc_path.sh file in the new Command Center installation directory.
```
$ source <install-dir>/greenplum-cc/gpcc_path.sh
```
Change to the new Command Center home directory.
```
$ cd $GPCC_HOME
```

View and follow the instructions in the update-extension.txt file.

$ cat update-extension.txt

Please update metrics_collector extension with the following steps.
Skip if you just reinstalled GPCC without any changes to GPDB binary.
For more information please check the documentation.

######################################
#                                    #
#   I M P O R T A N T  N O T I C E   #
#                                    #
######################################

When upgrading GPDB to a newer version,
DO NOT use "gppkg --migrate" to migrate the previous metrics_collector.

If you have to use "gppkg -- migrate" for some other packages,
first run "gppkg -r" to remove metrics_collector from the old GPDB 
installation.

Before you proceed with updating the metrics_collector extension,
be sure to back up these original files, in case you decide to roll back:

$GPHOME/lib/postgresql/metrics_collector.so
$GPHOME/share/postgresql/extension/metrics_collector*
$GPHOME/share/postgresql/extension/gp_wlm*

1. cd /usr/local/greenplum-cc-4.11.0/gppkg
2. Stop GPCC: gpcc stop
3. Drop extension: psql gpperfmon -c 'drop extension metrics_collector'
4. Use "gppkg -q --all" to list packages installed.
5. Remove the old version of the metrics_collector: "gppkg -r <name>-<version>"
6. Install the new version: gppkg -i MetricsCollector-6.2.0_gp_6.7.0-<OS>-<ARCH>.gppkg
7. Restart GPDB
8. Restart GPCC: gpcc start

Install With a Configuration File

You can provide a configuration file to the Greenplum Command Center installer to perform a non-interactive Command Center installation.

$ cd greenplum-cc-<version>
$ ./gpccinstall-<version> -c <config-file>

The following table contains the names of the parameters corresponding to the interactive installation prompts and their default values. Define parameters in a configuration file for any parameters that have no default value or to override default values.

Installer Prompt	Default	Parameter
Where would you like to install Greenplum Command Center?	/usr/local	path
What would you like to name this installation of Greenplum Command Center?	gpcc	display_name
On which port would you like to install the Greenplum Command Center web server?	28080	web_port
Would you like to enable SSL?	false	enable_ssl
Please provide the file path for the SSL certificate:	none	ssl_cert_file
Would you like to enable Kerberos?	false	enable_kerberos
Choose Kerberos mode (1.normal/2.strict/3.gpmon_only):	1	krb_mode
Please provide the path to the keytab file:		keytab
What is the name of the GPDB Kerberos service?	postgres	krb_service_name
What is the URL of the Command Center web server?	gpcc	webserver_url
Would you like to enable SSL?	true	enable_ssl
Please provide the file path for the SSL certificate:	/etc/ssl/certs/cert.pem	ssl_cert_file
Please choose a display language (1.English2.Chinese/3.Korean/4.Russian/5.Japanese)	1	language

If the enable_kerberos parameter is true, the keytab, webserver_url, krb_mode, and krb_service_name parameters must also be set.

If the enable_ssl parameter is true, the ssl_cert_file parameter is required.

The following installation configuration file example sets all parameters to their default values.

path = /usr/local
# Set the display_name param to the string to display in the GPCC UI.
# The default is "gpcc"
# display_name = gpcc

master_port = 5432
web_port = 28080
rpc_port = 8899
enable_ssl = false
# Uncomment and set the ssl_cert_file if you set enable_ssl to true.
# ssl_cert_file = /etc/certs/mycert
enable_kerberos = false
# Uncomment and set the following parameters if you set enable_kerberos to true.
# webserver_url = <webserver_service_url>
# krb_mode = 1
# keytab = <path_to_keytab>
# krb_service_name = postgres
# User interface language: 1 = English, 2 = Chinese, 3 = Korean, 4 = Russian, 5 = Japanese
language = 1

Non-Interactive Installation with Defaults

The non-interative installation is useful when installing Command Center in a cloud environment.

Source the greenplum_path.sh script in the Greenplum Database installation directory to ensure the GPHOME environment variable is set.
```
$ source /usr/local/greenplum-db/greenplum_path.sh
```
Run the Greenplum Command Center installer with the -auto option.
```
$ cd greenplum-cc-<version>
$ ./gpccinstall-<version> -auto
```

Note: When you run the installer with the -auto option, the Command Center installer uses HTTP as the default protocol for the Command Center web server. To override this, you must use the -c option to pass in a configuration file that has enable_ssl set to true and ssl_cert_file set to the cert file path.

Upgrade

Running gpccinstall with the -u option installs a Greenplum Command Center release using the configuration parameters from the Command Center installation. You can install a new Command Center release, or reinstall the current release. This option is also useful after you have added new hosts to the Greenplum Database cluster or replaced failed hosts.

The configuration parameters are read from the $GPCC_HOME/conf/app.conf file.

Source the greenplum_path.sh script in the Greenplum Database installation directory to ensure the GPHOME environment variable is set.
```
$ source /usr/local/greenplum-db/greenplum_path.sh
```
Source the gpcc_path.sh script in the Greenplum Command Center installation directory.
```
$ source /usr/local/greenplum-cc-<version>/gpcc_path.sh
```
Run the Greenplum Command Center installer with the -u option.
```
$ cd greenplum-cc-<version>
$ ./gpccinstall-<version> -u
```

Changed Location for the `gpmetrics` Directory Starting in Command Center 4.16

In Command Center 4.16, the gpmetrics directory default location changed from $MASTER_DATA_DIRECTORY to $HOME.

If you are upgrading from Command Center 4.15.x or earlier and a directory called gpmetrics does not already exist under $HOME, Command Center will migrate the gpcc.conf and gpcc-alert.yaml files from $MASTER_DATA_DIRECTORY/gpmetrics directory to $HOME/gpmetrics.

If a directory called gpmetrics does already exist under $HOME, you must copy the gpcc.conf and gpcc-alert.yaml files over manually before starting Command Center 4.16.0 or later for the first time.

NOTE: To specify a default location different than $HOME for the gpmetrics directory, configure the gpmetrics_home parameter in the $GPCC_HOME/conf/app.conf file. For more information, see the Command Center Console Parameters topic.

Set Up Command Center and Workload Management Extensions

You must follow the steps in this section only if you have upgraded your VMware Tanzu Greenplum Database system from a 5.x release earlier than 5.7.0.

The Greenplum Database metrics collection and workload management extensions are installed when you upgrade to VMware Tanzu Greenplum Database 5.7.0 or later. However, the upgrade procedure preserves your previous postgresql.conf configuration file, so you must manually set the server configuration parameters that enable the extensions. You must restart Greenplum Database if you change any configuration parameters.

To set up the Command Center and workload management extensions, log in to the master host as gpadmin and follow these steps.

Add the metrics collector and workload management shared libraries to the shared_preload_libraries configuration parameter.

Check the current value of the shared_preload_libraries configuration parameter.
```
$ gpconfig -s shared_preload_libraries
Values on all segments are consistent
GUC          : shared_preload_libraries
Master  value:
Segment value:
```
Add the Command Center and workload management libraries to the parameter. (If there were existing libraries in the parameter, append the new libraries, separated with a comma.)
```
$ gpconfig -c shared_preload_libraries -v '\$libdir/metrics_collector,\$libdir/gp_wlm'
```

Make sure the gp_enable_query_metrics configuration parameter is on.

gpconfig -s gp_enable_query_metrics
gpconfig -c gp_enable_query_metrics -v on

If you changed any configuration parameters, restart Greenplum Database.
```
gpstop -r
```

Installing Multiple Command Center Instances

You can install a Command Center instance for each Greenplum Database system installed on your cluster. This feature requires Greenplum Database 5.28.0 or above.

Follow these steps when installing an additional Command Center instance.

Source the greenplum_path.sh file in the target Greenplum Database system before you start the Command Center installer.
Run the latest Greenplum Command Center installer for the target Greenplum Database system.
- Choose an installation path that is different from any existing Command Center instances.
- Choose a name for the Command Center installation that is different from any existing Command Center instances.
- Choose a Command Center web server port number that is different from any existing Command Center instances.
When the installation has finished source the gpcc_path.sh file in the new Command Center installation directory.
Edit the $GPCC_HOME/conf/app.conf file.
- Change the rpc_port parameter from the default value, 8899, to a different, available port number.
- Change the ws_perf_port parameter from the default value, 6162, to a different, available port number.
- Change the agent_perf_port parameter from the default value, 6163, to a different, available port number.

Before you start or stop a Command Center instance, be sure to source the greenplum_path.sh file in the Greenplum Database installation directory and the gpcc_path.sh file in the corresponding Command Center installation directory. Then you can run the gpcc start, gpcc stop, or other gpcc commands.

Prepare the Standby Master Host

After the Command Center software is installed, you start the Command Center web server and backend on the master host or the standby master host. Running Command Center on the master host is recommended, but preparing the standby host ensures the standby can run Command Center if the master fails.

Copy the .pgpass file from the master host to the standby master host. Run these commands from the master:
```
$ ssh gpadmin@<standby_host>
$ scp gpadmin@<master_host>:~/.pgpass ~
$ chmod 600 ~/.pgpass
```
Note: There are two alternative methods you can use to supply the gpmon user’s password so that you do not have to put the .pgpass file on the host. Command Center only requires the gpmon password when you run gpcc start, gpcc stop, or gpcc status.
1. Set the PGPASSWORD environment variable before you run gpcc commands. Example:
```
$ PGPASSWORD=changeme gpcc status
```
2. Add the -W option to gpcc commands to have the command prompt you for the password. Example:
```
$ gpcc start -W
```
If the Greenplum Command Center web server is to support TLS/SSL, a server certificate must be obtained and installed on the Command Center host in a location readable by the gpadmin user.
If Greenplum Command Center is to support Kerberos authentication, Greenplum Database must have Kerberos authentication set up and the required principals and keytabs must be installed on the Command Center host. See Enabling Authentication with Kerberos for Kerberos setup instructions. You can install Command Center without Kerberos authentication initially and then enable Kerberos later by running the gpcc krbenable command.