Serial Console¶
Every virtual machine and unikernel node has a serial console. sherpa console <node> opens it
in your terminal. Containers have no serial console; use sherpa ssh.
How it Works¶
libvirt binds each node's serial console to a UNIX socket on the Sherpa server:
/opt/sherpa/run/console/<lab-id>/<node-index>.serial
A virtual machine's VNC console is a socket in the same folder, <node-index>.vnc; see
VNC.
Each lab's folder under /opt/sherpa/run/console/ is owned sherpa:kvm with mode 2770. Only
sherpa, members of kvm and root can reach the sockets. Members of kvm can already read
every lab's disks. sherpad creates the folder at sherpa up and removes it at sherpa destroy.
Connecting¶
sherpa console opens a WebSocket to sherpad:
GET /api/v1/labs/{lab_id}/nodes/{node_name}/console
It sends your login token as Authorization: Bearer <token> and uses the same TLS settings and
trusted certificate as every other command. sherpad connects to the node's socket and relays
the bytes in both directions. The bytes are raw serial data in binary frames. See the API Reference.
It needs no SSH key or account on the server. It works the same on Windows.
Who Can Connect¶
Only the lab's owner can open a node's console. Admins are refused too. The route takes only a bearer token, not the web UI's session cookie.
One Session¶
A console serves one session at a time. A second sherpa console to a console that is in use is
refused at once, and the message names the user, the client address and the time the session
began.
sherpa console <node> --force takes the console over from a session of your own, for example
one left open on another machine. The session taken over ends with a line saying who took it. A
session of another user is never taken over, though only the owner can open one.
How a Session Ends¶
| Cause | Close code |
|---|---|
You escape with Ctrl+], or ~. at the start of a line |
none; the client closes |
| The node stopped | 1000 |
Another session took it over with --force |
4001 |
| The login behind the token ended: logout, password change, user deleted. Checked every 30 seconds | 4002 |
| The relay to the socket failed | 1011 |
Guest Sessions¶
Disconnecting does not log the node's session out, because the serial port does not tell the node. Log out before you disconnect. Since only the owner can attach, a session left logged in is reachable only by the owner.
Logging¶
sherpad logs each session as the events console.opened, console.refused and
console.closed, with the user, lab, node, client address, duration and reason. It never logs the
bytes.