gaschz/ansible-qubes
1
0
Fork 0
mirror of https://github.com/Rudd-O/ansible-qubes.git synced 2025-06-06 18:08:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation improvements

Browse Source
This commit is contained in:
Manuel Amador (Rudd-O) 2016-10-12 17:00:17 +00:00
parent 2b005faa0c
commit c28f2cdb0b
3 changed files with 140 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
README.md
View File

@ -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 = <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`).
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=<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
-------------------------------------------------
How to use the connection technology with SaltStack
---------------------------------------------------
You can also integrate this plugin with SaltStack's `salt-ssh` program, by:

33
doc/Enhance your Ansible with Ansible Qubes.md Normal file
View File

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

103
doc/Remote management of Qubes OS servers.md Normal file
View File

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