ZRS
On this page

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

ZRS does not load in the browser #

ZRS uses port 9779 by default unless you changed it in the configuration. Check that your firewall allows traffic on that port.

# replace 192.168.0.0/16 with your internal subnet
sudo ufw allow from 192.168.0.0/16 to any port 9779
# replace 192.168.0.0/16 with your internal subnet
sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.0.0/16" port port=9779 protocol=tcp accept'
sudo firewall-cmd --reload

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.

Adding guest architectures for VMs #

The VM create form lists an architecture only when its QEMU emulator is installed.

Install the emulator and EFI firmware for each architecture:

# aarch64
sudo apt install -y qemu-system-arm qemu-efi-aarch64
# riscv64
sudo apt install -y qemu-system-misc qemu-efi-riscv64
# x86_64
sudo apt install -y qemu-system-x86 ovmf

Then restart libvirt and ZRS:

sudo systemctl restart libvirtd
sudo systemctl restart zrs

RHEL and Rocky currently don't package QEMU emulators for other architectures, so one has to come from a community repository or a source build.

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

Check the logs with sudo journalctl -u zrs -n 100. If you’re comfortable sharing any relevant lines, include them in your report with private information removed.

On this page