Console: a terminal through the agent

Backend → Console opens a real terminal on a monitored Linux machine, in your browser. It is meant for the moment after a ticket told you which service is wedged, when restarting it should not mean finding a laptop with the right SSH key on it.

How it works

Nothing is dialled and nothing listens. The agent already on the machine asks your install, over its normal outbound connection, whether anyone has typed. It asks the same way it checks for updates. Output goes back the same way. Both directions are held open by long polling. On the machine, the agent runs a real pseudo-terminal, so full-screen programs work: mc draws its blue window, arrow keys move, and colours are colours. In the browser, the terminal is xterm.js, served by your install like the other client libraries.

The shell runs as root. Treat access to the console as root access to the machine.

Who may open one

Every one of these must allow it:

• A signed-in person. No API key of any kind can open a session, and the console is deliberately not listed in the API catalogue.
• The account's Console capability, labelled "Console — a root shell". It is off by default for members, and always off for viewers. See Capabilities.
• The install-wide switch for terminals.
• The machine's switch, Allow a terminal on the host, on its settings page.
• How the machine was installed. Since agent 0.95.1 the agent refuses every session unless it was installed with --allow-terminal (tick Also allow a root terminal before copying the install command) or allowed later on the machine with sudo obscenter-agent allow-terminal. Machines installed before 0.95.1 keep accepting sessions, also after updating or re-running the installer; sudo obscenter-agent deny-terminal stops that. The console shows a machine that refuses, and why, before you click.
• The machine itself. An agent started with OBSCENTER_NO_TERMINAL=1 refuses every shell, whatever the dashboard or the install said.

A person with limited access sees only the machines they were given.

Using it

The page lists your Machines, each with an Open button. A session that is still running offers Back to it and End it. A machine can have three sessions at once. A session closes after 20 minutes with nothing typed. Output alone does not keep it open.

Quick commands are shared buttons above the terminal. The defaults are:

• failed units;
• the agent's journal;
• disk use;
• top by memory;
• who is listening;
• restart a service;
• service status;
• the file manager (mc).

A command can be for every machine or for one. A command that ends in a space is typed onto the prompt and left for you to finish, which is handy for "restart a service".

The audit

Who has been on these machines records every session: the machine, who opened it, when, how long it lasted, and why it ended. It is a record, not a transcript. Keystrokes and output are never stored.

Containers and Windows

An agent inside a container cannot open a shell. The console suggests the machine under it instead, if that machine has a host agent. The Windows agent has no console.