WHM Root to Reseller Handoff on FreeBSD VPS

Why this handoff matters on a live hosting account

If you are moving a WHM server from root administration to a reseller team, access removal is only part of the job. You need a clean line between infrastructure control and account-level support, and you need to avoid lockouts while you make that change. This tutorial shows a WHM root to reseller handoff workflow for a FreeBSD VPS where the panel service is already running and the handoff must be verified before root access is reduced.

This is a production-minded procedure for hosting customers, agencies, and support teams. It uses FreeBSD-specific checks, keeps rollback options available, and finishes with verification from both the server and a client workstation. If you are deciding whether a VPS is large enough for panel work and migration windows, Hostperl VPS hosting gives you the control needed for this kind of staged change.

For related operational context, see WHM reseller account provisioning on Ubuntu Server 24.04, shared hosting migration checklist for a clean 2026 move, and WHM backup restore drills.

What you will complete

• Confirm FreeBSD and panel service state before changing access.
• Create or update a non-root administrative account for the handoff.
• Verify WHM reseller permissions and account ownership boundaries.
• Test login, panel access, and backup recovery before reducing root exposure.
• Keep a rollback path if the reseller cannot manage the accounts safely.

Prerequisites and supported platform

Supported OS: FreeBSD 13.3 or FreeBSD 14.1 on a VPS where WHM/cPanel is already installed and licensed. This procedure is FreeBSD-specific because the operating system uses freebsd-version, pkg, rc.conf, and pf rather than Linux package tools.

Operational note: WHM/cPanel is not commonly deployed on FreeBSD in modern new builds, so this guide is for existing environments only. If your server runs Linux instead, use Hostperl's Linux VPS procedures for the equivalent handoff pattern.

1) Connect and identify the server

On your local computer

ssh root@203.0.113.10

203.0.113.10 is a reserved documentation address. Replace it with the real public IP assigned to your Hostperl server. Keep this root session open until the new access path is tested.

On the VPS as root

freebsd-version

This confirms the FreeBSD release. You should see a valid version such as 14.1-RELEASE. If the command is missing or fails, you are not on FreeBSD and should stop here.

hostname -f

This shows the current system hostname. For panel work, it should resolve cleanly and match your management expectations, such as server.example.com.

2) Check WHM and basic service health

On the VPS as root

service cpanel status

This checks whether the panel daemon is active. On a healthy server, you should see a running state rather than a stopped service.

sockstat -4 -l | egrep ':(2082|2083|2086|2087|2089)\b'

This confirms that the standard WHM and cPanel ports are listening. You should expect panel services bound to the expected interfaces.

If the panel is down, do not continue the handoff. Fix the service first and review the logs under /usr/local/cpanel/logs/.

3) Create the reseller administration account

WHM handoff should not rely on shared root credentials. Create a named administration user that will own the reseller workflow, then test it before you restrict anything else.

On the VPS as root

adduser deploy

Follow the prompts to create the account deploy. Use a strong password if you need temporary password access, or set a locked password if you plan to use SSH keys only. For a production handoff, key-based access is preferred.

pw groupmod wheel -m deploy

This grants sudo-style administration through the wheel group. On FreeBSD, wheel is the standard administrative group.

mkdir -p /home/deploy/.ssh

Create the SSH directory for the new account. The directory should exist before you copy the key.

cp /root/.ssh/authorized_keys /home/deploy/.ssh/authorized_keys

This copies the existing root SSH key so you can test the new account without generating a fresh one mid-change. If root does not already use SSH keys, create a dedicated key on your workstation and append the public key instead.

chown -R deploy:deploy /home/deploy/.ssh

This makes the key files owned by the new account.

chmod 700 /home/deploy/.ssh && chmod 600 /home/deploy/.ssh/authorized_keys

These permissions are required for OpenSSH to accept the key.

Verification

ls -ld /home/deploy /home/deploy/.ssh /home/deploy/.ssh/authorized_keys

You should see deploy ownership and restrictive permissions. If the permissions are too loose, SSH login will fail.

4) Test the new login before changing root access

Do not disable root login until the new account works from a second terminal.

On your local computer

ssh deploy@203.0.113.10

Replace 203.0.113.10 with your server IP. A successful login should drop you into the FreeBSD shell as deploy.

On the VPS as the non-root sudo user

id

You should see membership in wheel.

su -

Enter the root password only if you are explicitly keeping password access during the handoff. If the account is key-only and you have doas or sudo configured differently in your environment, use the approved elevation path instead.

If you want to keep the workflow closer to standard panel operations, you can also use the built-in WHM interface over HTTPS from the new account to confirm that the account reaches the panel without relying on root.

5) Review reseller ownership and account scope in WHM

Now confirm that the reseller can manage only the accounts you intended. The exact menu path depends on your WHM layout, but the checks stay the same:

• The reseller can open WHM and view the correct account list.
• The reseller cannot change server-level settings.
• The reseller can manage backups, packages, and account-level tasks only if those features are intended.

If you migrated this server from another host, compare the account count and packages against the source notes. A handoff fails most often when a reseller can log in but cannot see a required package or restore point.

For agencies that need this kind of controlled ownership change often, Hostperl's managed shared hosting and Hostperl affiliate program can be useful for packaging client work without handing over unnecessary server control.

6) Lock down SSH only after the new access path works

Only continue once the new account has passed login and WHM access checks. Then reduce the lockout risk in small steps.

On the VPS as root

cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak

This creates a recovery copy before any SSH change.

sed -i '' 's/^#*PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config

This disables root SSH login after you have already verified the deploy account. If your file does not contain that line, add it manually near the top of the file.

echo 'PasswordAuthentication no' >> /etc/ssh/sshd_config

This is safe only if you have confirmed key-based access for the new account. If you still rely on passwords for emergencies, stop here and keep password authentication enabled until a second backup login is proven.

Syntax test before reload

sshd -t

No output means the configuration syntax is valid. If you see an error, restore the backup before reloading.

Reload SSH safely

service sshd reload

This applies the change without breaking existing sessions. Keep the original root session open until a fresh deploy login succeeds again.

7) Set a rollback point for the panel and accounts

Before the handoff is final, take a usable backup of the panel state. If the reseller later reports missing accounts or a permission issue, you want a recovery point that does not depend on memory.

On the VPS as root

mkdir -p /backup/whm-handoff

tar -czf /backup/whm-handoff/cpanel-config-$(date +%F).tgz /var/cpanel /usr/local/cpanel/etc /etc/ssl /etc/ssh/sshd_config

This archive captures panel configuration, SSL material, and the SSH state you just changed. Store it on separate storage if your operational process requires off-server recovery.

For a proper restoration drill, pair this step with restore testing guidance and your own off-site backup policy.

8) Validate from a client workstation

The handoff is not complete until a client-side check proves the new access path works without the original root session.

On your local computer

ssh deploy@203.0.113.10

Confirm that the new login still works after SSH hardening. Then open the WHM URL in a browser using the server hostname, for example https://server.example.com:2087.

From that session, verify:

• The reseller can see only the assigned accounts.
• The backup and restore menus behave as expected.
• The account or package settings match your change record.

If this server is part of a migration, compare it with the source-host verification flow in shared hosting migration verification. The platforms differ, but the operational checks are similar: account visibility, service reachability, and data completeness.

9) Troubleshoot the most likely failures

SSH key login fails for the new account

Diagnostic command on the VPS as root

ls -ld /home/deploy /home/deploy/.ssh /home/deploy/.ssh/authorized_keys && tail -n 50 /var/log/auth.log

On FreeBSD, the clue is usually permission errors or a missing key file. Fix ownership and permissions, then retry:

chown -R deploy:deploy /home/deploy/.ssh && chmod 700 /home/deploy/.ssh && chmod 600 /home/deploy/.ssh/authorized_keys

WHM opens but reseller cannot see accounts

Diagnostic command on the VPS as root

grep -R "deploy" /var/cpanel/users /var/cpanel/resellers 2>/dev/null

If the account is missing from the reseller map, adjust the WHM reseller permissions and package ownership in the panel, then recheck the listing. Do not hand-edit files unless you have a documented panel procedure.

Reloaded SSH but lost access

If you still have a root session, restore the backup immediately:

cp /etc/ssh/sshd_config.bak /etc/ssh/sshd_config && sshd -t && service sshd reload

If you do not have another session, use Hostperl support or console access from your control panel provider to recover the server safely.

10) Final verification and persistence check

On the VPS as root

service sshd status

service cpanel status

sockstat -4 -l | egrep ':(22|2087|2083)\b'

You should see SSH and panel services running, with the expected ports listening after reboot-safe configuration.

On your local computer

ssh deploy@203.0.113.10

Then browse to the WHM interface again and confirm the reseller role is intact. If you can log in, view the intended accounts, and perform a harmless read-only action, the handoff is ready for production use.

FAQ

Can I disable root SSH access before testing the reseller account?

No. Keep the original root session open, test the new deploy login, and only then disable root SSH access.

Is this procedure valid for Linux WHM servers?

The handoff logic is the same, but the commands differ. FreeBSD uses freebsd-version, pkg, and pf-style administration, so use the matching OS branch for your platform.

What if the reseller needs more than account access?

Grant the minimum additional permissions needed for support. Avoid giving server-wide control unless the reseller is also responsible for infrastructure management.

Should I keep a backup after the handoff?

Yes. A recent backup and a restore test are part of the handoff, not an optional extra.