A restorepkg of an account archive lands on a server where the same username already exists — different customer, same name. The restore proceeds, the old account’s home directory is overwritten, the old MySQL databases are clobbered by the archive’s, and the team finds out from the original customer in the morning. cPanel’s restore path is not idempotent and not collision-aware by default. A prewwwrestore hook that checks for collisions is two hours of work that pays for itself the first time it fires.
What’s happening
The Standardized Hooks system exposes Whostmgr::Accounts::Create [pre] for new accounts, but restores use a different event: Whostmgr::Accounts::Restore [pre]. A registered pre-restore hook receives the restore payload — target user, source archive, owner — on stdin and can refuse by returning non-zero. The reseller running the restore sees the error message you produce; no filesystem changes happen.
How to verify
Inspect the registered restore hooks and the restore log path:
whmapi1 list_hooks category=Whostmgr event=Accounts::Restore
ls /var/cpanel/users/
whmapi1 list_users
tail -f /usr/local/cpanel/logs/error_log | grep -i restore
ls /var/cpanel/restore-archives/
The hooks list shows registered pre-restore validators. The user list shows what’s already on the box; a restore for a name that’s already there is the most common collision.
The fix
A collision-detecting pre-restore hook in three parts:
- Write the validator at
/usr/local/cpanel/scripts/yourorg-validate-restore.pl:
#!/usr/bin/perl
use strict;
use Cpanel::JSON ();
my $data = Cpanel::JSON::Load(do { local $/; <STDIN> });
my $user = $data->{user};
# Refuse if the username already exists
if (-d "/var/cpanel/users/$user") {
print STDERR "Restore refused: user '$user' already exists on this server. Rename or remove first.\n";
exit 1;
}
# Refuse if the home dir already exists (orphaned from a prior partial restore)
if (-d "/home/$user") {
print STDERR "Restore refused: /home/$user exists but is not a registered account. Investigate orphan first.\n";
exit 1;
}
exit 0;
- Register the hook:
whmapi1 add_hook category=Whostmgr event=Accounts::Restore stage=pre hook=/usr/local/cpanel/scripts/yourorg-validate-restore.pl. - Add quota and IP checks alongside the collision check. The restore can succeed in creating the account row but fail later if the destination doesn’t have IP capacity or the reseller’s quota is full; catching at pre-restore is cheaper than catching during the unpack.
- For automation that wants the restore to clobber intentionally (rare; mostly tests), the operator can pre-rename or pre-remove the conflicting account before retrying. The hook gives an explicit error rather than a silent overwrite.
When restores happen often — migrations, customer recoveries, DR drills — a guarded restore is part of how Stack Harbor’s cPanel server management practice keeps DR exercises from turning into incidents of their own.