Thursday, April 10, 2008

Configuring OpenSSH on Windows to support ControlTier

ControlTier's ability to automatically coordinate distributed command execution is built on a Secure Shell (SSH) protocol "network".

The assumption is that the system user account on a given system used to run a given "dispatchCmd" from ControlTier (usually from the administration node running Jobcenter) has been "equivalenced" to all client users and systems necessary to allow non-interactive authentication via SSH. This is usually achieved using public key authentication.

While it is a fair bet that a given Unix/Linux system will be running the SSH server to enable login services, this is almost never the case for Windows systems.

This posting captures the (unfortunately complex and arcane!) steps necessary to deploy an OpenSSH server on a Windows system. The goal is to enable the SSH service, enable a designated Windows user for remote access and facilitate command execution using the command shell (cmd.exe). (These notes do not deliver a full Cygwin installation, just the minimum necessary to enable SSH access).

The notes are an updated version of a posting to the ControlTier Google group.

SSH installation
  • Download the latest version of copSSH - this packaging of OpenSSH and Cygwin provides a GUI based installer that simplifies Windows installation.
  • Run the copSSH setup program as a user with Administrators group membership.
  • Install to "C:\copSSH" or "C:\cygwin" rather than the default location (make sure that there are no spaces in any of the Cygwin paths).
User setup
  • Create or designate a Windows local (not domain based) system account as the ControlTier user.
  • Set a password for the user, and set its home folder to the Cygwin installation hierarchy, e.g.: "C:\copSSH\home\user"
  • Log on and off once as the user to ensure settings are established, running a "cmd" shell to confirm that the HOMEDRIVE/HOMEPATH has indeed been set correctly.
Enable SSH for the user
  • Run copSSH's "01. Activate a user" item from the start menu.
  • Select the "user" and leave the default command shell for the time being.
  • Change the user's shell to "/bin/"
  • Deselect the options to create public key authentication keys and link the user's real home directory.
  • Create the following script in the Cygwin "bin" directory (e.g. "C:\copSSH\bin") using Notepad or similar:
    if [[ $# -eq 0 ]]
    exec /cygdrive/c/windows/system32/cmd /Q
    exec /cygdrive/c/windows/system32/cmd /Q /C "$@"
  • Convert the script to a Unix style text file as follows:
    C:\copSSH\bin>d2u done.

  • Test the SSH login using a password from a remote system:
    $ ssh build@myhost.mydomain
    build@myhost.mydomain's password:
    Last login: Thu Apr 10 08:11:49 2008 from
    Microsoft Windows [Version 5.2.3790]
    (C) Copyright 1985-2003 Microsoft Corp.


  • Note: Unfortunately, there is no full-screen editor that works directly over the SSH terminal window to the Windows server. Either edit files locally using WordPad (which understands Unix text files) and the "d2u" program as necessary, or scp configuration files off to a remote Unix/Linux system for editing.
  • Create a Unix text "authorized_keys" file (no extensions) in the users ".ssh" directory containing the public key of the remote ControlTier user that will administer the box (usually from the ControlTier server).
  • Confirm that it is possible to ssh to the account on the system from the equivalenced account on the ControlTier server and authenticate using public key (i.e. without interactively provided a password):
    $ ssh build@myhost.mydomain pwd
  • Note: When ssh'ing into Windows system (e.g. using Putty) be careful about how the backspace character is mapped. The Windows command shell expects "Control-H". Using other characters can cause spurious characters to be embedded in file and directory names, etc.
Configure the environment
  • By default, the SSH daemon/service does not support setting custom environment. Edit SSH daemon's configuration file (e.g. "C:\copSSH\etc\sshd_config") and set "PermitUserEnvironment yes".
  • Create an "environment" file in the user's ".ssh" directory containing the following variables required by the ControlTier client:
    C:\copSSH\home\build\.ssh>type environment

  • Note: The values of these variables will change with future upgrades and will be specific to your installation choices.
  • Use the "Advanced" tab of the "System Properties" control panel to add the Antdepo "bin" directory to the "Path" system environment variable
  • Restart the "copSSHD" service to pick up the changes.
  • Ssh into the box as the user user and check that the variables are "set" in the command shell.
Despite the complexity of these notes you may concede the relief not having to reboot the Windows server to make it all work!


Anthony Shortland


Chuck said...

following this process on my XP required me to modify the windoze firewall since it was actually On.

I did the following:


Click Add Port
* Name: sshd
* Port number: 22
* TCP selected

Click OK

Anthony Shortland said...

Deploying copSSH to Windows Server 2003 has revealed an issue specific to that variant of Windows.

Since Windows Server 2003 needs full credentials (username and password) to "switch effective user", automatic command execution using PKA authentication does not work using the general configuration described in this posting.

A future enhancement will modify ControlTier's Node type to store usernames and passwords as distinct attributes and supply them to Ant's SSHExec task thereby obviating the need for PKA to automate command execution.

Meanwhile, I've followed these instructions to switch the user who runs the SSH service to the application owner account required by my project.

While not completely satisfactory, this approach at least allows PKA to continue to be used while guaranteeing that commands run as the desired user account.