Troubleshooting

Common problems and how to resolve them.

Check service status and logs #

sudo systemctl status zrs

Follow the logs:

sudo journalctl -u zrs -f

Verify group membership #

The zrs user must be in the docker group to manage containers, and libvirt to manage VMs. The post-install script adds these automatically when the groups exist at install time:

getent group docker  | grep zrs

getent group libvirt | grep zrs

If either is missing (for example, you installed Docker after ZRS), add the user manually and restart the service:

sudo usermod -aG docker zrs

sudo usermod -aG libvirt zrs

sudo systemctl restart zrs

Fixing ownership after running as root #

If you previously ran zrs as root, SQLite may have created WAL files owned by root, preventing the service from writing. Reset ownership of the data directory:

sudo chown -R zrs:zrs /var/lib/zrs

sudo chmod -R u=rwX,g=rX,o= /var/lib/zrs

sudo systemctl restart zrs

Resetting the admin password #

Run the CLI as the zrs user, not as root, for the same reason as above:

sudo -u zrs zrs auth reset admin

Missing sudo command on Debian #

Switch to root:

su -

Install sudo and add your user to the sudo group:

apt update && apt install -y sudo && usermod -aG sudo your_username

Group changes apply to new login sessions. Exit the root shell, log out and back in, or reconnect your SSH session, then rerun the install steps.

Data locations #

• Database: /var/lib/zrs/zrs.db
• Certificates: /var/lib/zrs/certs/
• License: /var/lib/zrs/license
• Configuration: /etc/zrs/config.toml

Reporting bugs #

When reporting an alpha-channel issue to the ZRS team, please include:

1. Distribution and version (cat /etc/os-release)
2. zrs --version
3. Last ~100 lines of sudo journalctl -u zrs -n 100