Accessing the Grid

If you are a Drexel user, use your Drexel username and password to log on to the grid. An account will automatically be created for you the first time you log in, but an administrator must enable your account before you can use it.

Required Software

To fully utilize the grid, you will need an SSH client and an X Windows client. If you are using Linux, you already have everything you need. For other platforms, we recommend the following software:

  • Mac
    • XQuartz for X Windows support.
    • The built-in ssh command-line client.
  • Windows
    • MobaXterm for SSH and X Windows support. Choose the Home Edition and make sure you download the “Installer Edition.”
    • VcXsrv is a possible alternative, but we do not have experience using it ourselves.
    • PuTTY is not recommended.

Adding an SSH key

Access to the grid itself is done using SSH keys—you will only use a password to log in to the web interface. You may add and remove SSH keys in the SSH key profile pane. If you have never used SSH keys, see GitHub’s documentation for help. Be sure to add your public key to your account; if you try to add your private key, you will receive an error.

Logging in with SSH

Linux/macOS

On a UNIX-based machine, connect to the grid at the terminal by executing the following command. Be sure to replace USERNAME with your Grid username and PRIVKEYFILE with the path to your private key. If you are a Drexel student, your Grid username is the same as your Drexel username.

  1. Run ssh -i PRIVKEYFILE USERNAME@dwslgrid.ece.drexel.edu in your terminal.

If you need X11 forwarding, add the -X option to the command line above.

Windows (MobaXterm)

  1. Install MobaXterm.
  2. Open MobaXterm and click “Start Local Terminal.”
  3. Follow step 1 in the Linux/Mac OS section above.

Using gridcli

Once you have connected to the Grid, the gridcli command-line client will allow you to launch, stop, and snapshot containers. You can type gridcli -h to see a description of th available options. The first time you use gridcli, it will ask you for your username and password. Subsequent invocations will not require authentication.

Working with images

You can see a list of available images with the command gridcli images. You may also use any image from the following sources:

  1. The images: default remote. See here for a list.
  2. The ubuntu: default remote. See here for a list.
  3. The ubuntu-daily: default remote. See here for a list.

For example, you may specify ubuntu:20.04 to launch a bare Ubuntu 20.04 container. Image from these remote sources will not be listed by gridcli images.

Adding your own image

To use your own image, copy it to the images directory in your home directory. The image must be readable by all users. You can accomplish this by running chmod 0444 IMAGE at the terminal, where IMAGE is your image file. Although counter-intuitive, this will not allow other users to see or use your image. You can manage your images via the images tab. Marking an image “public” will make it available to every Grid user.

Showing available nodes

Node status is shown on the home page. You can also see a list of nodes and their statuses with the gridcli nodes command.

Launching an instance

An instance consists of an image running on a node. To launch one or more instances, you will need to specify an image to launch and one or more nodes on which to launch the image using the command gridcli node launch IMAGE NODE [NODE …].

Specifying UHD firmware

When launching an image on a node with an X310, the UHD firmware version can be specified with the –uhd option to gridcli node launch. Currently 3.9.5, 3.9.7, 3.15.LTS, and 4.0.0.0 are supported. By default, X310’s are re-flashed with UHD 3.9.5 firmware on launch. N210’s cannot be automatically flashed; all N210 nodes run UHD 3.9.5.

Showing running instances

You can see your currently running instances by running gridcli instances at the terminal. Each running node will be displayed along with the image it is running and when the instance was started.

Accessing an instance

Log on to an instance the same way you log on to dwslgrid.ece.drexel.edu: with your Grid username and one of the SSH keys you added to the Grid. You can only connect to an instance from dwslgrid.ece.drexel.edu; instances are not connected to the Drexel network. You will either need to copy your SSH key to dwslgrid.ece.drexel.edu or use SSH forwarding.

Proxying SSH connections through dwslgrid

See the OpenSSH Cookbook entry on proxies and jump hosts for details on how to automatically proxy SSH connections to instances through dwslgrid.ece.drexel.edu. If you are connecting to the Grid from a Linux or Mac, adding a section to your .ssh/config along the lines given below will allow you to connect easily to both dwslgrid and individual grid nodes. Be sure to replace USERNAME with your username and PRIVKEYFILE with the name of your private key.

Host dwslgrid dwslgrid.ece.drexel.edu
  HostName dwslgrid.ece.drexel.edu
  User USERNAME
  IdentityFile ~/.ssh/PRIVKEYFILE
  ForwardX11 yes
  ServerAliveInterval 60
  ServerAliveCountMax 2

Host grid??
  HostName %h
  User USERNAME
  IdentityFile ~/.ssh/PRIVKEYFILE
  ForwardX11 yes
  ProxyJump dwslgrid

Stopping an instance

Stop an instance by running gridcli node stop NODE, where NODE is the node running the instance.

Snapshotting an instance

You can snapshot a running instance by typing gridcli node snapshot NODE SNAPSHOTNAME, where NODE is the node running the instance and SNAPSHOTNAME is the name of the snapshot you want to create. The snapshot will be written to the images directory in your home directory and wil be named SNAPSHOTNAME.tar.gz.

If you receive the error The grid user does not have permission to write to /home/USER/images., where USER is your username, check that the permissions on your home directory allow the grid user to write to your images directory. Your home directory must have a+x permissions, which you can provide with the command chmod a+x ~. There must also be a directory images in your home directory that is owned by you, owned by the grid group, and has permissions 0770. If the images directory does not exist or has the wrong group, you will need to contact support to have it created.

REST API

The Grid provides a REST API (gridcli works exclusively via the REST API). Both Swagger documentation and ReDoc documentation is available. You can play with the api directly using the API endpoint. An OpenAPI schema is also available.

You can obtain an API token that will allow you to authenticate to the API without using a username and password via the API profile pane.

Contact

If you need additional help, please contact support@dwslgrid.net.