Set up libvirt discovery

Connect a KVM host managed by libvirt so Scanopy discovers its VMs, with their MACs, addresses and state, over SSH.

A libvirt host keeps a definition of every VM it runs, with each NIC's MAC and the bridge or network it sits on. Scanopy logs in to the host over SSH, reads those definitions with virsh, and records each VM as a host linked to the KVM host that runs it.

Beta

The libvirt (KVM) integration is in beta. Data collection may be incomplete and the credential fields may change in a future release. Please report anything that looks wrong.

Before you start

libvirt (KVM) credentials are created under Assets > Credentials and can be pointed at Remote hosts.

Creating a credential, assigning it, and overriding it on an individual host work the same way for every integration — see Creating a credential, Where a credential applies, and Auto-assignment. This guide covers only what is specific to libvirt (KVM).

Assign the credential to each KVM host.

What gets discovered

On each scan, the daemon runs virsh on the KVM host:

From the KVM host	Becomes
The KVM host	A host with a libvirt (KVM) service
Each domain, running or not	A host, linked to the libvirt (KVM) service, with its state (running, paused or stopped)
Each NIC in the domain's definition	An interface with the NIC's MAC
Addresses from libvirt's DHCP leases, the host's ARP table, and the QEMU guest agent	The VM host's IP addresses
The domain name	The host's name, shown as authored by libvirt. See Host Naming
The OS and hostname the guest agent reports	The VM host's OS and hostname
Interfaces the guest agent reports beyond the VM's configured NICs, each with its own MAC and a LAN address	A host per interface, tagged Network identity. See Network Identities

VMs appear grouped under their KVM host in the Workloads perspective.

A VM with no address from any source, such as a stopped VM or one bridged to the LAN without the guest agent, is recorded by its NIC's MAC. It gains its address when a network scan finds it, and stays one host.

A VM on libvirt's NAT network, or on a bridge with no uplink and no address on the KVM host, can't be reached from the daemon. The scan reports it with a warning that names the bridge.

Prerequisites

libvirt with virsh on the KVM host
A daemon running version 0.19.6 or later
SSH open from the daemon host to the KVM host
An account on the KVM host the daemon can log in to over SSH (see below)

Choose the account's access

Account	Gets
In the `libvirt` group	Every domain, its NICs, state and addresses, plus the guest agent's addresses, OS and hostname
Outside the group, with access to libvirt's read-only socket	The same, without the guest agent's data

Create an account in the libvirt group:

sudo useradd -m scanopy
sudo usermod -aG libvirt scanopy

Check it from the daemon host:

ssh scanopy@KVM-HOST virsh -c qemu:///system list --all

For a read-only account, leave out the usermod line and check with virsh -r instead. The daemon tries a full connection first and falls back to read-only.

Guest agent data needs qemu-guest-agent running in the VM and a org.qemu.guest_agent.0 channel in the domain's definition.

Choosing a credential type

libvirt has one credential type.

Credential type	How it connects	Can be targeted at	Requires daemon
libvirtBeta	Runs virsh over SSH, logged in with an SSH login.	Remote hosts	Newer than `0.19.5`

libvirt

The credential runs over an SSH login, which holds the username and the key or password. Choose one in SSH login, or choose Create SSH login. An SSH script credential and a libvirt credential can share one login.

Field	Required	Default	Description
Connection URI	Optional	`qemu:///system`	The libvirt connection virsh opens on the host. qemu:///system holds the VMs a hypervisor runs; use qemu:///session only for VMs one account runs as itself.

Connection URI defaults to qemu:///system, which holds the VMs libvirt starts at boot. Change it only for a host whose VMs live elsewhere, such as qemu:///session for one user's VMs.

The first login pins the KVM host's SSH key, as SSH logins do.

Verifying it works

Run a discovery from Discover > Scans
Open the scan session. The credential appears in the session's credential summary
Check Assets > Hosts for the KVM host, with a libvirt (KVM) service
Check Assets > Hosts for a host per domain, named as in virsh list --all
Open the Workloads perspective and confirm the VMs appear under the KVM host

Troubleshooting

virsh could not open qemu:///system

The login worked, and virsh refused both a full and a read-only connection. The rest of the message is virsh's own error. Add the account to the libvirt group, then log out and back in, or check the host's read-only socket (/run/libvirt/libvirt-sock-ro) is enabled.

VMs have no OS or hostname

The guest agent isn't answering. virsh domifaddr VM --source agent on the KVM host shows why: "not configured" means the domain has no agent channel, and "not connected" means qemu-guest-agent isn't running in the VM. A read-only account never gets agent data.

For login failures and host key mismatches, see SSH troubleshooting.

Set up libvirt discovery

On this page