README.md
1# ansible-sshjail
2
3[](https://github.com/austinhyde/ansible-sshjail/releases)
4
5An Ansible connection plugin for remotely provisioning FreeBSD jails separately from their jailhost.
6
7This works by SSHing to the jail host using the standard **Ansible** SSH _connection_, moving any files into the jail directory, and using jexec to execute commands in the scope of the jail.
8
9# Requirements
10
11Control node (your workstation or deployment server):
12
13* Ansible 2.0 RC3+
14* Python 2.7
15
16Jailhost:
17
18* FreeBSD
19* At least one configured jail
20* Python 2.7
21* SSH
22* sudo
23
24Target jail:
25
26* Python 2.7
27
28# Installation
29
30This is a "Connection Type Plugin", as outlined in the [Ansible docs](http://docs.ansible.com/developing_plugins.html#connection-type-plugins).
31
32To install sshjail:
33
341. Clone this repo.
352. Copy or link `sshjail.py` to one of the supported locations:
36 * `/usr/share/ansible/plugins/connection_plugins/sshjail.py`
37 * `path/to/your/toplevelplaybook/connection_plugins/sshjail.py`
38
39# Usage
40
41Using sshjail, each jail is its own inventory host, identified with a host name of `jail@jailhost`. You must also specify `ansible_connection=sshjail`.
42
43* `jail` is the name or hostname of the jail.
44* `jailhost` is the hostname or IP address of the jailhost.
45
46Keep in mind that `ezjail` encourages creating jails with their hostname, which implicitly names the jail with underscores substituted for dashes and dots. For example, a jail created with `ezjail-admin create test-jail 'em1|192.168.33.20'`, will have hostname `test-jail` and jail name `test_jail`. sshjail will accept either name in the ansible host specification.
47
48Also note that FreeBSD pkgng places Python at `/usr/local/bin/python2.7` by default. Make sure to specify this with the `ansible_python_interpreter` variable!
49
50The following inventory entries are examples of using sshjail:
51
52```
53# bare minimum
54my-db-jail@192.168.1.100 ansible_python_interpreter=/usr/local/bin/python2.7 ansible_connection=sshjail
55
56# sample vagrant configuration
57my-db-jail ansible_ssh_host=my-db-jail@127.0.0.1 ansible_ssh_port=2222 ansible_python_interpreter=/usr/local/bin/python2.7 ansible_connection=sshjail ansible_ssh_user=vagrant
58```
59
60Adding these hosts dynamically, like after freshly creating them via Ansible, or by iterating over `jls` output, can be done via the [built-in `add_host` module](http://docs.ansible.com/add_host_module.html):
61
62```YAML
63- name: add my-db-jail to ansible inventory
64 add_host: name=my-db-jail groups=jails
65 ansible_ssh_host=my-db-jail@{{ansible_ssh_host}}
66 ansible_ssh_port={{ansible_ssh_port}}
67 ansible_python_interpreter=/usr/local/bin/python2.7
68 ansible_connection=sshjail
69```
70
71## A note about privileges
72
73By default in FreeBSD, only root can enter jails. This means that when invoking `ansible` or `ansible-playbook`,
74you need to specify `--become`, and in a playbook, use `become: yes`/`become_method: sudo`. If sudo requires a password
75(shame on you if not, unless it's vagrant!), you'll need `--ask-become-pass` as well.
76
77This means any commands executed by sshjail roughly translate to `sudo jexec $jailName $command`.
78
79An alternative to requiring root access is to use the [`jailme`](http://www.freshports.org/sysutils/jailme) utility.
80`jailme` is "a setuid version of jexec to allow normal users access to FreeBSD jails".
81
82If you want to use `jailme`, you'll need to ensure it's installed on the jailhost, and specify the user to `sudo` as
83via `--become-user` on the command line, or `become_user: username` in a play or task. sshjail will prefer to use `jailme`
84if it's installed, whether you are sudoing as root or not.
85
86This results in commands similar to `sudo -u $becomeUser jailme $jailId $command`.
87
88Because of limitations of Ansible, this plugin cannot really do things like `sudo jexec sudo -u myuser $command`
89
90# Known Issues
91
92- None at the moment
93
94# Contributing
95
96Let me know if you have any difficulties using this, by creating an issue.
97
98Pull requests are always welcome! I'll try to get them reviewed in a timely manner.
99
){kind=link}