diff --git a/README.md b/README.md index 8f2a887..9be677f 100644 --- a/README.md +++ b/README.md @@ -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 -`salt-ssh` that enables you to use Ansible and SaltStack to manage your -Qubes OS VMs: +This is a kit of several tools to help you automate your Qubes OS +operations: -* from the `dom0`, -* from any VM within your Qubes OS machine, or even -* from a machine that has SSH access to your Qubes OS machine - (assuming there exists a proxy Qubes OS VM with SSH listening on the - target Qubes OS machine, and said VM is permitted to run `qubes.VMShell` - in other VMs of that system). +1. A computer program `bombshell-client` that can run in dom0 or + in any domU, which uses the `qubes.VMShell` Qubes RPC service + to provide an *interactive* session with a shell interpreter + (or any program of your choice) from a VM to any other VM. +2. A connection plug-in for Ansible that uses `bombshell-client` + 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 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 = ` 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 --------------------------------- @@ -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`. +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 = ` 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! Enjoy!