Troubleshooting
QCOW2 Image is Corrupt¶
Error¶
qcow2: Image is corrupt; cannot be opened read/write
Fix¶
qemu-img check -r all /opt/sherpa/images/<device_model>/<version>/virtioa.qcow2
sherpad does not start: the JWT secret is the wrong length¶
Error¶
The JWT secret /opt/sherpa/.secret/jwt.secret is 12 bytes long, not 32. Restore it from a
backup, or delete it to generate a new one, which logs every user out
Fix¶
sherpad signs login tokens with this file. It is 32 random bytes, so a different length means
it was damaged or replaced. Restore it from a backup if you have one, then start sherpad.
Otherwise delete it; sherpad generates a new one when it starts, and every user must then log
in again:
sudo rm /opt/sherpa/.secret/jwt.secret
sudo systemctl restart sherpad
sherpad does not start: the database key is missing or does not match¶
Error¶
One of:
The database key /opt/sherpa/.secret/db.key is missing, and the database's secret values are
sealed with it. Restore the key file that was backed up with this database; a new key cannot
open them
The database key does not match the key this database's secret values are sealed with. Restore
the key file that was backed up with this database
The database key /opt/sherpa/.secret/db.key is damaged
Fix¶
sherpad encrypts secret values in its database, such as each user's device password, with
the key in /opt/sherpa/.secret/db.key; see Database key.
The key is not in the database or its backups, so a restored database needs the key it was
backed up with. Copy that key back, owned by sherpa with mode 600, then start sherpad:
sudo install -o sherpa -g sherpa -m 600 /path/to/backed-up/db.key /opt/sherpa/.secret/db.key
sudo systemctl restart sherpad
sherpad never makes a new key for a database that already has encrypted values, because the
new key could not read them. Without the right key, restore a database backup taken together
with a key you have.
A user cannot log in: the account is locked¶
Error¶
username and/or password is incorrect
The same message is given for a wrong password and an unknown username, so it does not say the account is locked.
Fix¶
Three failed logins in a row lock an account, and it stays locked, even for the right password, until an admin unlocks it. Unlock it with:
sherpa server user unlock <username>
or with the Unlock button in the Locked column of the Users admin page in the web UI. The user can then log in with their password. Resetting the password does not unlock the account.
The built-in admin account is locked¶
Error¶
Logging in as admin gives username and/or password is incorrect even with the right password.
Fix¶
If another admin can log in, they unlock it with sherpa server user unlock admin. Otherwise,
root unlocks it on the Sherpa server with sherpad user unlock.
sherpad holds the database file open, so stop it first, unlock admin as the sherpa user,
then start it again:
sudo systemctl stop sherpad
sudo -u sherpa sherpad user unlock admin
sudo systemctl start sherpad
sherpad user unlock changes only whether admin is locked and its count of failed logins;
admin then logs in with its password. It works the same for any other account.