# virt – Manages virtual machines supported by libvirt

- Synopsis

- Requirements

- Parameters

- Examples

- Return Values

- Status

## Synopsis

- Manages virtual machines supported by libvirt.

## Requirements

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

- python >= 2.6

- libvirt-python

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---

autostart
boolean

Choices:
- no
- yes

start VM at host startup.

command
-

Choices:
- create
- define
- destroy
- freemem
- get_xml
- info
- list_vms
- nodeinfo
- pause
- shutdown
- start
- status
- stop
- undefine
- unpause
- virttype

In addition to state management, various non-idempotent commands are available.

name - |  | name of the guest VM being managed. Note that VM must be previously defined with xml. This option is required unless command is `list_vms`.

state
-

Choices:
- destroyed
- paused
- running
- shutdown

Note that there may be some lag for state requests like `shutdown` since these refer only to VM states. After starting a guest, it may not be immediately accessible. state and command are mutually exclusive except when command=list_vms. In this case all VMs in specified state will be listed.

uri - | Default: "qemu:///system" | libvirt connection uri.
xml - |  | XML document used with the define command. Must be raw XML content using `lookup`. XML cannot be reference to a file.

## Examples

    # a playbook task line:
    - virt:
        name: alpha
        state: running

    # /usr/bin/ansible invocations
    # ansible host -m virt -a "name=alpha command=status"
    # ansible host -m virt -a "name=alpha command=get_xml"
    # ansible host -m virt -a "name=alpha command=create uri=lxc:///"

    # defining and launching an LXC guest
    - name: define vm
      virt:
        command: define
        xml: "{{ lookup('template', 'container-template.xml.j2') }}"
        uri: 'lxc:///'
    - name: start vm
      virt:
        name: foo
        state: running
        uri: 'lxc:///'

    # setting autostart on a qemu VM (default uri)
    - name: set autostart for a VM
      virt:
        name: foo
        autostart: yes

    # Defining a VM and making is autostart with host. VM will be off after this task
    - name: define vm from xml and set autostart
      virt:
        command: define
        xml: "{{ lookup('template', 'vm_template.xml.j2') }}"
        autostart: yes

    # Listing VMs
    - name: list all VMs
      virt:
        command: list_vms
      register: all_vms

    - name: list only running VMs
      virt:
        command: list_vms
        state: running
      register: running_vms

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
list_vms list | success | The list of vms defined on the remote system Sample: ['build.example.org', 'dev.example.org']
status string | success | The status of the VM, among running, crashed, paused and shutdown Sample: success

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Ansible Core Team

- Michael DeHaan

- Seth Vidal (@skvidal)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.