# virt_net ## _Ansible_ module using libvirt to manage QEMU/KVM virtual networks.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

6.5 KiB


Ansible module using libvirt to manage QEMU/KVM networks

This module allow basic QEMU/KVM network management and comes in combination with the virt_vm Ansible module.

This module does not intend to cover every libvirt networks aspects and capabilities.

The objective of this module is to offer a suitable response to MCO System internal virtual networks configuration problematics.

There is no plan to make this module part of the community Ansible modules collection and, therefore, it will not be published to the Ansible Galaxy module collection.

This Ansible module is released under the WTFPL and you are encouraged to use it if it suits you needs.

You also may consider forking this module to adapt it to your specific needs.



The following packages are mandatory for this modules to be used (Centos 8 naming convention).

  • libvirt
  • libvirt-client
  • libvirt-daemon-driver-qemu
  • python3-libvirt
  • qemu-img
  • qemu-kvm
  • qemu-kvm-core
  • qemu-kvm-common
  • qemu-kvm-block-iscsi
  • qemu-kvm-block-ssh
  • qemu-kvm-block-gluster
  • qemu-kvm-block-rbd
  • qemu-kvm-block-curl
  • ipxe-roms-qemu
  • python3-libvirt
  • python3-lxml

Python3 modules

The following module is not available in basic Centos 8 packages repositories and must be installed with pip3

  • xmldiff


  • Generates and define persistent libvirt network from XML definition
  • Hot configuration modification and application whenever possible
  • Idempotent module


The module needs to have access to a template XML file (kvm_net.xml) stored in libvirt_tmp_path.

This template XML file must be deployed by a previous task.

The module needs to access XML domain files. These files will be searched in libvirt_qemu_conf_path.


This module is not a complete implementation of libvirt and some libvirt parameters are not available.

This module does not make any consistency ckeck on parameters. It's up to users to provide a consistent configuration to prevent failed module run or inconsistent network state. However, libvirt validates XML network files before defining the conresponding network so an invalid configuration would not be possible.

Registering a variable may be useful for debugging purpose (especially the live_settings dict that will show what has been successfully, or not, applied to the running network).

Known bugs

Most bugs are unknown :D

Please, send reports or patches to contact@at mcos.nc


var object type
uuid Network unique identifier str. Must be UUID formated
name Network name str. Should not contain space characters
mode Forward mode of the bridge interface (nat is actually the only supported mode and is default). See documentation str
bridge_name Name of the bridge interface that will be created str
mac_addr MAC address for the bridge interface str
dhcp_addr DHCP IP address used bay DHCP server str
dhcp_netmask Netmask for DHCP serveur network str
dhcp_first First available IP address of the DHCP range str
dhcp_last Last available IP address of the DHCP range str
dhcp_reserved List of 3 keys dicts such as {'mac_addr': ''', 'hostname': '', 'ip_addr': ''} list of dicts
active Define network state. Set to False, network will be immediately destroyed. Set to True, network will be started bool
autostart if set to True, network will auto start with libvirt daemon bool
present If set to False, existing network will be undefined and deleted. This operation is not recoverable. bool


The following example will create the default network. This network will be configured in nat mode and will use a bridge interface named virbr0 with MAC address 00:71:37:70:50:01.

The DHCP server for this network will be and its IP range will go from to

This network will reserve some IP addresses for the hosts specified by the dhcp_reserved list.

# vars/kvm_base.yml
# -- ---------------------------------------------------------------------------
libvirt_tmp_path: /var/lib/libvirt/tmp
libvirt_qemu_conf_path: /etc/libvirt/qemu
# vars/kvm_net.yml
# -- ---------------------------------------------------------------------------
- uuid: 'a45c13c9-6e30-48fd-962b-374194280b6e'
  name: default
  mode: nat
  bridge_name: virbr0
  mac_addr: 00:71:37:70:50:01
  - mac_addr: '00:71:37:05:00:01'
    hostname: test_vm
  - mac_addr: '00:71:37:05:00:02'
    hostname: test2_vm
  active: yes
  auto_start: yes
  present: yes
# roles/vm_host/tasks/kvm_net.yml
# -- ---------------------------------------------------------------------------
- name: include kvm_base vars
  include_vars: kvm_base.yml

- name: include kvm_net vars
  include_vars: kvm_net.yml

- name: create libvirt tmp dir
    path: "{{ libvirt_tmp_path }}"
    state: directory
    owner: root
    group: root
    mode: 0755

- name: base network XML file installation
    src: files/kvm_net.xml
    dest: "{{ libvirt_tmp_path }}/"
    owner: root
    group: root
    mode: '0644'

- name: KVM network configuration
    uuid: "{{ item.uuid }}"
    name: "{{ item.name }}"
    mode: "{{ item.mode }}"
    bridge_name: "{{ item.bridge_name }}"
    mac_addr: "{{ item.mac_addr }}"
    dhcp_addr: "{{ item.dhcp_addr }}"
    dhcp_netmask: "{{ item.dhcp_mask }}"
    dhcp_first: "{{ item.dhcp_first }}"
    dhcp_last: "{{ item.dhcp_last }}"
    dhcp_reserved: "{{ item.dhcp_reservation }}"
    autostart: "{{ item.autostart }}"
    active: "{{ item.active }}"
    present: "{{ item.present }}"
    libvirt_tmp_path: "{{ item.libvirt_tmp_path | default(libvirt_tmp_path) }}"
  register: net_creation
  loop: "{{ kvm_nets }}"