4.2. Listing Domains

⁠4.2. Listing Domains

The libvirt classes expose two lists of domains, the first contains running domains, while the second contains inactive, persistent domains. The lists are intended to be non-overlapping, exclusive sets, though there is always a small possibility that a domain can stop or start in between the querying of each set. The events class described later in this section provides a way to track all lifecycle changes avoiding this potential race condition.

The method for listing active domains, returns a list of domain IDs. Every running domain has a positive integer ID, uniquely identifying it amongst all running domains on the host. The method for listing active domains, listDomainsID, requires no parameters. The return value will be None upon error, or a Python list of the IDs expressed as ints.

⁠

Example 4.4. Listing active domains

# Example-4.py
#!/usr/bin/env python3
import sys
import libvirt

conn = None
try:
    conn = libvirt.open("qemu:///system")
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    exit(1)

domainIDs = conn.listDomainsID()
if domainIDs == None:
    print('Failed to get a list of domain IDs', file=sys.stderr)

print("Active domain IDs:")
if len(domainIDs) == 0:
    print('  None')
else:
    for domainID in domainIDs:
        print('  '+str(domainID))

conn.close()
exit(0)

In addition to the running domains, there may be some persistent inactive domain configurations stored on the host. Since an inactive domain does not have any ID identifier, the listing of inactive domains is exposed as a list of name strings. The return value will be None upon error, or a Python list of elements filled with names (strings).

⁠

Example 4.5. Listing inactive domains

# Example-5.py
#!/usr/bin/env python3
import sys
import libvirt

conn = None
try:
    conn = libvirt.open("qemu:///system")
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    exit(1)

domainNames = conn.listDefinedDomains()
if domainNames == None:
    print('Failed to get a list of domain names', file=sys.stderr)

domainIDs = conn.listDomainsID()
if domainIDs == None:
    print('Failed to get a list of domain IDs', file=sys.stderr)

domainNames = ""
try:
    if len(domainIDs) != 0:
        for domainID in domainIDs:
            domain = conn.lookupByID(domainID)
            domainNames.append(domain.name)
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    conn.close()
    exit(1)

print("All (active and inactive domain names:")
if len(domainNames) == 0:
    print('  None')
else:
    for domainName in domainNames:
        print('  '+domainName)

conn.close()
exit(0)

The methods for listing domains do not directly return the virDomain objects, since this may incur undue performance penalty for applications which wish to query the list of domains on a frequent basis. However, the Python libvirt module does provide the method listAllDomains which all the domains, active or inactive. It returns a Python list of the virDomain instances or None upon an error. The list can be empty when no persistent domains exist.

The listAllDomains method takes a single parameter which is a flag specifying a filter for the domains to be listed. If a value of 0 is specified then all domains will be listed. Otherwise any or all of the following constants can be added together to create a filter for the domains to be listed.

VIR_CONNECT_LIST_DOMAINS_ACTIVE

VIR_CONNECT_LIST_DOMAINS_INACTIVE

VIR_CONNECT_LIST_DOMAINS_PERSISTENT

VIR_CONNECT_LIST_DOMAINS_TRANSIENT

VIR_CONNECT_LIST_DOMAINS_RUNNING

VIR_CONNECT_LIST_DOMAINS_PAUSED

VIR_CONNECT_LIST_DOMAINS_SHUTOFF

VIR_CONNECT_LIST_DOMAINS_OTHER

VIR_CONNECT_LIST_DOMAINS_MANAGEDSAVE

VIR_CONNECT_LIST_DOMAINS_NO_MANAGEDSAVE

VIR_CONNECT_LIST_DOMAINS_AUTOSTART

VIR_CONNECT_LIST_DOMAINS_NO_AUTOSTART

VIR_CONNECT_LIST_DOMAINS_HAS_SNAPSHOT

VIR_CONNECT_LIST_DOMAINS_NO_SNAPSHOT

⁠

Example 4.6. Fetching all domain objects

# Example-6.py
#!/usr/bin/env python3
import sys
import libvirt

conn = None
try:
    conn = libvirt.open("qemu:///system")
except libvirt.libvirtError as e:
    print(repr(e), file=sys.stderr)
    exit(1)

print("All (active and inactive) domain names:")
domains = conn.listAllDomains(0)
if len(domains) != 0:
    for domain in domains:
        print('  '+domain.name())
else:
    print('  None')

conn.close()
exit(0)