Wireless Advanced Usage

Finite State Machine

The TWIST Wifi Aggregate Manager (TWIST-AM) implements a simple Finite State Machine, which is essentially determined by the implemented Federation AM API. Below graph illustrates the specific implementation of TWIST-AM.

digraph {
  graph [K="1.5" nodesep="1.0"]
  unallocated_pending[label="geni_unallocated"]
  allocated_pending[label="geni_allocated"]
  allocated_failed[label="geni_allocated\ngeni_failed"]
  provisioned_pending[label="geni_provisioned\ngeni_pending_allocation",shape=box]
  provisioned_notready[label="geni_provisioned\ngeni_notready"]
  provisioned_configuring[label="geni_provisioned\ngeni_configuring",shape=box]
  provisioned_ready[label="geni_provisioned\ngeni_ready"]
  provisioned_stopping[label="geni_provisioned\ngeni_stopping",shape=box]
  provisioned_failed[label="geni_provisioned\ngeni_failed"]

  unallocated_pending -> allocated_pending[label="allocate"]
  allocated_pending -> unallocated_pending[label="delete"]
  allocated_pending -> provisioned_pending[label="provision"]
  provisioned_pending -> provisioned_notready[style=dashed,color=darkgreen]
  provisioned_pending -> allocated_failed[style=dashed,color=red]
  provisioned_notready -> provisioned_configuring[label="geni_start"]
  provisioned_notready -> unallocated_pending[label="delete"]
  // provisioned_notready -> provisioned_pending[label="provision"]
  provisioned_configuring -> provisioned_ready[style=dashed,color=darkgreen]
  provisioned_configuring -> provisioned_failed[style=dashed,color=red]
  provisioned_ready -> provisioned_stopping[label="geni_stop"]
  provisioned_ready -> provisioned_configuring[label="geni_restart"]
  provisioned_ready -> unallocated_pending[label="delete"]
  // provisioned_ready -> provisioned_pending[label="provision"]
  provisioned_stopping -> provisioned_notready[style=dashed,color=darkgreen]
  provisioned_stopping -> provisioned_failed[style=dashed,color=red]
  allocated_failed -> unallocated_pending[label="delete"]
  allocated_failed -> provisioned_pending[label="provision"]
  provisioned_failed -> unallocated_pending[label="delete"]
  provisioned_failed -> provisioned_pending[label="provision"]
  allocated_pending -> allocated_pending[label="renew"]
  // provisioned_ready -> provisioned_ready[label="renew"]
  // provisioned_notready -> provisioned_notready[label="renew"]
}

The figure describes the lifetime of a sliver, which is the atomic element of a reservation. Every sliver has an Allocation State, which can be any of geni_unallocated, geni_allocated or geni_provisioned. This state is indicated in the upper string of each node in the previous figure. A geni_provisioned sliver also has an Operational State, e.g. geni_ready, which is specified by the lower string in each node.

The transition labels represent API calls that can be issued by the owner of the sliver, while the node is in the corresponding state. renew allows to change the expiration time of a reservation. All other calls trigger a state transition. Transitions can be immediate (e.g. allocate) or start a long running process (e.g. provision), where the sliver traverses an intermediate state. In that case the user shall poll for the sliver to arrive at the correct state or geni_failed.

For a detailed description refer to the official documentation of Allocation States, Operational States and API calls.

Omni cli

Install omni as part of geni-tools

Follow the official instructions to install omni.

Configure omni for use with TWIST-AM

Download the configuration template here and copy it to ~/.gcf/omni_config. Replace the placeholders to configure omni for your iMinds account.

Test your configuration:

omni -a twist getversion

Run the experiment

We assume you have a valid rspec file describing your experiment setup. You can use jFed-experimenter to configure the experiment and export the corresponding rspec file. Say the filename is experiment.rspec.

omni -a twist createslice name_of_slice
#optionally extend expiration time
omni -a twist renewslice name_of_slice YYYY-MM-DDTHH:MM:SS
omni -a twist allocate name_of_slice experiment.rspec
omni -a twist provision name_of_slice experiment.rspec

This last call starts a long-running process. You can repeatedly poll the status of the reservation:

omni -a twist status name_of_slice

Wait until all nodes have transitioned from operational_status:geni_pending_allocation to operational_status:geni_notready. During the process a node might fail, indicated by operational_status:geni_failed. You can drop that node from your reservation now in order to continue with the others. Check the output of status and identify the sliver which has failed. Copy the geni_sliver_urn and delete it from the slice:

omni-docker -a twist_test delete testslice -u urn:publicid:IDN+twist.tu-berlin.de+sliver+62fba692-9945-43bd-8d98-892b87a4136e

Poll the status until the node has disappeared from the slice.

When all nodes of the slice are geni_notready, you can start them:

omni -a twist poa name_of_slice geni_start

Use the status call to poll for operational_status:geni_ready. If a node fails repeat the procedure described above to delete it from the slice.

When all nodes are ready, you can get more details using

omni -a twist describe name_of_slice

This will provide positions, mac addresses and login information.