Administering the GSI-enabled OpenSSH Server
- Introduction
- Steps to setting up GSI OpenSSHD
- Privilege separation
- Environment variables
- SSH config files and keys
- Allowing only GSI authentication
- Server startup
- 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:
- 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.
- Authorize any users you want to be able to connect with GSI SSH.
- 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:
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:
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# 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.
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:
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:
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.