Batch reservations

A batch reservation runs an experiment without you. The Grid waits until the reservation’s nodes are free, starts the nodes, runs an RF scenario, a traffic scenario, or both, and stops the reservation when the scenarios end. The Grid does not give you a login on a batch reservation’s nodes unless its template lists you in usernames, so your image must start its radio by itself, and you read the results from the reservation’s logs afterward. See RF and traffic scenarios for how to write and name scenarios.

Writing a reservation template

You describe a batch reservation in a reservation template, a JSON file that gridcli fills out with Jinja before sending it to the Grid. The following template runs the traffic scenario USERNAME/single1MB for 75 seconds on grid01 and grid02:

{
    "name": {{ name }},
    "batch": {{ batch }},
    "traffic_scenario": "USERNAME/single1MB",
    "duration": "00:01:15",
    "scheduled_start_time": {{ scheduled_start_time }},
    "scheduled_duration": {{ scheduled_duration }},
    "add_dragonradio_routes": true,
    "nodes": [
        {
            "node": "grid01",
            "image": {{ image }},
            "traffic": true,
            "flash": {{ flash }},
            "disable_dragonradio_service": false
        },
        {
            "node": "grid02",
            "image": {{ image }},
            "traffic": true,
            "flash": {{ flash }},
            "disable_dragonradio_service": false
        }
    ]
}

The reservation’s fields are:

  • batch must be true.
  • rf_scenario and traffic_scenario name the scenarios to run. A batch reservation must have at least one.
  • duration is how long the scenarios run, e.g., "00:01:15" for 75 seconds. Without it, they run as long as the longer scenario is when the batch starts.
  • scheduled_duration is required, and may not be greater than 4 hours. The Grid replaces it with the time that the scenarios need once they start.
  • scheduled_start_time optionally gives a time before which the reservation will not start, e.g., "2026-10-12T14:30:00-04:00".
  • add_dragonradio_routes routes the traffic over the radios, as the --routes option to gridcli tg start does.
  • name names the reservation.
  • usernames lists users who may log in to the nodes.
  • nodes lists the nodes and how to start each one.

Each node’s fields are:

  • node is the node’s name. It is required.
  • image is the image to run.
  • traffic must be true on every node if the reservation runs a traffic scenario.
  • disable_dragonradio_service must be false for an image whose radio runs as the dragonradio service, so that the radio starts by itself. It is true by default.
  • flash and uhd_version choose the X310’s firmware, as the --no-flash and --uhd options do.
  • frequency and bandwidth set the radio’s center frequency and bandwidth in Hz.
  • radio_conf gives the contents of the radio’s radio.conf.
  • node_id sets the node’s radio node ID, which is the number in the node’s name by default.
  • rf_node and traffic_node choose the node’s scenario node. By default, the nodes, sorted by name, become scenario nodes 1, 2, and so on.

Template variables

The template can use variables that gridcli sets from its command-line options. Each variable’s value is JSON, so write {{ image }}, not "{{ image }}". These variables are always set:

  • image, from --image.
  • name, from --name, or null.
  • batch, which is true unless you give --no-batch.
  • scheduled_start_time, from --start, or null, which starts the reservation as soon as its nodes are free.
  • scheduled_duration, from --duration, which is 4 hours by default.
  • owner, from --owner, or null. Only staff may set a reservation’s owner.
  • flash, which is false with --no-flash.
  • privileged, bridge, and traffic, from --privileged, --no-bridge, and --traffic.
  • disable_dragonradio_service, which is false unless you give --no-batch or --no-dragonradio-service.

These variables are set only if you give their options, so a template that uses one fails without it:

  • uhd_version, from --uhd. Without it, the X310 is flashed with UHD 3.9.7.
  • frequency and bandwidth, from --frequency and --bandwidth.
  • radio_conf, the contents of the file given to --radio-conf.
  • usernames, from --user and --csv.

Submitting a batch reservation

Submit a template with gridcli reservation submit --image IMAGE FILE, where FILE is the template. Add the -n option before reservation to print the reservation that the template produces without submitting it. Only the template becomes the reservation, so an option such as --start has an effect only if the template uses its variable. For example, the template above starts at the time given by --start but always runs its scenario for 75 seconds.

A batch reservation is “Pending” until all of its nodes are free and its scheduled_start_time, if any, has passed. The Grid then starts the nodes, starts the scenarios about a minute later, and stops the reservation 30 seconds after the scenarios end. You can follow it at the Reservations link, and stop it early with gridcli reservation stop ID.