Installing Pivotal Greenplum Command Center

The Pivotal Greenplum Command Center installation utility installs the Command Center files on all hosts in the Greenplum Database cluster.

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 or on the standby master host. Running Command Center on the standby master avoids adding load to the master host.

Prerequisites

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

  • Greenplum Database must be installed and running. See the Pivotal Greenplum Command Center release notes for compatible Greenplum Database versions.
  • The Greenplum Database MASTER_DATA_DIRECTORY environment variable must be set.
  • The gpperfmon database and gpmon role must be created and the gpperfmon agents must be running. See Creating the gpperfmon Database.
  • 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. Alternatively, you can install Command Center as root and, when done, change ownership of all files in the installation directory to the gpadmin user. See Selecting and Preparing an Installation Directory for Command Center for options.

Important! If you upgraded to Pivotal 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.

Prepare the Standby Master Host

After the Command Center software is installed, you start the Command Center web server and backend on the standby master host or on the master host. Some preparation is required to enable Command Center to run on the standby master host.

  1. On the master host, edit the $MASTER_DATA_DIRECTORY/pg_hba.conf file and add the following entry to allow the gpmon user to authenticate from any host in the Greenplum Database cluster.

    host   all   gpmon   <IP_of_host>/32   md5
    

    Run gpstop -u to have Greenplum Database reload the file.

  2. 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
  3. 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. The default path is /etc/ssl/certs/cert.pem.

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

Selecting and Preparing an Installation Directory for Command Center

The Command Center installation directory must exist and be writable on every host in the Greenplum Database cluster by the Linux user who runs the Command Center installer. That user must also have passwordless ssh access to all hosts in the cluster. The Command Center installer creates a directory named greenplum-cc-web-<version> in the installation directory on every host in the Greenplum Database cluster. When Command Center installation is complete the greenplum-cc-web-<version> directory and all of its contents must be owned by the gpadmin user.

The default installation directory for Command Center is /usr/local. 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, you can use one of the following methods to install Command Center.

  • Temporarily change permissions on the installation directory to allow the gpadmin user to install Command Center.
  • As root, create the greenplum-cc-web-<version> directory in the installation directory on all hosts in the Greenplum Database cluster and change the directory’s ownership to gpadmin.
  • Run the Command Center installer as root and then change the ownership of the greenplum-cc-web-<version> directory and its contents to gpadmin.

All of these options require root to execute shell commands on every Greenplum Database host. The Greenplum Database utilities gpssh-exkeys and gpssh make this much easier.

Setting up Passwordless ssh for the root User

The root user must have passwordless ssh access to all Greenplum Database hosts in order to run the Command Center installer or to execute shell commands on Greenplum hosts using the gpssh utility. Follow this procedure to set up passwordless ssh access with the gpssh-exkeys utility.

  1. Log in to the master host as the root user.

  2. Create a text file, for example allhosts.txt, containing a list of all Greenplum Database cluster hosts, including the master and standby master host, one name per line.

  3. Source the Greenplum Database environment setup script in the Greenplum Database installation directory.

    # source /usr/local/greenplum-db-<version>/greenplum-db_path.sh
    
  4. Run the gpssh-exkeys utility, specifying the hosts file with the -f option.

    # gpssh-exkeys -f allhosts.txt
    

Create the Installation Directory and Install Command Center Software

Create the Command Center installation directory on all Greenplum Database hosts and assign permissions so that you can run the Command Center installer as the gpadmin user.

  1. Log in to the master host as the root user.

  2. Source the Greenplum Database environment setup script in the Greenplum Database installation directory.

    # source /usr/local/greenplum-db-<version>/greenplum-db_path.sh
    
  3. Use the gpssh utility to create the directory and set ownership on all hosts.

    # gpssh -f allhosts.txt
    => mkdir /opt/greenplum-cc-web-4.4.0
    => chown gpadmin:gpadmin /opt/greenplum-cc-web-4.4.0
    => exit
    
  4. As the gpadmin user, run the Command Center installer as described in Installation Steps. When prompted for the installation directory, enter /opt.

Change Ownership of the Command Center Directory Post-Installation

If you instead installed Command Center installer as the root user, then you must follow these steps to change the ownership of the installation directory and its contents to the gpadmin user. This example assumes you have installed Command Center as root in the opt directory, following the steps in Installation Steps. The files in the greenplum-cc-web-<version> directory and its contents are currently owned by root.

  1. Log in to the master host as root.

  2. Source the Greenplum Database environment setup script in the Greenplum Database installation directory.

    # source /usr/local/greenplum-db-<version>/greenplum-db_path.sh
    
  3. Run the following commands, providing the path to your Command Center installation.

    # gpssh -f allhosts.txt
    => chown -R gpadmin:gpadmin /opt/greenplum-cc-web-<version>
    exit
    

Now you can log in to the standby master or master host as gpadmin and start Command Center.

Installation Steps

You can run the Greenplum Command Center installer on the Greenplum Database master host. The software will be copied to all other hosts in the cluster.

Perform these steps as the gpadmin user, if gpadmin has write permission in the installation directory, or as root.

If you install Command Center as root, make sure root has passwordless ssh access to all hosts in the Greenplum Database cluster. (See Setting up Passwordless ssh for the root User.) When installation is complete, be sure to change the ownership of the Greenplum Command Center directory and contents to gpadmin. (See Change Ownership of the Command Center Directory Post-Installation.)

  1. Download Greenplum Command Center 4.x from Pivotal Network.

  2. Extract the installer from the zip file.

    $ unzip greenplum-cc-web-<version>-LINUX-x86_64.zip
    

    Extracting the installer creates a greenplum-cc-web-<version> directory containing the gpccinstall-<version> installation utility.

  3. 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
    
  4. Run the Greenplum Command Center installer.

    $ cd greenplum-cc-web-<version>
    $ ./gpccinstall-<version> -W
    

    The installer has three options.

    • The -c <config-file> option specifies the path to an installation configuration file to use for a non-interactive installation. See Install with a Configuration File.
    • The W option instructs the installer to prompt for the gpmon user’s password. The installer attempts to retrieve the gpmon password from the PGPASSWORD environment variable, if set, or from the ~gpadmin/.pgpass file, if present. If neither of these options is available, include the -W option to instruct the installer to prompt for 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.
      $ ./gpccinstall-<version> --ssh_path /usr/local/bin/ssh -W
    
  5. Read through the license agreement and enter y to accept.

  6. Where would you like to install Greenplum Command Center?

    The default installation directory is /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 gpadmin.

  7. What would you like to name this installation of Greenplum Command Center?

    Enter a name to display on Command Center web pages to identify this Greenplum Database system.

  8. On which port would you like to install the Greenplum Command Center web server?

    The default Command Center listen port is 28080. Press Enter to accept the default or enter another port number.

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

    Provide the file path for the SSL certificate

    Enter the path to the certificate installed on the Command Center host. The default is /etc/ssl/certs/cert.pem. The certificate must be readable by the gpadmin user.

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


    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 default service name for Greenplum Database is postgres. You can check the value of the service name for your Greenplum Database cluster with 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.

If you ran the installer as root, change the ownership of the Greenplum Command Center directory and contents to gpadmin. See Change Ownership of the Command Center Directory Post-installation.

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. Note that you must still view and accept the license agreement.

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

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: /etc/ssl/certs/cert.pem 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

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

If the enable_kerberos parameter is true, the keytab parameter is required and the webserver_url, krb_mode, and krb_service_name must be set to values from your Kerberos installation.

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 the hostname of the Greenplum master host
# display_name = localhost

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

Set Up Command Center and Workload Management Extensions

You must follow the steps in this section only if you have upgraded your Pivotal 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 Pivotal 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.

  1. 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'
    
  2. 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
    
  3. If you changed any configuration parameters, restart Greenplum Database.

    gpstop -r
    

Next Steps