Getting Started

Get started with ServersCTL in minutes. Install the free Linux agent using the one-shot command from the control panel and begin monitoring, managing, and protecting your servers from a single unified platform.

Introduction

A message from the developers.

ServersCTL started life as a solution to a problem many of us face: HAProxy is often the single point of failure in an otherwise resilient infrastructure.

The original goal was simple. Build a way to monitor HAProxy instances and automatically move traffic if a load balancer becomes unavailable without VRRP or a floating/failover IP address. Once the first working version was in place, it became clear that the underlying concept was far more powerful than we had anticipated.

By combining a lightweight agent with infrastructure-focused automation, we found ourselves solving many of the day-to-day challenges that infrastructure managers encounter. Monitoring, backups, disaster recovery, DNS failover, cPanel replication, service management, and operational visibility could all be brought together into a single platform.

ServersCTL is not intended to replace the tools you already use. Instead, it aims to sit alongside them, providing practical automation and visibility where it matters most.

Today, we are releasing the Linux agent free of charge for anyone to use. Our hope is that it saves you time, reduces operational headaches, helps keep your services online, and perhaps one day saves your bacon when you need a backup or a failover plan.

We release this with no limits on the number of pools you can have or the number of servers you may manage. If you find this product useful, support us by upgrading your account, contributing ideas or even reporting a bug. Everything helps.

We hope you find it useful.

What the agent is

The ServerCTL/BalCTL agent is a small Python 3.9+ process (stdlib only, no pip packages) that runs on each pool member Linux VM. It:

  1. Heartbeats to the control plane over outbound HTTPS (proves liveness, reports host/HAProxy state).
  2. Pulls jobs from the control plane after each successful heartbeat (install, reload, backup, restore, firewall, etc.).
  3. Optionally self-updates from a published zip bundle.

It is deployed as a systemd service: balctl-heartbeat.service, with secrets in /etc/balctl/agent.env.

Current release: check AGENT_VERSION in agents/balctl_heartbeat.py or python3 balctl_heartbeat.py --version.

Requirements

Server Stack

Operating system

Runtime dependencies

Component Required Notes
Python 3.9+
Yes
Stdlib only; on EL8 minimal images may need python39
systemd
Yes
Service: balctl-heartbeat.service
wget or curl
Install-time
Download agent.zip
unzip
Install-time
Extract bundle
sudo / root
For full feature set
Heartbeat itself can run unprivileged; most panel jobs need root

Optional packages (installed by agent jobs when needed)

Package When
haproxy
Install HAProxy job or BALCTL_PROVISION_HAPROXY=1
socat
Admin socket drain/ready, runtime HAProxy commands
firewalld
RHEL-family firewall jobs (auto-installed on first “Refresh rules” if missing, agent v78+)
ufw
Debian firewall backup jobs

Network requirements

Outbound HTTPS (required)

The VM must reach:

Destination Purpose
https://serversctl.com (or your BALCTL_API_BASE)
Heartbeat, job claim/complete, backup upload/download
https://download.serversctl.com/agent.zip
Self-update (default)
https://api.ipify.org (optional)
Public IPv4 discovery when BALCTL_PROBE_PUBLIC_IP=1

All agent API traffic must use HTTPS — the agent refuses plaintext BALCTL_API_BASE / BALCTL_UPDATE_URL (v28+).

Inbound (not required)

Panel-driven operations use the outbound job queue. No inbound SSH or agent port is required if the agent runs as root for privileged jobs.

IP allowlisting (enrollment)

When you create a pool member, you must supply at least one allowed source IPv4. This is the VM’s outbound/egress IP as seen when it calls the control plane — not necessarily its SSH IP or the IP traffic should hit.

The control plane validates CF-Connecting-IP against the enrolled allowlist on every agent request. Mismatch → 403.

Enrollment requirements

Before the agent can heartbeat, create the member in the dashboard (Add pool member):

Field Requirement
Hostname
Must match the JSON hostname the agent sends (case-insensitive). Override with BALCTL_HOSTNAME if OS hostname differs.
Allowed source IPs
One or more IPv4 addresses (comma-separated). Must include egress IP to control plane.
Enrollment secret
48 hex characters, no hyphens. Shown once in the modal. Not the member UUID on the card.
Member template
e.g. HAProxy balancer — determines which panel commands are available.
Linux family
Debian/Ubuntu vs RHEL — affects generated install one-liner.

Authentication model

  • Header: Authorization: Bearer <48-char-enrollment-secret>
  • Secret stored server-side as SHA-256 hash only.
  • 401 = wrong/unknown secret.
  • 403 = IP not allowlisted, or hostname mismatch, or missing CF-Connecting-IP.

Register & Install the Agent

Installation

When adding a pool, you will be asked whether the pool will be for HAProxy nodes. 

Only select the HAProxy Pool Template if the backend server(s) are currently running, or will be running, HAProxy.

For all other server types—including cPanel, OpenLiteSpeed, MySql/MariaDB, and general-purpose Linux hosts—select Generic Linux.

Choosing the correct template ensures that the UI enables the appropriate features and management tools for that server type. If you accidentally select the wrong template, remove any members from the pool and recreate the pool on the correct template.

Recommended: one-shot from the dashboard

You can access the UI using https://serversctl.com/app or https://balctl.com/app. Only the public websites are different.

  1. Register an account at https://serversctl.com/app/
  2. Add a new pool. https://serversctl.com/app/sites
    • Servers can be pooled together. For example, cPanel Servers, LiteSpeed, MariaDB/MySQL all use the Generic Linux template, or HAProxy servers use the dedicated HAProxy template.
  3. Select Add Member. The modal generates a paste-ready command that:
    • Ensures unzip + python3 (via apt or dnf/yum).
    • Downloads https://download.serversctl.com/agent.zip.
    • Runs balctl-agent.sh --enrol --key … --hostname … --api-base ….
    • Writes /etc/balctl/agent.env, runs --update, enables systemd.
  4. The ServersCTL UI will now start to report agent information.
    • See troubleshooting if you have problems.

To add further members to a pool. Keep using the Add Member button.

Files after install

Path Role
/usr/local/bin/balctl_heartbeat.py
Agent binary
/etc/systemd/system/balctl-heartbeat.service
systemd unit
/etc/balctl/agent.env
Secrets + config (chmod 600)
/var/lib/balctl/
State stamps (e.g. .haproxy-provisioned)

Bundle contents (agent.zip)

Flat zip: balctl_heartbeat.pybalctl-agent.shbalctl-heartbeat.env.examplebalctl-heartbeat.serviceREADME.mdLICENSEINSTALL_VM.txt.


Configuration (/etc/balctl/agent.env)

If your configured hostname is different from the hostname sent to ServersCTL, use BALCTL_HOSTNAME

Variable Required Default Purpose
BALCTL_ENROLLMENT_SECRET
Yes (heartbeat)
48 hex chars from modal
BALCTL_API_BASE
No
https://serversctl.com
Control plane origin
BALCTL_INTERVAL_SEC
No
1
Bootstrap interval only; control plane returns authoritative heartbeatIntervalSec (1–60s)
BALCTL_HOSTNAME
No
OS hostname/FQDN
Override reported hostname
BALCTL_DECLARE_IP
No
Fixed IPv4 in heartbeat JSON (for DNS failover)
BALCTL_PROBE_PUBLIC_IP
No
off
Discover public IPv4 via HTTPS each heartbeat
BALCTL_PUBLIC_IP_URL
No
https://api.ipify.org
Probe URL
BALCTL_UPDATE_URL
No
https://download.serversctl.com/agent.zip
Self-update zip
BALCTL_PROVISION_HAPROXY
No
off
One-shot HAProxy install on first start (root)
BALCTL_ALLOW_AGENT_DOWNGRADE
No
off
Allow installing older agent from zip (not recommended)

Systemd loads this via EnvironmentFile=/etc/balctl/agent.env. Manual sudo python3 … runs merge missing vars from the same file.

HAProxy Server Pools

HAProxy Server Pools

Overview & concepts

What is an HAProxy pool?

An HAProxy pool is a ServerCTL deployment preset for the edge tier: public DNS, one or more enrolled Linux VMs running HAProxy, and optional automatic promotion when the active host fails.

ServerCTL is the control plane. It does not terminate customer traffic itself. It:

Status: HAProxy pools are well tested and in public beta.

Core terminology

Term Meaning
Pool
One site/deployment in the dashboard
Member
One enrolled VM (node) with hostname, allowed egress IP, and enrollment secret
Active member
The host whose IPv4 the managed DNS A record points at
Standby
Enrolled member not currently receiving DNS traffic
Failover hostname
Public FQDN clients use (e.g. lb.example.com)
Member template
Role at enroll time — for HAProxy pools use HAProxy balancer

Architecture (high level)

Clients → DNS (Cloudflare / cPanel) → A record → Active HAProxy VM
ServerCTL Worker updates DNS
Standby HAProxy VMs ← agent heartbeats + jobs

Health for failover: A member is unhealthy when:

  1. No heartbeat within the failover delay window (10–120 seconds), or
  2. HAProxy is monitored, and systemd reports HAProxy inactive

Important: Clients must use the failover hostname, not a member’s raw IP. ServerCTL moves the A record; your apps keep the same DNS name.

What HAProxy pools include vs other presets

HAProxy pools uniquely enable:

Generic Linux pools hide HAProxy-specific jobs unless the agent detects HAProxy on the host.

HAProxy Server Pools

Create your first pool & Enroll your first member

Create your first pool

Step 1 — Add pool

  1. Go to Pools → Add pool
  2. Choose the HAProxy template
  3. Name the pool (e.g. production-edge)
  4. After create, you land in the pool with a setup banner

Step 2 — Connect DNS (Settings)

ServerCTL needs API access to authoritative DNS to create/update the failover A record.

Cloudflare

cPanel / WHM

You can save reusable Cloudflare credentials under Settings → API providers and link them to pools without re-entering tokens.

Step 3 — Enrol the first member

On Overview → Add member:

Field Notes
Member template
HAProxy balancer
Hostname
Must match JSON hostname from the agent; set BALCTL_HOSTNAME on the VM if OS hostname differs
Allowed source IPs
VM outbound IPv4 to serversctl.com (egress), not necessarily SSH address

After creating, copy the one-shot install command immediately and run it in the HAProxy Server — the enrollment secret is shown once.

The command:

Within a few seconds, the member tab should show a green heartbeat.

Step 4 — Set the public failover hostname

Settings or Managed DNS tab:

Step 6 — Add a standby (High Availability)

Repeat enrollment on a second VM. Enable Automatic failover in Settings when ready for unattended promotion.

HAProxy Server Pools

Pool workspace (Overview, Settings, DNS, DR, Monitoring)

Pool workspace

The pool page has a tab bar with three groups:

  1. Overview (pool home)
  2. Member tabs (one per enrolled host)
  3. Pool tools (DR, Monitoring, Settings, Managed DNS)

Overview tab


For HAProxy pools, Overview answers:

HAProxy-H2.png

Hero panel: Traffic-flow diagram — Cloudflare/DNS → active HAProxy → standbys.

Actions:

HAProxy-H3.png

KPI tiles: healthy members, failover-ready count, backups, cron jobs, last failover time.

Member cards show Active vs Standby, heartbeat state, and Make active on standbys.

Settings tab

Section Purpose
Pool name
Rename the pool
API providers
Cloudflare credentials, WHM links
Balancer failover
Auto-failover toggle, recovery time (10–120s)
Remove pool
Destructive — deletes pool and related data

Failover hostname, proxied vs DNS-only, and Dynamic DNS sync live on the Managed DNS tab (not only Settings).

Managed DNS tab

Disaster Recovery tab

Visible when the pool has 2+ members (HAProxy preset only).

Cross-member restore: Pick a target member, choose a snapshot from another host’s backups, restore scoped HAProxy files onto the target.

Requires Pro or active trial for cross-member restore.

Monitoring tab

Pool-wide alert settings and failover notification preferences (email when auto-failover promotes a standby).

Per-member monitoring is under each member’s Monitoring tab.

Protection tab

Only appears when 2+ cPanel members exist — not core HAProxy-only pools. Document separately if you mix cPanel hosts into an HAProxy pool.

HAProxy Server Pools

Pool members & enrollment

Member tab layout

 

Click a member in the tab bar to open its workspace. Sub-tabs:

Tab Purpose
Control panel
Host ops: reboot, updates, hostname, TLS domain (non-HAProxy PEM)
Security
UFW firewall, SSH enable/disable, firewall backup
Status
Live HAProxy traffic stats from heartbeat (show stat)
Cron & Jobs
Scheduled tasks + job timeline
Restore Backups
List snapshots, scoped backup/restore
Recipes
One-click enable flows (admin socket, SSH, Let’s Encrypt, agent update)
Monitoring
Member-level alert thresholds
Settings
Display name, hostname, allowed IPs, geo, remove member

HAProxy-specific Management actions (install, reload, drain, TLS failover) are surfaced on Control panel and via Recipes — the dedicated HAProxy tab exists in code but is hidden until product-ready.

HAProxy-HM3.png

Enrollment security model

Each heartbeat must satisfy:

  1. Bearer token — 48-character enrollment secret (hashed in D1)
  2. CF-Connecting-IP — must match allowed source IP(s)
  3. JSON hostname — must match enrolled hostname

Mismatch → 403 (IP) or credential errors.

Agent environment

Variable Purpose
BALCTL_API_BASE
Worker URL (e.g. https://serversctl.com)
BALCTL_ENROLLMENT_SECRET
From Add member modal
BALCTL_HOSTNAME
Override OS hostname
BALCTL_DECLARE_IP
Declare public IPv4 in heartbeat
BALCTL_PROBE_PUBLIC_IP=1
Probe public IP if not declared

Agent runs as root for HAProxy install, backup/restore, admin socket, and cert writes.

HAProxy Server Pools

DNS failover & traffic cutover

Manual cutover

Make active on a standby member → ServerCTL sets it as primary and updates the managed A record to its public IPv4.

Cut DNS to standby on Overview → promotes next failover-ready standby (same DNS update, overview-oriented workflow).

HAProxy-HM4.png

Automatic failover

Enable in Settings → Balancer failover.

When enabled, ServerCTL periodically evaluates the active member. Promotion triggers when:

A healthy standby is promoted; DNS is updated; optional email alert fires.

Failover delay

Setting Range
Recovery time
10–120 seconds
Community (free)
Fixed at 120s
Pro / trial
Faster presets (e.g. 10s, 30s)

Agents' heartbeat independently (~1s); failover delay is not the heartbeat interval.

Failover-ready criteria

A standby is ready when:

Dynamic DNS Sync

Optional for HAProxy pools when the active member’s WAN IPv4 changes (DHCP/ISP churn). Each heartbeat can push the new public IP to Cloudflare without manual DNS edits.

Proxied vs DNS-only

HAProxy Server Pools

HAProxy operations

Install & lifecycle

Action Command ID Notes
Install HAProxy
haproxy.provision
Fresh VM
Re-install
haproxy.provision + force: true
Overwrite install path
Reload
haproxy.reload
After config edits
Provision standby from backup
standby.provision_from_backup
Clone config from backup onto standby

Jobs are enqueued to the API; the agent claims and runs them on the next heartbeat.

Admin stats socket (drain / ready)

Runtime backend control requires a Unix admin socket in haproxy.cfg:

stats socket /run/haproxy/admin.sock mode 600 level admin expose-fd listeners
stats timeout 2m

Enable via Recipe: Enable HAProxy admin stats socket or Enable admin stats socket action.

Requires socot + agent as root. This is not a public HTTP stats page.

Backend server states

From Management/topology table:

Action Command ID HAProxy runtime
Drain
haproxy.server_drain
set server … state drain
Ready
haproxy.server_ready
state ready
Maintenance
haproxy.server_maint
state maint


TLS (Let’s Encrypt on HAProxy)

Recipe: Let’s Encrypt (failover / HAProxy)

The pool must have Cloudflare linked and a failover label set before the recipe applies.

Status tab

Shows live traffic from agent heartbeat enrichment — not a duplicate of the Overview topology diagram. Use for session rates, backend health columns, etc.

HAProxy Server Pools

Backups & disaster recovery

What gets backed up

HAProxy backup job captures:

Storage: Per member S3.

Path pattern:

/{userId}/sites/{siteId}/snapshots/{snapshotId}/

Restore flows

Same member: Restore Backups tab → pick snapshot → scoped restore → agent validates with haproxy -c → reload.

Cross-member (DR tab): Restore another member’s snapshot to a target VM — typically after an outage or a bad config push.

Fresh VM rebuild:

  1. Enrol new/replacement member
  2. Optional: Install HAProxy
  3. Restore snapshot
  4. Make active when ready

Standby provisioning

Provision standby from backup clones, HAProxy config from a backup onto a standby host — faster than manual copy for DR drills.

HAProxy Server Pools

Recipes & scheduled jobs

Recipes (member → Recipes tab)

Recipe When
Enable HAProxy admin stats socket
HAProxy detected
Enable SSH access
Always available
Let’s Encrypt (failover / HAProxy)
HAProxy + Cloudflare + failover FQDN
Update agent
When agent version outdated

Recipes show steps, completion state, and optional disable actions (e.g. remove admin socket lines).

Cron & Jobs tab

Control-plane cron (UTC) enqueues jobs on the next agent heartbeat.

Common presets:

Separate from per-member backup schedule on Restore Backups — both can exist.

Job timeline

All agent jobs appear in Cron & Jobs with status: pending → running → completed/failed. Remote actions from Overview cards also enqueue here.

HAProxy Server Pools

Agent reference

Heartbeat payload (HAProxy-relevant)

The agent sends JSON including:

ServerCTL validates IP against enrollment and stores the latest row per node.

CLI essentials

sudo balctl_heartbeat.py --version
sudo balctl_heartbeat.py --provision-haproxy # local install
sudo balctl_heartbeat.py --update # from configured agent.zip URL
sudo journalctl -u balctl-heartbeat.service -f

Job loop

  1. POST /api/agents/heartbeat
  2. Server returns pending jobs
  3. Agent executes, posts POST /api/agents/jobs/complete

Full agent docs: agents/README.md in the repo.

HAProxy Server Pools

Troubleshooting & FAQ

Symptom Likely cause Fix
403 on heartbeat
Wrong allowed IP or hostname
Update allowed IPs; set BALCTL_HOSTNAME
401 unknown credential
Used member UUID instead of enrollment secret
Re-enroll; use 48-char secret from modal
No HAProxy on card
No config / unit not detected
Install or ensure /etc/haproxy/haproxy.cfg exists
Drain buttons missing
No admin socket
Run admin socket recipe
Backup shows · D1 not · R2
R2 not bound when backup ran
Fix Worker binding; run new backup
Auto-failover didn’t run
Only one member, auto off, or no healthy standby
Add standby; enable auto; check readiness
DNS didn’t update
DNS not connected, private IP in heartbeat, label unset
Connect provider; use public IPv4; set label
Let’s Encrypt recipe greyed out
No Cloudflare or no failover FQDN
Complete DNS setup first

Support bundle: If contacting support, include the pool name, member hostname, journalctl excerpt, screenshot of member health badge.


Appendix — Plan gating (for operators)

Feature Community Pro / trial
Failover delay
120s only
10s–120s
Cross-member DR restore
Locked
Available
Premium DNS/provider modals
Gated
Available


Linux Server Pools

Generic Linux Server Pools provide monitoring and management for a wide range of Linux infrastructure. They support OpenLiteSpeed, MariaDB, Galera Cluster, and other Linux-based services running on Ubuntu, Debian, Rocky Linux, AlmaLinux, CentOS, Red Hat Enterprise Linux (RHEL), and compatible distributions.

Linux Server Pools

Part 1 - Overview & Concepts

What ServersCTL hosting pools are

ServersCTL (serversctl.com) is the control plane for redundant server infrastructure: enrol Linux VMs with the ServersCTL agent, monitor heartbeats, cut over DNS between peers, run stack backups, and (on the cPanel preset) orchestrate account replication and live WHM transfers.

server pool is one deployment in your dashboard — a set of members sharing failover DNS and pool-level settings. Members run what you actually install on each host. The dashboard exposes member tabs for OpenLiteSpeedMariaDB/MySQLGalera, and cPanel/WHM; each tab fills in when the agent detects that stack on that server.

ServersCTL does not host traffic. It moves DNS, queues remote jobs, and calls APIs where configured.

PoolOverviewLinuxGeneric.png

Pool Presets

Server pools are created using a preset template in the UI. This chapter is for the Generic Linux Server Preset. For HAProxy Server Pools, see the HAProxy chapter.


What runs on a member (stack compatibility)

Do not assume one VM runs every stack. Common deployments:

Deployment Typical member stacks Notes
cPanel / WHM hosting
cPanel tab + MariaDB tab (cPanel-managed MySQL)
Apache/httpd via cPanel — not OpenLiteSpeed
OpenLiteSpeed web farm
OpenLiteSpeed tab only
Standalone OLS
MariaDB / Galera nodes
MariaDB tab + Galera readout
DNS swing ≠ Galera quorum
Mixed pool
Different tabs per member
e.g. two cPanel standbys + one OLS edge — each member’s tabs reflect its OS

Core terminology

Term Meaning
Pool
One ServersCTL Pool.
Member
One enrolled server (hostname, egress IP, enrollment secret)
Active member
Host whose IPv4 receives the pool failover A record.
Stack tab
Member workspace: OpenLiteSpeed, MariaDB, cPanel, etc.
Protected account
cPanel account with a replication job.
Agent
balctl_heartbeat.py on each member — heartbeats to serversctl.com

Architecture

Clients → DNS (Cloudflare / WHM) → A record → Active member IPv4
ServersCTL Worker (serversctl.com)
Standby members' ← agent heartbeats (+ WHM replication on cPanel preset)

Failover health: missed heartbeat beyond failover delay (10–120 s). No HAProxy systemd check on hosting presets.

All Linux Servers should use the Generic Server Preset when adding a pool. Only ever select the HAProxy Preset if HAProxy is installed on your server.

Create a Generic Linux pool

CreatePool.png

    • Configuration preset: Generic Linux servers.

CreatePool-1.png

    • Name the Pool.
    • Now, go to the pool. Pool  Overview  Add server. Choose — RHEL/Ubuntu - Enter hostname, allowed egress IP.

CreateEnrollmentKey.png

  1. On the VM: 
    • Paste the install command into the console to install the agent. 
    • If you have existing installs of cPanel, OpenLiteSpeed, MariaDB etc. The agent will report this to the UI. 
    • When 2+ members run cPanel: pool Protection and Managed DNS tabs appear (see Chapter 1).
    • Optional: Configure DNS on Managed DNS for account-level cutover.

Add further members to the Pool

  1. From the pool overview tab click "Add Member".
  2. Name the member and supply the member's egress IP.
  3. Copy the install command into the console of the server being added to the pool.
  4. Repeat the process to add further members. There are no limits to the number of pools or members you may have.

How pool navigation works

Two layers on one screen


The UI is split into two sections. The top tabs manage overall pool settings and the lower tabs manage member settings.

Layer What it controls Examples
Pool tabs
Settings and services that span all members or protected accounts across members
Overview fleet, Protection replication, Managed DNS catalogue, pool Monitoring presets, pool Settings
Member tabs
One enrolled Linux server — host OS, detected stacks, jobs, and backups
Control panel, Security, cPanel, MariaDB, Cron & Jobs

Linux-Server-Pool-O2.png

Protection and Managed DNS are pool settings. They float in the top tab bar above the member server tabs. They coordinate account replicationDNS cutover, and provider keys across the fleet — not operations on a single box.

Pool tab visibility (Generic Linux template)

Pool tab Always? When it appears
Overview
Yes
Default landing
Member tabs (one per server)
When enrolled
Subtitle Member on Generic pools (not Active/Standby)
Protection
No
2+ members with cPanel detected
Managed DNS
No
Same as Protection on Generic pools (2+ cPanel members)
Monitoring
Yes
Pool-wide alert presets
Settings
Yes
Pool name, API providers, delete pool

Tab: Overview (first pool tab).

Purpose: Fleet-wide health — are agents reporting, are backups and jobs healthy across Linux servers?

What you see

Section Content
Fleet Status header
KPI widgets: member count, healthy agents, last check-in, backup count, cron jobs, running jobs, outdated agents
Fleet geography map
Members plotted when geo is set on each member’s Settings tab
Server tiles
One tile per enrolled member — click to open that member’s workspace
Actions
Add serverPool settings

Operator actions

Tab: Protection (pool tab bar).

When visible: 2+ pool members where the agent reports cPanel.

Purpose: Account-level warm standby — scheduled WHM backup → Secure Storage → restore on a standby server, with optional DNS cutover per protected account.

What you see

Section Content
Protection dashboard
KPIs: protected accounts, replication health, last sync
Server cards
Each cPanel-eligible member — readiness, WHM link, geography
Protected accounts
Per-account source → standby mapping, schedule, TTL, DNS provider
Replication log
Sync, DNS cut, transfer, and failure events
Geo map
Primary / standby geography when locations are set

Operator workflow

  1. Ensure 2+ cPanel members and WHM API keys (Settings or Managed DNS → API providers).
  2. Add protection — pick source account, target standby member, schedule (1h … 1mo), DNS TTL, DNS provider (Cloudflare or WHM).
  3. Replicate now / Replicate protected (Pro) — on-demand sync.
  4. Account Cut DNS — per-account A record swing to standby (coordinates with Managed DNS).
  5. After DNS cut: post-failover hook on standby.

Relationship to member tabs

Task Where
Bulk account replication, schedules, protection DNS
Pool Protection
Single-account migrate, live transfer sessions
Member cPanel → Migrate & Recovery
WHM account CRUD, suspend, AutoSSL
Member cPanel → Accounts

Protection is pool-wide orchestration; member cPanel is per-server WHM operations.

Replication Transfer

Replication can take anywhere from a few minutes to several hours, depending on the size of the account.

ReplicationTopologySync.png

The source agent will package the account and split it into multiple chunks, which are securely stored temporarily in D2 storage. Once all chunks have been uploaded, the UI instructs the receiving agent to download them and begin the restore process.

After the restore has completed successfully, all stored chunks are automatically removed from S3. As a guide, a 1.8GB backup typically takes around 5 minutes to replicate. Please take replication time into account when configuring your schedule. If the account is large, you may need to replicate once per day or every few days to avoid overlap and ensure the process completes cleanly.

ReplicationTopology.png

Tab: Managed DNS (pool tab bar).

When visible (Generic Linux): 2+ cPanel-detected members

Purpose: Pool-level DNS catalogue for protected accounts and optional dynamic DNS — WHM vs Cloudflare zones, record health, sync, import. The API keys listed here are for DNS only. Do not use your production WHM API key here. You must use Cloudflare or a cPanel DNS Cluster API Key.

What you see

Section Content
DNS Health
Zone summary, provider linkage, drift, topology banner (DNS Provider → Primary → Standby) when Protection is active
Protected account records
Per-FQDN proxied/DNS-only, enabled, active IP, cut actions
API providers
Cloudflare account keys (one Global), per-member WHM keys
Dynamic DNS card
Failover hostname and sync toggle (Generic pools — primary place for DNS failover config)
Actions
Refresh DNS, Sync WHM→CF, Add record, Import from Cloudflare

Operator actions

Protected DNS

The UI treats WHM servers as the source of truth and replicates changes to any linked DNS provider, as long as the account is marked as Managed. By default, the only record that will cut over automatically is the domain’s A record.

Multiple DNS Record Cut Over

You can configure the UI to cut over additional DNS records from the Protected Account DNS list. From here, you can specify A, AAAA, MX, and SRV records that should automatically cut to a standby server when the primary becomes unavailable.

Actions

The three‑dot menu under the Action column provides additional fine‑tuning options:

ManagedDNSActions.png

Pool vs member DNS

Scope Tab
Protected accounts, zone catalogue, provider keys, and failover FQDN
Pool Managed DNS
Per-member WHM key rotation
Pool Settings or Managed DNS API panel
Host TLS / Let’s Encrypt on a single VM
Member Control Panel or Recipes

Tab: Monitoring (pool tab bar).

Purpose: Pool-wide monitoring presets — distinct from per-member alerts on each server’s Monitoring tab.

Generic pool without Protection (0–1 cPanel members)

Infrastructure alerts section:

Generic pool with Protection (2+ cPanel members)

Protection DNS failover section (in addition to or instead of infrastructure, depending on layout):

Preset Meaning
Failover banner
How long pool header shows Failover active after DNS cut (Community: 2 h max)
Failover email
Notify when DNS moves to standby
Failover alert recipients
Team inboxes for protection cutover

Operator note

Configure per-member heartbeat and resource alerts on each server’s member Monitoring tab. Pool Monitoring is for fleet-level and protection DNS behavior.

Tab: Settings (pool tab bar).

Purpose: Pool identity, shared API credentials, danger zone.

What you see (Generic Linux)

Card Content
Pool name
Rename the pool
API providers
Cloudflare account keys (mark one Global). Each cPanel server needs its own WHM key (pool-level + per-member rows)
Danger zone
Delete pool
What is NOT on the Generic pool Settings
Feature Where instead
Balancer failover (auto-failover delay, make-active hostname)
Managed DNS (when tab visible) or optional — Generic pools work without DNS
Protection jobs
Protection tab
DNS record catalog
Managed DNS tab

HAProxy pools include Balancer failover on Settings.

Linux Server Pools

Part 2 - Member workspace (per-server tabs)

Member tab bar (Generic Linux Server Pool)

Tab Always in nav? Active when
Control panel
Yes
Always
Security
Yes
Always
OpenLiteSpeed
Yes (Generic)
Content when OpenLiteSpeed detected; else frosted not detected overlay
MariaDB
Yes (Generic)
Content when MariaDB/MySQL detected or cPanel-managed MySQL
cPanel
Yes (Generic)
Content when cPanel detected else frosted overlay
Status
Yes
Always — host/agent health summary
Cron & Jobs
Yes
Always
Restore Backups
Yes
Always
Recipes
Yes
Always
Monitoring
Yes
Always
Settings
Yes
Always

Member Control Panel

Purpose: Host-level operations on this Server — OS family, uptime, services, quick actions, TLS.

What you see

Section Content
Health strip
Agent version, heartbeat age, firewall summary
Console
Open a secure SSH session to the member
KPI row
CPU, memory, disk, load
Quick actions
Reboot, shutdown, install updates, backup (stack-aware), Let’s Encrypt (when applicable)
Services
Running units relevant to detected stacks
SSL / TLS
Certificate expiry, sync domain from DNS
Recent activity
Latest completed jobs

Member Security

Tab: Security.

Purpose: Host firewall and SSH on this member.

What you see

Section Content
Firewall KPIs
Enabled/disabled, rule count, last sync
Action tiles
Enable/disable firewall, add rule, manage rules, backup UFW config
SSH access
Key-based access helpers

Member OpenLiteSpeed

Tab: OpenLiteSpeed.
Sub Tabs: Overview, Recovery Wizard

For: VMs where OpenLiteSpeed is the web server — standalone OLS hosts.

Not for: Default cPanel/Apache hosting — expect a not-detected overlay on cPanel servers.

Overview

Web admin (:7080 link), KPIs, virtual hosts table, reload/restart/config test/backup/upgrade/LSPHP, logs.

OpenLitespeed-Overview.png

Recovery Wizard

Also known as Cross‑Member Restore, this feature allows you to automatically take a full backup of an OpenLiteSpeed account, including SSL certificates and the database*. The backup is stored within your Pool API Storage, and the Recovery Wizard allows you to restore that backup to a different OpenLiteSpeed server.

If you have a DNS API Key scoped for the domain, DNS records can be updated automatically during the recovery process. Simply select the appropriate API Key when using the Recovery Wizard.

* Database restoration requires that no additional MySQL/MariaDB password is set when accessing mysql from the command line. If an additional password has been configured, the automated restore process cannot proceed, and the database will need to be restored manually.

Recipes & backups

Install OpenLiteSpeedHarden OpenLiteSpeed on Recipes. Restore on Restore Backups (backup_openlitespeed, Pro).

Member MariaDB

Tab: MariaDB.
Subtabs: Overview, Databases

For: Dedicated DB servers or cPanel-managed MySQL on WHM hosts.

Standalone database server

Overview

Health, KPIs, schema cards, restart, config test, flush privileges, logical backup, harden, logs.

MariaDB-MySQL-Overview.png

Databases

The Databases tab lists all databases discovered on the OpenLiteSpeed server. Databases are detected by scanning for common configuration files such as wp-config.php and parsing their contents.

Databases can be backed up individually or via cron. For a full account backup, use the Recovery Wizard.

MariaDB-MySQL-Databases.png

cPanel-managed MySQL

If cPanel is on the same host: MariaDB tab shows a cPanel host notice — use member cPanel (§11) for account-level DB ops.

MariaDB-MySQL-cPanel.png

Galera (wsrep) (In Alpha)

When Galera is enabled, the agent will report the wsrep state. ServersCTL does not run quorum, SST, or writer election. DNS is active ≠ Galera primary.

Recipes & backups

Install MariaDB/MySQLHarden the database. Restore Backups. Advanced recipes require Pro.

Member-Recepies.png

Member cPanel

Tab: cPanel.

For: WHM servers — the most common ServersCTL hosting workload.

Inner tabs: Overview · Operations · Accounts · Migrate & Recovery

Overview (inner)

DNS banner, protection topology (when account is protected), service badges, WHM audit summary.

Operations (inner)

Restart web/mail/cPanel, config check, WHM backup, harden, WHM API status, listeners, disk, metrics.

Accounts (inner) (Pro)

CRUD, suspend, terminate, backups, AutoSSL, one-time login. Free: read-only, 5 accounts cap.

Live Migrate & Recovery (inner) (Pro)

Live transfer, sessions, push copy. Bulk replication and schedules: pool Protection (§3), not this inner tab alone.

WHM Binding

Full WHM API when member matches pool host. Run WHM link check recipe after DNS connect.

Member Status

Tab: Status.

Purpose: Read-only health and readiness snapshot for this member.

Generic Linux member

Section Content
OS / agent
OS family, agent version (outdated warning), generic probe template
Live stats
CPU, memory, disk from last heartbeat
Updates
Pending package updates
Firewall
Summary from heartbeat

Member Cron & Jobs

Tab: Cron & Jobs.

Purpose: Scheduled tasks on this member and visibility into recent job activity.

What you see

Section Content
KPI row
Cron count, backup schedules, last run
Schedules
Enable/disable, edit schedule (UTC), add from presets
Recent jobs
Timeline of agent and worker jobs

Common presets

Stack backups (backup.cpanelbackup.database, etc.), failover.evaluate where applicable.

Member Restore Backups

We are developing off-site backups. We currently only backup configuration unless stated in the UI. Contact us if you have questions.

Tab: Restore Backups.

Purpose: Snapshot catalog for this member — run backup, restore, delete.

Modes

Tab adapts to detected stack: cpanelopenlitespeeddatabase, or mixed.

Section Content
KPI row
Snapshot count, total size, last backup
Calendar
Backup history
Snapshot cards
Restore or delete individual snapshots

Pro required for restore actions on stack backups. 

Member Recipes

In development - Only ever use recipes on clean servers. 

Tab: Recipes.

Purpose: Guided install and harden flows — one-click enqueue of multi-step agent jobs.

Examples by stack

Recipe Stack
Install cPanel / harden
cPanel
Install OpenLiteSpeed / harden
OLS
Install MariaDB / harden
MariaDB
Galera cluster (read-only)
MariaDB + wsrep
SSH hardening, agent update
Host
WHM link check
cPanel + DNS
Let’s Encrypt (host or HAProxy)
Host / edge

Member Monitoring

Tab: Monitoring

Purpose: Per-member alert settings.

What you configure

Setting Meaning
Heartbeat miss alerts
Email when agent stops checking in
CPU / disk / service thresholds
Resource alerts for this server
Alert recipients
Account email + optional team inboxes
Recovery notifications
Notify when member recovers

Member Settings

Tab: Settings (member tab bar).

Purpose: Identity and location for this enrolled server.

What you see

Section Content
Display name / hostname
Must match agent JSON; BALCTL_HOSTNAME to override
Allowed source IPs
Member egress IPv4 allowed to call serversctl.com
Server location
Geo for pool Overview map and Protection geo map
Monitor settings
Member-level alert toggles (overlaps with Monitoring tab)
Remove member
Detach server from pool

WHM API keys for cPanel: prefer pool Settings / Managed DNS API providers; per-member WHM edit is available there.