Skip to main content
Version: Next

Relay and Agent

Two small services carry a server's serial console, and its VNC display once you have moved VNC to the relay:

  • The relay runs on the control server, behind its web server. Browsers reach it on the same address and port as the user interface.
  • The agent runs on each hypervisor. Only the control server's relay connects to it.

A browser never reaches a hypervisor. It talks to the control server, the relay there talks to the agent on the right hypervisor, and the agent connects to the server on the hypervisor itself.

Installing the relay​

The agent is installed and kept up to date by the normal hypervisor update. There is nothing to do on a hypervisor.

The relay needs one update of the control server run as root, because an update started from the user interface does not have the rights to install a service:

vfcli-ctrl update --mgmt-only

Until that has been done, the admin dashboard shows a notice saying the relay is not installed. After it, the relay keeps itself up to date: when an update brings a newer relay, the running one takes it over within about half a minute, and sessions that are open carry on.

Ports​

WherePortWho connects
Control server443Browsers, as for the user interface
Hypervisor8893The control server only

Consoles and VNC use the same address and port as the user interface. No other port needs opening on the control server.

The Agent card​

Each hypervisor's page has an Agent section:

  • Status shows whether the agent answers, and its version. Check asks it again.
  • Certificate shows the fingerprint of the agent's certificate. A changed certificate is picked up by itself. If the agent is refused after a hypervisor has been reinstalled, press Re-record.

Sessions​

A session is opened for one server and one user. It is closed when that user's access is removed, or after 30 minutes without activity.

Status, logs and restarting​

On the control server:

systemctl status vf-relay
journalctl -u vf-relay -f

On a hypervisor:

systemctl status vf-agent
journalctl -u vf-agent -f

Each session writes a line when it opens and when it ends. On a hypervisor the line names the server, who opened it, and what the agent connected to.

Neither service normally needs restarting. systemctl restart closes every open session, and so does restarting the control server's web server (vf-nginx). An update does not.

Debug report​

When something does not work on one hypervisor, this prints what its agent reports about itself, beside what the control server knows, as JSON:

vfcli-ctrl agent:debug 24

24 is the hypervisor's ID. The report has two parts:

  • control: the address the agent is reached at, whether the agent and the relay answer, and how far apart the two clocks are. A hypervisor whose clock is wrong by more than a couple of minutes cannot open sessions.
  • agent: the agent's version, the hypervisor's system, which control server addresses it accepts, and each running server with its console and its VNC display.

To look at one server only, give its ID or UUID:

vfcli-ctrl agent:debug 24 --server=1008

The report holds no password and no token, so it can be attached to a support ticket.