<type>documentation</type>
<domain>debug</domain>
<id>remote-debugging</id>
<title>Debugging Externally Launched Remote Code</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

This section describes how to debug code launched on a remote host. These instructions are
needed only if you cannot launch your code from Wing, for example if it runs under
a web server or as an embedded script in a larger application.

The following instructions rely on Wing Pro's `Remote Hosts <ref:proj/remote-hosts>`__ 
feature to display and edit remote files.  If you cannot use that feature for some
reason, follow the instructions for `Manually Configured Remote Debugging
<ref:debug/manual-remote-debugging>`__ instead.

(1) First set up a remote host configuration as described in `Remote Hosts
    <ref:proj/remote-hosts>`__ and create a project that sets the ``Python Executable`` 
    in ``Project Properties`` to the remote host and includes your remote source code.
    Before continuing, check that you can open remote files in Wing's editor.
    
(2) Copy ``wingdbstub.py`` from the directory where you installed the remote agent into 
    the same directory as your debug program.   By default this is 
    ``~/.wingpro~~MAJOR_VERSION~~/remote-~~FULL_VERSION~~.~~UPDATE~~/wingdbstub.py`` where
    ``~`` is the remote user's home directory.  This will vary if you changed the 
    ``Install Dir`` under the ``Advanced`` tab in the remote host configuration.
    If another copy of ``wingdbstub.py`` is used, configure it set ``WINGHOME`` 
    to the installation directory of the remote agent and ``localhost:50050`` for the
    Wing host and port.

(3) At the point where you want debugging to begin, insert the following 
    into your code:  ``import wingdbstub``. If you are debugging code in an 
    embedded Python instance, see the notes in `Debugging Embedded Python 
    Code <ref:debug/debugging-embedded-code>`__.  If you are debugging code
    running as a different user than the one in your remote host configuration,
    see ``Managing Permissions`` below.

(4) Make sure the Wing preference `Debugger > Listening > Accept Debug Connections 
    <script:show_preferences_gui#prefname="debug.passive-listen">`__ is turned on, to 
    allow connection from external processes.  Once this is enabled, Wing will
    start listening for connections on the remote host you configured in your project.

(5) Set any required breakpoints in your Python source code.

(6) Initiate the debug program from outside Wing in a way that causes it to 
    ``import wingdbstub`` and reach a breakpoint or exception.  
    
You should now see the status indicator in the lower left of the main Wing window change
to yellow, red, or green, as described in `Debugger Status <ref:debug/status>`__. If no
breakpoint or exception is reached, the program will run to completion, or you can use the
``Pause`` command in the ``Debug`` menu.

**Managing Permissions**

If your code is running as a different user than the one specified in your remote
host configuration, as may be the case if running under Apache or another web
server, then you will need to make some additional changes to make remote debugging 
work.   For example, your remote host configuration may set``Host Name`` to
``devel@192.168.0.50`` while the code is actually run by the user ``apache``.

In this case, Wing will not accept the debug connection because the security token from the
user running the code does not match what Wing is expecting.

To solve this, first edit your copy of ``wingdbstub.py`` and change the value for
``WINGHOME`` by replacing ``~`` with the full path to the home directory of the user
in the remote hots configuration.  This is needed because ``~`` will expand to a different
directory if the code is run as a different user.

Then go into the ``Install Dir`` from which you copied ``wingdbstub.py`` in step
(2) above and change the permissions of the file ``wingdebugpw`` so that the user running
the code can also read it. For example, if both your users are members of the group
``webdev`` then you can do this::

  chgrp webdev wingdebugpw
  
A less secure solution is just to change the permissions of this file so everyone
can read it::

  chmod 644 wingdebugpw
  
The disadvantage of this approach is that other users could potentially use the
contents of this file to connect to your instance of Wing against your will.

**Changing Remote Debug Port**

Remote debugging is implemented by listening locally and establishing a reverse SSH tunnel
to the remote host configured in your project.

By default Wing listens on port ``50050`` on the remote host. Note
that this is different than the default port used to listen on the local host, which is
``50005``, in order to prevent the remote agent from interfering with a local copy of
Wing, when both are in use.

If this conflicts with another service on the remote host, or if there are multiple remote
debug connections to a single host, you will need to change this port number to be unique
for each developer. To do this, edit the ``Debug Port`` property under the ``Advanced``
tab of your remote host configuration and track this change in ``kWingHostPort`` in your 
copy of ``wingdbstub.py`` on the remote host.

You can verify that Wing is listening on the remote host and inspect the port number being
used by hovering your mouse over the bug icon in the lower left of Wing's window.

**Debugging on Multiple Remote Hosts**

Wing listens locally and on the remote host specified in ``Python Executable`` in
``Project Properties``. To listen on multiple hosts at once, use separate projects and
multiple instances of Wing. You can open additional instances of Wing by adding ``--new``
to the `command line <ref:install/command-line-usage>`__.

**Diagnosing Problems**

If you have problems making this work, try setting the ``kLogFile`` variable in
``wingdbstub.py`` to log diagnostic information.

