Using gridcli to control reservations

Once you have connected to the Grid, the gridcli command-line client will allow you to launch and stop reservation and snapshot nodes. You can type gridcli -h to see a description of available options, and the gridcli reference lists every command. The first time you use gridcli, it will ask you for your username and password. You should provide the same username and password that you use to access the Grid web interface. gridcli saves the API token it obtains, so subsequent invocations will not require authentication. You can also give gridcli an API token instead of a password, as the REST API topic describes. Some gridcli operations, like stopping a reservation, can also be performed using the web interface.

Listing available nodes

When you launch a Grid reservation, you will need to specify which nodes to use. You may only specify nodes that are not already in use. Node status is shown on the Grid home page. You can also see a list of nodes and their statuses with the gridcli nodes command.

Listing reservations

A list of your reservations is available at the Reservations link. The command gridcli reservations will also list reservations, displaying each reservation’s name and unique identifier (in parentheses). You can use either the unique identifier or the name to manage the reservation using gridcli.

Launching a reservation

To launch a reservation, you must specify an image to run and a set of one or more nodes on which to run it. You can do this using the command gridcli reservation schedule IMAGE NODE [NODE …], where IMAGE, e.g., dragonradio-class, is an image name and each NODE is a node name, e.g., grid01. You can see a list of available images by clicking the Images link on the Grid web page after logging in. If you do not know which image you want to use, try the dragonradio-class image, which has GNU Radio 3.8 and Dragon Radio both pre-installed in an Ubuntu 22.04 image. The --name option gives the reservation a name. The gridcli command to launch a reservation will return immediately, but the reservation may take several minutes to start, especially if it must flash firmware. Once you have launched a reservation, you can see its status in the web interface at the Reservations link. When the status of the reservation changes to “Running,” you may connect to any of the nodes that are part of the reservation using SSH.

Specifying reservation start time and duration

By default, gridcli schedules a reservation that starts immediately and lasts for 4 hours. You may schedule an explicit start time using the --start flag when scheduling a reservation via gridcli. The argument to --start is a human-readable time specification, e.g., “10:30” or “1:30 pm”, and must be at least 5 minutes in the future. The duration of the reservation can be specified using the --duration flag, whose argument is also human-readable, e.g., “1 hour” or “30 minutes”. A reservation’s initial duration may not be greater than 4 hours, although it may be extended.

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 reservation schedule. Currently 3.9.5, 3.9.7, 3.15.LTS, 4.0.0.0, and 4.2.0.0 are supported. By default, X310s are re-flashed with UHD 3.9.7 firmware on launch. The --no-flash option skips flashing and leaves the firmware that the X310 already has. N210s cannot be automatically flashed. All N210 nodes run UHD 3.9.5 firmware.

Extending a reservation

If a reservation has less than an hour left, it may be extended an additional hour by clicking the icon in the web interface. You may also use the command gridcli reservation extend ID, where ID is the reservation’s unique identifier or name, to extend the reservation by an hour, or gridcli reservation extend --duration DURATION ID to extend it by a shorter DURATION. You can see the unique identifier for your reservations at the Reservations link on the web interface (the identifier is in parentheses) or by running the command gridcli reservations.

Stopping a reservation

A reservation can be stopped before its scheduled end time by clicking the icon in the web interface’s list of reservations or by executing the command gridcli reservation stop ID, where ID is the reservation’s unique identifier or name.

Reservation logs

When a reservation stops, the Grid copies each node’s /logs directory into the reservations directory in your home directory, so have your experiment write its results to /logs. Each reservation has a directory RESERVATION-ID, where ID is the reservation’s unique identifier, and each node has a directory in it named USERNAME-IMAGE-srnN-RESID, where IMAGE is the image’s name and N is the number in the node’s name. The reservation’s Inputs directory holds its configuration.