<type>documentation</type>
<domain>debug</domain>
<id>manual-remote-debugging</id>
<title>Manually Configured Remote Debugging</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

~~~if WINGPRO:
.. note::

  **Consider Easier Alternatives**  
  
  This section describes the complex process of manually configuring remote debugging with ``wingdbstub``.  
  These instructions are needed only if you cannot use the `Remote Hosts <ref:proj/remote-hosts>`__
  feature.  In most cases, you will want to follow the much simpler instructions in 
  `Debugging Externally Launched Remote Code <ref:debug/remote-debugging>`__ instead.
~~~

~~~if not WINGPRO:
.. note::

  **Consider Easier Alternatives**

  This section describes the complex process of manually configuring remote debugging with ``wingdbstub``.  
  This process is much easier in Wing Pro.  Before getting starting, you may want to take a look 
  at Wing Pro's `Remote Hosts <https://wingware.com/doc/proj/remote-hosts>`__ feature.
~~~

Another alternative to consider before getting started is installing Wing on the remote host
and using remote display of the IDE via Remote Desktop (Windows), Screen Sharing (OS X),
or X Windows (Linux/Unix).

**Configuration Steps**

(1) First set up Wing to successfully accept connections from another process within the
    same machine, as described in section `Debugging Externally Launched Code
    <ref:debug/debugging-externally-launched-code>`__.

(2) Optionally, alter the `Debugger > Listening > Server Host
    <script:show_preferences_gui#prefname="debug.network-server">`__ preference to the name
    or IP address of the network interface on which the IDE listens for debug connections.
    The default ``All Valid Interfaces`` indicates that the IDE should listen on all the
    network interfaces found on the host.
   
(3) Optionally, alter the preference `Debugger > Listening > Server Port
    <script:show_preferences_gui#prefname="debug.network-port">`__ to the TCP/IP port on 
    which the IDE should listen for debug connections. This value only needs to be changed
    if multiple copies of Wing are running on the same host.
   
(4) Set the `Debugger > Advanced > Allowed Hosts
    <script:show_preferences_gui#prefname="debug.passive-hosts">`__ preference to include 
    the host on which the debug process will be run. Wing will reject connections if the
    debug process host isn't included here and the connection is made directly, without an
    SSH tunnel.
   
(5) Configure any firewall on the system that Wing is running on to accept a connection on
    the server port from the system that the debug process will run on, or set up an SSH
    tunnel as described in `Manually Configuring SSH Tunneling <ref:debug/ssh-tunnels>`__.
   
(6) Install Wing's debugger on the machine on which you plan to run your debug program, 
    using one of the methods described in `Manually Installing the Debugger 
    <ref:debug/installing-debugger-core>`__.
   
(7) Transfer copies of all your debug code so that the source files are available on the
    host where Wing will be running and at least the ``*.pyc`` files are available on the
    remote host.
   
    During debugging, the client and server copies of your source files must match or the
    debugger will either fail to stop at breakpoints or stop at the wrong place, and
    stepping through code may not work properly.
       
    You will need to use Samba, rsync, sftp, NFS, or some other file sharing mechanism to
    keep the remote files up to date as you edit them in Wing.
       
    If files appear in different disk locations on the two machines, you will also need to
    set up a file location map, as described in `Manually Configured File Location Maps
    <ref:debug/file-location-maps>`__.
   
(8) On your remote host, copy ``wingdbstub.py`` out of the debugger installation and into
    the same directory as your source files and then add ``import wingdbstub`` to your
    Python source, as described in `Debugging Externally Launched Code
    <ref:debug/debugging-externally-launched-code>`__. You will need to set ``WINGHOME``
    in your copy of ``wingdbstub.py`` to match the location where you unstalled the
    debugger in step (6).
   
(9) In ``wingdbstub.py`` on your remote host, set ``kWingHostPort``. The host in this
    value must be the IP address of the machine where Wing is running. The port must match
    the port configured with the `Debugger > Listening > Server Port
    <script:show_preferences_gui#prefname="debug.network-port">`__ preference on the host
    where Wing is running.  If you set up an SSH tunnel in step (5) the host will be
    ``127.0.0.1`` and the port will depend on the SSH tunnel that was created.

(10) Restart Wing and try running your program on the remote host. You should see the Wing
     debugger status icon change to indicate that a debug process has attached.

**Example**

For an example configuration, see `Manually Configured Remote Debugging Example
<ref:debug/remote-debugging-example>`__.

**Diagnosing Problems**

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

