Skip to content

Latest commit

 

History

History
247 lines (183 loc) · 11.4 KB

README.md

File metadata and controls

247 lines (183 loc) · 11.4 KB
Raw

Remote X11

When working in a remote environment, this extension sets the DISPLAY environment variable so that X windows applications started from Visual Studio Code appear on the local machine.

For this extension to work, it must be installed on the remote machine, and you must be running an X server on the local machine. For SSH connections, the Remote X11 (SSH) extension must also be installed on the local machine (this should be installed automatically when you install this extension).

You may need to change some settings for this to work with SSH! Please check the "Authentication Settings" section below, as this extension cannot use VS Code's SSH authentication, and it does not support all SSH authentication methods.

For Windows hosts, this extension has only been tested with VcXsrv, but other servers such as Cygwin/X, Xming, and X410 should also work. Windows remotes are not currently supported.

For SSH connections, if the remote machine does not have Bash installed, you must change the remoteX11.SSH.displayCommand setting and provide a command that prints the value of the DISPLAY variable. If you are using port forwarding, you may also need to change the remoteX11.SSH.port setting. See below for more details.

Access Control

For containers and WSL 2, you will need to either authorize with your X server or disable access control.

For SSH and WSL 1 targets, connections to the X server will come from the local machine, so you should not need to configure anything for these to work.

X11 Forwarding

The Remote - SSH extension does not currently enable X11 forwarding (see issue #267). To work around this, the Remote X11 (SSH) extension creates an SSH connection to the remote machine with forwarding enabled in the background.

This extension currently only supports public key authentication. See below for more details on authentication settings.

Extension Settings

Changes to settings will normally apply automatically after a short delay. You may need to restart any terminals if setting changes result in the DISPLAY variable changing.

You can also use F1 > Remote X11: Reconnect Display to force an update.

  • remoteX11.display - Display number to connect to. Change this if your X server is using a display other than 0.
  • remoteX11.screen - Screen number to connect to.
  • remoteX11.container.enable - Set DISPLAY for containers?
  • remoteX11.SSH.enable - Enable X11 forwarding and set DISPLAY for SSH targets?
  • remoteX11.SSH.authenticationMethod:
    • keyFile - Authenticate with the private key file specified by remoteX11.SSH.privateKey. Passphrase-protected keys are not supported.
    • agent - Use ssh-agent to get keys. This method does support passphrase-protected keys.
  • remoteX11.SSH.agent - Name of a Unix socket or Windows named pipe for ssh-agent. Set to pageant to use Pageant on Windows. If left empty, defaults to Windows 10's OpenSSH agent (\\.\pipe\openssh-ssh-agent) or the SSH_AUTH_SOCK environment variable on other platforms. Only used if remoteX11.SSH.authenticationMethod is agent.
  • remoteX11.SSH.privateKey - Absolute path to your SSH private key file. Only used if remoteX11.SSH.authenticationMethod is publicKey.
  • remoteX11.SSH.XAuthPermissionLevel - Select between untrusted (ssh -X) and trusted (ssh -Y) permissions.
  • remoteX11.SSH.X11ConnectionType - Select between TCP and Unix sockets for the X11 connection. Defaults to tcp on Windows hosts or unix otherwise.
  • remoteX11.SSH.X11Socket - Selects the Unix socket to connect to. The screen number is appended to the end of this setting.
  • remoteX11.SSH.displayCommand - A command which prints DISPLAY=<DISPLAY> followed by a newline, where <DISPLAY> is the value of the DISPLAY variable. Note that there must not be any spaces in this text. Change this when connecting to a machine that doesn't support the default command.
  • remoteX11.SSH.timeout - Number of seconds to wait for the SSH shell to respond to the above command. Use 0 to wait forever.
  • remoteX11.SSH.host - Sets the hostname or IP address used to connect to the SSH server. Use this if Remote X11 tries to connect to the wrong address.
  • remoteX11.SSH.port - Sets the port used to connect to the SSH server. Use this if Remote X11 tries to connect to the wrong port.
  • remoteX11.WSL.enable - Set DISPLAY for WSL targets?

Authentication Settings

Remote X11 currently only supports public key authentication. You must use ssh-keygen to generate a public/private key pair and add your public key to your server's ~/.ssh/authorized_keys file.

There are two ways RemoteX11 can be configured to get keys:

Private Key File

If the remoteX11.SSH.authenticationMethod setting is keyFile, Remote X11 will read the file given by the remoteX11.SSH.privateKey file as your private key. This defaults to ~/.ssh/id_rsa, so you must change it if your file is named differently.

This method does not support passphrase-protected private keys! See below for methods that do.

SSH Agent

If the remoteX11.SSH.authenticationMethod setting is agent, Remote X11 will use ssh-agent to read keys added with ssh-add. See the VS Code documentation for instructions on enabling the SSH Agent.

To add your key to the SSH agent, open a terminal on the local machine and run:

ssh-add <path/to/private/key>

If your key is passphrase-protected, you will be prompted to enter the passphrase. You can then log in without re-entering the passphrase.

On Windows, you can also use Pageant instead of the built-in OpenSSH agent by changing the remoteX11.SSH.agent setting to pageant.

Troubleshooting

Is the extension installed?

When in a remote workspace, open the Extensions view (Ctrl+X) and check that "Remote X11" is installed and enabled on the remote machine. If you are using an SSH connection, also check that "Remote X11 (SSH)" is installed and enabled on the local machine.

Check the logs

When in a remote workspace, open the Output pane (Ctrl+Shift+U) and use the drop-down list in the upper-right to check the logs from "Remote X11". If everything is working correctly, the logs should show something similar to:

Setting up display for remote "ssh-remote".
Connecting to SSH user@address port 22
DISPLAY = localhost:11.0

If not, the error message may help you figure out the problem. Solutions to some common errrors are listed below.

Are the SSH address and port correct?

By default, Remote X11 uses the SSH_CONNECTION variable to determine the address and port to the SSH server. This may be incorrect if you are using features such as port forwarding.

Check the logs for the "connecting to SSH ..." message and check that the address and port are correct. If not, fix them with the the remoteX11.SSH.host and/or remoteX11.SSH.port settings. Note that these settings must be set on the remote machine, so open a remote workspace and use the Remote tab of settings to change them.

Is your X server running?

If you see DISPLAY = ... in the Remote X11 logs but nothing shows up when you run a GUI application, make sure your X server is running on your local machine.

Also make sure the remoteX11.display setting matches the display number your X server is set to use.

Are you using the correct connection type?

X11 servers on Windows typically use a TCP connection, and servers on Unix-based systems typically use a Unix socket. When remoteX11.SSH.X11ConnectionType is auto, it will select between TCP and Unix sockets accordingly. If the automatic selection is not correct, you can manually change it to use TCP or Unix sockets.

Is SSH able to find the display?

If you are using SSH and don't see DISPLAY = ... in the logs, check the logs from "Remote X11 (SSH)" for errors as well. Near the end of the logs should be a command to print out the DISPLAY variable. If this command is failing, try changing it with the remoteX11.SSH.displayCommand setting in your user (not remote) settings.

Cannot parse privateKey: Encrypted OpenSSH private key detected, but no passphrase given

Passphrase-protected keys are not supported with the default authentication method. You must use an SSH Agent instead. See Authentication Settings above for more details.

All configured authentication methods failed

Check your authentication settings. This usually means that either your public key is not in the remote server's authorized_keys file, or you haven't added your private key to your SSH agent. See Authentication Settings above for more details.

ENOENT: \.\pipe\openssh-ssh-agent

Windows' SSH Agent is probably not running. From the Start menu, open "Services" and make sure the OpenSSH Authentigation Agent service is running.

Authorization required, but no authorization protocol specified

Access control is enabled on your X server. Either authenticate with the server or disable access control. See https://en.wikipedia.org/wiki/X_Window_authorization for more details.

Error: Can't open display: ... on WSL 2

If you get this error when running an application from WSL 2, the connection is probably being blocked by the Windows firewall. You can edit the firewall rules to allow it:

  1. From the Start menu, open Windows Defender Firewall, then select "Advanced settings" from the left sidebar. This should open a window titled "Windows Defender Firewall with Advanced Security"

  2. Select "Inbound Rules" on the left.

  3. Find the rule with the following settings:

    • Name: the name of your X server, e.g. "VcXsrv windows xserver"
    • Action: Block
    • Protocol: TCP

  4. Right-click the rule and select "Properties".

  5. On the General tab, change the action to "Allow the connection":

    Firewall rule, general tab

  6. On the Scope tab, change "Remote IP address" to "These IP addresses" and add the following values:

    • 172.16.0.0/12
    • 192.168.0.0/16

    Firewall rule, scope tab

  7. Select OK to save your changes.

See microsoft/WSL#4139 for more details.

Other issues

If you get any other errors and you can't figure out the cause, create an issue at https://github.com/ChaosinaCan/vscode-remote-x11/issues and post your logs and I'll try to help.

If you are using SSH, please enable the remoteX11.SSH.verboseLogging setting to log technical details about the SSH connection to the "Remote X11 (SSH)" logs, and include those in your issue report. This is useful for finding issues such as the server not supporting the algorithm used by your private key.