Configuration reference

Hyperion reads two files. /etc/hyperion/agent.toml configures the agent on each node. /etc/hyperion/web.toml configures the panel on the master. Both are TOML. Every section and key is optional: a missing file or key means the default shown here.

• The services read their file when they start. After a hand edit, run sudo systemctl restart hyperion-agent, or sudo systemctl restart hyperion-web for the panel.
• When you save a setting in the panel, Hyperion writes the key into agent.toml without touching your comments or the order of the file, keeps the previous contents as agent.toml.bak, and restarts the agent. Passwords stay in the file; the panel only shows whether one is set.
• The Panel column names where the panel edits a key: the Settings page and, where it matters, the card. A dash means the panel has no field for it, so edit the file.
• On a cluster the master copies some settings to every node (the pages show an All nodes tag). Others belong to one node (an Each node tag). Edit a worker’s own settings from Nodes, on the node’s settings page.

agent.toml

[agent]

Key	Default	Meaning	Panel
socket_path	/run/hyperion.sock	Unix socket hctl and the panel use to reach the agent.	none
socket_group	hyperion-admin	Group that may use the socket.	none
state_db	/var/lib/hyperion/state.db	SQLite database.	none
secrets_dir	/etc/hyperion/secrets	Directory for secret files.	none
log_path	/var/log/hyperion/agent.log	Agent log.	none
home_root	/home	Sites live under <home_root>/<system user>/<domain>/htdocs.	none
backup_root	/var/lib/hyperion/backups/local	Where local backups are written.	none

[acme]

Key	Default	Meaning	Panel
contact_email	admin@example.com	Address Let’s Encrypt knows you by. Issuance refuses an empty address and addresses ending in @example.com, @example.org, @example.net or @hyperion.invalid.	Settings, HTTPS & previews, Let’s Encrypt contact
challenge_dir	/var/lib/hyperion/acme-challenges	Where HTTP-01 challenge files are written.	Settings, HTTPS & previews
renewal_window_days	30	The daily renewal check reissues a certificate when it expires within this many days. A value below 1 is treated as 1.	none
directory_url	https://acme-v02.api.letsencrypt.org/directory	Not used. Issuance always uses Let’s Encrypt production, or Let’s Encrypt staging when a request asks for it.	none

[enrollment]

Only a worker node has this section. The installer writes it.

Key	Default	Meaning	Panel
master_url	empty	The master to enroll with, for example https://panel.example.com.	none
invite_token	empty	One-time token from the master’s Nodes page.	none
node_label	empty	Name the node has in the cluster.	none
state_file	/etc/hyperion/node-id.json	Where the node id and secret are stored after enrollment. An existing file with no new token skips enrollment.	none
verify_tls	absent	Absent verifies the master’s certificate when master_url is https:// with a DNS name. true always verifies. false never verifies, and the invite token and the node’s secret then cross a channel others can read. A failed verification is never retried without verification.	none

[remote_rpc]

The listener that accepts the master’s signed requests.

Key	Default	Meaning	Panel
enabled	false	Whether the node accepts requests from the master. The worker installer turns it on. The local socket works either way.	none
bind	0.0.0.0:9443	Address and port to listen on. Open the port in your firewall for the master only.	none
advertise_addr	empty	Address the master dials, when it is not the detected public IP, for example a private-network address. Empty uses the detected public IP. Read at enrollment, so changing it needs a re-enroll.	none
tls_cert_file	/etc/hyperion/agent-rpc.crt	Certificate for the listener.	none
tls_key_file	/etc/hyperion/agent-rpc.key	Its key.	none

[email]

With enabled = false, postfix delivers straight to each recipient’s mail server. With true, mail goes through the relay in smtp_host. See Set up the outgoing mail relay.

Key	Default	Meaning	Panel
enabled	false	Use the SMTP relay below.	Settings, Mail, Outgoing relay
smtp_host	smtp.example.com	Relay host.	Settings, Mail
smtp_port	587	Relay port.	Settings, Mail
smtp_user	empty	Relay user.	Settings, Mail
smtp_password	empty	Relay password.	Settings, Mail
from_address	hyperion@example.com	Sender address.	Settings, Mail
from_name	Hyperion	Sender name.	Settings, Mail
security	starttls	starttls (port 587), tls (port 465) or plain.	Settings, Mail
default_to	empty	Address that receives cluster-wide notices for sites with no owner email.	Settings, Alerts, Recipients
inet_protocols	ipv4	Postfix inet_protocols for direct delivery: ipv4, ipv6 or all.	none
bind_address	empty	Postfix smtp_bind_address, the source address for outgoing mail. Empty leaves the choice to the kernel.	none
message_size_limit_mb	0	Postfix message_size_limit in MiB, 0 to 100. 0 leaves postfix’s own value alone, which is 10 MB unless changed by hand.	Settings, Mail, Largest message

[slack]

Key	Default	Meaning	Panel
default_webhook	empty	Slack incoming webhook for cluster-wide notices. A profile can set its own.	Settings, Alerts, Slack

[backup_remote]

The off-site FTP, FTPS or SFTP target.

Key	Default	Meaning	Panel
enabled	false	Push every successful backup to this target.	Settings, Backups, FTP / SFTP target
scheme	ftp	ftp, ftps or sftp.	same
host	empty	Server name.	same
port	21	Server port.	same
user	empty	Login.	same
password	empty	Password, stored in the file in plain text.	same
base_path	/hyperion-backups	Directory on the server. A directory per hosting is added below it.	same
keep_latest	0	Newest copies to keep per site on the target. 0 keeps everything. Range 0 to 1000.	same

[backup_retention]

Key	Default	Meaning	Panel
max_age_days	30	After each successful backup, archives older than this are deleted. Range 1 to 3650.	Settings, Backups, Archive retention
keep_latest_n	5	The newest backups per hosting that are always kept. Range 1 to 1000.	same

[backup]

Key	Default	Meaning	Panel
drop_local_after_offsite	false	Delete the local archive once an independent check confirms the off-site copy.	Settings, Backups, Local copies
keep_local_latest	0	Newest local copies per site to keep even so. 0 drops every verified copy. Range 0 to 1000. A value that is not a whole number turns dropping off.	same

[snapshots]

Key	Default	Meaning	Panel
enabled	true	Take a snapshot before Hyperion changes a site. It does nothing unless restic is installed.	none
keep_days	the max_age_days value	Snapshot age limit. 0 means never by age. Range 0 to 3650 when saved in the panel.	Settings, Backups, Snapshot retention
keep_last	the keep_latest_n value	Snapshots to keep. Range 0 to 1000.	same

[protection]

Key	Default	Meaning	Panel
mode	both	Which copy engine the node uses: backups, snapshots or both. Anything else is read as both.	Settings, Backups, What is kept

[permissions]

Key	Default	Meaning	Panel
enabled	true	The five-minute permission self-repair. A site can opt out on its own Security card.	none

[fail2ban]

The brute-force scanner. Values below a floor are raised to it at start. See Brute-force scanner.

Key	Default	Range the panel accepts	Panel
enabled	true		Settings, Brute-force & GeoIP
window_secs	600	1 to 86400	same
ban_ttl_secs	3600	60 to 31536000	same
repeat_ttl_secs	86400	60 to 31536000	same
repeat_lookback_secs	86400	0 to 31536000 (0 never escalates)	same
http_threshold	12	2 to 10000	same
ssh_threshold	8	2 to 10000	same
ftp_threshold	8	2 to 10000	same
mail_threshold	8	2 to 10000	same
waf_threshold	20	3 to 1000	same

[update]

Key	Default	Meaning	Panel
auto	false	Check for a new release every hour and install it in safe mode.	Settings, Panel, Updates

[cluster]

Held by the master.

Key	Default	Meaning	Panel
mode	master	standalone or master. Absent or unknown means master. A worker’s role comes from its enrollment, not this key.	none
master_accepts_hostings	true	Whether new sites may be placed on the master.	Settings, Cluster, Placement
test_node_ids	empty	Comma list of node ids marked as test nodes.	Nodes, Mark as test
test_domain_template	empty	Preview address template; empty means previews are off.	Settings, HTTPS & previews, Preview address
test_wp_no_index	false	Ask search engines to skip WordPress sites on test nodes.	Settings, Cluster, Test nodes
panel_hostname	empty	The panel’s own domain.	Settings, Panel, Panel domain
trash_enabled	false	A deleted site waits in Trash first.	Settings, Backups, Trash
trash_retention_days	30	Days in Trash before removal. Range 1 to 365.	same
audit_retention_days	0	Days to keep audit entries. 0 keeps them forever. Range 0 to 3650.	Settings, Access, Audit log retention
enforce_admin_2fa	true	Require two-factor sign-in for Administrator and Owner accounts.	Settings, Access, Two-factor sign-in
enforce_worker_cert_pinning	false	The master refuses a worker whose TLS certificate does not match the pin it reported.	Settings, Cluster, Channel hardening
enforce_response_auth	false	The master refuses unsigned answers from a worker that has published a signing key.	Settings, Cluster, Channel hardening

[migration]

Key	Default	Meaning	Panel
max_download_gb	64	Largest bundle a node accepts when it imports a moved or copied site. Read on the importing node. Range 1 to 1024; anything else means 64.	none

[performance]

Core Web Vitals in the care report.

Key	Default	Meaning	Panel
cwv_source	off	off, psi (Google PageSpeed Insights, which receives the site’s URL) or lighthouse (a local Lighthouse, which must be installed).	Settings, Customer letters, Core Web Vitals
strategy	mobile	mobile or desktop.	same
psi_api_key	empty	PageSpeed Insights key.	same
cwv_interval_days	7	Days between automatic measurements. 0 never. Range 0 to 365.	same

[notifications] and [letters]

The wording of alerts and of the customer letters. Every key is optional and an empty or missing key means the built-in text. You edit them in the panel; the file holds the result.

Section and key	Meaning	Panel
[notifications] slack_template, email_subject_template, email_body_template	Wrappers around alert messages.	Settings, Alerts, Wording
[notifications] care_report_subject_template, care_report_body_template, expiry_warning_subject_template, expiry_warning_body_template	Whole-letter replacements. Leave empty to use [letters].	Settings, Customer letters, Letters
[letters] lang	Language of the customer letters: en or cs.	Settings, Customer letters, Languages
[letters] operator_lang	Language of your own alerts.	Settings, Alerts, Language
[letters] billing_lang	Language of the billing reminder: en, cs, or empty to follow lang.	Settings, Customer letters, Languages
[letters] overrides_lang	Language your rewritten sentences are in: en, cs or empty.	Settings, Customer letters
[letters] any sentence id	One reworded sentence.	Settings, Customer letters, Sentences

web.toml

All keys sit in [web].

Key	Default	Meaning
listen	127.0.0.1:8443	Address and port of the panel. The installer writes 0.0.0.0:8443 unless you set HYPERION_LISTEN.
agent_socket	/run/hyperion.sock	The agent’s socket.
admin_user_file	/etc/hyperion/web-admin.json	The bootstrap administrator record.
session_key_file	/etc/hyperion/web-session.key	Key that signs session cookies. Created on first start.
csrf_key_file	/etc/hyperion/web-csrf.key	CSRF key. Created on first start.
session_ttl_secs	28800	Session lifetime from sign-in, 8 hours.
secure_cookies	true	Mark cookies Secure. Set false only for plain-HTTP testing.
session_cookie_name	hyperion_session	Name of the session cookie.
tls_enabled	true	The panel terminates TLS. It creates a self-signed certificate if none exists.
tls_cert_file	/etc/hyperion/web-tls/fullchain.pem	Panel certificate.
tls_key_file	/etc/hyperion/web-tls/privkey.pem	Panel key.
pma_listen	0.0.0.0:8447	Address of the phpMyAdmin listener. Empty switches it off and hides the button.
setup_state_file	/var/lib/hyperion/setup.json	State of the first-run wizard.

None of these keys has a field in the panel.

Related

• Set how long backups are kept
• Edit a node’s own settings
• Keep node settings in sync