sos - vault
Open-Core Model back to the blog Open-Core Model

Troubleshooting Guide

Troubleshooting Guide

"No license is installed" when creating a user

The appliance refuses new user creation until a .lic is uploaded. Go to Manage License and install one. If your license is uploaded but the message persists, check the page header — the license may be EXPIRED or REVOKED.

Browser warns about an untrusted certificate

The installer generates a self-signed cert (CN=sos-vault.local). Replace it from Certificate Manager: upload your real fullchain.pem and privkey.pem. If your environment uses an internal CA, also upload the corporate root under "Corporate Root CA" so other hosts on the network trust the new cert without a per-machine override.

Vault storage is nearly full

The vault is a plain directory (default /vault; see Disk Manager for the configured path). Free space the usual way: grow the underlying volume or filesystem, prune retired cases, or move /vault onto larger storage or a network share (NFS/CIFS) mounted by the OS and point Disk Manager at the new path.

Cannot install a license — "machine token mismatch"

The license binds to the host fingerprint captured at install (machine-id + DMI identifiers). If the hardware changed, the stored tokens no longer match the issued .lic. Re-run the installer to re-capture the host fingerprint, then generate a fresh license request key from Manage License, re-verify it at sos-vault.com, and order a replacement .lic from the Customer Portal.

Locked out of an admin account (2FA)

Admins must use TOTP 2FA. If an admin loses their authenticator device — or the appliance clock drifts on a host without NTP so the codes are rejected — reset 2FA for that account from a shell on the host, then have them sign in and re-enrol at Settings → Security:

docker compose exec -T <app-container> \
  sudo -u www-data php artisan 2fa:disable <email|username|id>

If the clock is the culprit, fix time sync (enable NTP/chrony) so future codes validate. To make 2FA optional for admins entirely, turn off the auth.two_factor_required_for_admins setting.

sos-vault.service will not start

Diagnostics in order:

sudo systemctl status sos-vault.service
sudo journalctl -u sos-vault.service -n 200 --no-pager
sudo docker compose -f /opt/sos-vault/docker-compose.yml ps
sudo docker compose -f /opt/sos-vault/docker-compose.yml logs --tail=200

Most failures are /etc/default/sos-vault pointing at the wrong install root, or the host running out of disk under /var/lib/docker.

nginx container reload after a cert upload silently fails

Check the sudoers fragment /etc/sudoers.d/sos-vault-cert was installed (mode 0440, owned root:root) and that SOS_VAULT_NGINX_CONTAINER matches your live compose service name. The fragment scopes www-data NOPASSWD on docker exec sos-vault-nginx nginx -s reload and nothing else.

Open-Core Model back to the blog Open-Core Model