qKVMDocs
All pages

Scripts and wall screens

Settings > Tokens makes two things that use qKVM without a person signing in. Both are shown once, qKVM keeps only what it needs to know them again, and an admin can take either back at any moment. Neither can change settings, accounts, devices or other tokens: that takes a person.

A link for a wall screen. Open it once in the browser of that screen. The browser keeps it, shows the wall as a display, and when qKVM has been restarted it comes back in by itself: nobody has to stand at the screen with a keyboard after a power cut. It can look at the machines it was made for, and no more than look. (The pictures are back by themselves as well: qKVM carries on after a restart, see Keeping it running. Only where it was started with --locked-start are they back once somebody has signed in anywhere.)

A token for a script has a role (viewer: look; operator: look, and act on machines), the machines it is for, and a date it works until. The script sends it with every request:

curl -H "Authorization: Bearer qkvm_..." https://qkvm.example:8787/api/v1/status

What a script may ask for, and what each request answers, is in The API: a token with the role viewer may look (GET /api/v1/wall, /status, a picture), one with the role operator may also act (GET /api/v1/actions, POST /api/v1/devices/{id}/actions).

  • Every answer is JSON. A refusal is {"code": "...", "message": "..."} with a status that fits: 401 without a valid token, 403 for what its role does not allow, 404 for a machine it is not for, 409 busy while something else is being done to that machine, 502 when the device refused or did not answer.
  • After a restart qKVM carries on by itself, and a token works as before. Where it was started with --locked-start, a token is answered 503 locked until somebody has signed in, because qKVM cannot reach its devices before that: that is not the way to start it where scripts run unattended. (The same answer comes for as long as the key it carries on with cannot be read, or does not fit yet: GET /healthz says "locked": true then.)
  • A token cannot ask for a way into a server's console, cannot type a saved text (it could read it back off the screen), and has nothing to sign out of.
  • What a token did is in the activity log under its name.