From c28f2cdb0bcfc545094bb1b46d2d1cd34ab69416 Mon Sep 17 00:00:00 2001 From: "Manuel Amador (Rudd-O)" Date: Wed, 12 Oct 2016 17:00:17 +0000 Subject: [PATCH] Documentation improvements --- README.md | 67 +----------- ...Enhance your Ansible with Ansible Qubes.md | 33 ++++++ doc/Remote management of Qubes OS servers.md | 103 ++++++++++++++++++ 3 files changed, 140 insertions(+), 63 deletions(-) create mode 100644 doc/Enhance your Ansible with Ansible Qubes.md create mode 100644 doc/Remote management of Qubes OS servers.md diff --git a/README.md b/README.md index f9856ac..8e2ef51 100644 --- a/README.md +++ b/README.md @@ -91,74 +91,15 @@ That's it -- `bombshell-client` should work against dom0 now. How to use the connection technology with automation tools like Ansible ----------------------------------------------------------------------- -You integrate it into your Ansible setup by: - -1. setting up a `connections_plugin = ` 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. - -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 below for instructions to enable remoting. -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. Note that Qubes OS will bother you every time you run -commands with the prompt to allow `qubes.VMShell` on the target VM you're -managing, unless you set said permission to default to yes (the pertinent -file to edit is in the `dom0` of the target Qubes OS machine, path -`/etc/qubes-rpc/policy/qubes.VMShell`). +See [Enhance your Ansible with Ansible Qubes](doc/Enhance your Ansible with Ansible Qubes.md). Enabling bombshell-client remote access to VMs in other machines ---------------------------------------------------------------- -Do this at your own risk. On the other machine: +See [Remote management of Qubes OS servers](doc/Remote management of Qubes OS servers.md). -* Ensure that Qubes OS instance has at least one `domU` VM running SSH, which - we will call the *target VM*. It's usually best to use a StandaloneVM for - the purpose. -* Enable remote network access to that VM by using - [Qubes network server](https://github.com/Rudd-O/qubes-network-server). - Set the necessary firewall rules on the VM to permit SSH connections from - the source VM. -* Ensure the target VM's SSH server lets your source VM log in passwordlessly - (pubkey auth). -* Ensure the policy file in the other machine's `dom0` (the file is located at - `/etc/qubes-rpc/policy/qubes.VMShell`) allows the target VM (the one - with the SSH server) to execute `qubes.VMShell` without prompting (otherwise - you will have to physically walk over to the other machine and authorize - each execution by hand). Usually a line `targetvm $anyvm allow` suffices. - -After declaring in your Ansible `hosts` file the VMs on the other machine that -you want to manage, add the following host attribute to each one. - -``` -vmonremotehost ansible_connection=qubes management_proxy= -``` - -That's it. Running `ansible vmonremotehost -m shell -a whoami` should provide -you with a crisp visual of the results of `whoami` on the VM `vmonremotehost`. - -The `management_proxy` variable tells the Ansible Qubes connection plugin -to first bridge the connection via SSH over to the target VM, and to then -execute `bombshell-client` to gain access to `vmonremotehost`. - -How to use the connection technology with Ansible -------------------------------------------------- +How to use the connection technology with SaltStack +--------------------------------------------------- You can also integrate this plugin with SaltStack's `salt-ssh` program, by: diff --git a/doc/Enhance your Ansible with Ansible Qubes.md b/doc/Enhance your Ansible with Ansible Qubes.md new file mode 100644 index 0000000..29fec86 --- /dev/null +++ b/doc/Enhance your Ansible with Ansible Qubes.md @@ -0,0 +1,33 @@ +# Enhance your Ansible with Ansible Qubes + +Integrate this software into your Ansible setup by: + +1. setting up a `connections_plugin = ` 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. + +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 below for instructions to enable remoting. +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. Note that Qubes OS will bother you every time you run +commands with the prompt to allow `qubes.VMShell` on the target VM you're +managing, unless you set said permission to default to yes (the pertinent +file to edit is in the `dom0` of the target Qubes OS machine, path +`/etc/qubes-rpc/policy/qubes.VMShell`). diff --git a/doc/Remote management of Qubes OS servers.md b/doc/Remote management of Qubes OS servers.md new file mode 100644 index 0000000..e765195 --- /dev/null +++ b/doc/Remote management of Qubes OS servers.md @@ -0,0 +1,103 @@ +# Remote management of Qubes OS servers + +This tutorial will help you combine [Qubes network server](https://github.com/Rudd-O/qubes-network-server) and Ansible to remotely manage a Qubes OS machine, and all VMs within it. + +## Set up the SSH access on the Qubes server + +Follow the [instructions to set up an SSH server on Qubes network server](https://github.com/Rudd-O/qubes-network-server/tree/master/doc/Setting up an SSH server.md). We'll use the same conventions as outlined in that document for the rest of this tutorial. + +## Set up Qubes policy for the `exp-manager` VM + +Since our objective is to manage the entire server machine from the `exp-manager` VM, we need +to set up a policy that allows us to remotely execute commands on any VM of the Qubes +network server, without having to be physically present to click any dialogs authorizing +the execution of those commands. + +In `dom0` of your Qubes server, edit `/etc/qubes-rpc/policy/qubes.VMShell` to add, +at the top of the file, a policy that looks like this: + +``` +exp-manager $anyvm allow +``` + +This tells Qubes OS that `exp-manager` is now authorized to run any command in any of the VMs. + +Try it out now. SSH from your manager machine into `exp-manager` and run: + +``` +qvm-run exp-net 'echo yes ; hostname' +``` + +You should see `yes` followed by `exp-net` on the output side. + +### If you want `exp-manager` to also run commands on `dom0` + +If you expect that you will need to run commands in `dom0` from your manager machine, +then you will have to create a file `/etc/qubes-rpc/qubes.VMShell` as `root` in `dom0`, +with the contents `/bin/bash` and permission mode `0644`. Doing this will enable you +to run commands on `dom0` which you can subsequently test in `exp-manager` by running command: + +``` +qvm-run dom0 'echo yes ; hostname' +``` + +like you did before. + +## Integrate your Ansible setup + +Assuming you have set up Ansible on your manager machine, [integrate +Ansible Qubes into your setup](./Enhance your Ansible with Ansible Qubes.md). + +Now, to your Ansible `hosts` file, add an inventory entry: + +``` +exp-manager ansible_connection=ssh ansible_ssh_host=x.y.z.w +``` + +Try to see if your `exp-manager` responds to Ansible now. On your +manager machine, run: + +``` +ansible exp-manager -m shell -a "hostname ; whoami" +``` + +You should see `exp-manager` promptly followed by `user` on the output. + +## Add VMs you want to manage to your Ansible setup + +At this point, all you must do is add to your Ansible `hosts` file +any number of VMs you want to manage. For example, if you'd like to +run commands on `exp-net`, you'd add it as follows: + +``` +exp-net ansible_connection=qubes management_proxy=x.y.z.w +``` + +This tells Ansible to use the Qubes connection plugin, and to proxy its +`bombshell-client` connection through `exp-manager`. The +`management_proxy` host variable tells the Ansible Qubes connection plugin +to first bridge the connection via SSH over to the target VM, and to then +execute `bombshell-client` to gain access to `exp-manager`. + +Thus, in your manager machine, run: + +``` +ansible exp-net -m shell -a "hostname ; whoami" +``` + +Ansible should promptly print `exp-net` followed by `user`. + +If you set up `dom0` to run commands on it, the same configuration can +be applied to it. In your `hosts` file, add: + +``` +dom0 ansible_connection=qubes management_proxy=x.y.z.w +``` + +Then, in your manager machine, run: + +``` +ansible dom0 -m shell -a "hostname" +``` + +Ansible should promptly print `dom0`.