<type>documentation</type>
<domain>proj</domain>
<id>ssh-setup-details-builtin</id>
<title>Working With Wing's Built-In SSH Implementation</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>

If you don't have OpenSSH or PuTTY on your system, you can still set up remote access
using Wing's built-in SSH implementation. You will be able to authenticate using either
SSH keys or login passwords. SSH keys can be used by loading them into an SSH agent, by
specifying a key in your remote host configuration, or by letting Wing search for keys.

If you plan to use SSH public/private key pairs for authentication (rather than login
passwords), then you will need to generate those keys outside of Wing first. Wing does not
provide a way to create new SSH keys.

Configuration
-------------

If you do not have OpenSSH or PuTTY on your system, Wing should automatically fall back
onto its own SSH implementation. Otherwise, if you want to force Wing to use its built-in
SSH implementation, you will need to set Wing's `Remote Development > SSH Implementation
<script:show_preferences_gui#prefname="main.ssh-executable">`__ preference to ``Built
In``.

Then open the ``Remote Hosts`` dialog from the ``Project`` menu and create a new remote
host configuration. Give it a name in the ``Identifier`` field, enter the ``Hostname`` as
either the ip address, hostname, or host specification in ``username@remotehost`` form.

Using Login Passwords
.....................

If you wish to authenticate using your password on the remote system, you should
now already be able to connect to the remote system.  When you save your remote
configuration, Wing will attempt to connect to the remote system, prompting you
for the login password as needed.  As part of this process, Wing will install its
remote agent on the remote host.

You can retry this connection from the ``Remote Hosts`` dialog by right-clicking on your
remote host configuration and selecting ``Probe Remote Agent``.

Using SSH Key Pairs
...................

Wing's built-in SSH implementation can also use SSH key pairs to authenticate with the
remote host.  You'll be able to access keys stored in an SSH agent, specify a particular
key to use, or allow Wing to search for keys.

However you store and access your SSH private key, you will first need to move the
corresponding public key to the remote host, if you have not already done so. This is
described in detail in ``Moving the SSH Public Key to the Remote Host`` in `Working with
OpenSSH <ref:proj/ssh-setup-details-openssh>`__.

Once this is done, you should be able to save your remote host configuration in Wing and
it will attempt to connect to the remote system, prompting you for the private key
passphrase, if is is encrypted. As part of this process, Wing will install its remote
agent onto the remote host.

You can retry this connection from the ``Remote Hosts`` dialog by right-clicking on your
remote host configuration and selecting ``Probe Remote Agent``.

Using an SSH Agent
..................

Before trying any other keys, Wing will try to access keys stored in the keychain provided
by OpenSSH's ``ssh-agent`` or PuTTY's
``pageant``, if either is running and has private keys loaded into it. This is done before
trying to use a specific SSH private key, before searching for keys, and and before
falling back on password authentication. 

You can prevent Wing from trying to use any SSH agent by unchecking the ``Remote
Development > Allow Access to SSH User Agent`` preference.

Specifying or Searching for Keys
................................

You can specify a particular SSH key to use by setting ``Private Key`` under the
``Options`` tab of your remote host configuration to the full path of the private key.

If no key is specified there, Wing looks for SSH keys in ``~.ssh`` (and on Windows in
``ssh``) in your home directory. The following default key names are supported:
``id_rsa``, ``id_dsa``, ``id_ecdsa``, and ``id_ed25519``. Wing tries to use all the
private keys that it finds in that list.

Host Keys
---------

Wing's builtin SSH implementation stores host keys in ``.ssh/known_hosts`` below your home
directory. The first time you connect to a host that is not the same host as where the IDE
is running, you will be prompted to accept its host key. 

An exception is made for any IP address that belongs to the local host.  For those,
Wing stores the host key automatically without prompting.

If the host key for any host (including local IP addresses) changes at a later date so
that it no longer matches the stored key, then Wing will warn and refuse to connect to
that host until you remove the old host key from ``.ssh/known_hosts``. This is a security
measure aimed at making "man in the middle" network security attacks more difficult.

Note that Wing's builtin SSH implementation ignores any more permissive OpenSSH
configuration you may have with respect to host keys and instead always prompts to accept
non-local keys and always blocks connections when a host key fails to match.

Limitations
-----------

Wing's built-in SSH implementation has some limitations:

**(1)** There is no way to generate an SSH key pair from Wing.  You will need to do
this outside of Wing using OpenSSH.

**(2)** Forwarding X11 is not supported. If you need to forward X11 connections from the
remote host, you will need to use OpenSSH or PuTTY as your SSH implementation.

If any of these are a problem for you, please email `support@wingware.com <mailto:support@wingware.com>`__.
