ansible-qubes/doc/Enhance your Ansible with Ansible Qubes.md

Enhance your Ansible with Ansible Qubes

This set of instructions assumes that you:

• are running within a Qubes OS system
• have an AppVM already set up (we'll call it managevm)
• have cloned this repository into that VM
• have Ansible installed in that VM
• have an Ansible setup already going on within that VM

Deploy the software to the right places

Integrate this software into your Ansible setup (within your managevm) VM) by:

1. setting up a connections_plugin = <directory> in your ansible.cfg file, pointing it to a directory you control, then
2. placing the qubes.py connection plugin in your Ansible connection_plugins directory as defined above, then
3. placing the qrun and bombshell-client executables in one of two locations:

• Anywhere on your Ansible machine's PATH.
• In a ../../bin directory relative to the qubes.py file.

Set up the policy file for qubes.VMShell

Edit (as root) the file /etc/qubes-rpc/policy/qubes.VMShell located on the file system of your dom0.

At the top of the file, add the following two lines:

managevm $anyvm allow

This first line lets managevm execute any commands on any VM on your system. You can also supply an ask policy instead of the allow policy specified above. Note that ask will make Qubes OS bother you every time you run commands (and Ansible plays) with the standard security prompt to allow qubes.VMShell on the target VM you're managing.

Now save that file, and exit your editor.

Optional: allow managevm to manage dom0

Before the line you added in the previous step, add this line:

managevm dom0 allow

This line lets managevm execute any commands in dom0. Be sure you understand the security implications of such a thing.

The next step is to add the RPC service proper. Edit the file /etc/qubes-rpc/qubes.VMShell to have a single line that contains:

exec bash

That is it. dom0 should work now.

Test qrun works

Test that qrun does the job. In the VM where you integrated your Ansible setup, run:

path/to/qrun <some VM> hostname

This should immediately return with the hostname of <some VM>, indicating that qrun successfully invoked bombshell-client on it, requesting the execution of hostname in <some VM>.

Register VMs on your Ansible inventory

After having done that, you can add Qubes VMs to your Ansible hosts file:

# The next line declares a simple connection to a domU on the same system.
workvm          ansible_connection=qubes
# The next line has a parameter which indicates to Ansible to first
# connect to the domU SSH at 1.2.3.4 before attempting to use
# bombshell-client to manage other VMs on the same system.
# See README.md for pointers to enabling remote management of Qubes servers.
vmonremotehost  ansible_connection=qubes management_proxy=1.2.3.4

You are now free to run ansible-playbook or ansible against those hosts. So long as those programs can find your ansible.cfg file, and your hosts file, it will work.