Connect to your target Linux system in Visual Studio

You can configure a Linux project to target a remote machine or the Windows Subsystem for Linux (WSL). For a remote machine, you need to set up a remote connection in Visual Studio. To connect to WSL, skip ahead to the Connect to WSL section.

When using a remote connection, Visual Studio builds C++ Linux projects on the remote machine. It doesn't matter if it's a physical machine, a virtual machine in the cloud, or WSL. To build the project, Visual Studio copies the source code to your remote Linux computer. Then, the code gets compiled based on Visual Studio settings.

Note

Starting in Visual Studio 2019 version 16.5, Visual Studio supports secure, Federal Information Processing Standard (FIPS) 140-2 compliant cryptographic connections to Linux systems for remote development. To use a FIPS-compliant connection, follow the steps in Set up FIPS-compliant secure remote Linux development instead.

Set up the SSH server on the remote system

If ssh isn't already set up and running on your Linux system, follow these steps to install it. The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7.6. However, the instructions should be the same for any distro using a moderately recent version of OpenSSH.

1. On the Linux system, install and start the OpenSSH server:

   sudo apt install openssh-server
   sudo service ssh start
   

2. If you'd like the ssh server to start automatically when the system boots, enable it using systemctl:

   sudo systemctl enable ssh
   

Set up the remote connection

1. In Visual Studio, choose Tools > Options on the menu bar to open the Options dialog. Then select Cross Platform > Connection Manager to open the Connection Manager dialog.

   If you haven't set up a connection in Visual Studio before, when you build your project for the first time, Visual Studio opens the Connection Manager dialog for you.

2. In the Connection Manager dialog, choose the Add button to add a new connection.

   

   In the options pane, CrossPlatform > C++ > Connection Manager is selected and the Add button is highlighted.

   To edit an existing connection, choose Edit. In either scenario, the Connect to Remote System window is displayed.

   

   In the Connect to Remote System window, there are fields for host name, port, user name, authentication type, and password. Port is set to 22. Authentication type is set to 'Password'.

3. Enter the following information:

   Entry	Description
   Host Name	Name or IP address of your target device
   Port	Port that the SSH service is running on, typically 22
   User name	User to authenticate as
   Authentication type	Password and Private Key are both supported
   Password	Password for the entered user name
   Private key file	Private key file created for ssh connection
   Passphrase	Passphrase used with private key selected above

   You can't click the Connect button until all the required fields are completed and the port is set to an integer between 1 and 65535.

   You can use either a password or a key file and passphrase for authentication. Key files are more secure than username/password. If you already have a key pair, it's possible to reuse it.

   Versions of Visual Studio before 17.10 support Elliptic Curve (EC), Rivert-Shamir-Adleman (RSA), and Digital signature algorithm (DSA) keys for remote connections. Because of security concerns, RSA and DSA keys are no longer supported in VS 17.10 and later. Only EC keys are currently supported. To create a key pair compatible with the connection manager use the command: ssh-keygen -m pem -t ecdsa -f <key-name>

   Note

   If using ssh-keygen to create the private key, you must specify the switch -m pem, or the key will not be accepted by Visual Studio. If your private key begins with -----BEGIN OPENSSH PRIVATE KEY-----, you must convert it with ssh-keygen -p -f <FILE> -m pem.

4. Choose the Connect button to attempt a connection to the remote computer.

   If the connection succeeds, Visual Studio configures IntelliSense to use the remote headers. For more information, see IntelliSense for headers on remote systems.

   If the connection fails, an info bar with error information appears and the fields that you may need to change are outlined in red.

   

   If you use key files for authentication, make sure the target machine's SSH server is running and configured properly.

   If you have trouble connecting to WSL on localhost, see Fix WSL localhost connection problems.

Host key verification

In Visual Studio version 16.10 or later, you're asked to verify the server's host key fingerprint whenever Visual Studio connects to a remote system for the first time. You may be familiar with this process if you've used the OpenSSH command-line client or PuTTY before. The fingerprint identifies the server. Visual Studio uses the fingerprint to ensure it's connecting to the intended and trusted server.

The first time Visual Studio establishes a new remote connection, you're asked to accept or deny the host key fingerprint presented by the server. Or, anytime there are changes to a cached fingerprint. You can also verify a fingerprint on demand: select a connection in the Connection Manager and choose Verify.

If you upgrade to Visual Studio 16.10 or later from an older version, it treats any existing remote connections as new connections. You're prompted to accept the host key fingerprint first. Then, Visual Studio establishes a connection and caches the accepted fingerprint.

You can also update remote connections from ConnectionManager.exe using the update argument.

Supported SSH algorithms

Starting in Visual Studio version 16.9, support for older, insecure SSH algorithms used to encrypt data and exchange keys is removed. Only the following algorithms are supported. They're supported for both client-to-server and server-to-client SSH communication:

Algorithm type	Supported algorithms
Encryption	aes128-cbc aes128-ctr aes192-cbc aes192-ctr aes256-cbc aes256-ctr
HMAC	hmac-sha2-256 hmac-sha2-512
Key exchange	diffie-hellman-group14-sha256 diffie-hellman-group16-sha512 diffie-hellman-group-exchange-sha256 ecdh-sha2-nistp256 ecdh-sha2-nistp384 ecdh-sha2-nistp521
Host key	ecdsa-sha2-nistp256 ecdsa-sha2-nistp384 ecdsa-sha2-nistp521

Configure the SSH server

First, a little background. You can't select the SSH algorithm to use from Visual Studio. Instead, the algorithm is determined during the initial handshake with the SSH server. Each side (client and server) provides a list of algorithms it supports, and then the first algorithm common to both is selected. The connection succeeds as long as there's at least one algorithm in common between Visual Studio and the server for encryption, HMAC, key exchange, and so on.

The Open SSH configuration file (sshd_config) doesn't configure which algorithm to use by default. The SSH server should use secure defaults when no algorithms are specified. Those defaults depend on the version and vendor of the SSH server. If Visual Studio doesn't support those defaults, you'll likely see an error like: "Could not connect to the remote system. No common client to server HMAC algorithm was found." The error may also appear if the SSH server is configured to use algorithms that Visual Studio doesn't support.

The default SSH server on most modern Linux distributions should work with Visual Studio. However, you may be running an older SSH server that's configured to use older, insecure algorithms. The following example explains how to update to more secure versions.

In the following example, the SSH server uses the insecure hmac-sha1 algorithm, which Visual Studio 16.9 doesn't support. If the SSH server uses OpenSSH, you can edit the /etc/ssh/sshd_config file as shown below to enable more secure algorithms. For other SSH servers, refer to the server's documentation for how to configure them.

First, verify that the set of algorithms your server is using includes algorithms supported by Visual Studio. Run the following command on the remote machine to list the algorithms supported by the server:

ssh -Q cipher; ssh -Q mac; ssh -Q kex; ssh -Q key

The command produces output like:

3des-cbc
aes128-cbc
aes192-cbc
aes256-cbc
...
ecdsa-sha2-nistp521-cert-v01@openssh.com
sk-ecdsa-sha2-nistp256-cert-v01@openssh.com

The output lists all the encryption, HMAC, key exchange, and host key algorithms supported by your SSH server. If the list doesn't include algorithms supported by Visual Studio, then upgrade your SSH server before proceeding.

You can enable algorithms supported by Visual Studio by editing /etc/ssh/sshd_config on the remote machine. The following examples show how to add various types of algorithms to that configuration file.

These examples can be added anywhere in /etc/ssh/sshd_config. Ensure that they're on their own lines.

After editing the file, restart the SSH server (sudo service ssh restart on Ubuntu) and attempt to connect again from Visual Studio.

Cipher example

Add: Ciphers <algorithms to enable>
For example: Ciphers aes128-cbc,aes256-cbc

HMAC example

Add: MACs <algorithms to enable>
For example: MACs hmac-sha2-256,hmac-sha2-512

Key exchange example

Add: KexAlgorithms <algorithms to enable>
For example: KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384

Host key example

Add: HostKeyAlgorithms <algorithms to enable>
For example: HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384

Logging for remote connections

You can enable logging to help troubleshoot connection problems. On the menu bar, select Tools > Options. In the Options dialog, select Cross Platform > Logging:

The options are open to Cross Platform > Connection Manager > Logging. Enable logging is checked, log to a file is checked, the logfile directory is set the documents folder, and log to the 'Cross Platform Logging' pane in the output window is checked.

Logs include connections, all commands sent to the remote machine (their text, exit code and execution time), and all output from Visual Studio to the shell. Logging works for any cross-platform CMake project or MSBuild-based Linux project in Visual Studio.

You can configure the output to go to a file or to the Cross Platform Logging pane in the Output window. For MSBuild-based Linux projects, MSBuild commands sent to the remote machine aren't routed to the Output Window because they're emitted out-of-process. Instead, they're logged to a file, with a prefix of "msbuild_".

Command-line utility for the Connection Manager

Visual Studio 2019 version 16.5 or later: ConnectionManager.exe is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the ConnectionManager command, see ConnectionManager reference.

TCP Port Forwarding

The rsync command is used by both MSBuild-based Linux projects and CMake projects to copy headers from your remote system to Windows for use by IntelliSense. When you can't enable TCP port forwarding, disable the automatic download of remote headers. To disable it, use Tools > Options > Cross Platform > Connection Manager > Remote Headers IntelliSense Manager. If the remote system doesn't have TCP port forwarding enabled, this error appears when the download of remote headers for IntelliSense begins:

rsync is also used by Visual Studio's CMake support to copy source files to the remote system. If you can't enable TCP port forwarding, you can use sftp as your remote copy sources method. sftp is often slower than rsync, but doesn't have a dependency on TCP port forwarding. You can manage your remote copy sources method with the remoteCopySourcesMethod property in the CMake Settings Editor. If TCP port forwarding is disabled on your remote system, an error appears in the CMake output window the first time it invokes rsync.

The output window includes these messages: Verify that TCP forwarding is enabled on the server, rsync: did not see server greeting, rsync error: error starting client-server protocol (code 5) at main.c(1675) [sender=3.1.3], An SSH channel couldn't be opened.

gdbserver can be used for debugging on embedded devices. If you can't enable TCP port forwarding, then you must use gdb for all remote debugging scenarios. gdb is used by default when debugging projects on a remote system.

Visual Studio's Linux support has a dependency on TCP port forwarding. Both rsync and gdbserver are affected if TCP port forwarding is disabled on your remote system. If this dependency impacts you, vote for this suggestion ticket on Developer Community.

Connect to WSL

Starting in Visual Studio 2019 version 16.1, Visual Studio has native support for using C++ with the Windows Subsystem for Linux (WSL). That means you can build and debug on your local WSL installation directly. You no longer need to add a remote connection or configure SSH. You can find details on how to install WSL here.

To configure your WSL installation to work with Visual Studio, you need the following tools installed: gcc or clang, gdb, make, ninja-build (only required for CMake projects using Visual Studio 2019 version 16.6 or later), rsync, and zip. You can install them on distros that use apt by using this command, which also installs the g++ compiler:

sudo apt install g++ gdb make ninja-build rsync zip

Fix WSL localhost connection problems

When connecting to Windows Subsystem for Linux (WSL) on localhost, you may run into a conflict with the Windows ssh client on port 22. In WSL, change the port that ssh expects requests from to 23 in /etc/ssh/sshd_config:

Port 23

If you're connecting using a password, ensure that the following is set in /etc/ssh/sshd_config:

# To disable tunneled clear text passwords, change to no here!
PasswordAuthentication yes

After making these changes, restart the SSH server (sudo service ssh restart on Ubuntu).

Then retry your connection to localhost using port 23.

For more information, see Download, install, and set up the Linux workload.

To configure an MSBuild project for WSL, see Configure a Linux project. To configure a CMake project for WSL, see Configure a Linux CMake project. To follow step-by-step instructions for creating a simple console application with WSL, check out this introductory blog post on C++ with Visual Studio 2019 and the Windows Subsystem for Linux (WSL).

See Also

Configure a Linux project
Configure a Linux CMake project
Deploy, run, and debug your Linux project
Configure CMake debugging sessions