<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>

Choosing an SSH Implementation
------------------------------

Wing can either use the same command line tools that you use outside of Wing to connect to
your remote systems, or you can use Wing's builtin SSH implementation to manage your 
secure SSH connections.

Using OpenSSH or PuTTY Executables
..................................

Wing can invoke the OpenSSH or PuTTY command line tools to implement secure access to remote
systems. This is the default approach because it often makes the most sense to connect to 
remote systems the same way that you already do outside of Wing. 

The following commands are used: ``ssh`` and ``scp`` (with OpenSSH) or ``plink.exe`` and
``pscp.exe`` (with PuTTY on Windows).

Wing looks for these tools on the ``PATH`` on the machine where it is running, and on
Windows it also searches for ``PuTTY`` and Cygwin-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`` it will fall back to using its built-in SSH
implementation. If you instead want to use a command line OpenSSH or PuTTY executable then
you will need to add its directory to your ``PATH`` or use Wing's `Remote Development > SSH
Implementation <script:show_preferences_gui#prefname="main.ssh-executable">`__ preference
to specify the full path of the command. If this is set, Wing also tries to find ``scp``
(or ``pscp.exe`` for PuTTY on Windows) in the same directory as the specified ``ssh`` or
``plink.exe`` executable.

Using Wing's Built-in SSH Implementation
........................................

If you don't have OpenSSH or PuTTY on your system, or you want to avoid using them, you
can ask Wing to use its own built-in SSH implementation to connect to your remote
systems. This is done by setting Wing's `Remote Development > SSH Implementation
<script:show_preferences_gui#prefname="main.ssh-executable">`__ preference to ``Built
In``.

This implementation will try to use a private SSH key if present on your system, or you
can specify one in the remote host configuration you will create in Wing. If no private
SSH key is found or specified, Wing will attempt to authenticate with a login password.

Setting up SSH Access
---------------------

To work with a remote host, you first need to set up secure SSH remote access outside of
Wing Pro. You can configure this in any of the following ways:

**(1)** Create and use an SSH key pair and store your SSH private key into the keychain
provided by an SSH user agent (such as OpenSSH's ``ssh-agent`` or PuTTY's ``pageant``), so that
SSH connections can be established without repeatedly reauthenticating.

**(2)** Create and use an SSH key pair by typing in your passphrase to unlock your private
key whenever it is needed.

**(3)** Log into the remote system via SSH by typing your login password as needed.

The configuration of the ``sshd`` server on the remote system controls whether or not SSH
key pairs and/or login passwords are allowed for authentication. This may depend on your
company's security policy.

If you choose option **(1)** you will authenticate outside of Wing, using the
keychain managed by 
your system's SSH user agent, before establishing a connection to the remote
host. Depending on your security configuration, your system may store
credentials and unlock your private key automatically at login, it may prompt
to unlock your key when it is used by Wing, or it may be necessary for you to
load your key into the SSH user agent manually before Wing tries to connect
to the remote host.

If you choose option **(2)** or **(3)**, Wing will prompt you for your
private key passphrase or your login password as needed, once per session.
See How Wing Stores Passphrases below for details.

.. note::

  **Important:** Option **(1)** is the only choice that works with OpenSSH on
  Windows. All three options work in all other cases.

If you cannot already log into the remote host using one of these options, please
refer to `SSH Setup Details <ref:proj/ssh-setup-details>`__ before going any further.

How Wing Stores Passphrases
---------------------------

If you have configured your SSH client to require a passphrase to unlock your private key,
or if you password authenticate with the remote system, then Wing will prompt you to enter
these as needed.

Passphrases are stored in memory so they can be reused as needed, for example to reconnect
to the remote host after the connection is dropped, or to start an SSH tunnel for a new
debug session.

However, passphrases entered into Wing are never written to disk and thus must be
re-entered each time Wing is restarted.

In the event that Wing fails to connect to a remote host, cached passphrases are purged
and must be reentered.  You can also force Wing to purge any cached credentials from 
the ``Remote Hosts`` dialog, by right-clicking on the host and selecting ``Clear
Cached Credentials``.

If you don't want Wing to ask for passphrases, you will need to create an SSH key
pair and load your private key into an SSH user agent (option ``(1)`` above).  This
is described in `SSH Setup Details <ref:proj/ssh-setup-details>`__.

Preventing Access to an SSH User Agent
--------------------------------------

To prevent Wing from ever trying to access a keychain provided by an SSH user agent like OpenSSH's
``ssh-agent`` or PuTTY's ``pageant``, you can uncheck the `Remote Development > Allow Access to
SSH User Agent <script:show_preferences_gui#prefname="main.use-ssh-agent">`__
preference. 

When this is done, you may need to specify which SSH private key to use in
your Wing remote host configuration, and Wing will prompt for your SSH
private key passphrase or login password, as needed.

Custom SSH Connection Responses
-------------------------------

Some SSH configurations require additional responses on the command line, before the SSH
connection can be made. For example, you may be prompted to select a two-factor
authentication method.

In this case, you can configure your responses using ``Connection Responses`` under the
``Advanced`` tab in your remote host configuration. Responses may either be automatic
with fixed values that are given in the configuration or collected from the user. 

This is only relevant if you are *not* using Wing's built-in SSH implementation. See
`Configuring Remote Hosts <ref:proj/remote-config>`__ for details.

