# Command line

Source: <https://deckpa.com/en/docs/cli>

> The deckpa command lets you get access back, audit the server, and manage services even when the panel is down.

## Running the command

The `deckpa` command is installed together with the panel (`/usr/local/bin/deckpa`). Connect to the server over SSH as root and run it; a user who is not root must type `sudo deckpa ...`. The command cannot be called over the network. It lets you administer the server without opening the panel when the panel is down, a password is forgotten, or an IP rule has locked you out.

```bash
deckpa              # shows the command list
deckpa version      # product name, version, and install time
deckpa info         # panel address, hostname, and SSH port
```

Command output is in English; the panel's language setting does not carry over to the command line. For commands that take a user name, the command asks for it if you leave it out, and lists the existing panel users if the name is not found. Commands that change a user or an access rule (`reset-user`, `disable-2fa`, `unlock`, `unsuspend`, `clear-allowlist`) write the action to the audit record, which you can see on the **Audit** tab of the **Logs** page.

## Getting access back

The commands below are the way out for an administrator who is locked out. They talk to the panel's local database and its system service, and do not need an internet connection.

- `deckpa info` prints the panel address (`https://<ip>:<port>`), the server's hostname, and the SSH port from the configuration. It is the first command to try if you forgot the address or the port.
- `deckpa list-users` lists panel users with their role, suspension state, and two-factor authentication state.
- `deckpa reset-user [user]` asks for a new password twice (at least 12 characters) and saves it. All of that user's open panel sessions and the phpMyAdmin and OpenLiteSpeed admin sessions are closed. It then asks whether to reset two-factor authentication too; if you answer `y`, a new secret is generated and printed, and the old recovery codes are deleted.
- `deckpa disable-2fa [user]` turns two-factor authentication off completely and deletes the recovery codes; the user then signs in with the password only. Use it when the authentication device is lost.
- `deckpa unlock [user]` removes the sign-in lockout caused by failed attempts. The lockout starts after 5 failed attempts within 15 minutes.
- `deckpa unsuspend [user]` re-enables a suspended panel user.
- `deckpa setup-link` reprints a lost first-setup link while no user exists yet. If an administrator account has already been created, it tells you to use `reset-user` instead.
- `deckpa clear-allowlist` empties the panel's IP allow list. While the list is empty, the panel is reachable from every IP address. If a bad rule locked you out, this is the only way back into the **Network & Access** page.
- `deckpa set-port [port]` changes the panel port with the same steps as the panel screen (see [Panel settings](https://deckpa.com/en/docs/panel-settings)). Use it if you entered the wrong port and can no longer reach the panel. The panel restarts on the new port a few seconds later.
- `deckpa fix-ssh-port` makes the SSH port recorded in `config.yaml` match the port the SSH service is actually listening on.

> The panel has no "I forgot my password" flow; the way to recover a forgotten password is the `reset-user` command. Because the command runs on the server with root rights, protect SSH access to the server at least as carefully as the panel.

## deckpa doctor: server audit

It measures whether the server is in the expected security and configuration state, using the same checks as the panel's **Health Check** page. The command changes nothing. It measures fresh on every run, and the measurement is done by the system service, which runs as root.

```bash
deckpa doctor                        # full report
deckpa doctor --quiet                # hides the rows that pass
deckpa doctor --tier host            # one layer
deckpa doctor --only ssh-hardening,disk-free
deckpa doctor --json                 # machine-readable output
```

The checks are grouped into five layers; the valid names for `--tier` are `host`, `privilege`, `tenant`, `service`, and `panel`. `--only` takes one or more check IDs, which appear in the report rows (for example `firewall-ports`, `cert-expiry`, `backup-freshness`). The report starts with a summary of the server, shows the results layer by layer, and ends with a single block of fix commands in order of importance.

The exit code can be used in scripts:

- `0`: no critical or warning-level problem.
- `1`: at least one critical check failed.
- `3`: no critical problem, but there is a warning.
- `2`: an unrecognized option was given.

Checks that could not be measured are marked as skipped and do not affect the exit code. If the command cannot reach the system service, that is an error too: if you see a message like `executor unreachable`, first confirm with `deckpa status` that the services are running.

## deckpa top: what is happening now

`doctor` shows whether the server is configured correctly; `top` shows what is happening at that moment: the load average (together with the core count), memory, swap, disk wait share, and the processes using the most resources. The table has columns for PID, user, CPU percentage, RSS memory, thread count, elapsed time, and command.

```bash
deckpa top                      # the 50 heaviest processes
deckpa top -n 100               # a longer list
deckpa top --watch              # live screen, refreshed every 2 seconds
deckpa top --watch --interval 5 # every 5 seconds
deckpa top --json               # a single sample, machine-readable
```

If the list is cut off, the command prints how many processes it shows and the total; use `-n` for more. `--watch` works only in a terminal; the interval must be between 1 and 60 seconds, and it cannot be combined with `--json`. Press `Ctrl-C` to leave the live screen. Reading process information needs root rights, so the system service does the measuring here as well.

## deckpa vhost-custom: per-site OpenLiteSpeed configuration

If you need to add sections to a site's OpenLiteSpeed configuration that the panel does not generate, write them in files named like `/usr/local/lsws/conf/vhosts/<domain>/custom.d/NN-name.conf` (owned by root, mode 0644). This command checks and activates those files.

```bash
deckpa vhost-custom check                 # checks all sites
deckpa vhost-custom check example.com     # one site
deckpa vhost-custom apply example.com     # includes the files in the site, reloads OpenLiteSpeed if needed
deckpa vhost-custom restore example.com   # activates pending files that came from a backup
deckpa vhost-custom discard example.com   # deletes pending files that came from a backup
```

The check looks at each file's name, type, owner, permissions, size, and syntax. A file is accepted when:

- Its name contains letters, digits, `.`, `_`, and `-` and ends in `.conf`. Symbolic links are refused.
- It is owned by root or `lsadm` and is not writable by the group or others (`chmod 644`). The same rule applies to the `custom.d` directory with mode 755.
- At the top level it contains only `extprocessor`, `context`, `websocket`, `realm`, and `accessControl` sections; `include` is refused. Context paths the panel reserves (certificate validation, suspension, and error pages) cannot be used.
- Curly braces are balanced and every opened `<<<` block is closed.

Custom configuration files restored from a backup do not become active on their own: they wait in the site's `custom.d.restored/` directory. After you review them, activate them with `restore` or throw them away with `discard`. When a problem is found, the command exits with code 1.

## Service commands and updating

These commands call `systemctl` and `journalctl` directly, need root, and work even when the panel does not.

- `deckpa restart`, `start`, and `stop` manage the panel's two system services (`deckpa-executor` and `deckpa-api`) together and print the state of each at the end.
- `deckpa status` and `deckpa logs` show the service state and follow the panel logs live.
- `deckpa lockdown [on|off]` is the emergency command. `on` (the default) takes the panel offline while SSH and these commands keep working. `off` brings the panel back.
- `deckpa bans` lists the IP addresses blocked by `fail2ban` in the panel and SSH protection rules. `deckpa unban [ip]` removes one block; without an IP, it removes all blocks.
- `deckpa reboot` restarts the server. It asks for confirmation first; `-y` or `--yes` skips the question.
- `deckpa update` downloads, verifies, and installs the latest version in the channel, the same way as the button on the panel's **Update** page (see [Updates and release channels](https://deckpa.com/en/docs/update)).

If you cannot reach the panel at all, a sensible order is: check the services with `deckpa status`, confirm the address with `deckpa info`, remove blocks with `deckpa unban` and `deckpa clear-allowlist` if needed, and finally renew the password with `deckpa reset-user`.