DEBOPS.LIBVIRTD(5)

NAME
debops.libvirtd - Manage libvirt virtualization host

SYNOPSIS

debops service/libvirtd [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

debops.libvirtd Ansible role manages the libvirtd <https://libvirt.org/> daemon on a virtualization host (server side). It will automatically install QEMU KVM support on any host that is not a KVM guest, to allow for easy deployment of KVM virtual machines.

Configuration of libvirtd instance (local or remote) can be performed using debops.libvirt role, which uses the libvirt API to manage the server.

GETTING STARTED

The management of the libvirt daemon is split into a few Ansible roles to allow easier control over a lot of configuration options. The roles are meant to be used together, with only the main role taking care of the environment itself. See the example playbook provided with the main role to see how they are used together.

The debops.libvirtd role will install libvirtd along with virtualization components required on the server. It manages the configuration of the main libvirtd daemon process. The role detects if the OpenNebula environment is enabled using the specific Ansible inventory groups and enables support for OpenNebula in libvirt.

The debops.libvirtd_qemu role manages the configuration of the QEMU/KVM virtualization environment. The role supports custom configuration required by OpenNebula nodes, which is enabled automatically when OpenNebula environment is detected by the main role.

  Example inventory

This role should be enabled on virtualization hosts, you can do this by adding a host to the [debops_service_libvirtd] group:

[debops_service_libvirtd]
hostname

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.libvirtd role:

---
- name: Install and manage libvirtd
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_libvirtd' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ libvirtd__apt_preferences__dependent_list }}'
    - role: nsswitch
      tags: [ 'role::nsswitch', 'skip::nsswitch' ]
      nsswitch__dependent_services:
        - '{{ libvirtd__nsswitch__dependent_services }}'
    - role: ferm
      tags: [ 'role::ferm', 'skip::ferm' ]
      ferm__dependent_rules:
        - '{{ libvirtd__ferm__dependent_rules }}'
        - '{{ libvirtd_qemu__ferm__dependent_rules }}'
    - role: python
      tags: [ 'role::python', 'skip::python' ]
      python__dependent_packages3:
        - '{{ libvirtd__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ libvirtd__python__dependent_packages2 }}'
    - role: libvirtd
      tags: [ 'role::libvirtd', 'skip::libvirtd' ]
    - role: libvirtd_qemu
      tags: [ 'role::libvirtd_qemu', 'skip::libvirtd_qemu', 'role::libvirtd', 'skip::libvirtd' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::libvirtd
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

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

  libvirtd__configuration

The libvirtd__*_configuration variables are YAML lists which define the contents of the /etc/libvirt/libvirtd.conf configuration file. The lists are parsed by the template in order defined by the libvirtd__combined_configuration variable, which allows modification of the parameters defined in earlier lists by the latter ones.

Each element of the list is a YAML dictionary. The dictionary can specify libvirtd configuration parameters as dictionary keys and they values as dictionary values:

libvirtd__configuration:
  - 'min_workers': 5
    'max_workers': 20
  - 'unix_sock_group':    'libvirt'
    'unix_sock_ro_perms': '0770'
    'unix_sock_rw_perms': '0770'

Parameters specified in this way will automatically be configured as "present" in the configuration file to override any "comment" state (see below).

Alternatively, each YAML dictionary can contain a name key, which tells the role to interpret a given dictionary using specific parameters:

name
    Required. Name of the parameter to manage. Parameter names can contain alphanumeric characters and an underscore (_) character. See the /etc/libvirt/libvirtd.conf configuration file for a list of known parameters and their meaning.

state
    Optional. If not specified or present, the parameter will be present in the configuration file. If absent, the parameter will not be included in the generated configuration file. If comment, the parameter will be commented out in the configuration file. If ignore, a given YAML dictionary will not be evaluated.

comment
    Optional. String or a YAML dictionary with a comment for a particular parameter.

value
    Optional. Specify the value of a given parameter. Values can be booleans, numbers, quoted strings or YAML lists of strings; empty variants work as well. If value parameter is not specified, an empty string will be set and the parameter will be automatically quoted.

section
    Optional. Specify the name of the section of the configuration file in which the parameter should be placed. Section names and their order are defined in the libvirtd__configuration_sections variable. If a section is not specified, an unknown section will be automatically selected.

weight
    Optional. Positive or negative number that affects the placement of the parameter within the configuration file section. The heavier the "weight", the lower the parameter will be placed; negative numbers make the "weight" parameter lighter therefore it will be placed higher. If weight is not specified, it's set at 0.

  Examples

Add custom parameters:

libvirtd__configuration:
  - name: 'custom_param'
    value: 'custom-value'

Change the section and order of existing parameters:

libvirtd__configuration:
  - name: 'listen_tls'
    section: 'authn'
    weight: 30

Comment out a specific parameter conditionally:

libvirtd__configuration:
  - name: 'listen_addr'
    value: '0.0.0.0'
    state: '{{ "present"
               if ansible_distribution == "Debian"
               else "comment" }}'

  libvirtd__configuration_sections

This list defines the sections of the /etc/libvirt/libvirtd.conf configuration file, as well as their order in the generated file. Each element of the list is a YAML dictionary with specific parameters:

name
    Required. Name of the section, specified in the configuration entries as the section parameter. Should be short and recognizable.

title
    Required. A short description of the given configuration file section which will be added as a header.

comment
    Optional. a string or a YAML dictionary with additional comments about a given section, added after the title.

state
    Optional. If not specified or present, the section will be included in the configuration file. If absent, the entire section (including the parameters that belong to it) will be omitted in the generated configuration file. If hidden, the section will be present but the title and section comment will not be included.

  Examples

Set a custom list of sections:

libvirtd__configuration_sections:
  - name: 'section-one'
    title: 'First section'
  - name: 'section-two'
    title: 'Section with hidden title'
    state: 'hidden'
  - name: 'section-three'
    title: 'Third section'

AUTHOR
Maciej Delmanowski, Robin Schneider

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others