Enable R1Soft self-service restore in cPanel

R1Soft's block-level snapshots are excellent at storing data and miserable at exposing it to end users. Out of the box, every "restore my deleted file" request becomes a ticket — an operator mounts the disk safe, copies the file out, and chases the customer for confirmation. The cPanel plugin closes that loop. Once installed and paired with the Server Backup Manager (SBM), users open R1Soft Restore Backups in cPanel, pick a recovery point, browse their home directory or databases, and restore. No ticket, no operator time.

This guide installs the plugin on a cPanel server already protected by an SBM, wires it to the right API key, and walks the per-user permission knobs most operators get wrong on the first attempt. Plan 20 minutes end-to-end on a server with one disk safe.

Prerequisites

• cPanel & WHM 110 or later on AlmaLinux, Rocky, or CloudLinux
• An R1Soft agent already installed and registered with SBM
• At least one completed recovery point in the disk safe (the plugin shows nothing until then)
• Root or sudo on the cPanel server, and an SBM admin account with API access
• A valid R1Soft license on the SBM

Install the plugin RPM

The plugin ships in the R1Soft yum repo you already added during the agent install:

yum -y install serverbackup-cpanel
/usr/local/cpanel/scripts/install_r1soft_plugin

The install_r1soft_plugin helper drops the plugin into /usr/local/cpanel/base/frontend/jupiter/r1soft/, registers it with AppConfig, and rebuilds the dynamicui cache. Restart cpsrvd to pick up the new icon:

/scripts/restartsrv_cpsrvd

The plugin appears under Files → R1Soft Restore Backups in every cPanel user's interface — but it cannot list anything yet because it has no credentials for the SBM.

Generate an API key on the SBM

End-user restores call the SBM API on behalf of the user. Give the plugin a dedicated API key — never reuse an admin key:

1. On the SBM: Settings → API → New API Key
2. Name it after the cPanel server (cpanel-host-lhr01-plugin)
3. Role: Restore Operator (not Administrator)
4. Copy the key — only shown once

The Restore Operator role can list disk safes, mount recovery points, and restore. It cannot delete safes, change policies, or add protected machines. If a cPanel server is later compromised, an attacker with this key cannot destroy backups — they can only read them.

Pair the plugin with the SBM

On the cPanel server, drop the SBM connection details into the plugin config:

cat > /etc/r1soft/cpanel-plugin.conf <<'EOF'
sbm_url=https://sbm-lhr01.example.com:8443
api_key=<the-key-from-the-previous-step>
agent_hostname=cpanel-host-lhr01.example.com
EOF
chmod 600 /etc/r1soft/cpanel-plugin.conf
chown root:root /etc/r1soft/cpanel-plugin.conf

agent_hostname must match exactly what the SBM knows the machine as — the value in Protected Machines on the SBM, not the literal hostname output. A mismatch produces an empty restore list with no error.

Test the connection from the cPanel server:

serverbackup-cpanel --test-connection

A clean run returns Connection OK — 1 disk safe, 47 recovery points. A 401 means the API key is wrong; a 404 means agent_hostname does not match SBM's view of the machine.

Expose the icon via Feature Manager

By default, the plugin is visible to every cPanel user. Most hosting operators want to gate it — restore access is a paid tier or a trust signal — via WHM Feature Manager:

1. WHM → Packages → Feature Manager
2. Edit the feature list (or create a new one, e.g. with-backups)
3. Find R1Soft Restore Backups and tick or untick
4. Apply the feature list to the relevant packages

Users on a feature list that excludes the plugin see no icon and cannot hit the URL directly — cPanel returns a 403.

Verify as a user

Log in to cPanel as a test account. Open Files → R1Soft Restore Backups. The first load takes 2-5 seconds while the plugin queries the SBM for that user's recovery points. You should see:

• A dropdown of recovery point timestamps for the disk safe holding this account
• A file tree rooted at the user's home directory (/home/<user>)
• Per-file and per-folder restore buttons

Pick a small test file, restore to a new path (/home/<user>/restore-test/), and confirm the file appears with the original content. The plugin streams from the SBM directly — first restore of a multi-GB folder can take a minute. After that, the user gets a notification in cPanel when the operation completes.

Common failures

Empty recovery point list. The agent_hostname in the plugin config does not match what the SBM has. Compare against the SBM's Protected Machines → Edit → Hostname field, not uname -n. Fix the config, restart cpsrvd.

401 Unauthorized in serverbackup-cpanel --test-connection. The API key was either typed wrong or rotated on the SBM. Generate a new key on the SBM, paste into /etc/r1soft/cpanel-plugin.conf, retest.

Restore button greyed out. The Restore Operator role on the API key was not assigned, or the key was created as a "Read Only" role. Recreate as Restore Operator. Read Only can list but cannot mount and restore.

Slow file tree (5+ seconds per click). The SBM is mounting and unmounting the recovery point per request. Increase the plugin's mount cache TTL:

# /etc/r1soft/cpanel-plugin.conf
mount_cache_ttl=600

10 minutes is the sweet spot — long enough to absorb a user's clicks through a directory tree, short enough that a freshly completed recovery point appears within a few minutes.

User can see other users' files. This is a misconfigured agent_hostname pointing at a multi-tenant disk safe with no per-home filter. The plugin honours the cPanel username and rejects paths outside /home/<user> — but only if it knows the user. If the URL is hit while not logged in (a session bug), it will refuse cleanly. If users on the same server can see each other's homes, you have a separate cPanel session issue.

Operational notes

The plugin does not consume an extra R1Soft license slot — it uses the same agent the SBM is already protecting. It does consume a cPanel API call per restore action; on a busy fleet this is negligible.

If you run Disk Safe replication, users by default restore from the primary SBM. Failover requires updating sbm_url in the plugin config on every cPanel server — this is the one part of R1Soft that does not failover automatically. Most operators script this as part of the SBM promotion runbook.

For the broader procurement view on whether R1Soft's plugin UX is good enough versus alternatives, the R1Soft vs JetBackup comparison covers the day-to-day end-user experience honestly. JetBackup's plugin is cleaner; R1Soft's underlying restores are faster on large datasets.

Next steps

• Bootstrap a fresh agent: install R1Soft on AlmaLinux.
• Survive a datacenter outage: Disk Safe replication.
• Compare end-user UX: R1Soft vs JetBackup.
• Buy or renew: R1Soft license.