Concepts
Every other page in this manual uses the words below. Read this page once, then come back to look a term up. Each term has its own heading, so a link such as /start/concepts/#hosting lands on the entry.
Servers and the cluster
Section titled “Servers and the cluster”Hyperion
Section titled “Hyperion”Hyperion is a hosting control panel for Debian servers. It creates and runs websites (Linux user, nginx configuration, PHP, database, certificate, WordPress), takes backups, and watches the servers. You work in a web panel, with the hctl command line, or through an HTTP API.
Hyperion does not provide mailboxes. It sends mail from your sites and from the panel through the server’s own postfix. It does not run DNS for your domains; the only DNS it answers is the optional challenge zone used for automatic wildcard certificate renewal.
The agent is the program that changes the server. It runs as the hyperion-agent systemd service on every Hyperion server, as root. It creates users, writes nginx and PHP-FPM configuration, runs backups, and keeps the state of that server in a local database.
The agent listens on a local Unix socket, /run/hyperion.sock, which root and members of the group hyperion-admin can use. Worker nodes also listen on port 9443 for requests from the master. Because hctl talks to the socket, it keeps working when the panel is down.
The panel is the web interface and the /api/v1 HTTP API. It runs as the hyperion-web systemd service, only on the master, and listens on port 8443 by default. It speaks only HTTPS. The panel asks the agent on a server to do the work; it does not change servers itself.
Cluster
Section titled “Cluster”A cluster is one master and any number of workers. A single server is a cluster of one: the master hosts sites itself.
Master
Section titled “Master”The master is the server that runs the panel. It holds the list of nodes, the user accounts, the audit log and the key it signs requests to workers with. The master also runs an agent and can host sites like any other node. In Settings, Cluster, the option Allow new sites on the master turns that off, which makes the master a control plane only. In the node list the master is the row marked this server.
Worker
Section titled “Worker”A worker is a server that hosts sites but does not run the panel. It runs only the agent. The master drives it by sending signed requests to port 9443. You add a worker by creating an invite on the master and running the node installer on the new server, as described in Add a worker node.
A node is any server in the cluster, the master or a worker. The sidebar item Nodes lists them. A node has a label you can rename and a node ID that never changes. The master’s own node is addressed as local in panel links such as /services?node=local.
Invite
Section titled “Invite”An invite is a one-time token that lets a new server join the cluster. You create it on Nodes, under Add a node. The token is shown once, and the master stores only its hash. See Add a worker node.
Enrollment and heartbeat
Section titled “Enrollment and heartbeat”Enrollment is the first call a new worker makes to the master, presenting an invite. After that the worker sends a heartbeat to the master every 60 seconds. The Nodes page treats a worker as offline when no heartbeat has arrived for 300 seconds.
Drained node
Section titled “Drained node”A drained node keeps serving its existing sites but gets no new ones. You drain a node from its row on Nodes, for example before maintenance.
Test node and preview address
Section titled “Test node and preview address”A test node takes only sites on a preview subdomain. The preview address is a template (for example {name}.preview.example.com) set under Settings, HTTPS & previews, and it works through a wildcard preview certificate. Because a site on a test node takes its domain from the template, a test site cannot take a real customer’s domain. You mark a node as a test node from its row on Nodes. See Preview a website before its DNS moves and Create a test website.
Hosting
Section titled “Hosting”A hosting is one site as Hyperion manages it: a primary domain with its aliases, a Linux user, files, optionally a database and a PHP version, a certificate, and the settings around them. The sidebar item Hostings lists them. The panel also says website and site, and this manual uses all three words for the same thing. hctl says hosting. See Create a website.
Hosting type
Section titled “Hosting type”Every hosting has one type, chosen in Add a website:
| Type in the panel | What it serves |
|---|---|
| WordPress website | WordPress, installed with the site, plus a database. |
| Static website | Files served as they are. |
| PHP application | Your own PHP code, with an optional database. |
| App behind a proxy | nginx forwards the domain to an address you give, where an app is already running. |
| Redirect | Every request is sent to another address. |
System user
Section titled “System user”Every hosting runs as a Linux user, its system user. Hyperion derives the name from the domain unless you give one in the System user field of the create form. Site files and PHP-FPM run as this user.
htdocs and the hosting folder
Section titled “htdocs and the hosting folder”The files of a hosting live in /home/<system-user>/<domain>/. Inside it, htdocs is the web root: the folder nginx serves and where you upload the site. The sibling folders logs and tmp hold the site’s logs and temporary files. The /home part is the home_root setting in /etc/hyperion/agent.toml.
Hosting state
Section titled “Hosting state”A hosting is in one of these states: provisioning (being created), active, suspended, failed, deleting and trashed.
Suspended
Section titled “Suspended”A suspended hosting is switched off on purpose, for example for an unpaid invoice, an expiry date or going over a disk limit. Visitors see a notice page instead of the site. Files and database are kept. You resume the hosting to bring it back.
Maintenance mode
Section titled “Maintenance mode”Maintenance mode is a per-site switch that makes every visitor request answer with a generic 503 “we will be back” page. Certificate renewals keep working. Unlike suspension, the hosting stays active.
Trash is the holding area for deleted hostings. It is off by default: until you turn on Move deleted sites to Trash first (Settings, Backups, Trash), deleting a site removes it for good. With Trash on, a deleted site is taken offline but its files, database, certificates and system user are kept for a number of days (30 by default, 1 to 365). Within that time you can restore it from Trash in the sidebar or delete it for good. After that the scheduler deletes it permanently. See Suspend, resume or delete a website.
An alias is an extra domain name that serves the same hosting, such as the www. version of the domain. The create form calls the field Other addresses.
Move, copy and import
Section titled “Move, copy and import”Move / copy relocates a hosting to another node, or makes a copy of it there; the page is reached from the Move / copy item on a hosting. Import brings sites and their databases in from a CloudPanel or HestiaCP server, or from another Hyperion node. Its sidebar item is Import. See Move or copy a site and Import sites with one command.
Plans and products
Section titled “Plans and products”Profile
Section titled “Profile”A profile is a plan template you apply to hostings. It holds limits (PHP memory, execution time, PHP workers, database connections and disk), the backup schedule and retention, expiry rules, an optional price, alert channels, and the WordPress plugins and themes to install. The sidebar item is Profiles & limits. See Create and edit a profile and Apply a profile to sites.
A profile keeps a link to its sites, but saving a profile changes only the template. The sites on it keep the values they were applied with until you click Re-apply to N websites (N is the number of sites on it) on the profile’s edit page. A site has one profile at a time.
A quota is the disk limit of a hosting. A profile or the site’s own settings can set a soft limit, which warns, and a hard limit. What happens at the hard limit is a per-site choice: notify, or suspend the site. A site suspended by its disk limit resumes by itself once its use falls below 90% of the hard limit. See Set a disk quota.
Care package
Section titled “Care package”The panel’s name for this is Care packages. A care package is a maintenance service you sell, defined under Care packages in the sidebar. See Create a care plan. It lists the features the service includes and an optional price shown to the customer. The features are automatic WordPress updates, file integrity and malware scanning, uptime monitoring, brute-force protection, firewall rules (Standard or Strict) and the OWASP Core Rule Set, automatic backups, and the care report email. Each yes/no feature is On, Off or Leave alone. A package enforces only what it includes, and puts it back if someone switches it off. A site can hold several packages at once.
A profile is copied onto a site once. A care package stays bound to the site and is enforced continuously.
Care plan
Section titled “Care plan”A care plan is a care package as held by one site: the package, the price the customer agreed to, and the date it starts. Hyperion stores the price, language and checklist with each activation, so editing a package later does not change what an existing customer agreed to. This manual says care plan for “the package on this site” and care package for the definition. The panel only says care package. See Put a site on a care plan.
Hyperion does not invoice anyone. The price is text shown to the customer, and with a billing interval it starts a reminder for you.
Care report
Section titled “Care report”A care report is the monthly email sent to a site’s owner, covering the work the care plan includes. You can also send a one-off report for a date range. The wording customers receive is under Settings, Customer letters. See Send care reports to customers and Change customer letters and the email logo.
Backups
Section titled “Backups”Backup archive
Section titled “Backup archive”A backup archive is a .tar.gz of a site’s files plus a database dump. Archives are made on a schedule, on demand with Back up now on the site’s Backups tab, and before automatic WordPress updates. They are kept on the site’s node and copied to your off-site targets. An archive is what brings a site back after a server is lost. See Back up a site and set a schedule.
Snapshot
Section titled “Snapshot”A snapshot is taken by hand from a site’s Backups tab, and by Hyperion before automatic updates. Content shared between snapshots is stored once, a snapshot can show what changed, and it never leaves the node. A snapshot answers “undo this bad update”. It does not replace an archive. See Take and restore snapshots.
Settings, Backups, What is kept chooses whether Hyperion keeps both, archives only, or snapshots only. Both is the default.
Off-site target
Section titled “Off-site target”An off-site target is a place outside the server that receives a copy of every backup archive: an S3-compatible bucket, or an FTP, FTPS or SFTP server. You manage them under Settings, Backups, Off-site copies. See Copy backups off-site.
Security
Section titled “Security”The WAF is the per-site web application firewall in nginx. Each site has a level: Off, Standard or Strict. An optional second tier applies the OWASP Core Rule Set. See Turn on the web application firewall for a site.
A ban is a temporary block of an IP address, triggered by repeated failed logins or by refusals from the WAF. The Protection and Firewall items in the sidebar show current and past bans. See Review, add and lift IP bans.
Firewall
Section titled “Firewall”The Firewall page manages an nftables ruleset per node: whether the node filters at all, which ports are open and to whom, which port presets are applied, and who is banned. See Manage a node’s firewall.
People and access
Section titled “People and access”Every panel user has one role. The labels in the panel are:
| Role | What it can do |
|---|---|
| Owner | Full control, including users, roles, nodes and every Settings form. |
| Administrator | Full control of all hostings. Cannot open Users, Roles or Nodes, and sees Settings read-only. |
| Operator | Staff who manage the hostings they are assigned. |
| Customer | An end user with a slimmer menu, limited to their own hostings. |
| Read-only | View only, on the hostings assigned. |
Operators and Read-only users see only the hostings granted to them on the Access tab of each hosting. That tab does not list Customers. Under Roles in the sidebar you can build custom roles from individual permissions. Built-in roles lists what each role can do.
Two-factor authentication
Section titled “Two-factor authentication”Two-factor authentication (2FA) adds a six-digit code from an authenticator app to the password sign-in. Enrolling also produces ten single-use backup codes. By default Owner and Administrator accounts must have 2FA, and an account without it is sent to set it up at sign-in. The rule is the option Require 2FA for Administrator and Owner accounts under Settings, Access. See Set up two-factor sign-in.
API key
Section titled “API key”An API key is a bearer token for the /api/v1 HTTP API. You create it under API keys in the sidebar. A key can never do more than the person who created it. See Create and revoke an API key.
Operating Hyperion
Section titled “Operating Hyperion”Setup wizard
Section titled “Setup wizard”The setup wizard is the set of browser pages that finishes an installation. See Run the setup wizard.
Setup code
Section titled “Setup code”The setup code is a 16-character code printed by the installer. It proves you are the person who ran the installer, before any administrator account exists. It works once and expires after 24 hours. hyperion setup-link prints a new one while setup is unfinished.
Background job
Section titled “Background job”Every slow action in the panel (creating a site, a backup, a restore, a certificate, an import, a WordPress install) runs as a background job. A job has named steps with progress, and it keeps running if you close the browser. The sidebar item Background jobs lists them. See Follow background jobs.
hctl and the hyperion command
Section titled “hctl and the hyperion command”hctl is the command line. It talks to the agent on the server you run it on, so it works when the panel is not reachable. hyperion is a short front door installed next to it. It handles update, setup-link, version, status, logs and help, and passes everything else to hctl, so hyperion info and hctl info are the same command.
Component
Section titled “Component”A component is a piece of optional server software that Hyperion installs and manages: PHP 8.1 to 8.4 with wp-cli, MariaDB, PostgreSQL, Redis, FTP (vsftpd) and phpMyAdmin. The setup wizard asks which to install. The installed list is kept in /etc/hyperion/components, and an update restores only the software listed there.
Service health
Section titled “Service health”Service health in the sidebar shows the state of the systemd services Hyperion depends on, on every node. Open a node there to restart or install services. See Check the health of a node’s services.