Default variables: configuration

Some of debops.libvirt default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

libvirt__connections
libvirt__networks
libvirt__pools

libvirt__connections 

This is a dictionary variable which defines libvirt connections and their aliases. Each key is an alias of a given connection. Currently only local and SSH connections are supported by the role.

Examples

Define local and remote libvirt connections:

libvirt__connections:
  'localhost':  'qemu:///system'
  'vm-host':    'qemu+ssh://vm.example.org/system'
  'local-lxc':  'lxc:///'
  'lxc-host':   'lxc+ssh://lxc.example.org/'

libvirt__networks 

This is a list of network definitions specified as YAML dicts. Each dict defines separate network interface which then can be configured and enabled in libvirt.

List of parameters supported by all network types:

name

Required. Name of the network interface used as a handle in virsh and virt-manager.

type

Required. Specifies what XML template will be used to configure the interface. Different templates might require different parameters.

Currently supported templates are:

bridge: Network will be configured as a simple host bridge, all configuration is done on the host (outside of libvirt). You need to specify item.bridge parameter as name of the host bridge to use.
direct: The network will be configured as a MACVTAP interface. You need to specify the item.bridge parameter as the underlying host NIC to use.
dnsmasq: Network will be configured as a bridge with dnsmasq used as internal DNS and DHCP server.

bridge

Required. Name of the network interface to use.

state

Specify the state the network should be in. If not specified, interface will be defined and started automatically. Known states:

undefined or absent:: Network will be destroyed if active and removed from libvirt configuration.
present:: Network will be defined in libvirt but will not actively start at the creation time. It might or might not start on boot depending on item.autostart parameter.
active:: Network will be defined if not present and automatically started at creation time, or if it's inactive.

uuid

String, optional, if not set, a random UUID will automatically be generated for this network.

autostart

Boolean, optional, defaults to True. Specify if a network should start (True) or not (False) at boot time.

uri

Name of the libvirt connection configured in ~/.config/libvirt/libvirt.conf to use to configure this network. If not specified, default connection (most likely localhost which is an alias configured to qemu:///system by default) is used.

interface_present

Specify a name of a network interface on the host; network will be configured only when a specified interface exists. This only works in the "local mode", not on remote libvirt connections.

List of parameters supported by the direct network type:

trust: Boolean, optional, defaults to True. Whether the guest VM should be trusted to manage its own MAC address and multicast group memberships. Necessary for IPv6 support.

List of parameters supported by the dnsmasq network type:

addresses: List of IPv4 or IPv6 addresses in host/prefix format. These IP addresses will be configured on the create bridge. If DHCP is enabled, it will be configured only on first IPv4 and first IPv6 network specified (libvirt limitation).
forward: Boolean. If specified, traffic to external networks will be forwarded to the upstream interface.
forward_mode: Name of the forward mode to use. If not specified, nat will be configured by default. See libvirt network documentation for more details.
dhcp: Boolean. If present and True, enable DHCP server for this network. Only first subnet of each type (IPv4, IPv6) will have DHCP configured.
dhcp_range: List which specifies start and end of DHCP range offered to hosts in the network. If not specified, [ '10', '250' ] is used by default to fit in /24 CIDR network.
domain: DNS domain to sent to hosts by DHCP server.
domain_local: Boolean. Specify if requests that don't exist for local domain in dnsmasq should be forwarded to upstream DNS servers (they are forwarded by default).
bootp: Boolean. Enable or disable support for BOOTP/PXE options in DHCP server.
bootp_file: File path sent to the host which instructs them to download a given file from TFTP server. If none is specified, /undionly.kpxe is used, which is default for iPXE.
bootp_server: IP address of the TFTP server to which hosts are redirected by DHCP server. If it's not set, DHCP server points hosts to its own IP address.

Examples

Create host bridge network, only if a given bridge exists:

libvirt__networks:
  - name: 'external'
    type: 'bridge'
    bridge: 'br0'
    interface_present: 'br0'

Create a NAT network on remote libvirt host:

libvirt__networks:
  - name: 'nat'
    type: 'dnsmasq'
    bridge: 'virbr0'
    addresses: [ '192.0.2.1/24', '2001:db8:ab::1/64' ]
    forward: True
    dhcp: True
    uri: 'vm-host'

libvirt__pools 

This is a list of storage pool definitions specified as YAML dicts. Each dict defines separate storage pool which then can be configured and enabled in libvirt.

List of parameters supported by all storage pool types:

name

Required. Name of the storage pool used as a handle in virsh and virt-manager.

type

Required. Specifies what XML template will be used to configure the pool. Different templates might require different parameters.

Currently supported templates are:

dir:

Storage pool will be configured as a directory in existing filesystem. You need to specify an absolute path to a directory using item.path parameter.

Directory should already exist before storage pool can be activated, otherwise you can create it using the build command.

nfs:

Storage pool is a directory exported from a NFS server, which will be mounted on a given path. See below for supported parameters.

logical: Storage pool is a LVM volume group which can be located on local or remote block device(s). See below for supported parameters.

state

Specify the state the storage pool should be in. If not specified, pool will be defined and started automatically. Known states:

deleted:: Storage pool contents will be erased (this is a destructive operation), and it will be undefined afterwards.

undefined or absent: storage pool will be destroyed if active and removed from libvirt configuration.
present: storage pool will be defined in libvirt but will not actively start at the creation time. It might or might not start on boot depending on item.autostart parameter. Storage pool might need to be built before it can be activated, which can be done using build command.
inactive: storage pool will be stopped if present.
active: storage pool will be defined if not present and automatically started at creation time, or if it's inactive.

autostart

Boolean, optional, defaults to True. Specify if a storage pool should start (True) or not (False) at boot time.

uri

Name of the libvirt connection configured in ~/.config/libvirt/libvirt.conf to use to configure this storage pool. If not specified, default connection (most likely localhost which is an alias configured to qemu:///system by default) is used.

List of parameters supported by nfs storage pool type:

host: IP address or hostname of NFS server which holds the exported filesystem.
src: Path on the NFS server with exported filesystem, for example /srv/nfs.
path: Path in the local filesystem where remote NFS share should be mounted, for example /media/nfs/remote-vm. If this directory does not exist, it will be created by debops.libvirt role automatically.

List of parameters supported by logical storage pool type:

name: Name of the storage pool will be used as name of the LVM Volume Group.
devices: List of block devices which should be used to create LVM Volume Group. If this list is defined, debops.libvirt will run the build command to attempt and create new Volume Group. If it's not specified, existing Volume Group will be configured instead (it can be created beforehand using LVM commands).

Examples

Create a directory storage pool on local machine (default libvirt storage pool:

libvirt__pools:
  - name: 'default'
    type: 'dir'
    path: '/var/lib/libvirt/images'

Create a NFS-based storage pool on remote libvirt host:

libvirt__pools:
  - name: 'nfs-pool'
    type: 'nfs'
    host: 'nfs.example.org'
    src:  '/srv/nfs'
    path: '/media/nfs/libvirt'
    uri:  'vm-host'

Create a LVM-based storage pool from existing Volume Group:

libvirt__pools:
  - name: 'vg_kvm'
    type: 'logical'

Default variables: configuration

libvirt__connections

Examples

libvirt__networks

Examples

libvirt__pools

Examples

libvirt__connections 

libvirt__networks 

libvirt__pools 