REFERENCE.md

Reference

Table of Contents

Classes

• libvirt: Install the necessary packages and make sure libvirtd is running
• libvirt::install: Install the necessary packages
• libvirt::ksm: A class to configure Kernel Shared Memory components. This isn't strictly tied to libvirt, but it's included in the qemu-kvm package so
• libvirt::kvm: Set up libvirt to use KVM
• libvirt::polkit: Add a rule file allowing members of a group to use libvirt
• libvirt::service: Make sure libvirtd is running

Defined types

• libvirt::vm: The options in the vm() define use the exact same field syntax as the virt-install command. See virt-install(1) for variable details

Classes

libvirt

Install the necessary packages and make sure libvirtd is running

Parameters

The following parameters are available in the libvirt class:

• package_list
• service_ensure
• ksm
• kvm
• load_kernel_modules
• manage_sysctl
• package_ensure

package_list

Data type: Array[String]

List of packages related to libvirt to be managed

Default value:

[
    'virt-viewer'
  ]

service_ensure

Data type: String

ensure setting for libvirtd

Default value: running

ksm

Data type: Boolean

Manage Kernel Shared Memory

Default value: false

kvm

Data type: Boolean

Manage kvm

Default value: true

load_kernel_modules

Data type: Boolean

Manage kernel modules from this module

Default value: true

manage_sysctl

Data type: Boolean

Manage associated sysctl settings from this module

Default value: true

package_ensure

Data type: String

Ensure setting for all packages in this module

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

libvirt::install

Install the necessary packages

Parameters

The following parameters are available in the libvirt::install class:

• package_list
• package_ensure

package_list

Data type: Array[String]

List of packages related to libvirt to be managed

Default value: $libvirt::package_list

package_ensure

Data type: String

Ensure setting for all packages in this module

Default value: $libvirt::package_ensure

libvirt::ksm

A class to configure Kernel Shared Memory components.

This isn't strictly tied to libvirt, but it's included in the qemu-kvm package so it made sense to include it here.

Since there are no useful man pages at this time, the comments were lifted from the configuration files.

Parameters

The following parameters are available in the libvirt::ksm class:

• package_list
• package_ensure
• enable
• ksm_max_kernel_pages
• ksm_monitor_interval
• ksm_sleep_msec
• ksm_npages_boost
• ksm_npages_decay
• ksm_npages_min
• ksm_npages_max
• ksm_thres_coef
• ksm_thres_const

package_list

Data type: Array[String]

The list of required packages for this module. Source: Data in Modules

package_ensure

Data type: String

ensure setting for all packages in this module

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

enable

Data type: Boolean

Enable the ksm related sevices

Default value: true

ksm_max_kernel_pages

Data type: Optional[Integer]

The maximum number of unswappable kernel pages which may be allocated by ksm (0 for unlimited) If unset, defaults to half of total memory.

Default value: undef

ksm_monitor_interval

Data type: Integer

The number of seconds ksmtuned should sleep between tuning adjustments Every KSM_MONITOR_INTERVAL seconds ksmtuned adjust how aggressive KSM will search for duplicated pages based on free memory.

Default value: 60

ksm_sleep_msec

Data type: Integer

Millisecond sleep between ksm scans for 16Gb server. Smaller servers sleep more, bigger sleep less. How many Milliseconds to sleep between scans of 16GB of RAM. The actual sleep time is calculated as sleep = KSM_SLEEP_MSEC * 16 / Total GB of RAM The final sleep value will be written to /sys/kernel/mm/ksm/sleep_millisecs

Default value: 100

ksm_npages_boost

Data type: Integer

Amount to increment the number of pages to scan. The number of pages to be scanned will be increased by KSM_NPAGES_BOOST when the amount of free ram < threshold (see KSM_THRES_* below)

Default value: 3000

ksm_npages_decay

Data type: Integer[default,0]

Amount to decrease the number of pages to scan The number of pages to be scanned will be decreased by KSM_NPAGES_DECAY when the amount of free ram

= threshold (see KSM_THRES_* below)

Default value: -50

ksm_npages_min

Data type: Variant[Enum['shmall'],Integer]

Minimum number of pages to be scanned at all times If this variable is set to 'shmall', then half of the value in /proc/sys/kernel/shmall will be used.

Default value: 'shmall'

ksm_npages_max

Data type: Variant[Enum['shmall'],Integer]

Maximum number of pages to be scanned at all times If this variable is set to 'shmall', then the value in /proc/sys/kernel/shmall will be used.

Default value: 'shmall'

ksm_thres_coef

Data type: Integer

If free memory is less than this percentage KSM will be activated. NOTE: Only KSM_THRES_CONST or KSM_THRES_COEF is actually used. Whichever results in a larger number wins.

Default value: 10

ksm_thres_const

Data type: Optional[Integer]

If free memory is less than this number KSM will be activated NOTE: Only KSM_THRES_CONST or KSM_THRES_COEF is actually used. Whichever results in a larger number wins.

Default value: undef

libvirt::kvm

Set up libvirt to use KVM

Parameters

The following parameters are available in the libvirt::kvm class:

• package_list
• package_ensure
• manage_sysctl
• load_kernel_modules

package_list

Data type: Any

List of packages to be managed for KVM

• Defaults in module data

package_ensure

Data type: Any

Default value: $::libvirt::package_ensure

manage_sysctl

Data type: Any

Default value: $::libvirt::manage_sysctl

load_kernel_modules

Data type: Any

Default value: $::libvirt::load_kernel_modules

libvirt::polkit

Add a rule file allowing members of a group to use libvirt

Parameters

The following parameters are available in the libvirt::polkit class:

• ensure
• group
• priority
• result
• local
• active

ensure

Data type: Enum['present','absent']

Create or destroy the rules file

Default value: 'present'

group

Data type: Variant[String,Array[String]]

The group that membership is checked against

Default value: 'virtusers'

priority

Data type: Integer[0,99]

Priority of the file to be created

Default value: 10

result

Data type: Polkit::Result

Deny of approve access

Default value: 'yes'

local

Data type: Boolean

Require users to be at a local seat

Default value: true

active

Data type: Boolean

Require users to have an active session

Default value: true

libvirt::service

Make sure libvirtd is running

Parameters

The following parameters are available in the libvirt::service class:

• service_ensure

service_ensure

Data type: String

ensure setting for libvirtd

Default value: $libvirt::service_ensure

Defined types

libvirt::vm

The options in the vm() define use the exact same field syntax as the virt-install command.

See virt-install(1) for variable details.

If virbr0 doesn't do what you need it to, you may need to set up your own bridge using the networking module.

If you do set up your own bridge, make sure your call of this define 'require's that network stanza.

Examples

libvirt::vm { 'test_system':
   mac_addr          => 'AA:BB:CC:DD:EE:FF',
   size              => 20,
   networks          => { 'type' => 'bridge', 'target' =>  'br0' },
   pxe               => true,
   disk_opts         => { 'bus' => 'virtio' }
}

Parameters

The following parameters are available in the libvirt::vm defined type:

• size
• mac_addr
• sparse
• mem
• arch
• machine
• ostype
• osvariant
• bridge
• networks
• vcpus
• vcpu_options
• numatune
• cpu
• description
• security
• cpuset
• full_virt
• accelerate
• sound
• noapic
• noacpi
• pxe
• cdrom_path
• location_url
• ks_url
• target_dir
• disk_bus
• disk_opts
• graphics
• virt_type
• host_device
• watchdog

size

Data type: Integer

mac_addr

Data type: Optional[String]

Default value: undef

sparse

Data type: Boolean

Default value: false

mem

Data type: Integer

Default value: 512

arch

Data type: Optional[String]

Default value: undef

machine

Data type: Optional[String]

Default value: undef

ostype

Data type: String

Default value: 'linux'

osvariant

Data type: String

Optimize the guest configuration for a specific operating system (ex. 'fedora18', 'rhel7', 'winxp'). See man virt-install for more information.

Default value: 'rhel7'

bridge

Data type: String

A legacy option for connecting to a single bridge. '$bridges' is now the favored option.

Default value: 'virbr0'

networks

Data type: Optional[Array]

An array of hashes of networks where you can specify both the mac and model of each network if desired.

This option overrides '$bridge'

Example: [ { 'type' => 'bridge', 'target' => '', 'mac' => '', # Optional 'model' => '', # Optional }, { 'type' => 'network' 'target' => '', 'mac' => '', # Optional 'model' => '', # Optional } ]

Default value: undef

vcpus

Data type: Integer

Default value: 1

vcpu_options

Data type: Optional[Hash]

A hash of options that match the vcpus extended arguments. Options will be passed directly and without translation. Example: { 'maxvcpus' => '3', 'sockets' => '2' }

Default value: undef

numatune

Data type: Optional[Hash]

A hash of options that correspond to the numatune options. Example: { 'nodeset' => '1,2,3', 'mode' => 'preferred' }

Default value: undef

cpu

Data type: Optional[Hash]

A hash of the 'cpu' options: { 'name' => '<cpu_name>', 'features' => ['+','-','disable='] 'match' => 'vendor' => }

Default value: undef

description

Data type: Optional[String]

Default value: undef

security

Data type: Optional[Hash]

A hash of the 'security' options: { 'type' => '' 'label' => '' }

Default value: undef

cpuset

Data type: Optional[String]

Default value: undef

full_virt

Data type: Boolean

Default value: true

accelerate

Data type: Boolean

Default value: true

sound

Data type: Boolean

Default value: true

noapic

Data type: Boolean

Default value: false

noacpi

Data type: Boolean

Default value: false

pxe

Data type: Boolean

Default value: false

cdrom_path

Data type: Optional[String]

Default value: undef

location_url

Data type: Optional[String]

This has been overloaded to accept DVD ISO image paths as well. If the target ends in '.iso' the correct option will be used.

Default value: undef

ks_url

Data type: Optional[String]

Default value: undef

target_dir

Data type: Stdlib::AbsolutePath

The directory in which to install the VM.

Default value: '/var/VM'

disk_bus

Data type: Optional[String]

A legacy option now superseded by '$disk_opts'

Default value: undef

disk_opts

Data type: Optional[Hash]

A hash of options as presented to the disk parameter of virt-install Supported options are: bus, perms, cache, format, io, error_policy, serial

Default value: undef

graphics

Data type: Hash

A hash of options that are passed to the '--graphics' option of virt-install, see the man page for details.

Example: { 'type' => 'vnc', 'port' => #optional 'tlsport' => #optional 'listen' => #optional 'keymap' => #optional 'password' => #optional 'passwordvalidto' => #optional }

Default value: { 'type' => 'vnc', 'keymap' => 'en_us' }

virt_type

Data type: Optional[String]

Default value: undef

host_device

Data type: Optional[String]

Default value: undef

watchdog

Data type: Hash

A hash of options to pass to the watchdog option of virt-install. Options are 'model', and 'action'(optional)

Default value: { 'model' => 'default' }