<type>documentation</type>
<domain>debug</domain>
<id>ssh-tunnels</id>
<title>Manually Configuring SSH Tunneling</title>
<date>$Date: 2009-11-20 12:56:20 -0500 (Fri, 20 Nov 2009) $</date>
<version>$Revision: 21161 $</version>
<product>per+</product>

If you are manually configuring remote debugging *without* Wing Pro's 
~~~if WINGPRO:
`Remote Hosts <ref:proj/remote-hosts>`__ feature, 
~~~
~~~if WINGPER:
`Remote Hosts <https://wingware.com/doc/proj/remote-hosts>`__ feature,
~~~
you may find that firewalls get in the way of making a direct connection between the
remote host and Wing running locally. The best way around this is to establish an SSH
tunnel that forwards network traffic from the remote host to the local host. This also
encrypts all your debugger traffic in a secure way.

Doing this does require a working SSH server, but most remote hosts will already have that
running. You will also need to set up remote login using SSH first, and in most case add
your SSH key to the list of allowed keys on the remote host, so that SSH can login without
any password.

Setting up SSH to a remote host is described in detail in `SSH Setup Details
<ref:proj/ssh-setup-details>`__.

Once that is done, SSH tunneling can be configured as described below.

**Tunneling with OpenSSH**

When Wing is running on OS X or Linux, or if you have OpenSSH on Windows provided by
cygwin or Git Bash, tunneling can be done as follows from the machine that is running Wing
(not the remote host)::

  ssh -N -R 50005:localhost:50005 username@remotehost
    
You'll need to replace ``username@remotehost`` with the login name and ip address
of the remote host.

The ``-N`` option causes ssh to set up the tunnel but not run any command on the 
remote host.

The ``-R`` option sets up a reverse tunnel, which is needed since the debug process
initiates the connection back to the IDE.  The argument following it indicates that
port ``50005`` should be tunneled from the remote host to ``locahost``.

Optionally, an ``-f`` option could be added just after ``ssh`` to cause ``ssh`` to run in
the background. Without this option, you can use ``Ctrl-C`` to terminate the tunnel. With
it, you'll need to use ``ps`` and ``kill`` to manage the process.

If you also want a login shell on the remote host, use this form instead::

  ssh -R 50005:localhost:50005 username@remotehost bash

**SSH Tunneling with PuTTY**

When Wing is running on Windows and you don't have OpenSSH available, ``PuTTY`` can be
used instead to configure an SSH tunnel. This is done on the ``Connections > SSH >
Tunnels`` page in ``PuTTY`` configuration: Set ``Source port`` to ``50005``,
``Destination`` to ``localhost:50005``, and select the ``Remote`` radio button, then press
the ``Add`` button. Once this is done the tunnel will be established whenever PuTTY is
connected to the remote host.

**Using Different Port Numbers**

The above assumes the default configuration, where Wing is listening for connections on
port ``50005``. If for some reason you can't use port ``50005`` as the debug port on
either machine, this can be changed on the remote host with ``kHostPort`` in
``wingdbstub.py`` or with the ``WINGDB_HOSTPORT`` environment variable. To change the port
the IDE is listening on, use the ``Debugger > Listening > Server Port`` preference
and or ``Debug Server Port`` in ``Project Properties`` in Wing.

If this is done, you will need to replace the port numbers in the SSH tunnel invocation 
in the following form::

  ssh -N -R <remote_port>:localhost:<ide_port> username@remotehost

``<remote_port`` is the port specified in ``kHostPort`` or with ``WINGDB_HOSTPORT``
environment variable on the remote host, and ``<ide_port>`` is the port set in 
Wing's preferences or ``Project Properties``. 

On Windows using PuTTY, the ``Source port`` is the port set with ``kHostPort`` or
``WINGDB_HOSTPORT`` on the remote host, and the port in the ``Destination`` is
the port Wing is configured to listen on.

