virsh connection URIs
The URI tells virsh which driver, transport, host, and privilege scope to use. Most confusion comes from using the right command against the wrong URI. Common URI families | URI | Meaning | Typical use | | | | | | qemu:/
The URI tells virsh which driver, transport, host, and privilege scope to use. Most confusion comes from using the right command against the wrong URI.
Common URI families
| URI | Meaning | Typical use |
|---|---|---|
qemu:///system | Local system instance | Host-wide management, root-owned guests, shared networks and pools |
qemu:///session | Per-user session instance | Unprivileged labs or desktop testing |
qemu+ssh://root@hv-a/system | Remote over SSH | Simple secure remote administration |
qemu+tls://hv-a/system | Remote over TLS | Managed remote API access with certificates |
System URI
Use qemu:///system for host-wide operations that need the system instance and its shared guest, network, and storage state.
Session URI
Use qemu:///session for unprivileged per-user labs where system-wide bridges and pools are not the target.
Remote SSH URI
Use the SSH transport when you want secure remote access without standing up certificate listeners first.
Remote TLS URI
Use the TLS transport when the host exposes a managed remote API endpoint and certificate-based identity matters.
The most important distinction
qemu:///system and qemu:///session do not point at the same state. A guest visible in one may not exist in the other.
virsh -c qemu:///system list --all
virsh -c qemu:///session list --allCommon mistakes
- Creating a guest in session scope and then looking for it in system scope.
- Connecting over SSH and assuming TLS settings are relevant.
- Forgetting that remote URIs usually expose host policy issues such as polkit or SASL earlier than local commands do.
Fast validation
virsh -c qemu:///system uri
virsh -c qemu+ssh://root@hv-a/system hostname
virsh -c qemu+tls://hv-a/system capabilities