External command-line access to DoC machines via Secure Shell (SSH)

Secure shell ('ssh') is a network protocol allowing secure, remote machine access to Linux machines. 'ssh' also refers to applications that allow you to connect using this network protocol. All Linux machines in DoC are running a secure shell daemon/server.

The local machine (the client or your home machine) must be running a secure shell client; ssh client implementations are freely available for all major platforms (please see below).  If your home machine runs Windows 10/11, or MacOS, or any version of Linux, ssh should come with it, or be trivially installable.  The rest of this guide concentrates on using your built-in ssh client.

Setting up SSH

When you start using ssh in DoC, one of the first things you will need to do is to set up a trusted SSH key with a strong passphrase.  You need to do this while onsite (with your laptop), before being able to ssh into any of our shell servers. This section explains, step by step, how to do that.  Here we assume that you have no existing SSH setup either at DoC or on your laptop that you want to keep.  If that's not true, you might want to backup any existing .ssh directory either in your DoC home directory or on your laptop before starting.

  1. Bring your laptop into College.  Sit down and login to any Linux lab machine on Level 2 Huxley.  I'm going to assume that you've logged into beech17 (list of lab PCs).  Start a terminal.
  2. Now, to set up your trusted SSH key, rather than describe each step separately, we've written an experimental Perl script that will hopefully do it for you.  If you're absolutely sure you don't mind overwriting most of ~/.ssh in your DoC home directory:  run this command on your beech17 (DoC lab machine) terminal:  

    ~dcw/bin/setup-ssh.

  3. This will ask you for the new SSH key's passphrase.  Make up and memorise a good strong passphrase, and enter it twice.  One way of generating a good passphrase might involve picking 3 or 4 unrelated words and stringing them together, either with spaces or with some punctuation to make it even more secure.  For example: herring fluffy Poster! would be an excellent passphrase (but don't use this one, obviously!).  Note that you are technically permitted to leave the passphrase blank: please do not do this, passphrases add an important extra level of security.  If we can ever figure out how to, we'll ban SSH keys with blank passphrases.
  4. setup-ssh creates your new SSH key in ~/.ssh/id_ed25519 (the private key) and ~/.ssh/id_ed25519.pub  (the public key).  It also arranges for all DoC linux machines to trust your new SSH key, by appending the new public key to your ~/.ssh/authorized_keys file (creating it if necessary).  All these files are stored in your DoC home directory, which is common to every DoC Linux lab machine (and shell server) that you login to.
  5. setup-ssh then writes you a possible ssh configuration file for your laptop/home machine, placing this temporarily in ~/.ssh/HomeConfig in your DoC home directory.  This picks a couple of shell servers at random and 3 lab machines at random, and adds suitable ssh Host declarations, one per shell, one per lab machine, and one for each combination of a shell server and a lab machine (this is what other parts of this page call "2-hop ssh").
  6. setup-ssh then tells you precise commands that you must run on your laptop - connected via ImperiaWPA wifi - that will copy your new private key and HomeConfig from your DoC home directory onto your laptop.  Run these commands on your laptop, being extremely careful to get them character-perfect.
  7. Finally, setup-ssh tells you some test ssh commands to try from your laptop - try them now, verify that they work - and then suggests that you run a companion script ~dcw/bin/setup-sshagent to help you configure ssh-agent on your laptop.  You don't have to do this right now - but you might want to come back to it when you get bored of entering your SSH passphrase repeatedly.  Note that if your laptop runs Windows 10 or 11, you should run ~dcw/bin/setup-sshagent --windows, whereas if your laptop runs (any) Linux or MacOS X, just run ~dcw/bin/setup-sshagent.
  8. These scripts are experimental, feel free to read them to see what commands they run.  If you get into difficulties, ask your lab organiser for help if you're in an organised session, or email doc-help@imperial.ac.uk otherwise (copy/pasting the output of the setup-ssh run would be helpful) and explaining where things went wrong.

Using SSH once you've setup your SSH key

In the last few years, you cannot ssh into DoC Linux machines from outside the College network, individual lab machines are firewalled off - so you cannot directly ssh from your offsite home machine to a lab machine.

The only DoC Linux machines that you can directly ssh into from outside the College network are the following 5 DoC Linux servers:

  • shell1.doc.ic.ac.uk

  • shell2.doc.ic.ac.uk

  • shell3.doc.ic.ac.uk

  • shell4.doc.ic.ac.uk

  • shell5.doc.ic.ac.uk

To ssh to a shell server, you will need to have setup a trusted ssh key (shared between your laptop and DoC systems) and setup your .ssh/config on your laptop. This is covered in the "Setting Up SSH" section above.  This became necessary in December 2024 when password-based SSH authentication was disabled on the shell servers at ICT's request to increase system security.  Trusted SSH keys replaced password-based access on the shell servers.

Note: Please do not run any CPU-intensive or memory-intensive code on the shell servers: they exist only as gateway machines.  Read the two hop section below!  Long running jobs (that is, over a day, and with very large RAM requirements) should run on batch1.doc.ic.ac.uk or batch2.doc.ic.ac.uk. 

If you want to be able to ssh to any other DoC Linux machine, you can either do this:

  • go in two hops (first ssh into one of the above shell servers, then ssh from that shell server to whichever DoC linux machine you wanted to connect to). See the later section on Two Hop SSH Access for more details about doing this.
  • or (when offsite) by first connecting to College Unified Access and then ssh'ing directly to your chosen DoC machine, using your College password or your SSH passphrase (whichever it asks for).
  • or (when onsite with a laptop), connecting to ImperiaWPA wifi - and then ssh'ing directly to your chosen DoC machine, using your College password or your SSH passphrase (whichever it asks for)..

Please note that whenever you enter a DoC hostname, unless it's one of the machines that your laptop's .ssh/config has a host entry for, you will need to use a fully qualified hostname, as in batch1.doc.ic.ac.uk not just batch1.  Of course you can add additional short host entries for whichever machines you regularly ssh to by editing your laptop's .ssh/config file.

Under Linux, MacOS, or Windows 10/11, you can run an ssh command such as the following in your shell/command line interpreter (eg. Terminal, cmd or Powershell on Windows):

ssh shell3

You can replace shell3 with shell1, shell2, shell4 or shell5 in the above example to use one of the other shell servers.

(This assumes that you've got a .ssh/config on your laptop created by setup-ssh, if not then you could run:

ssh YOURUSERNAME@shell3.doc.ic.ac.uk

)

From any ssh window on a DoC host, you can run text-mode programs (eg. editors such as Vim, Pico or Emacs) but you won't be able to run X clients (graphical programs). That can be done, but is beyond the scope of this guide.  We recommend that you learn to use the power of the command line.  If you want to edit files and you can't learn a Linux editor, then learn one!  In desperation you could use scp to grab a copy of the file, edit it locally, and scp it back again.

Two Hop SSH Access via a Shell server (if you have used setup-ssh)

We said earlier that you shouldn't run intensive CPU processes on shell servers, they're intended only as gateways.  So most ssh access that you will need to do will be in "two hops": ssh first into a shell server and then from that shell server ssh into a particular lab machine.  If you look at your laptop's .ssh/config file (that setup-ssh created for you, remember) you will see that it has Host entries for the shell servers (the Host shell? entry) and for a small number of randomly chosen lab machines.

Suppose you want to ssh to beech17 from offsite.  Of course you can't just ssh USERNAME@beech17.doc.ic.ac.uk from offsite because it's firewalled off.  The easiest option is to go via a shell server.  You could do it in two explicit steps:

ssh shell3

(giving your SSH key passphrase) and then from the shell3 window:

ssh beech17

(giving either your College password or your SSH key passphrase).  This should work, but there's a neater way:

ssh -J shell3 DOCUSERNAME@beech17.doc.ic.ac.uk

should "jump" or "proxy" through shell3 to beech17 - still asking for your passphrase twice, of course.  If  beech17 is one of the Hosts in your laptop's .ssh/config. then you could abbreviate the above to:

ssh -J shell3 beech17

But in that case, your .ssh/config probably also contains a "beech17viashell3" pseudo-host entry that hides away all this "-J shell server" stuff.  In that case, all you need type is:

ssh beech17viashell3

which is a lot simpler.  Note: the pseudo-hostname "beech17viashell3" can be anything you want, for instance "doclab1" - just edit the .ssh/config file. It would, however, be foolish to choose a real DoC lab hostname as that would confuse everyone, forever.

Of course, if beech17 and beech17viashell3 are not named in your .ssh/config, just edit your .ssh/config and add the following two Host entries:

Host beech17
        User dcw
        HostName beech17.doc.ic.ac.uk
        IdentityFile ~/.ssh/doc_ed25519
Host beech17viashell3
        User dcw
        HostName beech17
        ProxyJump shell3
        IdentityFile ~/.ssh/doc_ed25519


Using ssh-agent at home, to avoid ssh asking for a passphrase/password

Wouldn't it be nice if you could enter your ssh key passphrase once, and then do multiple ssh and scp commands, without having to re-enter your passphrase each time.

You can do this on your laptop/home PC via ssh-agent and your trusted SSH key.  When you ran setup-ssh at the beginning of this process, the last thing it suggested was that you run a companion script ~dcw/bin/setup-sshagent to help you configure ssh-agent on your laptop.  Now that you've got bored of entering your SSH passphrase repeatedly, you can do that.  Note that if your laptop runs Windows 10 or 11, you should run ~dcw/bin/setup-sshagent --windows, whereas if your laptop runs (any) Linux or MacOS X, just run ~dcw/bin/setup-sshagent.

Alternatively, here's the old instructions that are basically equivalent to what setup-sshagent tells you to do.

I'm going to assume that your key is an ED25519 file whose private key is stored in .ssh/doc_ed25519 on your laptop.  If it's something different, eg an RSA key whose private key is stored in .ssh/id_rsa, say, substitute id_rsa for doc_ed25519 in the instructions below.

To use this key automatically on your Linux or Mac laptop/home PC, each time you reboot your laptop, start an ssh-agent:

eval `ssh-agent`  [Note: Recent Windows machines seem to not only come with ssh-agent, but have it automatically running.  Other Windows machines come with ssh-agent, but have the ssh-agent service disabled.  Skip this eval step on such machines, and instead search in Windows Services for the OpenSSH agent service, and enable it if it's not already enabled].

Then add your DoC ssh key into the agent via:

ssh-add ~/.ssh/doc_ed25519

It will prompt you for your passphrase - enter it. Check that it worked via:

ssh-add -l

Now that you’ve done all this, as long as the ssh-agent is running and has your key in it, you should be able to:

ssh shell3 echo hi

and have it say hi without prompting you for a passphrase. Isn't that lovely?

Note that this ssh-agent, loaded with your ssh key, lasts forever, and lets anyone with physical access to your laptop/home machine to ssh, as you, to all DoC linux machines.  This is convenient - but dangerous.  For security, at the end of your working day (or when leaving a secure environment with this setup on your laptop), we recommend that you remove your loaded keys from the agent via:

ssh-add -D

This leaves your ssh-agent running, but loaded with no keys.  The next day, simply redo

ssh-add ~/.ssh/doc_ed25519

and enter your passphrase again.

 

Other Uses of SSH Keys

Other places where you may wish to use trusted ssh keys and ssh-agents include our Gitlab server gitlab.doc.ic.ac.uk.  You can upload a public key into Gitlab via the web interface, and then if you are running ssh-agent loaded with that private key (as described above), you will be able to use ssh based git commands with no passphrases needed.  This is extremely convenient.  Just remember to remove your keys via the ssh-add -D command suggested above.

You can also (if you must) use VS Code's remote ssh plugin.  Activate ssh-agent as described above, and then just enter "ssh LviaS" (for some lab machine L and shell server S that is named in your .ssh/config) as the machine to connect to. If "ssh LviaS echo hi" works outside of VS Code then the remote ssh plugin should work too.