Note: The following guide is for Linux/Unix based systems including Mac that use OpenSSH or a compatible ssh client. If you are using a Windows system, we recommend the official "Windows Subsystem for Linux" (WSL2) provided by Microsoft to create a linux system kernel and environment within Windows.
The core of this article will be based around configuring your SSH client to make your life simpler. This will start with the basic configuration to tell your SSH client about specific hosts (remote servers) that you connect to. Different access parameters for each host can be independently specified here. By default, your ssh configuration file for your profile on your local machine will likely be located at
~/.ssh/config. Edit this file using a text editor of your choice.
Set Up Host Aliases¶
Let's create some host aliases for the CCI landing pads so that we can simplify our initial ssh command. Let's say that your CCI username was
EXPLname. Typically, you'd connect to a landing pad through ssh with a command like:
You could add the following lines to your ssh configuration file:
This would allow you to refer to specific landing pads by an alias (nickname) instead of a full address. It also will use the configured username to connect to the specified host so your ssh command to connect to a landing pad would now be:
This also affects SCP commands, so if you wanted to transfer a file
test.txt that existed in your local machines home directory, you could now transfer it to your barn (or anywhere else) with the following command:
scp ~/test.txt cci01:~/barn/
Note: This SSH configuration file is also normally where you could supply specific public-key identity files for passwordless access. However, CCI systems require two-factor authentication with each new SSH connection and has disabled public-key authentication for off-site connections. As such, generating and configuring these identity files is not documented here. There is, however, a way to create multiple connections using only one authentication...
As previously mentioned, for security reasons, the CCI requires the TOTP authentication with each new connection, ruling out standard public-key authentication methods for remote access. When needing to access CCI systems repeatedly through SSH, including terminal access, SCP, or remote filesystem mounting, it can be a hassle to need to authenticate with your PIC, app-generated token, and password every time. There are ways, however, to establish a consistent connection to a host (such as a landing pad) and any SSH based communication directed to that host will be routed through the existing connection, rather than opening a new one. This is called SSH multiplexing.
In short, SSH can be configured on your device so that when a connection is established to a specific named host, a control socket is created. Any subsequent connections to that specific named host (the host must be named and configured in your SSH Config) will be directed over that existing control socket if it exists. If that control socket doesn't exist, then a new one is created. This control socket can be configured so that it remains active for a specified time (or indefinitely) even after multiplexed sessions are closed. This means that you could create an SSH connection with a landing pad, authenticate, disconnect, and reconnect without needing to enter your PIC+Token and Password a second time.
The first step is to configure SSH through its configuration file similar to the example above. But this time we are going to configure it to create a control socket upon successful connection. Then future connections to the same host can utilize this existing socket without the need for additional authentication.
Building on the above example for CCI user
EXPLname, we'll add SSH configuration options for
ControlMaster is the main option that enables SSH multiplexing, setting it to
auto will enable future connections to the same host without prompting that this is intended.
ControlPath specifies where and how the control socket will be created. In this example, we give it format placeholders for the hostname, port of access, and username; these placeholders will be populated when the control socket file is created.
ControlPersist configures how long the socket will remain open after the last SSH connection is severed.
Now we are able to do the following:
It will prompt for your PIC+Token and Password. Upon successful connection, the a control socket will exist in the
~/.ssh/ directory on the user's local machine. Specifically in this example, the control socket will be a named file
After successfully connecting, you'll be dropped into a shell on landing pad 1. You can exit the shell, and then reconnect within a 4 hour time window and not need to re-authenticate.
We can change the
ControlPersist option to
0 and the socket will remain open indefinitely.
Deleting this file will close the socket, requiring re-authentication when connecting again.
This also applies to SCP, so the previous example of transferring
test.txt will also, then, work without re-authentication.
However, things that sever connections could interrupt the socket and require premature re-authentication, connecting to a VPN, loss of internet connection, changing networks, random hiccups/broken pipes, etc.
Remote Filesystem Mounting¶
For users who prefer GUI file management, relying on editing your files using CLI text editors like vim, emacs, nano, etc. may be an inconvenient way to modify files. Alternatively, one could modify a file locally and then use SCP to transfer it to the CCI but this is also inconvenient and time consuming.
If you are one of those users, then there is a better solution: SSHFS: mounting CCI directories to your local machine. In other words, creating a directory that appears as if it were a natural folder on your computer but is constantly synchronized with a directory at the CCI. This synched directory includes all subdirectories and files within it as well. We can, for example, mount our CCI Home directory on our local machine over SSH and then edit the files locally using any text editor we'd like, CLI or otherwise! This includes vim, emacs, VSCode, Sublime, you name it.
The tool we'll use to mount a networked filesystem over SSH is called
sshfs. Some linux distros might include it already but it may need to be installed on your local machine. For Ubuntu/Debian as an example, it can be installed with:
sudo apt-get install sshfs
First, for convenience and simplicity of this tutorial, we'll create a main directory that will contain all of our mount points and subdirectories in it for each of the directories we want to mount. It's also good practice to have this directory of mount points should you ever want to apply this technique to other network accessible servers.
Now that we've got the SSHFS tool installed and our mount point created, let's actually create the connection. The tool's usage pattern is as such:
sshfs <USERNAME>@<HOSTNAME>:/path/to/desired/directory /path/to/mount/point -o <OPTIONS>
For our example we're going to be mounting our home directory, this will allow us to navigate all of our immediately accessible files and directories such as
scratch, and similar. Let's say your CCI project and username are EXPL and EXPLname respectively, the command to mount your home directory to the mount point we created above is as follows:
sshfs EXPLname@blp01.ccni.rpi.edu:/gpfs/u/home/EXPL/EXPLname ~/mounts/home -o follow_symlinks
-o follow_symlinks part is very important. Barn, Scratch, Barn-Shared, and Scratch-Shared appear as subdirectories within your home directory on the CCI systems, but they are actually symbolic links (symlinks in Linux lingo). Essentially they are shortcuts to where the directories are actually located within the CCI. Without this additional option provided to SSHFS, these shortcuts will appear as blank files to you on your local machine. With this option, SSHFS knows to keep an eye out for the shortcuts and populate them to their actual location when you try to access them locally.
To disconnect, close any windows or editors accessing the mounted directories and execute the following command:
sudo umount ~/mounts/home
You will be prompted for your local machine's sudo password. If this is unsuccessful and closing all windows and editors still doesn't work, rebooting the system will do the trick.
SSH Multiplexing Revisited¶
You'll notice that when you executed that sshfs command to mount your home directory locally, it asked for your PIC+Token and password. But what if we had set up SSH multiplexing (see above)?. This sshfs tool mounts the networked filesystem and synchronizes it all over SSH, which means if we had an established SSH control socket, we could direct sshfs to use that existing connection and not require another CCI authentication!
Assuming that you have set up your SSH configuration as specified in the above examples on SSH Multiplexing, we could instead make our sshfs command as follows:
sshfs cci01:/gpfs/u/home/EXPL/EXPLname ~/mounts/home -o follow_symlinks
If the control socket for cci01 exists, then it will use that; otherwise it will ask for authentication via PIC+Token and password.