<type>documentation</type>
<domain>proj</domain>
<id>remote-config</id>
<title>Configuring Remote Hosts</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>

Remote hosts are configured using ``Remote Hosts`` in the ``Project`` menu, to tell Wing
about the remote host and how to connect to it. The following values may be specified in
the three tabs of the remote host dialog:

**Identifier** (required) is the unique short name used to reference this remote host
configuration. It is used in the URLs that reference resources on the remote host. If an
existing remote host configuration's ID is changed, Wing will track that change in all the
remote host references stored in the project. However, for shared remote host
configurations, it's best not to change the identifier after it is used.

**Host Name** (required) is the remote host's name or IP address. The the host name may
include the username, in the form ``username@hostname`` or ``username@ipaddress``. This is
needed if the user name on the remote host is different from the user on the local host.
For containers hosted by Vagrant or similar tools, the host name must include
``username@`` even if the remote and local user names are the same. This tells Wing that
an SSH tunnel is necessary even if the host name or IP address is for the local host. If
this field is changed in an existing remote host configuration, Wing will try to find
remote resources on the new host name.

**Python Executable** is the Python to use for running Wing's remote agent and for
debugging or executing remotely. This can be left blank if ``python`` can be found on the
``PATH`` and is a supported version of Python. Otherwise, it should be the name of a
Python that can be found on the ``PATH``, the full path to the Python executable, or a
path relative to the configured ``Base Directory`` (see below). If your Python cannot be
run without certain environment variables, such as PYTHONHOME or PYTHONPATH, you will need
to set up a custom startup script as described in `Specifying Environment for the Remote
Python <ref:proj/remote-python-env>`__. For ``virtualenv``, just use the full path to
virtualenv's Python executable. This sets up the necessary environment before running your
code. When in doubt, run the Python you want to use outside of Wing and inspect
``sys.executable`` after typing ``import sys``. This is the value you want to use for the
``Python Executable`` in the remote host configuration.

**Base Directory** is the directory on the remote host from which all file references are
made, so that Wing will show only the relative path from the configured base directory. By
default, it is the remote user's home directory. If this value is a partial path, it is
interpreted to be relative to remote user's home directory. When this value is changed on
an existing configuration, Wing will try to find resources relative to the new base
directory.

**Forward X11** enables X11 display from the remote host to the host where Wing is
running. On OS X and Windows this requires installing and configuring an X11 server, such
as XQuartz on OS X or MobaXTerm on Windows. With OpenSSH this uses ``ForwardX11Trusted``
style forwarding. For finer control of authentication options, leave this option disabled
in Wing and instead set options in your ``.ssh/config`` file. On Windows with PuTTY, this
is done in the ``SSH > Auth > X11`` section of host configuration in ``PuTTY``. On Windows
with VNC, you may instead need to set ``DISPLAY=:1`` in the ``Environment`` in ``Project
Properties``.

**SSH Port** sets the port on which OpenSSH is running on the remote host. The default is
port ``22`` or whatever port number is configured in ``.ssh/config`` or PuTTY's saved
sessions.

**Private Key** specifies the private key file to use when connecting to the remote host.
The default is to use the SSH user agent (``ssh-agent`` for OpenSSH or ``pageant`` for
PuTTY). The key file format must match the SSH implementation being used (usually ``.rsa``
for OpenSSH and ``.ppk`` for PuTTY).

**File Encoding** is the default text encoding to use when opening or creating files on
the remote host, if the file does not explicitly set the encoding.

**I/O Encoding** is the text encoding to use for I/O to and from processes started on the
remote host by the debugger or ``OS Commands`` tool.

**Install Dir** is the full path to the installation location of Wing's remote agent on
the remote host. Wing will automatically install and update the remote agent as needed.
Using the default for this setting is recommended, since that will automatically add and
remove remote agent installations according to which versions of Wing you are using.

**Use SSH Tunnel for username@localhost** controls whether the remote agent will connect
to Wing over a reverse SSH tunnel even if connecting to another user on the local host.
This should be disabled if the user is another account on the local host or when 
connecting to Linux running under Windows Subsystem for Linux (WSL) and must be enabled
when connecting to isolated containers like Vagrant.

**Remote Agent Port** is the TCP/IP port to use for the remote agent on the remote end of
the SSH tunnel. When this is not specified, Wing uses a random port number determined on
the IDE side of the connection. This usually works but there is no guarantee that the port
will also be available on the remote end. When set, this property should be an unused
unprivileged ephemeral port number (usually between ``1025`` and ``65535`` on Windows,
``32768`` and ``61000`` on Linux, and ``49152`` and ``65535`` elsewhere).

**Remote Debug Port** is the first TCP/IP port to use for the debugger on the remote end
of the SSH tunnel. By default, as for Remote Agent Port, a random port is used. When a
value is specified, Wing uses only ports starting with the given port, up to however many
ports are needed for active debug sessions and ``Python Shells``.

**2FA Card Selector** is used with OpenSSH integrations that prompt for selection of a 2FA
card at startup. The text entered is written to the SSH process at startup. It is stored
as plain text in the remote host configuration so should not be used for passwords. This
value is only used with OpenSSH and not PuTTY.


Installing and Running the Remote Agent
---------------------------------------

After a remote host is configured, Wing will try to connect to that host and install the
remote agent if it is not already present. If installation of the remote agent fails, you
will be presented with diagnostic output to send to `support@wingware.com
<mailto:support@wingware.com>`__ for help.

In rare cases you may need to install the remote agent manually as described in `Manually
Installing the Remote Agent <ref:proj/manual-remote-install>`__. One such case can occur
on Linux when ``uname`` reports a different bittedness than is being used by Python. For
example, ``uname`` may report a 64-bit system but Python may be 32-bit.

Once installed, the remote agent is started or restarted as needed and will exit after a
timeout period if it is unused. The remote agent allows Wing to search, inspect, read, and
write files and directories, create or delete files, start debug or execution, run unit
tests, invoke version control operations, run ``Python Shell``, invoke commands in ``OS
Commands``, and perform other actions on the remote host to support the IDE's
functionality. The necessary SSH tunnels for communication to the remote agent and to
support debugging files remotely are also managed automatically.

You can find a log of the remote agent's activities in the file ``remote-agent.log`` 
within the `Settings Directory <ref:install/user-settings-dir>`__ on the remote host.

Shared Remote Hosts Configurations
----------------------------------

Remote host configurations can either be stored in the project file or shared in the 
`Settings Directory <ref:install/user-settings-dir>`__ so they can be accessed from all
projects. To make a remote host configuration shared, check the ``Shared`` box for that
configuration in the remote host manager accessed from ``Remote Hosts`` in the ``Project``
menu.

In general, a shared remote host configuration should be used when the project file
is stored on the remote host, and non-shared remote host configurations should be used
when a project file is stored locally but accesses resources on a remote host.
