Using the GSI-Enabled OpenSSH Client

1. Introduction
2. Setting up your environment
3. Creating a proxy credential
4. Getting authorized to connect to a site
5. Running OpenSSH
6. GSI-related OpenSSH options
7. GSI-enabled OpenSSH troubleshooting

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 GSI user certificate from an appropriate Certificate Authority.

Setting up your environment

Set the GLOBUS_LOCATION environment variable to the location of your GSI-enabled OpenSSH installation. It may already be set for you by your system administrator.

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:

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

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:

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:

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

Some common errors are listed below. If you need additional assistance please run ssh with the '-v' argument (specifying verbose output) and send the output to the gsi-openssh-user@globus.org email list.

• GSS-API error Failuring acquiring GSSAPI credentials: GSS_S_CREDENTIALS_EXPIRED

  This means that your proxy certificate has expired. You need to acquire a new proxy certificate and run SSH again.

• SSH prompts you for a pass phrase when you run it

  This could mean that you don't have a proxy certificate, try acquiring one and running SSH again. It could also mean that the GSI authentication is failing for some reason and SSH is falling back to a different authentication mechanism. Reasons that it might fail include:

  • The host you are connecting to does not have a GSI-enabled SSHD
  • You are not authorized to use GSI authentication to the host. Contact the administrator.
• Library error from ssh-keysign

  If you install ssh-keysign setuid root for hostbased authentication, you may experience library errors, because LD_LIBRARY_PATH is ignored for setuid executables. You can fix it in one of the following ways:

  • Add the GSI libraries to the default system library search path (for example, by editing /etc/ld.so.conf and running ldconfig).
  • Build ssh-keysign statically with gpt-build -static.
  • Use ssh-keysign from a non-GSI build of OpenSSH.