<type>documentation</type>
<domain>proj</domain>
<id>remote-ssh</id>
<title>Setting up SSH for Remote Development</title>
<date>$Date: 2010-05-14 11:53:19 -0400 (Fri, 14 May 2010) $</date>
<version>$Revision: 22093 $</version>
<product-version>6+</product-version>
<product>pro+</product>

To work with a remote host, you first need to set up secure SSH remote access outside of
Wing Pro. You should configure this so that you can connect to the host without having to
enter a password each time you connect. Instead, you want authentication to occur using an
SSH key pair, and by entering your password once to load the key into an SSH user agent.

On Linux and OS X this is done with the standard OpenSSH tool suite that comes with the
OS. On Windows this can be done with `PuTTY
<http://www.chiark.greenend.org.uk/~sgtatham/putty/>`__ or by using OpenSSH provided by
Cygwin or Git Bash. If you do not already have this set up, or you cannot log into the
remote host without entering a password every time you connect, please refer to `SSH Setup
Details <ref:proj/ssh-setup-details>`__ before going any further.

Accessing the SSH Agent From Wing
---------------------------------

Once you have SSH working outside of Wing, and can connect to the remote host without
entering a password, start Wing in an environment where it will be able to access your SSH
keys via the SSH user agent. How this is done varies according to OS and which SSH
implementation you are using:

**Windows with PuTTY** -- Start ``pageant.exe`` from the command line. Then right-click on
the icon that appears in the lower right of your screen and select ``Add Key``. You may
need to redo this each time you log in. The private key file can also be passed to
``pageant.exe`` on the command line.

**Windows with OpenSSH in Cygwin or Git Bash** -- Start Cygwin and type ``ssh-agent bash``
on the command line and use ``ssh-add`` to add your key. Then type ``set | grep SSH_``,
copy the ``SSH_AGENT_PID`` and ``SSH_AUTH_SOCK`` lines, and paste them into the
``Environment`` in Wing's ``Project Properties``. You will need to redo this each time you
quit Cygwin since the contents of the environment variables will change. One way to avoid
having to set these environments is described in ``Connecting without SSH User Agent``
below.

**OS X** -- Add your key to ``Keychain Access`` and optionally set usage restrictions for
the key with ``Get Info`` from the ``File`` menu. Depending on how your key is configured
in ``Keychain Access`` you may need to unlock your key again or run ``ssh-add`` on the
command line each time you log in.

**Linux** -- Add your key with ``ssh-add`` on the command line. You need to rerun
``ssh-add`` each time you log in. If for some reason your Linux distribution does not run
``ssh-agent`` on its own, run ``ssh-agent bash`` followed by ``ssh-add`` and then launch
Wing from that command line with ``~~EXECUTABLE~~-~~MAJOR_VERSION~~.~~MINOR_VERSION~~`` so
it inherits the necessary environment.

Specifying the OpenSSH or PuTTY Executables
-------------------------------------------

Wing uses the following command line tools to implement secure access to remote hosts:
``ssh`` and ``scp`` (with OpenSSH) or ``plink.exe`` and ``pscp.exe`` (with PuTTY).

Wing looks for these tools on the ``PATH`` on the machine where it is running, and on
Windows it also searches for ``PuTTY`` and Cygin-provided ``ssh`` (in that order) in
common installation locations if it cannot find them on the ``PATH``.

If Wing cannot find ``ssh`` or ``plink.exe`` you will need to add its directory to your
``PATH`` or set the `Network > SSH Executable
<script:show_preferences_gui#prefname="main.ssh-executable">`__ preference in Wing to the
full path of the command. If this is set, Wing also tries to find ``scp`` (or ``pscp.exe``
on Windows with PuTTY) in the same directory as the specified executable.

Connecting without an SSH User Agent
------------------------------------

Although we recommend against it from the standpoint of maintaining proper security, it is
possible to use SSH without an SSH user agent. This is done by creating an SSH key without
an encryption password and using it as the ``Private Key`` under the ``Options`` tab in
your remote host configuration.

If you need your unencrypted SSH key also outside of Wing, you can instead configure
OpenSSH or PuTTY to use it with a specific host:

**With OpenSSH**, the key can be specified for a host by adding it to ``~/.ssh/config`` as
follows::

      Host somehost
          User someuser
          IdentityFile ~/.ssh/someuser@somehost/id_rsa_no_pw 

**With PuTTY on Windows**, configuration is done with ``putty.exe`` where you create a
saved session and set the ``private key file for authentication`` in the ``Connection >
SSH > Auth`` configuration area. Then save the session and ``plink.exe`` will use that
unencrypted private key without prompting for a password.

