Example tasks¶
As we are developing the qubesos module heavily, the module will see some update to the syntax of the commands and available options.
For now please check the given examples below to learn more.
Our example inventory file¶
We can use the following command to create our inventory file. This will automatically include all of the VMs in your Qubes. You’ll have to re-run it after creating new VMs, if you want ansible to be able to work with them.
Warning
Remember that the following command will rewrite the inventory file.
ansible localhost -m qubesos -a 'command=createinventory'
Once you have an inventory file, you can run ansible playbooks like this:
ansible-playbook -i inventory my_playbook.yaml
If the [standalone_vms] section is empty in your inventory file, please delete that and also the corresponding connection details from the inventory file.
Make sure a vm is present¶
This is the preferred method to create a new vm if it is not there.
---
- hosts: local
connection: local
tasks:
- name: Create our test vm
qubesos:
guest: supansible
label: blue
state: present
template: "debian-9"
Only the guest name is the must have value, by default it will use the system default template and netvm. The default label color is red.
Setting different property values to a given vm¶
Note
This must be done when the vm is in shutdown state. Means this will also work while creating the vm.
---
- hosts: local
connection: local
tasks:
- name: Make sure the VM is present
qubesos:
guest: xchat2
state: present
properties:
memory: 1200
maxmem: 2400
netvm: 'sys-whonix'
default_dispvm: 'fedora-28-dvm'
label: "yellow"
- name: Make sure the xchat7 is present
qubesos:
guest: xchat2
state: present
- name: Run the xchat2 VM
qubesos:
guest: xchat2
state: running
Note
Always remember to move the state to running to get the vm up and running.
Resizing volume¶
This can be done using volume property. You can set the “private” volume size in AppVMs, and “root” volume size in StandAloneVM or TemplateVM. Right now it takes the size in bytes.
tasks:
- name: Make sure the VM is present
qubesos:
guest: xchat2
state: present
properties:
memory: 1200
maxmem: 2400
netvm: 'sys-whonix'
label: "yellow"
volume:
name: "private"
size: "5368709120"
Available properties¶
The following are the different available properties and their data type.
‘autostart’: bool
‘debug’: bool
‘include_in_backups’: bool
‘kernel’: str
‘label’: str
‘maxmem’: int
‘memory’: int
‘provides_network’: bool
‘template’: str
‘template_for_dispvms’: bool
‘vcpus’: int
‘virt_mode’: str
‘default_dispvm’: str
‘netvm’: str
‘features’: dict[str,str]
‘volume’: dict[str,str]
If you want to make changes to any existing vm, then first move it to shutdown state and then use properties along with the present state to change any value.
We can even add/update/remove features
from a VM using properties.
---
- hosts: local
connection: local
tasks:
- name: Make sure the VM is present with right features
qubesos:
guest: xchat2
state: present
properties:
memory: 1200
maxmem: 2400
netvm: 'sys-whonix'
default_dispvm: 'fedora-28-dvm'
label: "yellow"
features:
life: "better"
can_fix_world_problem: False
news: "good"
To delete a feature (if that exists), mark the value as “None”. To make it an empty string, that is the False value, use “” as value. Example is given below.
features:
life: "None"
news: ""
Different available states¶
destroyed
pause
running
shutdown
undefine
present
Warning
The undefine state will remove the vm and all data related to it. So, use with care.
Different available commands¶
The following commands are currently available.
shutdown¶
It will try to shutdown the vm normally.
ansible localhost -i inventory -m qubesos -a 'guest=xhcat2 command=shutdown'
destroy¶
The destroy command will forcefully shutdown the guest now.
ansible localhost -i inventory -m qubesos -a 'guest=xhcat2 command=destroy'
Note
Use the destroyed state to properly destroy a vm than this command.
Find all vms with a particular state¶
The following example will find all the vms with running state.
ansible localhost -i inventory -m qubesos -a 'state=running command=list_vms'
In the same way you can find vms with shutdown or paused state.
Install a package and copy to file to the remote vm and fetch some file back¶
Here is an example playbook (install_packages.yaml) for the same.
---
- hosts: xchat7
tasks:
- name: Ensure sl is at the latest version
ansible.builtin.package:
name: sl
state: latest
become: true
- name: example copying file with owner and permissions
copy:
src: foo.conf
dest: /etc/foo.conf
- name: Fetch os-relase
fetch:
src: /etc/os-release
dest: /tmp/fetched
You can run the playbook using the following command.
ansible-playbook -i inventory -b install_packages.yaml
You can also pass -u different_user or the set ansible_user value to run the above playbook as a different user in the vm.
Execute a command in every running vm¶
First remember to create our inventory file using createinventory
command.
Then you can use the following playbook. We are just running hostname
command
in every running vm.
---
- hosts: localhost
connection: local
tasks:
- name: Find running hosts
qubesos:
command: list_vms
state: running
register: rhosts
- hosts: "{{ hostvars['localhost']['rhosts']['list_vms'] }}"
connection: qubes
tasks:
- name: get hostname
command: hostname
Execute a command in every running vm except sys vms¶
---
- hosts: localhost
connection: local
tasks:
- name: Find running hosts
qubesos:
command: list_vms
state: running
register: rhosts
- name: Find non system vms
set_fact:
myvms: "{% for name in rhosts.list_vms %}{% if not name.startswith('sys-') %}{{ name }},{% endif %}{% endfor %}"
- hosts: "{{ hostvars['localhost']['myvms'] }}"
connection: qubes
tasks:
- name: Get hostname
command: hostname
Shutdown all vms except the system vms¶
We are not shutting down any VM which starts with sys- in this example.
---
- hosts: localhost
connection: local
tasks:
- name: Find running hosts
qubesos:
command: list_vms
state: running
register: rhosts
- debug: var=rhosts
- name: Shutdown each vm
qubesos:
command: destroy
guest: "{{ item }}"
with_items: "{{ rhosts.list_vms }}"
when: item.startswith("sys-") != True
You can use the above shutdown_all.yaml
playbook using the following command.
ansible-playbook -i inventory -b shutdown_all.yaml