FILE: @(#) 1.4 09/05/06 22:57:09 README.sshWindows SSH AND RAZOR The Razor 5.2 release introduces two elements that rely upon ssh. The Razor remote command-line extends a subset of the Razor 'local' command-line to remote users via ssh. The ssh tool provides an alternative approach to authenticating remote users against the local password file via 'rexec'. OVERVIEW The basic idea is to have each remote user create a public/private key pair as well as a passphrase. The private key is retained on the host from which the remote Razor Versions, Issues, or Threads client will be run. The corresponding public key is installed on the Razor License Manager host. The user will provide the (optional) passphrase to indicate that they are the rightful owner of the keys. Through the use of an ssh agent, the remote Razor user can avoid having to authenticate themselves multiple times as they attempt to connect to remote Razor servers via remote command-line, Versions, Threads, and/or Issues. OBTAINING PuTTY TOOLSET Most non-Windows platforms include a variant of the OpenSSH toolset. For Windows, the PuTTY toolset will be used. The toolset can be downloaded from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html In particular the 'puttygen.exe', 'plink.exe', and 'pageant.exe' tools will be required. These tools can be downloaded from the PuTTY site individually are as a bundle. For purposes of example, the PuTTy tools have been installed in C:\PuttyTools. SSH SETUP Each remote Razor user mush create a public/private key pair. The PuTTY toolset includes the 'puttygen.exe' utility for generating a key pair. 1) Launch the C:\PuttyTools\puttygen.exe tool. 2) Select the 'Generate' button. 3) Move the mouse about the GUI's blank area to add a unique, random element to the key generation process. 4) The key generation can take several minutes to complete. 5) When key generation is complete, the GUI will display the public key, key fingerprint, key comment, as well as fields for specifying and confirming the key 'passphrase'. 6) Specify a 'passphrase' that will be used to safegard your key. The passphrase should be handled like a account password. For our example, a passphrase of "Over the hills and through the woods". 7) Select the 'Save public key' button to create a local copy of the key, e.g. C:\PuttyTools\puttyXpPublicKey. 8) Select the 'Save private key' button to create a local copy of the key, e.g. C:\PuttyTools\puttyXpPrivateKey.ppk 9) Razor may not be able to locate the PuTTY tools even if their installation directory is included in your PATH. Define a new environment variable, RAZOR_PUTTY_INSTALL_DIR, to specify where the PuTTY utilities have been installed, e.g. C:\PuttyTools Let's review what we have. The 'public' key has been saved as 'C:\PuttyTools\puttyXpPublicKey'. This key will need to be installed on the Razor License Manager host. The corresponding private key has been saved as 'C:\PuttyTools\putty\XpPrivateKey.ppk'. This key is NOT to be distributed. The private key is also protected with the passphrase that you have provided. INSTALLING YOUR PUBLIC KEY Your public key will need to be installed on the server that you will be connecting to via ssh. Authenticating remote Issues, Versions, and/or Threads users against the local password file will require that you install your public key on the Razor License Manager host. Accessing your your Razor Database Manager via the Razor remote command-line will require that you install your public key on the DB host. If the Razor License and Database Managers are co-located you'll need to install the key in a single location. You must have an account on the server that you'll be connecting to via ssh. Once you have your key file on the server you'll need to add its contents to your 'authorized_keys' file, i.e. $HOME/.ssh/authorized_keys. If you've used ssh on the server file before then you'll already have an authorized_keys file. You'll simply append your public key file to the authorized_keys file. If you've never used ssh on the server you'll have some additional setup work to do. Let's look at what is required: Establish a ssh connection to the server host using the PuTTY (C:\PuttyTools\putty.exe) tool. Specify the IP address of the server. Login using username and password. $ cd $HOME $ mkdir .ssh $ chmod 700 .ssh $ cd .ssh $ cp authorized_keys authorized_keys. $ vi authorized_keys << Insert the public key by inserting the text in the 'PuTTY Key Generator' GUI's 'Public key for pasting into OpenSSH authorized_keys file:' window. Save the file and verify that the new key was (pre)appended properly. There should be one key entry per line. >> $ chmod 600 authorized_keys CONFIGURING SERVER SSH POLICIES You'll need to work with the server's system admin to enable support for ssh as applicable. The server's 'sshd_config' file is the place to start. By convention all of the default values are commented out via "#" token. Here are the more notable entries from the sshd_config template: PubkeyAuthentication yes AuthorizedKeysFile .ssh/authorized_keys AllowUsers <> You'll need to make your changes and restart the ssh daemon. CONFIGURING PuTTY's SSH-AGENT, PAGEANT When the remote Razor client attempts to authenticate the user via ssh there is not opportunity for the user to enter the ssh passphrase. Therefore, the user must setup an ssh agent to effectively cache the passphrase ahead of time. Once the agent is started it will step in and complete the ssh authentication on your behalf without having to reenter the passphrase. The agent is started by double-clicking C:\PuttyTools\pagent.exe. You'll want to use the 'Add Key' button to browse to your private key (C:\PuttyTools\puttyXpPrivatekey.ppk) and specify your passphrase ("Over the hills and through the woods"). At this point all ssh-aware applications including the Razor remote clients, Razor remote command-line will work with the ssh agent to obtain the necessary authentication without bothering the user for the passphrase. TEST DRIVING SSH Once you've installed your public key and enabled ssh on the server you'll want to try to ssh into the remote server to validate your setup. There's no point trying to utilize the Razor remote command-line or authenticate via ssh until you've convinced yourself that you ssh setup is working. Open a Windows command prompt window. We'll use PuTTY's 'plink' tool to run a command on the server via ssh. From the command line, enter: C:\PuttyTools\plink -ssh -agent -i C:\PuttyTools\puttyXpPrivatekey.ppk @ E.g. "C:\PuttyTools\plink -ssh -agent -i C:\PuttyTools\puttyXpPrivatekey.ppk brian@192.168.1.113 uname -a" The plink tool should run your command directly on the the remote server. Since the the pageant tool is holding your authenticated key you should NOT be prompted for the passphrase. In the event that ssh fails, you'll want to work with server sys admin to troubleshoot. There are a few places to start. On the server side you'll want to: - Review sshd_config file - Review firewall configuration to verify that ssh is enabled - Verify that the ssh daemon (sshd) is running - Check the log files to see why access is denied On the client side you'll want to: - Review firewall configuration to verify that outgoing ssh connection is allowed - Attempt to start the ssh connection using 'verbose' mode to see debugging info. Use "ssh -v <>" RazorPC performs a simple SSH-based test to verify that the user, as specified in the RazorPC login window, has sufficiently authenticated themselves to the Razor License Manager host. RazorPC uses the PuTTY toolset's 'pscp' command to list the contents of the "/" directory on the Razor License Manager host. If the remote user can manipulate SSH to list the directory contents then RazorPC considers the user authenticated. RazorPC uses the following command for authentication purposes: /pscp -v -ls -agent -batch -sftp @:/ E.g. "C:\PuttyTools\pscp -v -ls -agent -batch -sftp brian@192.168.1.113:/" This command should successfully authenticate the remote user via SSH, list the contents of the remote "/" directory, and exit. If the command hangs it is usually due to either an SSH authentication failure or output (generated by 'echo ...') in the user's login shell running on the Razor License Manager host. USING SSH TO AUTHENTICATE REMOTE ISSUES, VERSIONS, THREADS USERS By default the remote Issues, Versions, and Threads clients will seek authenticate against the local password file using 'rexec' rather than ssh. To override the default value, the 'RAZOR_USE_SSH_REMOTE_AUTH' environment variable must be set prior to launching the Razor remote client(s). FURTHER INFORMATION The PuTTY help. Select 'Help' button in pagent, puttygen, or putty tools. The man pages for ssh, ssh-keygen, ssh-agent, ssh-add. OpenSSH website (http://www.openssh.org) SSH User Identities white paper (http://www.securityfocus.com/infocus/1810) SSH and ssh-agent white paper (http://www.securityfocus.com/infocus/1812) ---------------------------------------------------------------------- ---------------------------------------------------------------------- CONFIGURING A SSH SERVER FOR WINDOWS-BASED RAZOR SERVER The previous portions of the README file discuss how to configure and operate an ssh client under Windows. The Razor remote command-line interface (CLI) interacts with a remote Razor server using the OpenSSH ssh and scp tools for authentication, execution of remote commands, and file transfers. Use of the remote CLI requires that the Razor server operate an ssh server. Most non-Windows platforms include a variant of the OpenSSH server as part of the basic installation. If your Razor server is hosted on a Windows platform you'll need to do a fair amount of work to get an ssh server installed. An OpenSSH server can be installed on your Windows host. The following article provides an excellent procedure for installing, configuring, and testing your OpenSSH installation on Windows. http://pigtail.net/LRP/printsrv/cygwin-sshd.html