Using the GSI-Enabled OpenSSH Client

Introduction

This is a guide for using the GSI-enabled OpenSSH client. It assumes that you (or your system administrator) have already installed the GSI OpenSSH program and that you have also acquired a user certificate from an appropriate Certificate Authority.

Setting up your environment

GSI-enabled OpenSSH needs to be able to find certain files and directories in order to properly function.

GSSAPI_MECH_CONF: Applies to mechglue used to support both GSI and Kerberos GSSAPI mechanisms. Used to specify the location of the mech.conf file that lists the mechanism-specific GSSAPI libraries (both Kerberos and GSI versions). If GSSAPI_MECH_CONF is not set then /etc/mech.conf is used. This applies to both the clients and the server. The NCSA GSSAPI mechglue distribution includes a sample mech.conf file. You will need to edit the library paths in that file and install it in an appropriate location on your system. If the mech.conf file is not found, the GSSAPI mechglue library will not load any GSSAPI mechanisms and GSI-OpenSSH will simply skip GSSAPI authentication.
LD_LIBRARY_PATH: The ssh client is typically linked dynamically with Globus security libraries, which must be present in the dynamic linker's search path. This typically requires $GLOBUS_LOCATION/lib to be included in the list in the LD_LIBRARY_PATH environment variable, which is set by the $GLOBUS_LOCATION/libexec/globus-script-initializer script, which should be called from any ssh invocation script. Alternatively, to set LD_LIBRARY_PATH appropriately for the Globus libraries in an interactive shell, source $GLOBUS_LOCATION/etc/globus-user-env.sh (for sh shells) or $GLOBUS_LOCATION/etc/globus-user.env.csh (for csh shells).
X509_CERT_DIR: Specifies a non-standard location for the CA certificates directory.
X509_USER_CERT: Specifies a non-standard location for the certificate to be used for authentication to the server.
X509_USER_KEY: Specifies a non-standard location for the private key to be used for authentication to the server.
X509_USER_PROXY: Specifies a non-standard location for the proxy credential to be used for authentication to the server.

Creating a proxy credential

Create a proxy credential for GSI authentication by running the grid-proxy-init program. This is your single sign-on to the Grid. By default, grid-proxy-init will create a proxy credential good for 12 hours. To create a proxy credential with a different lifetime, use the -hours option. For example:

% grid-proxy-init -hours 8

To delete a proxy that was previously create with grid-proxy-init, run:

% grid-proxy-destroy

Getting authorized to connect to a site

Before you can connect to a site the site needs to know the identity on your GSI certificate so that they can map that identity to your local account. At a minimum, the site will need to know your subject name from your certificate. You can get your subject name by running grid-cert-info with the -subject argument. For example:

% grid-cert-info -subject

Email your subject to the administrator of the system you wish to connect to so that they can add your entry to the appropriate authorization files.

Running OpenSSH

Once you have your proxy credential all you should have to do is run OpenSSH providing it with the hostname of the host you want to connect to. For example:

% ssh myhost.somedomain.edu

Note: gsissh is an alternate name for the GSI-enabled ssh client. You should then find yourself automatically logged into your account on the remote system. If something goes wrong please see the troubleshooting section for assistance.

GSI-related OpenSSH options

Two options allow control over the behavior of GSI-OpenSSH:

Proxy delegation: By default, GSI-OpenSSH will forward (delegate) your proxy credential to the remote host when you connect, so you can authenticate to additional Grid services from that host. To disable that behavior, add the following line to your ~/.ssh/config file:
GssapiDelegateCredentials no
GSI authentication: To disable GSI authentication and key exchange, add the following lines to your ~/.ssh/config file:
GssapiAuthentication no
GssapiKeyExchange no

GSI OpenSSH troubleshooting

Please consult the GSI-OpenSSH Client Troubleshooting page.