forked from tomster/ezjail-remote
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.rst
145 lines (88 loc) · 5.75 KB
/
README.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
``ezjail-remote`` is a 'remote control' and convenience wrapper for the ``ezjail-admin`` command of the most excellent `ezjail <http://erdgeist.org/arts/software/ezjail/>`_ tool (which in turn is itself a convenience wrapper for `jails <http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/jails.html>`_, `FreeBSD <http://www.freebsd.org>`_'s leight-weight virtualization solution).
Its main features are:
* more sophisticated support for flavours, i.e. interactive configuration and/or templating as opposed to ezjail's hardcoded flavours
* you can ssh into jails created by ``ezjail-remote`` immediately upon creation (no more manual mucking about with sshd config or uploading your public key!)
* unlike ``ezjail-admin``, ``ezjail-remote`` is not installed on the jail host, but on your local machine. This means *it doesn't introduce any further dependencies on the jail host whatsoever* (ezjail itself purposefully limits itself to ``sh``).
..note: In general ezjail-remote tries to keep up with ezjail development, so unless stated otherwise, it requires (and by default also installs) the latest version of ezjail (version 3.2.2 as of this writing).
Usage
=====
ezjail-remote uses the `fabric <http://docs.fabfile.org>`_ library to remotely run its tasks. Basically it provides a so-called *fabfile* that contains all of the commands of ``ezjail-admin``.
This means that its usage differs slightly from that of ``ezjail-admin``. In particular, you provide the hostname of the jail server via the ``-H`` switch and the parameters for the command (such as the name of the jail etc) separated with a colon, like so::
ezjail-remote -H host(s) <COMMAND>:param1,param2,param3
or::
ezjail-remote -H host(s) <COMMAND>:param1=foo,param3=bar
See the `full documentation of what fabric has to offer here <http://docs.fabfile.org/en/1.2.0/usage/fab.html#command-line-options>`_.
In particualar, you can...
* run ``ezjail-remote --help`` to see a list of the available *options*
* run ``ezjail-remote -l`` to see a list of the available *commands*
* run ``ezjail-remote -d COMMAND`` to see a detailed description of a command
As a side effect of using fabric, you can run ezjail-admin commands against multiple jailhosts at the same time.
Bootstrapping
=============
ezjail-remote doesn't only make it easy to create and manage jails, it also helps you set up a jailhost environment from scratch. This is done with the ``bootstrap`` and ``install`` commands.
To successfully run the bootstrap command the following requirements need to be met on the host:
* sshd is up and running
* ssh login for root is (temporarily) enabled
* currently we also require an internet connection (to install ezjail) but this will eventually be replaced with uploading a copy of ezjail.
For example (logged in as root on the console)::
echo 'PermitRootLogin yes' >> /etc/ssh/sshd_config
echo 'ifconfig_em0=DHCP' >> /etc/rc.conf
passwd # give yourself a TEMP_PASSWORD
dhclient em0 # note the IP_ADDR you get
/etc/rc.d/sshd onestart
Now you can run the bootstrap command using the temporary password you gave yourself::
ezjail-remote -H IP_ADDR bootstrap
This
* disables root login
* permanently enables SSH for the jail host (and limits it to the primary IP address)
* creates an admin user with your username and public SSH key
..note: Before installing ezjail with the ``install`` command you may want to set up additional things, such as ZFS pools, network interface aliases, etc.
To install ezjail you can use the ``install`` command, which either installs it from the ports or from CVS (for the brave)::
ezjail-remote -H IP_ADDR install
If you want to use a CVS snapshot::
ezjail-remote -H IP_ADDR install:source=cvs
If you want to use ZFS (and you should!) supply the pool it should use via the jailzfs parameter::
ezjail-remote -H IP_ADDR install:jailzfs='jails/ezjail'
Commands
========
In its simplest form, ezjail remote offers the exact same commands as ezjail-admin, namely ``[archive|config|console|create|delete|install|list|restore|start|stop|update]``. In addition to that it provides enhanced versions of ``create`` and ``destroy`` (the latter a more thorough variant of the ``delete`` command.)
create
------
creates a new jail instance on the given host, creates an admin user with sudo privileges and enables ssh access via public key.
after setting up the jail it attempts to execute a method named ``setup`` from ``ezjailremote.flavours.<name-of-flavour>``, passing on all parameters, including any additional, arbitrary keyword arguments.
parameters
**********
name
name of the new jail, *required*
IP
the IP address, *required*
admin
name of the admin user for the jail, defaults to the current user. the user will be created and added to ``wheel`` (which in turn will be allowed to sudo without password).
keyfile
public key to install for the admin user, defaults to ``~/.ssh/identity.pub``.
flavour
the name of the local flavour, defaults to ``basic``.
ctype
defaults to None and refers to the `-c` flag, meaning, you can set it to `simple`, `bde`, `eli` or `zfs`.
destroy
-------
stops, removes and deletes the given jail instance (but not before asking you one last time, explicitely). however, once you confirm, the jail is irrevocably *gone*.
parameters
**********
name
name of the new jail, *required*
Installation
============
Simply use easy_install::
easy_install ezjail-remote
Development
===========
To develop ezjail-remote itself, check out a copy of this repository and then::
virtualenv . --no-site-package
./bin/python setup.py develop
TODO:
*****
* document flavour development
* use a base class for flavours
* list them (with their docstr) with ezjail-remote list-flavours
* allow chaining/nesting/stacking of flavours (i.e. always include basic)