# Command-line reference

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

Source: https://zopanel.net/docs/cli  
Updated: 2026-10-07

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

| Command | What it does |
| --- | --- |
| `zopanel setup` (or `install`) | Sets up a fresh server. See [Install ZoPanel](/docs/install). |
| `zopanel update` | Installs the latest signed release, and rolls back if it is not healthy |
| `zopanel rollback [--db] [--binary-only]` | Goes back to the version before the last update |
| `zopanel version` | Prints the version, commit and build date (`--version` and `-v` work too) |
| `zopanel ctl reset-password USER [--password PASS]` | Sets a new panel password |
| `zopanel ctl disable-2fa USER` | Turns off two-factor authentication for a user |
| `zopanel ctl allow-ip IP\|--clear` | Replaces or clears the panel's IP allow list |
| `zopanel ctl rebuild` | Applies every account and website configuration again |
| `zopanel ctl feature enable\|disable NAME` | Turns a root-only feature on or off |
| `zopanel ctl info` | Shows version, server ID, plan and counts |
| `zopanel ctl doctor` | Checks the server and says how to fix problems |
| `zopanel ctl support-bundle` | Packs logs and configuration, without secrets, for support |
| `zopanel ctl dr-restore FILE.zpb --key KEY [--dry-run]` | Restores the panel database and `/etc/zopanel` from a configuration backup |

`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](/docs/install) explains every option.

## update

```bash
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](/docs/updating).

## rollback

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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.

| Feature | What it allows |
| --- | --- |
| `root-terminal` | The administrator's root shell in **Terminal** |
| `custom-nginx` | **Custom nginx directives** on websites |
| `custom-docker` | Custom Docker images in the App Store, plus Dockerfile and ready-made image deployments |

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

## ctl info

```bash
zopanel ctl info
```

```text
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

```bash
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](/docs/operations).

## ctl support-bundle

```bash
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:

```bash
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](/docs/disaster-recovery).