Command-line reference

Every zopanel command: install, update, rollback, version, and the ctl tools for passwords, 2FA, allowed IPs, rebuilds, features, doctor and recovery.

Updated Oct 7, 2026 · 5 min read

ZoPanel is a single binary, /usr/local/zopanel/bin/zopanel. Run it as root on the server. update, rollback and every ctl command refuse to run as another user.

Overview

serve, agent, fsop, appdetect, sendmail, confine and update-guard are used by ZoPanel's own services. Do not run them by hand.

setup

zopanel setup sets up ZoPanel on a fresh server. It is normally run by the install script. The main options are --profile web|full, --with (extra components), --php, --admin-user, --admin-email, --hostname and --license. The installation guide explains every option.

update

zopanel update

1. Downloads the release manifest for your channel and checks its signature.
2. Installs the new binary if it is newer. Otherwise it prints ZoPanel is up to date.
3. Takes a snapshot of the panel database and restarts the services on the new version.
4. Checks that the panel is healthy. If it does not come up within 3 minutes, the previous binary and database are restored automatically.

The check runs as its own systemd unit, so a dropped SSH session does not stop it halfway. Option: --channel NAME picks the update channel.

You can also update from Settings → Updates (Update now), or turn on Automatic updates, which install new releases at 04:00 server time. See Updating ZoPanel.

rollback

zopanel rollback          # previous version
zopanel rollback --db     # previous version and the database saved before the update
zopanel rollback --binary-only   # previous version, keep the current database

Without options, ZoPanel restores the pre-update database only when the last update failed and finished less than 30 minutes ago. An older snapshot would lose everything done since then, such as new accounts, sites and mailboxes, so ZoPanel keeps the current database and tells you to add --db if you really want the snapshot.

ctl reset-password

zopanel ctl reset-password admin                     # random 16-character password
zopanel ctl reset-password admin --password 'N3w-Pass!'

Prints the new password. All of the user's sessions are signed out and all of their API tokens are revoked. For hosting accounts, the SFTP password is not changed. Change it from the panel.

ctl disable-2fa

zopanel ctl disable-2fa admin

Removes the user's two-factor secret, signs them out everywhere and revokes their API tokens. They can sign in with their password and set up 2FA again.

ctl allow-ip

zopanel ctl allow-ip 203.0.113.10       # only this address may open the panel
zopanel ctl allow-ip 203.0.113.0/24     # or this network
zopanel ctl allow-ip --clear            # allow every address again

This replaces the list set in Settings → General → Restrict panel access with the single IP or CIDR you give, or empties it with --clear. The panel then restarts.

ctl rebuild

zopanel ctl rebuild

Restarts the panel and has it rewrite every website's nginx and PHP configuration from the database. It also applies account limits and PHP settings again. Use it after restoring a configuration backup, or when configuration files were edited by hand. It waits up to 15 minutes and prints how many websites were applied and how many failed. Details are in journalctl -u zopanel.

ctl feature

zopanel ctl feature enable custom-docker
zopanel ctl feature disable root-terminal

These features give the panel root-level power. They can only be switched on the server, so a stolen panel session cannot turn them on.

The setting is stored in /etc/zopanel/agent-features.json.

ctl info

zopanel ctl info

Version:   <version>
Server ID: <server id>
Plan:      <plan> (valid=true)
Sites:     <number>
Accounts:  <number>

Give the Server ID to support when a license is bound to the wrong server.

ctl doctor

zopanel ctl doctor

Checks the core services, the agent, the panel health check, the panel database, free disk space, available memory, the panel certificate, clock sync, the last update and the activity log. Each failure comes with the fix. It changes nothing, and exits with status 1 if it finds a problem. See Operations and monitoring.

ctl support-bundle

zopanel ctl support-bundle
# Support bundle (no passwords or keys inside): /root/zopanel-support-20261007-101500.tar.gz

Writes a .tar.gz with the doctor report, versions, failed services, resource usage, recent logs and the configuration. Secret values are removed.

ctl dr-restore

Restores a lost or rebuilt server's panel from a configuration backup (.zpb), after you install ZoPanel again:

zopanel ctl dr-restore zopanel-config-DATE.zpb --key RECOVERY-KEY --dry-run   # only check the file
zopanel ctl dr-restore zopanel-config-DATE.zpb --key RECOVERY-KEY
zopanel ctl rebuild

The .zpb file comes from Backups → Disaster recovery → Download configuration (.zpb), or from your S3 storage, where it is uploaded daily when remote backups are on. The recovery key is shown on the same card (Show key). You can also pass it in the ZOPANEL_RECOVERY_KEY environment variable, which keeps it out of the process list. The command:

1. stops ZoPanel;
2. keeps the current database and /etc/zopanel as *.before-restore-<time>;
3. writes the backed-up database and configuration files;
4. starts ZoPanel again.

Then run zopanel ctl rebuild, and restore each account with Backups → Disaster recovery → Restore from S3. Websites, databases and mail come from the account backups, not from the .zpb file. The full procedure is in Disaster recovery.