Administering the GSI-enabled OpenSSH Server

  1. Introduction
  2. Steps to setting up GSI OpenSSHD
    1. Acquiring a host certificate
    2. Authorizing users
    3. Running GSI OpenSSHD
  3. Privilege separation
  4. Environment variables
  5. SSH config files and keys
  6. Allowing only GSI authentication
  7. Server startup
  8. Usage statistics collection

Introduction

This is a guide for administering the GSI-enabled OpenSSH server (SSHD). It assumes that you have already built and installed the GSI-enabled OpenSSH programs.

This guide is meant solely to cover the GSI aspects of GSI-OpenSSHD, it is not meant to be a full manual for OpenSSHD itself. Be sure to read the documentation included with the OpenSSH package.

Steps to setting up GSI OpenSSHD

To set up the GSI-OpenSSH server you need to take the following steps, which are described in detail in following sections:

  1. Acquire a host certificate for any hosts you wish to run GSI SSHD on. This may take a couple of days so do it ahead of time.
  2. Authorize any users you want to be able to connect with GSI SSH.
  3. Configure and run the SSHD daemon itself.

Step 1: Acquiring a host certificate

Each host on which you want to run a GSI daemon will need a host certificate. Instructions for getting a host certificate can be found in the Globus Toolkit Quickstart.

Make sure that the host key's 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).

Step 2: Authorizing users

Any users that you want to be authorized to use GSI to connect to your system need to be listed in your grid-mapfile. Instructions on creating enteries in the grid-mapfile may be found in the Globus Toolkit Admin Guide.

Step 3: Running GSI OpenSSHD

You should be able to run OpenSSHD as you normally would, basically become root and run sshd:

sh# sshd

OpenSSHD will log events to the system log file. If you have problems with OpenSSHD, it is often useful to add the '-d' flag, which will run it in debugging mode producing lots of output. For example:

sh# sshd -d

Privilege separation

Privilege separation, or "privsep," is a method in OpenSSH by which operations that require root privileges are performed by a separate privileged monitor process. Its purpose is to prevent privilege escalation by containing corruption to an unprivileged process.

To enable privilege separation, run the following commands prior to executing the GSI-OpenSSH post-install step:

sh# mkdir /var/empty
sh# chown root:sys /var/empty
sh# chmod 755 /var/empty
sh# groupadd sshd
sh# useradd -g sshd -c 'sshd privsep' -d /var/empty -s /bin/false sshd

Environment variables

GSI-enabled OpenSSHD 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 client.
X509_USER_KEY
Specifies a non-standard location for the private key to be used for authentication to the client.
X509_USER_PROXY
Specifies a non-standard location for the proxy credential to be used for authentication to the client.

Please refer to the Globus Toolkit Admin Guide for more information on the above environment variables.

SSH config files and keys

The GSI-OpenSSH setup script sets up the default configuration files and keys based on your system's environment.

$GLOBUS_LOCATION/etc/ssh/moduli

moduli is some 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 X11Forwarding enabled. You may need to customize this file for compatibility with your system SSH installation (i.e., compare with /etc/ssh/ssh_config).

$GLOBUS_LOCATION/etc/ssh/ssh_host_key[.pub]

Your system's RSA public-/private-key pair for SSH protocol 1 communications.

$GLOBUS_LOCATION/etc/ssh/ssh_host_dsa[.pub]

Your system's DSA public-/private-key pair for SSH protocol 2 communications.

$GLOBUS_LOCATION/etc/ssh/ssh_host_rsa[.pub]

Your system's RSA public-/private-key pair for SSH protocol 2 communications.

$GLOBUS_LOCATION/etc/ssh/ssh_prng_cmds

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 with /etc/ssh/sshd_config). For example, to enable PAM authentication, you will need to set "UsePAM yes" in this file.
If the post-install script found existing 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.

Allowing only GSI authentication

By default the GSI-OpenSSH server will support all standard OpenSSH authentication methods, in addition to GSI, so it can be used as a replacement for the system's SSH server. If you prefer to allow only GSI authentication, modify $GLOBUS_LOCATION/etc/ssh/sshd_config to contain the following:

Protocol 2
RSAAuthentication no
PubkeyAuthentication no
PasswordAuthentication no
ChallengeResponseAuthentication no

You can also remove the non-GSI host keys to force the server to use only GSI host keys:

sh# rm -f $GLOBUS_LOCATION/etc/ssh/*key*

Server startup

Normally you want SSHD to start when the system boots up. A startup script can be found at $GLOBUS_LOCATION/sbin/SXXsshd. Place this file in your system init.d directory and run any commands necessary to turn on the sshd service at start-time. As an example, Red Hat Linux systems store their system init scripts in /etc/rc.d/init.d/.

Usage statistics collection

By default, the sshd server will send generic usage statistics (without user-identifying information) to the GSI-OpenSSH Project. Please see the GSI-OpenSSH Privacy Policy for more details, including instructions for opting out of usage statistics collection and/or for configuring your own usage statistics collector.