File-service daemon setup

The file manager, log viewer, native scheduled tasks and backup list/restore/download need a small daemon on each Plesk box, because Plesk’s file and backup tooling lives outside REST reach. Set it up once per server.

1. Why this daemon exists

The customer client area browses, edits, uploads and downloads a subscription’s files. Plesk’s file backend is the filemng utility, which lives in /usr/local/psa/admin/sbin/ — not /usr/local/psa/bin/. The Plesk REST CLI gateway only resolves utilities in bin/, so filemng is unreachable through it, and there is no native REST file endpoint either. The same wall applies to the backup list tool (pmm-ras, in admin/bin/); restore and download run through the daemon too, so it can confirm a backup belongs to the customer’s domain before touching it.

Since ImpulsePlesk manages existing Plesk boxes over the REST API only — no SSH, no VPS provisioning — the file manager, logs, scheduled tasks and backup listing need their own transport. That transport is a small inbound, TLS, bearer-auth daemon installed on each Plesk box: the same admin-proxy shape the other Impulse infrastructure modules use, adapted to a one-line installer for the existing-host model.

Note

What it backs: the native file manager, the parsed log browser, native scheduled tasks, and backup list / restore / download. Without it, those specific surfaces are unavailable; everything else in the client area — including creating a backup — runs over the Plesk API.

2. Run the one-time installer

1. In ImpulsePlesk → Infrastructure, open the server’s menu and choose Installer.
2. Copy the one-line curl … | sudo bash command it shows. It is shown once and works once, within 24 hours; choosing Installer again replaces it.
3. Run it on the Plesk box as root.

# On the Plesk box, as root — the addon generates this command per server:
curl -fsSL "https://<your-whmcs>/modules/servers/impulseplesk/file-proxy-bootstrap.php?id=<token-id>" \
  -H "X-Impulse-Token: <one-time-secret>" | sudo bash

The installer is self-contained (it installs its dependencies with apt, dnf or yum); the box needs Python 3.10 or later, which the daemon’s pinned packages require. It stands up:

• A Python venv under /opt/impulse-fileproxy with pinned dependencies.
• An unprivileged daemon user (impulsefp) that runs the service.
• A root privsep helper at /usr/local/sbin/impulse-fileproxy-op — the only root code — reached through a single sudoers rule.
• A self-signed TLS certificate, a systemd unit (impulse-fileproxy) listening on TCP 8447, and UFW rules allowing only your WHMCS server on that port.

Only your WHMCS server should reach port 8447

The bootstrap mints a per-server bearer secret, and the UFW rule allows the address your WHMCS server reports for itself. If WHMCS reaches the box from another address — behind NAT, or over the other IP family — add a rule for that address too. If the box has no UFW (common on RHEL-family servers, which use firewalld or the Plesk Firewall), the installer prints the port and address to open in your own firewall.

3. Test the connection & capture the pin

Back in WHMCS, choose Test connection from the server’s menu. After testing the Plesk API, it:

• Reads the daemon’s TLS fingerprint over the unauthenticated /tls-info endpoint and pins it the first time (trust-on-first-use / TOFU). A later certificate that doesn’t match the pin is reported, never trusted silently.
• Verifies authenticated reachability over /health with the bearer secret.
• Moves the file-service status to active.

Turn on the File manager feature

Enable File manager (and, if you want native cron, Scheduled tasks) under Settings → Native Features so customers see it in their dashboard. Logs and backups light up from the same daemon.

4. How it stays tenant-safe

The daemon is per-server admin-grade, so the customer-facing scope is enforced in the module (WHMCS auth → subscription → system login → per-site docroot). The box-side controls are defense-in-depth:

• Privilege separation — the daemon runs unprivileged; one sudoers rule lets it invoke the root helper and nothing else.
• User validation — the helper only ever operates as a subscription user whose home is under /var/www/vhosts/ with a non-zero uid; never root or system daemons.
• OS-enforced boundary — before touching disk the helper setgid/setuids (one-way) to the subscription user, so even a path-confinement bug can’t reach another tenant’s files.
• Path confinement — request paths are normalised (./.. clamped) and asserted to stay within the user’s home before any filesystem access.
• No content leakage — the bearer secret is stored encrypted, masked in module logs, and the daemon’s audit log records actions, not file contents.

Backups run as root

The backup list/restore endpoints run the root-only Plesk backup tools (pmm-ras / pleskrestore) without dropping to the subscription user, except download/export, which drops in order to deliver the file into the customer’s home. Export is single-domain-only so a server-wide dump can never package a co-tenant’s data.

5. Update or disable

Update: the daemon version tracks the module. When a release bumps it, the server shows an update badge and its menu offers Update server, which pushes the new daemon and root helper together, signed by the module and verified on the box before install — no SSH. The box doesn’t roll back to the old files by itself. A daemon too old for in-place updates asks you to run Installer on it once instead.

Disable: choose Disable file service from the server’s menu. The module drops the bearer secret and stops using the daemon, and Show details gives the command that removes the daemon, its files, the sudoers rule and the systemd unit from the box. The impulsefp user and the firewall rule for port 8447 stay until you remove them.

Client-area opcache gotcha

If your PHP opcache doesn’t revalidate files (opcache.validate_timestamps=0), reset it or restart PHP-FPM for the pool that serves WHMCS after uploading a new release, or the updated client-area code won’t run and the file manager can appear stale.