VS Code Remote Usage with SSH

Last update: 06 Aug 2024 [History] [Edit]

Use Case

If you have access to an Almalinux 9 machine (through ssh) that you can use for code development, but you don’t have convenient interactive access to it, or don’t have administrator rights to it, this method is probably the most convenient way of using VS Code for ATLAS code development for you.

In this setup you can run VS Code on any one of its supported platforms (many flavours of Linux, macOS and Windows).

Tip Another option is to use the Remote - Tunnels extension from Microsoft. The disadvantage with this solution is you are dependent on their servers being up - the advantage is you can potentially log into machines behind a firewall more easily.

Requirements

The requirements on the client side are very lightweight with this approach.

Setup

If you are connecting remotely (i.e. from outside CERN), please first have a look at ssh tunnelling below.

If you are running on Windows, you should also follow the Windows instructions on installing OpenSSH.

Press F1, and choose “Remote-SSH: Connect to Host…” (or possibly “Remote-SSH: Connect Current Window to Host…”), and enter the host that you want to connect to.

Once the connection is established (probably after you had to enter your password), make sure that all the extensions that you’ll want to use, are “enabled” on the remote host. Note that you do not need to do this on every connection, only during the first time that you are making use of the host.

Next you need to set up your work area. One convenient way is to open a new terminal from the VS Code top menu, and in that terminal set up a partial build of athena as you normally would. With something like:

cd <some appropriate place>
git clone ssh://git@gitlab.cern.ch:7999/<username>/athena.git
<set up the appropriate branch>
<create a package_filters.txt file>
mkdir build
cd build/
asetup <the appropriate release>
cmake -DATLAS_PACKAGE_FILTER_FILE=../package_filters.txt ../athena/Projects/WorkDir/

With that done, you can finally tell the application to open the freshly cloned athena repository for editing.

Note that when you do this, VS Code will “re-initialise” the connection. Meaning that you will (probably) have to re-enter your password, and the terminal that you used previously, will go away. Because of this, it can be a very viable option to do the initial setup of the work area on the remote host in a terminal independent of VS Code, and only once the repository and the build directory have been set up, connect to the host with the editor.

If you did everything correctly, now you can start editing the source files in the package(s) that you set up for the partial build.

Advanced SSH use-cases

Setup SSH tunnel

If you want to connect to a machine behind a firewall (for example, you want to connect to your CERN desktop from home) then you can do the following:

ssh -N -L 2222:REMOTE_MACHINE_NAME:22 USERNAME@lxplus.cern.ch

WarningIf you are on a Windows machine, you should first follow the Windows instructions to install an OpenSSH client and server.

You can now follow the standard setup instructions above, except using 127.0.0.1 (or localhost) as the remote host to connect to. Specifically, you will need to click “Remote-SSH: Connect to Host…”, then choose ‘Add New SSH Host’ and then use the following ssh command : ssh -p 2222 USERNAME@127.0.01. You only need to do this once, as long as you save it in a .ssh/config file as prompted: next time, you can just select 127.0.0.1 from the list.

Alternatively you can use ProxyJump option of ssh, for example

ssh -J USERNAME@lxplus.cern.ch USERNAME@REMOTE_MACHINE

You have to type your password two times, the first time to lxplus, the second time to your remote machine. You can make it the default changing the your ssh configuration (usually in ~/.ssh/config) to include the following:

Host myremote
     HostName USERNAME@REMOTE_MACHINE
     ProxyJump USERNAME@lxplus.cern.ch

and then you can call connect to your remote machine simply with ssh myremote.

Hosts with home folder on network storage

It is not adviseable to install VS Code on network storage, especially AFS. If you have the ability to use permanent storage (or semi-persistent /tmp), that is preferred. In any case you should force lock files in /tmp using the remote.SSH.lockfilesInTmp setting. You can also set the installation path using remote.SSH.serverInstallPath dictionary. See an example below

{
    "remote.SSH.lockfilesInTmp": true,
    "remote.SSH.serverInstallPath": {
        "naf-dev~alma9": "/var/data/tadej/vscode/alma9",
        "naf-dev~centos7": "/var/data/tadej/vscode/centos7",
        "naf-dev": "/var/data/tadej/vscode/default",
    }
}

CERN also provides a KB article on recommendations for Lxplus.

Direct SSH to a container

It is possible to directly enter an Apptainer/Singularity container by utilising the SSH RemoteCommand functionality. First enable the remote.SSH.enableRemoteCommand setting in VS Code. Then configure your .ssh/config and add e.g. a suffix to your configuration, for example

Host lxplus_vscode~alma9
    RemoteCommand ~/.local/bin/run_container alma9
    RequestTTY yes

Note that in the example the command is wrapped in a script on the remote host. This is due to manual binding of directories which is very host-specific. Also it is assumed that lxplus_vscode configuration already exists.

Once ready, you can first test the connection e.g. ssh lxplus_vscode~alma9. When you confirm you are in a container you can just use the label in VS Code to connect in the container directly.

Disclaimer: The setting remote.SSH.remoteServerListenOnSocket may need to be set to false.

Tip If you are running a Lima VM, there is an even easier solution - see our Lima documentation.

Multiplexing SSH for Lxplus

Lxplus uses a load balancer to direct SSH connections to different nodes. This can cause problems since VS Code connects several times when starting up. Thus it could start the server on one node, and be looking for it on another. SSH allows for multiplexing your connection, i.e., one connection is opened and all subsequent SSH requests will go through that initial connection. Thus you, and VS Code, always end up on the same initial node. Hopefully, resulting in a more stable setup.

You can enable this option using ControlMaster auto in your local ssh_config for your connection to lxplus. You can create a separate host entry if you don’t want to change all of your connections to lxplus. ControlPath is a location for the sockets and ControlPersist keeps the socket open for N seconds after the last connection is closed. An example snippet from an ssh_config where you would connect to host lxplus_vscode in VS Code:

Host lxplus_vscode
    hostname lxplus.cern.ch
    user X
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p 
    ControlPersist 60  
    ... the rest of your entry ...

The only downside is that this does not work with SSH remote commands, which is experimentally supported by VS Code.