VS Code Remote-SSH Guide

VS Code offers an extension called “Remote - SSH” that allows users to code on remote servers with their local VS Code configuration (all extensions are preserved regardless of the server). This provides an easy way for students that use VS Code already to develop on the SoCS Linux servers regardless of their hardware platform without extra configuration steps.

• The “Remote-SSH” extension must be installed in your VS Code instance. This can be done by navigating to the “Extensions” menu item on the left bar on VS Code, searching for the “Remote - SSH” extension, and installing it.
• The Cisco AnyConnect VPN used by the University must be installed on your main device if you are planning to develop off campus. Do not attempt to download this tool from third party links. It can be downloaded directly from the university's servers at “vpn.uoguelph.ca”. Please follow the official documentation (you will need to login with your University Single Sign On credentials).

The workflow for using Remote-SSH with VS Code to develop on the SoCS Linux servers varies on campus and off campus. If you are off campus, you must first connect to VPN by:

1. Open the Cisco AnyConnect app.
2. Select the “split tunnel” mode by clicking on the drop down menu. If you do not see this option, you can edit the text field in the dropdown and enter “vpn.uoguelph.ca” to get access to it.
3. Authenticate using your University single sign on credentials. As of writing, you will have to authenticate using MFA everytime you use the University VPN.

If you are on campus and connected to University WIFI, you do not need to connect to the VPN to develop on SoCS Linux servers using VS Code.

Next, you must configure Remote-SSH with the SoCS Linux server by:

1. Open VS Code on your local machine.
2. Navigate to the “Remote Explorer” menu item from the left bar.
3. Right click on the “SSH” folder and choose “New Remote”.
4. A prompt will show up at the top of VS Code, enter “ssh [username]@linux.socs.uoguelph.ca”, where [username] is your university username.
5. A second prompt will ask you for your password. Enter your University single sign on credentials. As of writing, you will not require MFA to authenticate to the SoCS Linux servers.
6. First time setup will require 1-2 minutes. Following that, you can connect to the linux servers simply by choosing “linux.socs.uoguelph.ca” in the SSH folder and connect.

NOTE: After entering the SSH command, you may get a prompt asking you for the platform of your remote server if it is not automatically recognized. Choose “Linux” if you get this prompt and then enter your password regularly.

Please note that every time you wish to use Remote-SSH to develop on the SoCS Linux servers from off campus, you will need to connect to the VPN first. Otherwise your credentials in the authentication step will be rejected by the firewall. If you run into any other issues, please reach out to the SoCS IT Team at “help@socs.uoguelph.ca”.

A common error that students may run into when developing on the SoCS Linux servers using VS Code is not being able to authenticate on git when cloning or pushing (with a “missing or invalid credentials” error). This error occurs when using git through a terminal opened within VS Code due to a conflict between the git package on the server and the authentication handler of VS Code's Git extension. To resolve this:

1. Open VS Code.
2. Click on “File” on the top left, then “Preferences”, and “Settings”.
3. Using the search bar, find “git.terminalAuthentication”
4. Uncheck the checkbox.
5. Git commands should now authenticate correctly. If they do not, reconnect to the server using Remote-SSH.