community.libvirt.virt_net – Manage libvirt network configuration

Note

This plugin is part of the community.libvirt collection (version 1.0.2).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.libvirt.

To use it in a playbook, specify: community.libvirt.virt_net.

Synopsis

  • Manage libvirt networks.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6
  • python-libvirt
  • python-lxml

Parameters

Parameter Choices/Defaults Comments
autostart
boolean
    Choices:
  • no
  • yes
Specify if a given network should be started automatically on system boot.
command
string
    Choices:
  • define
  • create
  • start
  • stop
  • destroy
  • undefine
  • get_xml
  • list_nets
  • facts
  • info
  • status
  • modify
in addition to state management, various non-idempotent commands are available. See examples. Modify was added in version 2.1
name
string
name of the network being managed. Note that network must be previously defined with xml.

aliases: network
state
string
    Choices:
  • active
  • inactive
  • present
  • absent
specify which state you want a network to be in. If 'active', network will be started. If 'present', ensure that network is present but do not change its state; if it's missing, you need to specify xml argument. If 'inactive', network will be stopped. If 'undefined' or 'absent', network will be removed from libvirt configuration.
uri
string
Default:
"qemu:///system"
libvirt connection uri.
xml
string
XML document used with the define command.

Examples

# Define a new network
- community.libvirt.virt_net:
    command: define
    name: br_nat
    xml: '{{ lookup("template", "network/bridge.xml.j2") }}'

# Start a network
- community.libvirt.virt_net:
    command: create
    name: br_nat

# List available networks
- community.libvirt.virt_net:
    command: list_nets

# Get XML data of a specified network
- community.libvirt.virt_net:
    command: get_xml
    name: br_nat

# Stop a network
- community.libvirt.virt_net:
    command: destroy
    name: br_nat

# Undefine a network
- community.libvirt.virt_net:
    command: undefine
    name: br_nat

# Gather facts about networks
# Facts will be available as 'ansible_libvirt_networks'
- community.libvirt.virt_net:
    command: facts

# Gather information about network managed by 'libvirt' remotely using uri
- community.libvirt.virt_net:
    command: info
    uri: '{{ item }}'
  with_items: '{{ libvirt_uris }}'
  register: networks

# Ensure that a network is active (needs to be defined and built first)
- community.libvirt.virt_net:
    state: active
    name: br_nat

# Ensure that a network is inactive
- community.libvirt.virt_net:
    state: inactive
    name: br_nat

# Ensure that a given network will be started at boot
- community.libvirt.virt_net:
    autostart: yes
    name: br_nat

# Disable autostart for a given network
- community.libvirt.virt_net:
    autostart: no
    name: br_nat

# Add a new host in the dhcp pool
- community.libvirt.virt_net:
    name: br_nat
    command: modify
    xml: "<host mac='FC:C2:33:00:6c:3c' name='my_vm' ip='192.168.122.30'/>"

Authors

  • Maciej Delmanowski (@drybjed)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/libvirt/virt_net_module.html