Installing the Greenplum Client Tools
A newer version of this documentation is available. Use the version menu above to view the most up-to-date release of the Greenplum 5.x documentation.
Installing the Greenplum Client Tools
This section contains information for installing the client programs on your client machine and for enabling Greenplum Database to accept remote client connections:
- Running the Client Tools Installer
- Configuring the Command-Line Tools
- Enabling Greenplum Database for Remote Client Connections
- Configuring a Client System for Kerberos Authentication
- Next Steps
See the Greenplum Database Release Notes for the list of currently supported platforms for the Client Tools.
Running the Client Tools Installer
The Greenplum Database client tools installer installs the following client tools:
To install the Greenplum Database client tools
- Download the appropriate greenplum-clients-<version>-PLATFORM.bin installer package for your platform from Pivotal Network.
- Unzip the
- Run the
- The installer will prompt you to accept the license agreement and to provide an installation path. For the installation path, be sure to enter an absolute path if you choose not to accept the default location (for example, /mydir/gp-client-tools). The client tools are installed into greenplum-db-<version> by default.
Configuring the Command-Line Tools
As a convenience, a greenplum_clients_path.sh file is provided in your client tools installation directory following installation. It has the following environment variable settings:
GPHOME_CLIENTS — The installation directory of the Greenplum Database client tools.
PATH — The paths to the command-line utilities.
LD_LIBRARY_PATH — The path to the library files.
You can source this file in your user's startup shell profile (such as .bashrc or .bash_profile).
For example, you could add a line similar to the following to your chosen profile files (making sure the right install path is used):
After editing the chosen profile file, source it as the correct user to make the changes active. For example:
Additional Connection Environment Variables
The PostgreSQL command-line tools require several connection parameters in order to be able to connect to a Greenplum Database database. In order to save some typing on the command-line, you can create the following environment variables in your preferred profile file (such as .bashrc).
- PGDATABASE — The name of the default Greenplum database to connect to.
- PGHOST — The Greenplum master host name or IP address.
- PGPORT — The port number that the Greenplum master instance (postmaster process) is running on.
- PGUSER — The default database role name to use for login.
Enabling Greenplum Database for Remote Client Connections
In order for Greenplum Database to be able to accept remote client connections, you must configure your Greenplum Database master so that connections are allowed from the client hosts and database users that will be connecting to Greenplum Database.
To enable remote client connections
- Make sure that the pg_hba.conf file of the
Greenplum Database master is correctly configured to allow connections from
the users to the database(s) using the authentication method you want. For
details, see "Editing the pg_hba.conf File" in the Greenplum Database
Administration Guide, and also see the Greenplum Database
Security Configuration Guide.
Make sure the authentication method you choose is supported by the client tool you are using.
- If you edited pg_hba.conf file, the change requires a server reload (using the gpstop -u command) to take effect.
- Make sure that the databases and roles you are using to connect exist in the system and that the roles have the correct privileges to the database objects.
Configuring a Client System for Kerberos Authentication
If you use Kerberos authentication to connect to a Greenplum Database with the psql utility, your client system must be configured to use Kerberos authentication. If you are not using Kerberos authentication to connect to a Greenplum Database, Kerberos is not needed on your client system.
- Setting Up a Client System with Kerberos Authentication
- Accessing Greenplum Database with psql
For information about enabling Kerberos authentication with Greenplum Database, see the "Kerberos Authentication" chapter in the Greenplum Database Administrator Guide.
The following are requirements to connect to a Greenplum Database that is enabled with Kerberos authentication from a client system with Greenplum Database client software.
- Kerberos must be installed and configured on the Greenplum Database master host. See Enabling Greenplum Database for Remote Client Connections.
- The client systems require the Kerberos configuration file krb5.conf from the Greenplum Database master.
- The client systems require a Kerberos keytab file that contains the authentication credentials for the Greenplum Database user that is used to log into the database.
- The client machines must be able to connect to Greenplum
Database master host.
If necessary, add the Greenplum Database master host name and IP address to the system hosts file.
On Linux systems, the hosts file is located in /etc.
Required Software on the Client Machine
The Kerberos kinit utility is required on the client machine. The kinit utility is available when you install the Kerberos packages:
Setting Up a Client System with Kerberos Authentication
To connect to Greenplum Database with Kerberos authentication requires a Kerberos ticket. On client systems, tickets are generated from Kerberos keytab files with the kinit utility and are stored in a cache file.
- Install a copy of the Kerberos configuration file
krb5.conf from the Greenplum Database master. The file
is used by the Greenplum Database client software and the Kerberos
Install krb5.conf in the /etc directory.
If needed, add the parameter default_ccache_name to the [libdefaults] section of the krb5.ini file and specify the location of the Kerberos ticket cache file on the client system.
- Obtain a Kerberos keytab file that contains the authentication credentials for the Greenplum Database user.
- Run kinit specifying the keytab file to
create a ticket on the client machine. For this example, the keytab file
gpdb-kerberos.keytab is in the current directory. The
ticket cache file is in the gpadmin user home directory. For
$ kinit -k -t gpdb-kerberos.keytab -c /home/gpadmin/cache.txt gpadmin/kerberos-gpdb@KRB.EXAMPLE.COM
Accessing Greenplum Database with psql
From a remote system, you can access a Greenplum Database that has Kerberos authentication enabled.
To connect to Greenplum Database with psql
- As the gpadmin user, open a command window.
- Start psql from the command window and
specify a connection to the Greenplum Database specifying the user that
is configured with Kerberos authentication.
The following example logs into the Greenplum Database on the machine kerberos-gpdb as the gpadmin user with the Kerberos credentials gpadmin/kerberos-gpdb:
$ psql -U "gpadmin/kerberos-gpdb" -h kerberos-gpdb postgres