GT 3.9.3 GSI-OpenSSH : System Administrator's Guide

Introduction

This is a guide for installing and administering GSI-enabled OpenSSH. This guide is meant solely to cover the GSI aspects of GSI-OpenSSH, and is not meant to be a full manual for OpenSSH itself. Please refer to the OpenSSH Home Page for general documentation for OpenSSH.

Building and Installing

To install GSI-enabled OpenSSH, follow the instructions for the Globus Toolkit All Services or Pre-WS Installer.

You can optionally pass build-time configure options to the GSI-OpenSSH package by setting the macro GSI_OPENSSH_GPTMACRO during the build phase. No options are typically needed for client-only installations, but options are often needed for full server functionality. The following table lists suggested options for different platforms.

Platform Configuration
Linux --with-pam --with-md5-passwords --with-tcp-wrappers
Solaris --with-pam --with-md5-passwords --with-tcp-wrappers
Irix --with-tcp-wrappers
AIX --with-tcp-wrappers

Note: If you enable PAM support with the --with-pam configuration option, be sure to also set "UsePAM yes" in $GLOBUS_LOCATION/etc/ssh/sshd_config after installation.

If you have an already configured and installed system-wide SSHD and you would like your build of GSI-OpenSSH to behave similarly, investigate the configure options available in GSI-OpenSSH and select those options that would add the functionality that your current SSHD possesses. Be aware that since GSI-OpenSSH is based on OpenSSH, the standard set of functionality is turned on by default.

Please do not attempt to override the following options:

--prefix
--sysconfdir
--with-globus
--with-globus-flavor
--with-ssl-dir

Configuring

Information on configuration settings and environment variables can be found in the public interface guide.

GSI authentication is very sensitive to clock skew. You must run a system clock synchronization service of some type on your system to prevent authentication problems caused by incorrect system clocks. We recommend NTP. Please refer to your operating system documentation or the NTP Home Page for installation instructions. Please also ensure your system timezone is set correctly.

Deploying

  1. To install the GSI-Enabled OpenSSH Server on most systems, you must be a privileged user, such as root.

    sh$ /bin/su - root

    Note: If your system functions like this and you attempt to run these commands as a user other than root, these commands should fail.

  2. (optional) Start a copy of your system's currently running SSH server on an alternate port by running, eg.
    sh# /usr/sbin/sshd -p 2000 &

    You may then choose to log in to this server and continue the rest of these steps from that shell. We recommend doing this since some sshd shutdown scripts do particularly nasty things like killing all of the running SSH servers on a system, not just the parent server that may be listening on port 22.

    Roughly translated, this step is about guaranteeing that an alternate method of access is available should the main SSH server be shutdown and your connection via that server be terminated.

  3. Locate your server's startup/shutdown script directory. On some systems this directory may be located at /etc/rc.d/init.d, but since this location is not constant across operating systems, for the purposes of this document we will refer to this directory as INITDIR. Consult your operating system's documentation for your system's location.
  4. Run the following command
    sh# mv $INITDIR/sshd $INITDIR/sshd.bak
  5. Either copy or link the new sshd script to your system's startup/shutdown script directory.
    sh# cp $GLOBUS_LOCATION/sbin/SXXsshd $INITDIR/sshd
  6. Shutdown the currently running main SSH server.
    sh# $INITDIR/sshd.bak stop
  7. Provided you still have a connection to the machine, start the new SSH server.
    sh# $INITDIR/sshd start
  8. Test the new server by connecting to the standard SSH port (22) and authenticating via multiple methods. Especially test that GSI authentication works correctly.
  9. If you are performing a new install, or if the old server was not configured to be started at run-time and shutdown automatically at system halt or reboot, either use a system utility such as RedHat's chkconfig to configure the system for the correct run-levels, or manually link up the correct run-levels.
    sh# /sbin/chkconfig sshd reset
    The recommended run-levels are listed in a set of comments within the SXXsshd startup script. For example, on standard Unix systems we recommend running the GSI-Enabled OpenSSH server in run-levels two, three, four, and five.
  10. Finally, if, as a precautionary measure, you started a SSH server on an alternate port in order to complete the install process, you can now safely stop all instances of that server.

Testing

  • Edit the file $GLOBUS_LOCATION/sbin/SXXsshd so that the GSI-Enabled OpenSSH server starts up on an alternate port.
  • Run the command
    sh# $GLOBUS_LOCATION/sbin/SXXsshd start
    and verify that the server is running by checking that it both shows up in a process listing and creates a file named $GLOBUS_LOCATION/var/sshd.pid.
  • From a remote machine attempt to connect to the local server on the modified test port using the standard SSH authentication methods plus authenticating via your GSI credentials. This may require you to authorize these users via an appropriate entry in the grid-mapfile.
  • Stop the SSH server by running the command
    sh# $GLOBUS_LOCATION/sbin/SXXsshd stop
    and reverse any changes you made that altered the port on which the server resided upon startup. After this step, running SXXsshd start should start the server on the default port (22).

    • Troubleshooting

    [help for common problems sysadmins may experience]