ReferenceEvery page

panelctl(1)

administer the panel from the console

Name

panelctl — administer the panel from the console

Synopsis

panelctl [-f file] command [argument ...]

Description

panelctl manages panel accounts and roles without going through the interface, so that the first account, and any recovery from a lockout, does not depend on the interface being reachable. It reads the database directly and must run as the account named by panel_user.

The commands are as follows:

user add name [-roles list] [-display name]
Create an account. The password is read from the terminal without echo, or from standard input when there is no terminal. It must be at least twelve characters.
user list
List accounts with their roles and state.
user passwd name
Set a password.
user roles name role[,role ...]
Replace an account's roles.
user disable name, user enable name
Disabling an account ends its sessions immediately.
user totp name
Enrol a second factor and print the secret and its otpauth URI.
user totp-remove name
Take an account's second factor away, for a lost phone: it signs in with the password alone until one is set up again (Your account, on the page).
role list
List roles and the permissions they carry.
role grant role permission ...
role revoke role permission ...
Installing a module creates permissions no role holds yet; this is how they are handed out. A permission is dotted, and may end in ‘**’ to cover everything beneath it.
bundle make -module id -suite codename -arch arch [-mirror url] [-components list] [-packages list] [-o file]
Copy a module's packages, and what they depend on, from a Debian mirror into a bundle for a device without internet. Run it anywhere that reaches the mirror, for the device's Debian release and architecture, and upload the file on that device's Modules page. Nothing is signed here: the bundle carries Debian's own signed index, which the device checks against its Debian archive keys. Needs no configuration file and no database.
certify app [-o file]
Run an app from the catalogue as the panel would run it — the same podman arguments as its unit, as nobody, in folders under /srv removed afterwards — and check it: its image is for this machine, it answers its health check, nothing in it runs as root or has a capability, it listens only on the ports its recipe opens, and it starts again after being stopped. The report is written to file, by default <app>-<arch>.json in the current directory; an app is offered on an architecture once a report that passed ships in the release. Run as root, with rootful podman, and with the app's ports free: stop the installed app on the Self-hosted page first. Exits non-zero when a check fails. Needs no configuration file and no database.
install [disk [--confirm disk]]
Copy the running system onto a disk, which is erased. Without an argument it lists the disks; the device this system runs from is marked and refused. The layout follows the way the machine starts: an EFI partition for UEFI, a BIOS boot partition otherwise, or, on a board whose card carries a U-Boot for it in /usr/lib/panel-uboot (the NanoPi R5S), that U-Boot at 32 KiB and one root partition from 16 MiB, started through /boot/extlinux/extlinux.conf; only onto an eMMC or a card, which is all the board's boot ROM reads. The U-Boot is written only to the board its compatible file names, and only when it matches its sha256. The device name must be typed to confirm; --confirm gives it instead of the prompt, which is how the install page in the browser has the installer run it (1.139.0). Root's password is locked on the disk.
audit tail [-n count]
Show the most recent entries in the audit trail.
restore status
Whether a restore is waiting to be kept, what it replaced, and how many times the panel has started since; and where switching its modules is (since 1.146.0): switched when the panel next starts, being switched, switched as the backup has them, or back as they were after an undo, with any module that would not switch and why.
restore confirm
Keep a restore that is waiting. The snapshot from before it stays, so it can still be reverted.
restore revert
Undo a restore now, kept or not: the files, then the accounts. The modules it switched are switched back by the broker, at once if it is running or when it next starts.
restore boot-check
For the service unit: undoes a restore nobody kept on the second start after it. Nothing else undoes one.

Changes that would leave no enabled account able to administer the panel are refused.

Examples

Create the first administrator:

# panelctl user add admin -roles admin

Let operators see the system module, which installing it does not grant:

# panelctl role grant operator sys.**

A VPN bundle for a Raspberry Pi running Debian 13:

panelctl bundle make -module vpn -suite trixie -arch arm64

Certify Jellyfin on this machine, with the installed one stopped:

# panelctl certify jellyfin

Move a NanoPi R5S's system from its card onto its eMMC:

panelctl install
panelctl install /dev/mmcblk1

See also

panel.conf(5), panel-masterd(8)