Configuring Remote Hosts
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.
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 for help.
In very rare cases you may need to install the remote agent manually as described in Manually Installing the Remote Agent. 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 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 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.
