EZSCALE/virtfusion-whmcs-module
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

feat: add PowerDNS reverse DNS (PTR) integration

Browse Source 
Introduces an opt-in reverse DNS management subsystem backed by a PowerDNS
Authoritative HTTP API. Runs via a companion WHMCS addon module
(modules/addons/VirtFusionDns) that holds settings and a Test Connection
page; the server module reads those settings from tbladdonmodules and
short-circuits when the addon is absent or disabled, so provisioning is
unaffected for operators who don't use the feature.

Lifecycle hooks:
- createAccount creates PTRs for every assigned IP (forward DNS must
  already resolve to the IP — FCrDNS enforcement)
- renameServer updates only PTRs whose content matched the old hostname,
  preserving client-custom records
- terminateAccount deletes all PTRs before the local state is purged
- TestConnection merges PowerDNS health check with the existing VirtFusion
  check
- A DailyCronJob hook reconciles missing PTRs additive-only (never
  overwrites)

Client UI: new "Reverse DNS" panel on the service overview with one
editable PTR input per assigned IP, per-row status badges, and
forward-DNS rejection on save. Admin services tab gets a parallel
widget with Reconcile (additive) and Reconcile (force reset) buttons.

New subsystem at lib/PowerDns/:
- Client.php    PowerDNS API wrapper (X-API-Key, listZones/getZone/
                patchRRset/notifyZone), auto-NOTIFY on successful PATCH
- Config.php    Loads + decrypts addon settings from tbladdonmodules
- IpUtil.php    PTR-name generation (IPv4 + IPv6), zone matching,
                RFC 2317 classless parsing
- Resolver.php  FCrDNS verification via dns_get_record with CNAME-chain
                following and per-(hostname,ip) caching
- PtrManager.php Orchestrator: syncServer, deleteForServer, listPtrs,
                setPtr, reconcile, reconcileAll

Security hardening helpers added to Module and applied to the rDNS
endpoints:
- requirePost()           HTTP method gate (405 on non-POST mutations)
- requireSameOrigin()     Origin/Referer check against WHMCS host (CSRF
                          defence against cross-site form POST)
- requireServiceStatus()  tblhosting.domainstatus filter (Active for
                          writes, Active+Suspended for reads)

RFC 2317 classless delegations (e.g. 64/64.113.0.203.in-addr.arpa.)
supported with alignment validation: rejects misaligned start addresses
that don't correspond to any real delegation boundary.

PowerDNS zone IDs containing '/' are URL-encoded as '=2F' per the
PowerDNS API convention. PATCH success triggers PUT /zones/{id}/notify
so slaves pick up the SOA-bumped serial immediately.

Includes IPv4 + IPv6 support, per-IP write rate limit (10s), fresh
IP-ownership re-verification on every client write (defends against
stale-ownership after IP reassignment), and audit logging of every
successful edit to the WHMCS module log.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Prophet731
2026-04-17 21:08:22 -04:00
parent d253bd44e6
commit ad85439dfb
18 changed files with 3312 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
modules/servers/VirtFusionDirect/lib/ModuleFunctions.php
View File

@@ -5,8 +5,38 @@ namespace WHMCS\Module\Server\VirtFusionDirect;
/**
* Extends Module to handle the WHMCS service lifecycle for VirtFusion servers.
*
* Responsibilities include: provisioning (create, suspend, unsuspend, terminate),
* package changes, usage updates, client area rendering, and admin tab fields.
* WHY A SEPARATE CLASS FROM MODULE
* --------------------------------
* The WHMCS module interface (VirtFusionDirect.php) expects top-level functions
* like VirtFusionDirect_CreateAccount(). Those functions delegate into methods
* on this class so:
* 1. The top-level functions stay one-liners that are easy to audit.
* 2. All lifecycle logic lives in an object we can instantiate and unit-exercise
* without going through WHMCS's dispatch machinery.
* 3. The shared behaviour with Module (API calls, auth, validation) comes for
* free via inheritance — no copy-pasted curl setup or error handling.
*
* ERROR MESSAGE CONVENTION
* ------------------------
* Every public method either returns the literal string 'success' or an error
* string that WHMCS will render to the admin in the service activity log. Do NOT
* return arrays, objects, or booleans — WHMCS treats anything other than
* 'success' as an error and displays it verbatim.
*
* EXCEPTION HANDLING
* ------------------
* Every public method is wrapped in try/catch. Uncaught exceptions bubbling up
* to WHMCS appear as stack traces in the admin UI and leak implementation detail,
* so we catch and convert to a human error string. Log::insert() captures the
* original exception message for diagnostics in the module log.
*
* PowerDNS INTEGRATION
* --------------------
* createAccount(), terminateAccount(), and (via parent Module) renameServer()
* call into PowerDns\PtrManager to sync rDNS. Those calls are wrapped in their
* OWN try/catch so DNS failures never bubble up to WHMCS — provisioning must
* succeed even if PowerDNS is temporarily unreachable. See cleanupPowerDnsForService()
* for the termination-time cleanup helper.
*/
class ModuleFunctions extends Module
{
@@ -163,6 +193,33 @@ class ModuleFunctions extends Module
Database::systemOnServerCreate($params['serviceid'], $data);
$this->updateWhmcsServiceParamsOnServerObject($params['serviceid'], $data);
// Initialize reverse DNS for the newly-assigned IPs.
//
// Ordering: after Database::systemOnServerCreate() AND
// updateWhmcsServiceParamsOnServerObject() so mod_virtfusion_direct
// has the stored server_object (admin reconcile later reads it) and
// tblhosting has the primary IP (for cross-check on client edits).
//
// But BEFORE ConfigureService::initServerBuild() so rDNS is in place
// when the VPS first boots — mail servers and other services that
// check FCrDNS during early-boot see correct PTRs.
//
// Non-blocking: rDNS failures are logged but never fail provisioning.
// A broken PowerDNS or missing zone must not prevent a customer
// from getting the VPS they paid for.
try {
if (PowerDns\Config::isEnabled()) {
// syncServer with $oldHostname=null means "create mode" — see
// PtrManager::syncServer() docblock for the semantics.
$hostname = PowerDns\PtrManager::extractHostname($data);
if ($hostname !== null) {
(new PowerDns\PtrManager)->syncServer($data, null, $hostname);
}
}
} catch (\Throwable $e) {
Log::insert('PowerDns:createAccount', ['serviceid' => $params['serviceid']], $e->getMessage());
}
// If the server is created successfully, we can initialize the server build.
$cs = new ConfigureService;
$vfUserId = isset($data->data->owner->id) ? (int) $data->data->owner->id : null;
@@ -304,6 +361,7 @@ class ModuleFunctions extends Module
switch ($request->getRequestInfo('http_code')) {
case 204:
$this->cleanupPowerDnsForService($service);
Database::deleteSystemService($params['serviceid']);
$this->updateWhmcsServiceParamsOnDestroy($params['serviceid']);
@@ -312,6 +370,7 @@ class ModuleFunctions extends Module
case 404:
if (isset($data->msg)) {
if ($data->msg == 'server not found') {
$this->cleanupPowerDnsForService($service);
Database::deleteSystemService($params['serviceid']);
return 'success';
@@ -335,6 +394,33 @@ class ModuleFunctions extends Module
}
}
/**
* Delete any PTR records owned by this service before the local record is erased.
* The stored server_object is the last source of the IP list; once deleted from
* the module table we'd have no way to find them again. Non-fatal — DNS failures
* never block termination.
*
* @param object|null $service Row from mod_virtfusion_direct (has server_object JSON)
*/
protected function cleanupPowerDnsForService($service): void
{
try {
if (! PowerDns\Config::isEnabled()) {
return;
}
if (! $service || empty($service->server_object)) {
return;
}
$decoded = json_decode($service->server_object, true);
if (! is_array($decoded)) {
return;
}
(new PowerDns\PtrManager)->deleteForServer($decoded);
} catch (\Throwable $e) {
Log::insert('PowerDns:terminate', ['service' => $service->service_id ?? null], $e->getMessage());
}
}
/**
* Suspend a VirtFusion server, queuing the action if another operation is in progress.
*
@@ -552,6 +638,9 @@ class ModuleFunctions extends Module
if ($params['status'] != 'Terminated') {
$fields['Options'] = AdminHTML::options($systemUrl, $params['serviceid']);
if (PowerDns\Config::isEnabled()) {
$fields['Reverse DNS'] = AdminHTML::rdnsSection($systemUrl, $params['serviceid']);
}
}
return $fields;
@@ -659,6 +748,7 @@ class ModuleFunctions extends Module
'serviceStatus' => $params['status'],
'serverHostname' => $serverHostname,
'selfServiceMode' => (int) ($params['configoption4'] ?? 0),
'rdnsEnabled' => PowerDns\Config::isEnabled(),
],
];
} catch (\Throwable $e) {