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: "" Adding tags to a vm ------------------- We can also add tags to a VM using the tags values. It has to be a list of strings. :: --- - hosts: local connection: local tasks: - name: Make sure right tags are assigned qubesos: guest: xchat2 state: present tags: - "Linux" - "IRC" - "Chat" 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. removetags +++++++++++ Use this command with a list of tags to remove them from a given VM. :: --- - hosts: local connection: local tasks: - name: Make sure right tags are removed qubesos: guest: xchat2 command: removetags tags: - "Linux" - "IRC" - "Chat" 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