Overview

Hello and welcome to the official documentation of µLab at The Cooper Union for the Advancement of Science and Art! We've been a completely student-run organization responsible for maintaining the computing resources of the Electrical Engineering department at the Albert Nerken School of Engineering for over 30 years!

As far as we're aware, µLab is one of the only student-run organizations that exist in the United States with near-complete autonomy from its parent institution. With that comes a few perks:

  • Full control over the 199.98.27.0/24 subnet
  • Dozens of virtual machines & containers hosting services
  • Fifty-five workstations which are all centrally managed & orchestrated
  • Six physical servers (including a GPU compute node!)

License

Cooper Union µLab documentation is distributed under the CC BY-NC-SA 4.0.

Connecting with SSH

The Secure Shell Protocol, or SSH for short, is your gateway for accessing µLab resources. Using SSH, you can conceivably access any of our resources from anywhere in the world with the bonus of being safe and secure!

Invoking the SSH Client

At its most basic level, SSH provides you with a remote shell. As such, you will need to utilize a terminal to make a connection.

Open a new terminal or command prompt window and type the following:

$ ssh -p31415 first.last@dev.ee.cooper.edu

Let's breakdown the command:

  • ssh: the invocation of the SSH program
  • -p31415: if you're trying to connect outside of the Cooper network, you'll need to manually specify port 31415 as the school's firewall blocks SSH's default port
  • first.last: your µlab username
  • dev.ee.cooper.edu: the host which we are trying to connect (this can be any valid hostname running an SSH daemon)

If you're connecting for the first time to a machine, you might have to accept the host's key fingerprint:

$ ssh -p31415 first.last@dev.ee.cooper.edu
The authenticity of host '[dev.ee.cooper.edu]:31415 ([199.98.27.254]:31415)' can't be established.
ED25519 key fingerprint is SHA256:w1duK0IPo7QWWBInuQKk7fdoYefMvi1SAZ8giVmDVQA.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? _

All you need to do here is to type yes.

There's some very clever cryptography working behind the scenes to ensure your connection is secure. The math governing this is far beyond the scope of this short guide, but it is here to prevent what's called a "man-in-the-middle attack." If a malicious entity were to intercept your SSH connection, you might see the following if you were to try connecting again:

$ ssh -p31415 first.last@dev.ee.cooper.edu
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that a host key has just been changed.
The fingerprint for the ED25519 key sent by the remote host is
SHA256:someMaliciousKeyOverHereDontTryConnecting11.
Please contact your system administrator.
Add correct host key in /home/user/.ssh/known_hosts to get rid of this message.
Offending RSA key in /home/user/.ssh/known_hosts:1
Host key for [dev.ee.cooper.edu]:31415 has changed and you have requested strict checking.
Host key verification failed
$ _

If you see this message above when you attempt to connect, and you don't know for sure that the host key fingerprints have changed, DO NOT ATTEMPT TO CONNECT! Instead, try to move to a different network connection to see if that resolves the issue. If this persists, please reach out to <eeadmin@cooper.edu>.

Adding an SSH Configuration

Having to type such a long command can become tiring quite fast. Using a non-standard SSH port also creates the annoying situation of having to manually specify the port for each program that uses SSH internally. If only we could avoid this headache!

To avoid this conundrum, you'll need to add a few things to your SSH configuration file. This file is located at ~/.ssh/config on UNIX-like operating systems and %USERPROFILE%\.ssh\config (typically C:\Users\username\.ssh\config) on Windows . Open this file in a text editor of your choice and add the following:

Host *.ee.cooper.edu
	User first.last
	Port 31415

After the addition of these lines, you'll be able to connect using SSH like so:

$ ssh dev.ee.cooper.edu

Let's say you wanted to type even less because you often SSH into the remote development machine. You can add a host alias to your SSH configuration file like so:

Host dev
	Hostname dev.ee.cooper.edu
	User first.last
	Port 31415

Now all you'd need to type to SSH to the remote development machine would be:

$ ssh dev

File Access

Accessing your µLab files necessitates a file-transfer client that supports the SSH protocol. Although there are a lot of clients to choose from, we'll cover a few of the most popular options.

SCP

OpenSSH secure file copy (scp) is a command that behaves much like the cp command with the added bonus of working over SSH. The command has the following semantics:

$ scp [OPTIONS] source ... target

Lets say you want to download a file called homework.c under ~/cu/ece-160/ to your local directory, the command would be as follows:

$ scp -P 31415 first.last@dev.ee.cooper.edu:cu/ece-160/homework.c .
(first.last@dev.ee.cooper.edu) Password:
homework.c                            100% 1247    60.8KB/s   00:00
$ _

Or lets say you wanted to copy a file called project.c in your local directory to the folder ~/cu/ece-160/:

$ scp -P 31415 project.c first.last@dev.ee.cooper.edu:cu/ece-160
(first.last@dev.ee.cooper.edu) Password:
project.c                          100% 3102   140.7KB/s   00:00
$ _

And if you want to move a directory, you'll have to run the command recursively with the -r flag:

$ scp -r -P 31415 first.last@dev.ee.cooper.edu:cu/ece-160 .
(first.last@dev.ee.cooper.edu) Password:
homework.c                    100% 1247    74.2KB/s   00:00
project.c                     100% 3102   167.6KB/s   00:00
lesson-0.md                   100% 2783   135.9KB/s   00:00
assignment-0.md               100% 1492    76.1KB/s   00:00
...
$ _

Note that if you added µLab hosts to your SSH configuration the commands above could have been simplified down to the following:

$ scp dev.ee.cooper.edu:cu/ece-160/homework.c .
$ scp project.c dev.ee.cooper.edu:/tmp
$ scp -r @dev.ee.cooper.edu:cu/ece-160 .

SFTP

OpenSSH secure file transfer (sftp) is a client which gives you an interactive way to transfer files to remote hosts. To begin an interactive session type the following:

$ sftp -P 31415 first.last@dev.ee.cooper.edu
Connected to dev.ee.cooper.edu.
sftp> _

To see a list of commands, type help:

sftp> help
Available commands:
bye                                Quit sftp
cd path                            Change remote directory to 'path'
chgrp [-h] grp path                Change group of file 'path' to 'grp'
chmod [-h] mode path               Change permissions of file 'path' to 'mode'
chown [-h] own path                Change owner of file 'path' to 'own'
copy oldpath newpath               Copy remote file
cp oldpath newpath                 Copy remote file
df [-hi] [path]                    Display statistics for current directory or
                                   filesystem containing 'path'
exit                               Quit sftp
get [-afpR] remote [local]         Download file
help                               Display this help text
lcd path                           Change local directory to 'path'
lls [ls-options [path]]            Display local directory listing
lmkdir path                        Create local directory
ln [-s] oldpath newpath            Link remote file (-s for symlink)
lpwd                               Print local working directory
ls [-1afhlnrSt] [path]             Display remote directory listing
lumask umask                       Set local umask to 'umask'
mkdir path                         Create remote directory
progress                           Toggle display of progress meter
put [-afpR] local [remote]         Upload file
pwd                                Display remote working directory
quit                               Quit sftp
reget [-fpR] remote [local]        Resume download file
rename oldpath newpath             Rename remote file
reput [-fpR] local [remote]        Resume upload file
rm path                            Delete remote file
rmdir path                         Remove remote directory
symlink oldpath newpath            Symlink remote file
version                            Show SFTP version
!command                           Execute 'command' in local shell
!                                  Escape to local shell
?                                  Synonym for help
sftp> _

As an example, lets see how we'd do everything we did with scp with sftp:

sftp> get cu/ece-160/homework.c .
Fetching /afs/ee.cooper.edu/user/f/first.last/cu/ece-160/homework.c to ./homework.c
homework.c                                            100% 1247    68.5KB/s   00:00
sftp> put project.c cu/ece-160/
Uploading project.c to /afs/ee.cooper.edu/user/f/first.last/cu/ece-160/
project.c                                             100% 1247   137.3KB/s   00:00
sftp> get -R cu/ece-160 .
Fetching /afs/ee.cooper.edu/user/f/first.last/cu/ece-160/ to ./ece-160
Retrieving /afs/ee.cooper.edu/user/f/first.last/cu/ece-160
homework.c                                            100% 1247    81.3KB/s   00:00
project.c                                             100% 3102   171.4KB/s   00:00
lesson-0.md                                           100% 2783   251.6KB/s   00:00
assignment-0.md                                       100% 1492   152.7KB/s   00:00
...
sftp> _

Once you're done, either type exit or press ^D to quit.

sftp> exit
$ _

FileZilla

If command line programs aren't your thing, there's always FileZilla. When connecting, you'll need to specify the following information:

  • Host: sftp://dev.ee.cooper.edu
  • Username: first.last
  • Password: ****************
  • Port: 31415

Common

Here is a list of software guaranteed to be installed on all µLab hosts:

  • Build Systems:
    • CMake - tools designed to build, test, and package software
    • Make - controls the generation of executables and non-source files
    • Meson Build - extremely fast and user friendly build system
    • SCons - a software construction tool
  • Editors:
    • ed - line-oriented text editor
    • Emacs - an extensible, customizable, text editor, and more
    • nano - a small and simple text editor
    • Neovim - hyper extensible Vim-based text editor
    • Vim - the ubiquitous text editor
    • Visual Studio Code1 - editor optimized for building and debugging
  • Shells:
    • Bash - the Bourne Again SHell
    • fish shell - the user-friendly command line shell
    • Zsh - the Z Shell
  • Utils:
    • bat - a cat clone with wings
    • exa - a modern replacement for ls
    • fd - a simple, fast and user-friendly alternative to find
    • fzf - a command-line fuzzy finder
    • Git - fast, scalable, distributed revision control system
    • Git LFS - git extension for versioning large files
    • GnuPG - a complete and free implementation of the OpenPGP
    • htop - an interactive process viewer
    • man-db - the on-line manual database
    • man-pages - the Linux man-pages project
    • Mosh - the mobile shell
    • ripgrep - recursive regex pattern finder respecting your .gitignore
    • shellcheck - shell script analysis tool
    • shfmt - a shell parser and formatter for POSIX shell and bash
    • tmux - a terminal multiplexer
    • tree - a recursive directory listing command
1

Not installed on headless systems.

VS Code Remote Development

VS Code is one of the most popular text editors, and it'd be a shame if you couldn't use it on µLab hosts if it is your editor of choice. Thankfully Microsoft provides an easy-to-use editor extension that allows working remotely over SSH without much configuration. Feel free to reference the official guide, as we'll only cover configuration changes and quirks you may run into while remotely editing on µLab hosts.

Before getting started, we highly recommend you add µLab hosts to your SSH configuration to decrease the complexity of connecting!

Lock Files in /tmp

Since we have a federated login for µLab with home directories stored on a network file system, lock files stored in a user home directory can cause issues when connecting to hosts. To avoid this, change the remote.SSH.lockfilesInTmp setting to true.

Stale Sessions

If you leave your session running for an extended period, your Kerberos ticket may expire, preventing you from editing files. To circumvent this, you'll need to kill your existing session and initiate a new one. You can do this by opening the command pallet and searching for Remote-SSH: Kill VS Code Server on Host... and selecting the appropriate host when prompted.

Contributors

Here is a list of the contributors who have helped in writing our documentation, huge shout-out to them!

  • Jacob Koziej (EE '25)