Skip to content
Hyperion

Check the health of a node's services

Service health checks the systemd units Hyperion depends on, live, on every node: nginx, the panel and agent, the PHP-FPM versions, the database servers, postfix, the FTP server and more. Use it first when a site, the panel or mail misbehaves, and the notification bell points at a server problem.

Before you start

Section titled “Before you start”
  • You are an Administrator or an Owner to read the page. Starting, restarting, stopping, installing and reading the journal need the Owner role.

Steps

Section titled “Steps”

Read the verdict

Section titled “Read the verdict”
  1. Open Service health in the sidebar, under Operations.
  2. On a cluster, the page first lists every node under Nodes, worst first. The line above reads “N nodes · every installed service running.” or “N of M nodes need attention.” Each row shows the units that need a look and a count of healthy ones. Click a node to open its page. A single server opens straight to its page, and a row of chips on a cluster switches between nodes (← All nodes, master, and each worker).
  3. On a node’s page, read the coloured line at the top. It reads “All N installed services running.” or names what is wrong, for example “nginx failed · postfix stopped”. Red means a core unit is down, orange means an optional one is.
  4. Read the groups:
    • Core · the panel needs these: nginx, hyperion-agent and hyperion-web.
    • Optional · databases, PHP, mail, FTP: every other installed unit.
    • Not installed on this node: a fold with units that are absent. A missing core unit stays in the main list as missing.

The page refreshes the live groups every 15 seconds without a reload.

Each row has the unit’s label and name, a status pill, and facts: how long it has been up, its memory, its PID, the last result, its version, and “restarted N×” when systemd restarted it on its own. A note under the row says “Won’t start at boot.” or “Masked on purpose; systemd will not start it.” when that applies.

Pill Meaning
running Active
failed systemd marked the unit failed
stopped Not running. Red for a core unit, orange for an optional one
restarting… A transient state, not counted as a problem
masked Disabled on purpose
missing A core unit that is not installed
not installed An optional unit that is absent. Not a problem

Act on a service

Section titled “Act on a service”

As an Owner you see buttons on a row.

  1. Click Restart on a running unit and confirm. Hyperion runs systemctl restart <unit> on that node, and active connections may briefly drop. The agent cannot restart itself from here, because that would cut off the command. Run sudo systemctl restart hyperion-agent on the node instead.
  2. Click Start on a stopped unit and confirm.
  3. Click Install on a unit in Not installed on this node and confirm. Hyperion runs apt-get install -y <unit> and systemctl enable --now <unit> on that node. It can take up to 5 minutes. An Install progress group shows the result while it runs and for about ten minutes after.
  4. Click Details on a row to open the unit’s page. It shows the same facts and the recent journal (“Recent log · last 100 lines”). Owners also see Stop, Start at boot and Don’t start at boot.

Stopping or disabling nginx, hyperion-web or hyperion-agent is not offered, because it would cut off the panel. Stop takes a service offline until you start it again, and sites that rely on it stop working. Don’t start at boot leaves the service running until it is stopped or the node reboots.

From the command line, on the node:

Terminal window
sudo hctl service list
sudo hctl service restart php8.3-fpm

service list shows active and enabled state for each unit, with critical services that are down counted apart from optional ones. Only names from that list are accepted.

Other groups on the page

Section titled “Other groups on the page”

The same page holds three more groups, reached from the links at its top:

  • PHP versions: every installed PHP branch checked against the security advisories Hyperion knows, with its build, status and the sites that use it. Use Set PHP versions and limits to install or remove a branch and to move sites.
  • Mail delivery: the postfix checks, covered in Diagnose mail delivery on a node.
  • Troubleshooting, for Owners only: tools for an install that fails with “Read-only file system” or “/usr is not writable”. Diagnose only reads. Diagnose and auto-fix also runs mount -o remount,rw / and, when /usr is separate, chattr -i /usr and mount -o remount,rw /usr. Remount only runs mount -o remount,rw / and nothing else. On snap-managed or ostree images these fail by design.

All actions are audited.

Check that it worked

Section titled “Check that it worked”
  • The line at the top reads “All N installed services running.”
  • The row you acted on shows the pill running and a fresh “up” time.
  • After Install, the unit moves from Not installed on this node to Optional.

If it fails

Section titled “If it fails”
  • “Status unknown — the node did not answer the probe.”: the node’s agent is unreachable. Check the node’s network and its agent, then reload.
  • A row keeps showing “restarted N×”: systemd restarts the unit on its own. Open Details and read the journal.
  • You see no buttons: only an Owner sees them. The page footer says “Restart and install need the super-admin role.”
Section titled “Related”