Updating experimental hardware

Updating experimental hardware often requires updating the firmware on the host computer.

When first creating an experiment, the host computer (e.g. a raspberry pi) is usually physically accessible, so you can connect a keyboard, and monitor, to it and do the updates directly. Or you might have it plugged into a local network so you can ssh into it (which is much more convenient).

To carry on with ssh connections when the experiment is deployed, it's usually most convenient to make sure you have a cmd/shell relay setup. Your system administrator should have done this. That way, you can connect to your experiment via ssh even if it is behind a firewall (your connection is securely relayed).

to connect to an experiment, or more likely, a set of experiments you are working on, you will need to let your system administrator know which experiments you want to work on.

They will create a file like this spin38-41.list:

spin38
spin39
spin40
spin41

Then they will run ./shelltoken.sh spin38-41.list > spin38-41.tokens to produce some content like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b3BpYyI6InNwaW4zOCIsInByZWZpeCI6InNoZWxsIiwic2NvcGVzIjpbImNsaWVudCJdLCJhdWQiOiJodHRwczovL3NoZWxsLWFjY2Vzcy5leGFtcGxlLnByYWN0YWJsZS5pbyIsImV4cCI6MTY1Njc2NzIwOSwiaWF0IjoxNjUzMzExMjA5LCJuYmYiOjE2NTMzMTEyMDl9.h4Ns4SldcAoeBttRcl5PxIpnw-BhyCg8jz0-D6g2XLY
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b3BpYyI6InNwaW4zOSIsInByZWZpeCI6InNoZWxsIiwic2NvcGVzIjpbImNsaWVudCJdLCJhdWQiOiJodHRwczovL3NoZWxsLWFjY2Vzcy5leGFtcGxlLnByYWN0YWJsZS5pbyIsImV4cCI6MTY1Njc2NzIwOSwiaWF0IjoxNjUzMzExMjA5LCJuYmYiOjE2NTMzMTEyMDl9.rHKDQeUN-0__jqo6x2emhjvjuR4-JKJa5ec_rkCoIrM
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b3BpYyI6InNwaW40MCIsInByZWZpeCI6InNoZWxsIiwic2NvcGVzIjpbImNsaWVudCJdLCJhdWQiOiJodHRwczovL3NoZWxsLWFjY2Vzcy5leGFtcGxlLnByYWN0YWJsZS5pbyIsImV4cCI6MTY1Njc2NzIwOSwiaWF0IjoxNjUzMzExMjA5LCJuYmYiOjE2NTMzMTEyMDl9.CnBJjy7hbjatsDVRKFW1BYZe5oHN4ksTGlGE6NsPLpc
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b3BpYyI6InNwaW40MSIsInByZWZpeCI6InNoZWxsIiwic2NvcGVzIjpbImNsaWVudCJdLCJhdWQiOiJodHRwczovL3NoZWxsLWFjY2Vzcy5leGFtcGxlLnByYWN0YWJsZS5pbyIsImV4cCI6MTY1Njc2NzIwOSwiaWF0IjoxNjUzMzExMjA5LCJuYmYiOjE2NTMzMTEyMDl9.VryXENS77PJSRsDJxcMq0q-PVS1O1fdKdssv-aE4SD0

Your system administrator will supply you with a list of JWT tokens in a file. The tokens above are just examples and do not connect to real experiments, so can be shown here - but your token file must be carefully stored, because it provides access to the experiments to anyone who obtains it.

The tokens are not readable in their current form, but can be inspected with code (do not paste into jwt.io or other website introspection tools - introspect locally only!), e.g.

{
  "topic": "spin38",
  "prefix": "shell",
  "scopes": [
    "client"
  ],
  "aud": "https://shell-access.example.practable.io",
  "exp": 1656767209,
  "iat": 1653311209,
  "nbf": 1653311209
}

To connect to your experiments, install shellrelay executable, put it on your path, and run the supplied script e.g.

$ ./shellconnect.sh spin38-41.tokens
49156 https://shell-access.practable.io/shell/spin38
49157 https://shell-access.practable.io/shell/spin39
49163 https://shell-access.practable.io/shell/spin40
49164 https://shell-access.practable.io/shell/spin41

Ports are assigned to free ports in the private range, so if you are running multiple versions of this on different token files, you can always get free ports, so check the port numbers each time you start the script to make sure you are connecting to the correct ones - they are not fixed like with the previous client (risk of clashing if you had multiple token sets and wanted to run the script with several different token scripts)

To connect, you then issue an ssh command to localhost, at the port listed above, e.g.

$ ssh your-user@localhost -p 49156

You may also need to be supplied with certificates for ssh authentication - this is site-dependent.

If your connections hang at any point, just issue pkill shellrelay and re-run the connection script. At present the connection cannot handle piping long files so tends to quit during ansible jobs. Aim to get as much of the automated work done before deploying the experiments! For now, deployed experiments can be manually administered via this procedure.