SigComm 2022 Cosmos Testbed Tutorial

Prerequisites

If you are registered for the tutorial session and you are planning to participate in the live demos, please follow these instructions prior to the session. We will be unable to assist you with account setup during the tutorial session.

Create an Orbit Account

1. Register for a Cosmos/Orbit account here: ​https://www.orbit-lab.org/userManagement/register. For your organization, please select "ACM SIGCOMM 2022 TUTORIAL: COSMOS" from the drop-down menu.
2. Look for a verification email with a link. After clicking the verification link, your account will be submitted to Cosmos administrators for approval. Account approval is not immediate, so please try to do this in advance of the tutorial. Please note that your account will not be approved unless you are registered for the tutorial.

Set up SSH keys

Access to the Cosmos testbed is typically through ​SSH, which requires the use of public key authentication. You will need to generate a public-private pair of keys and upload them to the account management page so that you can use your keys to log into Cosmos machines. You will also need to verify that you have an SSH client available on your personal machine.

Linux

NOTE: These instructions are NOT for Ubuntu running on Windows using Windows Subsystem for Linux (WSL).

These instructions assume you will be using a standard command-line SSH client for linux. If you have not already done so, ensure that you have it installed by running the following commands in a command-line terminal:

sudo apt-get update
sudo apt-get install openssh-client

Generating keys

Each distribution has their own location for the specific generation tools. These instructions are based on the documentation for Ubuntu (​located here).

To create your public and private SSH keys, open a command-line terminal and type:

ssh-keygen -t rsa

You will be prompted for a location to save the keys, and a passphrase for the keys which we highly recommend using. This passphrase does not have to be the same as your COSMOS account password.

Generating public/private rsa key pair.
Enter file in which to save the key (...):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in ...
Your public key has been saved in ...
Your public key is now available as .ssh/id_rsa.pub in your home folder.

This process will generate and store a private key and a public key file. The private key will be stored in the file and location you specify when prompted, and the public key file will be named the same as your private key file but with a .pub extension.

Uploading your public key to your COSMOS account

To upload you public key to your cosmos account, do the following:

1. Go to ​Profile and sign in with your COSMOS username and password

2. Click on "Change My Profile" option in the left side menu

3. Click the "Choose File" button next to "Public key file"

4. Navigate to where your public key file is stored (typically /home/your_username/.ssh)

5. Select the .pub file corresponding to the key you wish to use for COSMOS access

6. Click "Open"

7. Click the "Update Profile" button

As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the COSMOS network. Please do NOT delete this key.

Configuring your SSH client

Under normal circumstances, as long as the private key file is located in the /home/your_username/.ssh/ folder, the command line SSH client will use the correct key when connecting.

To test your setup, open a command-line terminal and (replacing your_cosmos_username with your own COSMOS username) type:

ssh your_cosmos_username@gw.orbit-lab.org

You should be prompted to enter your key file passphrase and be able to successfully connect.

Type exit and press the Enter key to end the SSH session.

Common issues and how to solve them

• If you receive a message like the following:

  The authenticity of host 'gw.orbit-lab.org (128.6.192.134)' can't be established.
  ECDSA key fingerprint is SHA256:iLKtq2Z8wB3ADJdEyM1CwoU85gOeqIUyB4GOJ2YloQg.
  Are you sure you want to continue connecting (yes/no)?
  

  This is a normal message that occurs when your computer connects via SSH to another that it has never connected to before or if the "fingerprint" of the other machine changed (due to replacement or reconfiguration). Simply type yes and connection will proceed normally.

• If you receive a message like the following:

  Permission denied (publickey).
  

  Try connecting again but manually specifying the location where your private SSH key is stored as in the following example:

  ssh -i /path/to/your/private_key your_cosmos_username@gw.orbit-lab.org
  

Windows

Install OpenSSH client on your Computer

These instructions assume that you are using a currently supported version of Windows 10 and Windows 11. If you are using an older version of windows, please follow the instructions on this page: ​https://wiki.cosmos-lab.org/wiki/GettingStarted#no3.

1. Go to Settings—>Apps—>Optional Features] in Windows Settings.

2. If "OpenSSH Client" is listed under the Installed features, you are all set and can go to the next step.

3. If "OpenSSH Client" is not listed under the Installed features, click on the View features button right next to the Add an optional feature text.

4. In the Search bar on top of the Add an optional feature, type in "OpenSSH Client", and click on the checkbox next to it, and click next.

5. Review details of what will be installed and click Install.

6. Wait for it to be installed, you might need to restart your PC according to what it says in Settings.

Generating keys

1. Open Powershell in Windows as Admin.

The following steps ensure that your key is saved in the right location

2. Type in

   cd C:\Users
   

3. Type in

   ls
   

   to see what is your user name

4. Type in

   cd <your Username>
   

5. Type in

   cd .ssh
   

   (if this folder doesn't exist then create it)

6. type in

   ssh-keygen -t rsa
   

   You will be prompted for a location to save the keys, and a passphrase for the keys which we highly recommend using. This passphrase does not have to be the same as your ORBIT account password.

   Generating public/private rsa key pair.
   Enter file in which to save the key (...):
   Enter passphrase (empty for no passphrase):
   Enter same passphrase again:
   Your identification has been saved in ...
   Your public key has been saved in ...
   The key fingerprint is:
   SHA256:...
   The key's randomart image is:
   ...
   

Uploading your public key to your ORBIT account

To upload you public key to your orbit account, do the following:

1. Go to ​https://www.orbit-lab.org/cPanel/controlPanel/start and sign in with your ORBIT username and password

2. Click on "Change My Profile" option in the left side menu

3. Click the "Choose File" button next to "Public key file"

4. Navigate to where your public key file is stored (typically C:\Users\your_username\.ssh)

5. Select the .pub file corresponding to the key you wish to use for ORBIT access

6. Click "Open"

7. Click the "Update Profile" button

As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the ORBIT network. Please do NOT delete this key.

Configuring your SSH client

Under normal circumstances, as long as the private key file is located in the C:\Users\your_username\.ssh\ folder, the command line SSH client will use the correct key when connecting.

To test your setup, open Powershell and (replacing your_orbit_username with your own ORBIT username) type:

ssh your_orbit_username@gw.orbit-lab.org

You should be prompted to enter your key file passphrase and be able to successfully connect.

Type exit and press the Enter key to end the SSH session.

Common issues and how to solve them

• If you receive a message like the following:

  The authenticity of host 'gw.orbit-lab.org (128.6.192.134)' can't be established.
  ECDSA key fingerprint is SHA256:iLKtq2Z8wB3ADJdEyM1CwoU85gOeqIUyB4GOJ2YloQg.
  Are you sure you want to continue connecting (yes/no)?
  

  This is a normal message that occurs when your computer connects via SSH to another that it has never connected to before or if the "fingerprint" of the other machine changed (due to replacement or reconfiguration). Simply type yes and connection will proceed normally.

• If you receive a message like the following:

  Permission denied (publickey).
  

  Try connecting again but manually specifying the location where your private SSH key is stored as in the following example:

  ssh -i /path/to/your/private_key your_orbit_username@gw.orbit-lab.org
  

Mac

Mac OS has a native command line ssh client that can be used to remotely log into consoles. From the Finder select Applications → Utilities → Terminal to open a command line terminal.

Generating keys

Generate the public and private keys using the following command

ssh-keygen -t rsa

Follow the prompt to save the keys in the default location, use a passphrase for additional security. Once your keys are saved successfully, a 'randomart' will be generated.

your_username@Macintosh ~ % ssh-keygen -t rsa -C mac
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/your_username/.ssh/id_rsa): 
Created directory '/Users/your_username/.ssh'.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/your_username/.ssh/id_rsa.
Your public key has been saved in /Users/your_username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:... mac
The key's randomart image is:
...

Uploading your public key to you COSMOS account

To upload you public key to your cosmos account, do the following:

1. Go to ​Profile and sign in with your COSMOS username and password

2. Click on "Change My Profile" option in the left side menu

3. Click the "Choose File" button next to "Public key file"

4. Navigate to where your public key file is stored (typically /Users/your_username/.ssh). Note: because the .ssh folder begins with a period, it is hidden in the file browser by default. You can press "command"+"shift"+"." to show hidden files and folders in the file browser.

5. Select the .pub file corresponding to the key you wish to use for COSMOS access

6. Click "Open"

7. Click the "Update Profile" button

As a side note, expect to see a default auto generated public key in the list (ends with @internal1). This is used for SSH access between machines inside the COSMOS network. Please do NOT delete this key.

Configuring your SSH client

Under normal circumstances, as long as the private key file is located in the /Users/your_username/.ssh/ folder, the command line SSH client will use the correct key when connecting.

To test your setup, open a command-line terminal and (replacing your_orbit_username with your own ORBIT username) type:

ssh your_orbit_username@gw.orbit-lab.org

You should be prompted to enter your key file passphrase and be able to successfully connect.

Type exit and press the Enter key to end the SSH session.

Common issues and how to solve them

• If you receive a message like the following:

  The authenticity of host 'gw.orbit-lab.org (128.6.192.134)' can't be established.
  ECDSA key fingerprint is SHA256:iLKtq2Z8wB3ADJdEyM1CwoU85gOeqIUyB4GOJ2YloQg.
  Are you sure you want to continue connecting (yes/no)?
  

  This is a normal message that occurs when your computer connects via SSH to another that it has never connected to before or if the "fingerprint" of the other machine changed (due to replacement or reconfiguration). Simply type yes and connection will proceed normally.

• If you receive a message like the following:

  Permission denied (publickey).
  

  Try connecting again but manually specifying the location where your private SSH key is stored as in the following example:

  ssh -i /path/to/your/private_key your_cosmos_username@gw.orbit-lab.org
  

Choose a method for running graphical applications remotely

Because SSH is a text-based interface, we need additional tools to run graphical applications such as gnuradio companion or mininet on the machines in the testbed. There are several options available: X forwarding, chrome remote desktop, and vnc over an ssh tunnel (we will not discuss this option here, but anyone who is familiar with this method should feel free to use it).

X Forwarding

X11 is the default windowing system on linux systems. Graphical applications on linux are X11 clients which communicate with the X server software, which is what renders the clients onto the screen and handles requests from the clients for user input. The communication between client applications and an X server can be forwarded over an ssh session, which is how ​X forwarding displays remote applications— the application runs on the remote machine, but uses the ssh session to communicate with an X server on your local machine.

Linux

If you are using linux, you shouldn't need to install anything to use X forwarding, because you're already running an X server on your local machine. You simply have to run your ssh session using the -Y flag on the command line:

ssh -Y -t cosmos-user@sb.cosmos-lab.org

Keep in mind that you will have to use the flag for each ssh command you use, so if you ssh to a console and then from the console to the node, you will have to use the flag in both ssh commands in order to forward the applications all the way back to your local machine.

Windows

In addition to ssh client, remote X11 access on Windows requires installation of X11 Server. There are a number of open source or free servers available including:

1. ​VcXsrv
2. ​Xming
3. ​mobaXterm (includes ssh client)

As an illustration, we will use configuration based on Putty and VcXsrv and connect with remote graphics capability to the node1-1.sb1:

• Install Putty and make sure you can log into ORBIT gateway or console
• Install VcXsrv and make sure it is running say on display 1 (without any applications)
• Start Putty and load the appropriate session
• Configure X11 forwarding under "Connection→SSH→X11":
  • Check mark on "Enable X11 forwarding"
  • Set "X display location" to: 127.0.0.1:1 (note matching display number)
• Save the session
• Open the session to SB1 i.e. connect to the console.sb1.orbit-lab.org
• On the console execute

    ssX -Y -t root@node1-1
  

and connect to the node.

Mac

Mac users will need to install and run the ​XQuartz X server application. Then you will run your ssh commands with the -Y flag to enable X forwarding:

ssh -Y -t cosmos-user@sb.cosmos-lab.org

Chrome Remote Desktop

​Chrome Remote Desktop is a remote desktop software from Google which allows you to interact with a desktop session on a remote machine from your browser. Note that using this method will link the remote desktop sessions to your google account. You'll never need to provide information about your account to the node, but you'll only be able to connect to the node using remote desktop by using the client in your browser while you are signed in to your google account.

1. Go to this link ​https://remotedesktop.google.com/headless/ and click begin. You can skip downloading and installing remote desktop to your node— it will already be installed. Follow the steps until you reach the command to start the remote desktop session.
2. In your ssh session, type su sigcomm to switch to operating as the sigcomm user. Chrome remote desktop will not work if run by the root user.
3. Copy the command to start the remote desktop session and paste it into your ssh session. You will be prompted to enter a pin.
4. Go to ​https://remotedesktop.google.com/access/. You should see the machine you just set up. When you open a session to it, you will have to enter the pin you created in the previous step.