Skip to content

VNC

VNC (Virtual Network Computing) shows a virtual machine node's screen and takes its keyboard and mouse. Use it for devices that need a graphical console, or when SSH is not up yet, for example during the first boot or a password recovery. sherpa vnc <node> connects your own VNC viewer to it, from any machine with the CLI.

How it Works

Every virtual machine node has a VNC graphics adapter. QEMU listens for VNC on a UNIX socket on the Sherpa server, next to the node's serial console:

/opt/sherpa/run/console/<lab-id>/<node-index>.vnc

The socket is in the lab's console folder, owned sherpa:kvm with mode 2770. Only sherpa, members of kvm and root can reach it. Members of kvm can already read every lab's disks.

Connecting

Run sherpa vnc in the lab's folder:

sherpa vnc <node> [--force]

It first asks the server whether you can open the node's VNC console, and stops with the reason if not (see Who Can Connect). Then it opens a port on 127.0.0.1 on your machine, picked by the system, and prints the address:

VNC console of ubu01 in lab my-lab: connect a VNC viewer to 127.0.0.1:40123. Ctrl+C to stop.

Point any VNC viewer at that address. Each connection your viewer makes is relayed over a WebSocket to sherpad, which connects to the node's socket:

GET /api/v1/labs/{lab_id}/nodes/{node_name}/vnc

sherpa vnc sends your login token and uses the same TLS settings and trusted certificate as every other command. See the API Reference. It needs no SSH key or account on the server, and works the same on Windows.

sherpa vnc keeps listening until you press Ctrl+C, so your viewer can disconnect and connect again. Viewers that read a small number after a colon as a display number take a port this high as a port; TigerVNC's vncviewer also takes 127.0.0.1::40123, with two colons, as always meaning a port.

Note

The port is on your machine's loopback address, but other accounts on your machine can connect to it while sherpa vnc runs. The node's VNC server asks for no password.

Who Can Connect

Only the lab's owner can open a node's VNC console. Admins are refused too. sherpa vnc asks the server before it opens a port, so a refusal ends it at once, with the server's reason and exit code 1, and no address is printed:

  • Access denied: only the owner of lab '<lab-id>' can open its consoles
  • the node or lab not found, or Not logged in
  • a container or a unikernel, which have no VNC console
  • Node '<node>' is not running. Start it with 'sherpa resume'.

A VNC console in use by another session of yours is not a refusal: sherpa vnc prints its address, then The VNC console of <node> is in use by <user> from <client-ip> since <time> UTC: viewers are refused until that session ends, or take it over with 'sherpa vnc <node> --force'., and keeps listening. With --force it says ...: a viewer connecting takes it over. instead.

Once it is listening, the server checks again each time your viewer connects. If the console is in use or the node has stopped by then, sherpa vnc prints the reason and keeps listening, so you can connect again; any other refusal ends it.

One Session

A VNC console serves one session at a time, as the serial console does, so one viewer at a time sees and drives the screen. A node's VNC and serial consoles are separate: you can have both open. While your viewer is connected, a second connection is refused at once with The VNC console of <node> is in use by <user> from <client-ip> since <time> UTC. Close that session, or take it over with 'sherpa vnc <node> --force'.

With sherpa vnc <node> --force, each connection takes the VNC console over from a session of your own, for example one left open on another machine. A session of another user is never taken over.

How a Session Ends

A viewer's connection ends when the viewer disconnects, when you press Ctrl+C, when the node's VNC server closes it (The node's VNC console closed the connection., for example when the node stops), when another session of yours takes it over with --force, and when your login ends. The server checks the login every 30 seconds. sherpa vnc prints a line for each connection that ends, with the server's reason.

sherpad logs each session as the events console.opened, console.refused and console.closed with console = "vnc", with the user, lab, node, client address, duration and reason. It never logs the screen or the keys.

Applicability

Node Kind VNC Available
Virtual Machine Yes
Container No
Unikernel No