Documentation improvements

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:
+See [Enhance your Ansible with Ansible Qubes](doc/Enhance your Ansible with Ansible Qubes.md).
-
-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.
-
-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`).
 
 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
+How to use the connection technology with SaltStack
-  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=<IP of domU running SSH>
-```
-
-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
--------------------------------------------------
 
 You can also integrate this plugin with SaltStack's `salt-ssh` program, by:
 

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 = <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.
+
+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`).

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`.