<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.

**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``. In this case, Wing first looks for ``python3`` and then falls back to using
``python``. Otherwise, it can either be set to ``Activated Env`` to enter a command that
activates a virtualenv or Anaconda environment on the remote host (so that ``python``
launches the correct Python), or it can be set to
``Command Line`` to specify the ``python`` to run. In the latter case, 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). When in
doubt about the location of the Python you want to use, run it outside of Wing and execute
``import sys; print(sys.executable)`` to obtain the value to use.  Note that if your
activate script's full path contains a space you will need to use ``Command Line`` instead.
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>`__.

**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.  Note that ``~`` (tilde) in remote file names will be expanded as the 
``Base Directory`` when it is set.

**Forward SSH Agent** controls whether to forward the local SSH Agent (running on the host
where the IDE is running) to the remote process. When this is done, processes run on the
remote host will be able to authenticate using the local SSH Agent. This can be useful,
for example, for pushing changes to a revision control repository or running other
commands that require an SSH connection that can be authenticate using keys stored in your
local SSH Agent. The default is to allow any external configuration or defaults to take
effect.

**Forward X11** enables X11 display from the remote host to the host where Wing is
running. On macOS and Windows this requires installing and configuring an X11 server, such
as XQuartz on macOS 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``.  Forwarding X11 only works with OpenSSH and PuTTY.  It is not supported
by Wing's built-in SSH implementation.

**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`` if using OpenSSH.
When using PuTTY, Wing ignores port numbers configured by a saved session and always uses
port ``22`` as the default. This works around a bug in PuTTY's ``pscp.exe`` that prevents
remote agent installation when there is no PuTTY saved session. As a result, any
non-standard port number used by a host reached through PuTTY must also be set here
in Wing's remote host configuration.

**Private Key** specifies how Wing accessed the private key to use when connecting to the
remote host. The default is to use the keychain provided by 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`` or ``.pem`` for OpenSSH and ``.ppk`` for PuTTY). With OpenSSH on Linux
or macOS, the key file must be set to be readable only by the user running Wing, for
example with ``chmod 600 mykey.pem``.  If the key is encrypted, Wing will prompt for
the passphrase to decrypt it when it is used.

**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.

**Installation Directory** is the full path to the installation location of Wing's remote
agent on the remote host. Using the default ``Automatic`` for this setting is strongly
advised, since that ensures that the remote agent version matches the IDE version and
that old unused remote agent installations are automatically removed. You should set this
to a specific directory only in rare cases for development or diagnostic purposes. Doing
so may cause problems if the remote agent version does not exactly match the IDE version.

**Manage SSH Tunnel** controls whether Wing manages SSH tunnels to allow the remote
agent and debugger to connect from the remote host to the IDE.  The default of
``Auto-configured`` establishes SSH tunnels only if the remote host is not the same
as the local host.  This should be disabled for container systems that automatically
forward network traffic, such as Windows Subsystem for Linux (WSL), and it must be enabled
when connecting to isolated containers that appear to be the same as localhost,
like Vagrant.  **Important:** When this option is disabled, network traffic between
the IDE and the remote system is entirely unencrypted, both for the remote agent
and the debugger.  This option should only be disabled when working on the local host
or if the underlying network is otherwise encrypted (for example, by a VPN or a
manually configured encrypted tunnel).

**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). When a fixed
port is specified, Wing still uses a random port on the local end of connections, unless
``Manage SSH Tunnel`` is also disabled. In that case, the same port number is used at both
ends of the connection, and this must match port mappings established by configuration
made outside of Wing. This option must be set to ``Use Random Port`` when using
``ControlMaster`` in the OpenSSH configuration. Using a fixed port in that case may fail
because the control master can prevent reusing the port when the remote agent is
restarted.

**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``. When a port is
specified, Wing still uses a random port on the local end of connections, unless ``Manage
SSH Tunnel`` is also disabled. In that case, the same port number is used at both ends of
the connection, and this must match port mappings established by configuration made
outside of Wing. This option must be set to ``Use Random Port`` when using
``ControlMaster`` in the OpenSSH configuration because that will hold onto previously used
SSH tunnel ports indefinitely until the remote host is restarted.

**Connection Responses** is a collection of custom responses to send to the SSH client
during startup. Each value gives a string to match within the final line of output
received so far from the SSH client and a response. The match string is applied using glob
style matching with ``*`` and ``?`` wildcards and ``[]`` groups (for example ``card
selector`` or ``*select*card[123]*`` or ``*continue[?]*``). Matching is case-insensitive
by default. The match string may be preceded by ``case:`` to force case-sensitive
matching. If the match string is empty then the response is sent immediately when any
output is seen from the SSH client process. The response is either a string to send to the
SSH process or ``[prompt:type]`` to collect the value from the user, where ``:type`` is
optional and may contain ``password`` to obscure the input and/or ``nocache`` to prevent
caching the value in memory for future connections (for example
``[prompt:password-nocache]``). When ``[prompt]`` is used, a default value may be entered
after the closing ``]``. Each response is sent only once, even if the match is seen again,
but multiple entries with the same match are allowed and are used in the order given.
This feature is disabled when using Wing's built-in SSH implementation, since there
are no non-standard interactions during SSH startup in that case.

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 very 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.
