Skip to main content

Terminal

Root shell in the browser.

Terminal opens a root shell (/bin/bash -l) right in the browser. Commands take effect immediately without asking – the terminal is meant for maintenance and troubleshooting, everything common is done through the interface.

Usage​

  • Several terminals: New terminal opens up to four shells as tabs on the page. Each shell runs while the page is open; leaving the page ends it.
  • Size: The terminal adapts to the window; programs like htop or nano get the new size at once. Full screen uses the whole screen, A−/A+ change the font size (remembered in the browser).
  • Copy and paste: select and press Ctrl+Shift+C, paste with Ctrl+Shift+V (Ctrl+C stays interrupt in the shell).
  • Mobile devices: A bar with Esc, Tab, Ctrl+C, Ctrl+D and arrow keys complements the on-screen keyboard.
  • End: exit or Ctrl+D ends the shell; Reconnect opens a new one.

Open sessions​

The table Open sessions lists every terminal and console session of all admins (user, address, target, opened, last input). End session closes a session and terminates every program running in it – also a forgotten shell in another browser. At most 8 root shells can be open at the same time (consoles of the virtualization do not count), and 16 WebSocket connections per admin in total.

Security​

  • Only logged-in admins with a completed second factor (Security); the browser has to come from the same address (Origin check). The session is checked again every 30 seconds: logging out, expiry or losing admin rights closes the shell. Only input keeps the login active; an open, unused terminal ends with the session's idle timeout.
  • Opening and closing every shell is recorded in the audit log (terminal.open, terminal.close, with user, address and session id), and so is End session (terminal.session.close). The input itself is not logged.
  • Over HTTP the input travels unencrypted; switch on HTTPS for access from outside your own LAN.

Technology​

The browser connects through a WebSocket to /api/ws/terminal?cols=…&rows=… (gateway in server/preload.cjs). Output arrives as binary frames, input and size changes as JSON ({ "type": "input", "data": … }, { "type": "resize", "cols": …, "rows": … }). The pseudo terminal is created without native Node modules by script -qfec from util-linux; size changes are set with stty -F /dev/pts/N, and the kernel then sends SIGWINCH to the program. On a slow connection the output pauses above 4 MiB of buffer until the browser has caught up. On close the shell gets SIGHUP, after 3 seconds SIGKILL. The same component serves as the console of containers and VMs under Virtualization.

Mock mode​

In mock mode an echo terminal answers: it echoes input, answers stty size and ends with exit. It also runs on Windows.