GSI-OpenSSH Commands

Abstract

The gsissh(1), gsiscp(1), and gsisftp(1) commands provide the same
interfaces as the standard
OpenSSH ssh, scp,
and sftp commands, respectively, with the added
ability to perform X.509 proxy credential authentication and
delegation.

Tool description

Command syntax

Name

Synopsis

Tool description

Use the gsiscp command to securely copy files to
or from a remote machine.

Command syntax

gsiscp [-P port]
[[user@]host1:]file1 [...] [[user@]host2:]destfile

Name

gsisftp — Secure file transfer

Synopsis

gsisftp

Tool description

The gsisftp command provides an interactive
interface for transferring files to and from remote machines.

Command syntax

gsisftp [[user@]host[:dir[/]]]

Chapter 1. Configuring

The GSI-enabled OpenSSH software is installed with a default set of
configuration files, described below.
You may want to modify the ssh_config file before using the
clients and the sshd_config file before using the server.

If the GSI-enabled OpenSSH install script finds existing SSH key
pairs, it will create symbolic links to them rather than
generating new key pairs. The SSH key pairs are not required for
GSI authentication. However, if you wish to support other SSH
authentication methods, make sure the sshd (running as root) can
read the key pair files (i.e., beware of NFS mounts with
root_squash). If running multiple sshds on a system, we recommend
configuring them so they all use the same key pairs (i.e., use
symbolic links) to avoid client-side confusion.

$GLOBUS_LOCATION/etc/ssh/moduli

moduli is a crypto parameter for generating keys.

$GLOBUS_LOCATION/etc/ssh/ssh_config

ssh_config contains options that are read by ssh, scp, and sftp at
run-time. The installed version is the default provided by
OpenSSH, with GSI authentication and X11Forwarding enabled.
You may need to customize
this file for compatibility with your system SSH installation
(i.e., compare it with /etc/ssh/ssh_config).

ssh_prng_cmds contains paths to a number of files that ssh-keygen may
need to use if your system does not have a built-in entropy pool (like
/dev/random).

$GLOBUS_LOCATION/etc/ssh/sshd_config

sshd_config contains options that are read by sshd when it starts
up. The installed version is the default provided by OpenSSH, with
X11Forwarding enabled. You may need to customize this file for
compatibility with your system SSH installation (i.e., compare it
with /etc/ssh/sshd_config). For example, to enable PAM
authentication, you may need to set "UsePAM yes" in this file.

Appendix A. Errors

Run grid-proxy-init to acquire a new proxy certificate, then run gsissh again.

...no proxy credentials...

Failing to run grid-proxy-init to create a user proxy with which to connect will result in the client notifying you that no local credentials
exist. Any attempt to authenticate using GSI will fail in this case.

...bad file system permissions on private key; key must only be readable by the user...

The host key that the SSH server is using for GSI authentication must only be readable by the user which owns it.
Any other permissions will cause this error.

Make sure that the host key's UNIX permissions are mode 400 (that is, it should only have mode readable for the user that owns the file,
and no other mode bits should be set).

...gssapi received empty username; failed to set username from gssapi context; Failed external-keyx for <user> from <host> <port>...

If the server was passed an "implicit username" (i.e. requested to map the incoming connection to a username based on some
contextual clues such as the certificate's subject), and no entry exists in the grid-mapfile for the incoming connection's certificate subject,
the server should output a clue that states it is unable to set the username against which to authenticate.

If the subject name given in the system's grid-mapfile points to a non-existent user, the server will give an internal error
which is best caught when it is running in debugging mode.

Add a new account to the system matching the username pointed at by the user's subject in the grid-mapfile.

...gssapi received empty username; no suitable client data; failed to set username from gssapi context; Failed external-keyx for <user> from <host> <port>...

Should the user attempt to connect without first creating a proxy certificate, or if the user is connecting via a SSH client that does
not support GSI authentication, the server will note that no GSSAPI data was sent to it. Verify that the client is able to connect through
another GSI service (such as the gatekeeper) to make sure that the user's proxy has been created correctly.

Verify that you are using a GSI-enabled SSH client and that your GSI proxy has been properly initialized via
grid-proxy-info. If you need to initialize this proxy, use the command grid-proxy-init.

Glossary

G

grid map file

A file containing entries mapping certificate subjects to local user
names. This file can also serve as a access control list for GSI
enabled services and is typically found in
/etc/grid-security/grid-mapfile. For more
information see the Gridmap section here.

H

host certificate

An EEC belonging to a host. When using GSI this certificate is
typically stored in
/etc/grid-security/hostcert.pem. For more
information on possible host certificate locations see the GSI C Developer's Guide.

P

proxy credentials

The combination of a proxy certificate and its corresponding private
key. GSI typically stores proxy credentials in
/tmp/x509up_u<uid>, where <uid> is the user id of the proxy
owner.