gaschz/ansible-qubes
1
0
Fork 0
mirror of https://github.com/Rudd-O/ansible-qubes.git synced 2025-03-01 14:22:33 +01:00
Code Issues Packages Projects Releases Wiki Activity

rewrite readme to be clearer

Browse Source
This commit is contained in:
Manuel Amador (Rudd-O) 2015-10-22 01:17:43 +00:00
parent f480d4a87b
commit 3347c9722c
1 changed files with 101 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
README.md
View File

@ -1,60 +1,45 @@
Ansible connection plugin for Qubes Qubes OS DevOps automation toolkit
=================================== ==================================
This is a connection plug-in for Ansible and set of commands for SaltStack This is a kit of several tools to help you automate your Qubes OS
`salt-ssh` that enables you to use Ansible and SaltStack to manage your operations:
Qubes OS VMs:
* from the `dom0`, 1. A computer program `bombshell-client` that can run in dom0 or
* from any VM within your Qubes OS machine, or even in any domU, which uses the `qubes.VMShell` Qubes RPC service
* from a machine that has SSH access to your Qubes OS machine to provide an *interactive* session with a shell interpreter
(assuming there exists a proxy Qubes OS VM with SSH listening on the (or any program of your choice) from a VM to any other VM.
target Qubes OS machine, and said VM is permitted to run `qubes.VMShell` 2. A connection plug-in for Ansible that uses `bombshell-client`
in other VMs of that system). to make the full power of Ansible automation available to
Qubes OS administrators and users.
3. A set of commands for SaltStack `salt-ssh` that fake SSH
and SCP using `bombshell-client` to enable SaltStack management
of Qubes OS VMs.
`bombshell-client` and the other programs in this toolkit that
depend on it, can be used to remotely manipulate Qubes OS VMs:
* from the `dom0` within your Qubes OS machine
* from any `domU` within your Qubes OS machine
* to the `dom0` (you must install the `qubes.VMShell` RPC handler
on `dom0` first) within your Qubes OS machine
* to any `domU` within your Qubes OS machine (no work needed)
* to any `dom0` or `domU` in a remote Qubes OS machine, provided:
* that Qubes OS instance has at least one `domU` VM running SSH,
* the SSH server is accessible via the network from the client
machine running `bombshell-client` (firewall rules, etc.)
* the SSH server lets the client log in passwordlessly (pubkey auth)
* you have set up the `dom0` `/etc/qubes-rpc/policy/qubes.VMShell`
such that RPC invocations from the `domU` running the SSH server
are allowed to other VMs.
What this means:
With this toolkit, now you can script the setup and maintenance of
an entire network of Qubes OS machines.
**Warning: this is a massive hack.** Please be *absolutely sure* you **Warning: this is a massive hack.** Please be *absolutely sure* you
have reviewed this code before using it. Contributions welcome. have reviewed this code before using it. Contributions welcome.
How to use this
---------------
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:
```
workvm ansible_connection=qubes
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.
You can also integrate this plugin with SaltStack's `salt-ssh` program, by:
1. placing the `bombshell-client`, `qrun`, `qssh` and `qscp` commands
in some directory of your path, then
2. symlinking `ssh` to `qssh` and `scp` to `qscp`.
These commands will transparently attempt to SSH into a host unless it is
unresolvable, in which case they will assume it's a VM and fall back to
using the `bombshell-client` to communicate with said presumed VM.
SaltStack's SSH-based `salt-ssh` automator will pick these fake SSH and
SCP clients, and they will work transparently.
Bombshell remote shell technology Bombshell remote shell technology
--------------------------------- ---------------------------------
@ -70,6 +55,71 @@ The command above spawns a `command-to-run` on `vmname`, interactively. Standar
Spawns the `command-to-run` on the `vmname`, interactively, printing communication channel interaction behavior into the standard error of the invoker, and into the root journal of the `vmname`. Spawns the `command-to-run` on the `vmname`, interactively, printing communication channel interaction behavior into the standard error of the invoker, and into the root journal of the `vmname`.
Fairly simple:
./bombshell-client vmname bash
starts an interactive bash shell (without a prompt, as there is no tty)
on the machine `vmname`. Any progran can be run in this way. For
example:
./bombshell-client vmname hostname
should give you the host name of the VM `vmname`.
The rsync manpage documents the use of a special form of rsh to connect
to remote hosts -- this option can be used with `bombshell-client`
to run rsync against other VMs as if they were normal SSH hosts.
How to use this with automation tools like Ansible and SaltStack
----------------------------------------------------------------
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.
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`).
You can also integrate this plugin with SaltStack's `salt-ssh` program, by:
1. placing the `bombshell-client`, `qrun`, `qssh` and `qscp` commands
in some directory of your path, then
2. symlinking `ssh` to `qssh` and `scp` to `qscp`.
These commands will transparently attempt to SSH into a host unless it is
unresolvable, in which case they will assume it's a VM and fall back to
using the `bombshell-client` to communicate with said presumed VM.
SaltStack's SSH-based `salt-ssh` automator will pick these fake SSH and
SCP clients, and they will work transparently.
Bug bounties
------------
The bounties that were published have been collected. Sorry! Open source works! The bounties that were published have been collected. Sorry! Open source works!
Enjoy! Enjoy!