README.rst
1Overview
2========
3
4The ploy_ezjail plugin provides integration of `ezjail`_ with `ploy`_ to manage `FreeBSD`_ jails.
5
6.. _ezjail: http://erdgeist.org/arts/software/ezjail/
7.. _ploy: https://github.com/ployground/
8.. _FreeBSD: http://www.freebsd.org
9
10
11Installation
12============
13
14ploy_ezjail is best installed with easy_install, pip or with zc.recipe.egg in a buildout.
15
16
17Masters
18=======
19
20To use ploy_ezjail you need a host running FreeBSD on which you want to manage jails.
21
22You declare a master with ``[ez-master:masterid]`` where ``masterid`` is the name you want to use for this master.
23Now you can either add options like for a ``plain`` ploy instance, or you can use the ``instance`` option to refer to another instance from your config like this::
24
25 [ez-master:master1]
26 host = myhost.example.com
27
28 [plain-instance:foohost]
29 host = foohost.example.com
30
31 [ez-master:master2]
32 instance = foohost
33
34The latter is most useful in conjunction with other ploy backend plugins, as it allows you to easily switch between provisioners, i.e. to have an ``ez-master`` provisioned on VirtualBox during development and on a ``plain`` instance in production.
35
36
37Options
38-------
39
40``debug-commands``
41 If set to ``yes``, the commands executed on the host are echoed locally.
42
43``instance``
44 The instance to use as host for this master.
45 If empty, the local machine is used without an ssh connection.
46
47``ezjail-admin``
48 Path to the ``ezjail-admin`` script on the host.
49 Defaults to ``/usr/local/bin/ezjail-admin``.
50
51``sudo``
52 Use ``sudo`` to run commands on the host.
53
54
55Instances
56=========
57
58At the moment all jails will be created using ZFS (the ``-c zfs`` option of ``ezjail-admin``), so the host needs to be setup accordingly.
59
60
61Options
62-------
63
64``ip``
65 The ip address to use for the jail.
66
67 This can either be a single IPv4 address::
68
69 ip = 10.0.0.3
70
71 or any number of IPv4 and IPv6 addresses attached to different devices::
72
73 ip = lo1|10.0.0.3,vtnet0|2a03:b0c0:3:d0::3a4d:c002
74
75 The latter format is `ezjail's <http://erdgeist.org/arts/software/ezjail/>`_ own.
76 **Required**
77
78``flavour``
79 The **flavour** to use for this jail. This is explained in the `ezjail docs <http://erdgeist.org/arts/software/ezjail/>`_.
80
81``ezjail-name``
82 The **name** to use for the jail. By default the id of the instance is used.
83
84``mounts``
85 Additional mount points for the jail.
86 You can specify one mount point per line.
87 The format is::
88
89 src=SRC dst=DST [ro=true] [create=true]
90
91 The ``src`` is the path on the host, ``dst`` is the path inside the jail.
92
93 If ``ro`` is set to ``true``, then the mount is read only.
94
95 When ``create`` is enabled, then the ``src`` path is created with ``mkdir -p``.
96 The ``dst`` path is always created inside the jail with ``mkdir -p``.
97
98 You can reference `ZFS sections`_ inside ``src`` with ``{zfs[name]}`` where ``name`` is the ``ez-zfs`` section name.
99 You can use the name of the jail instance with ``{name}}`` in both ``src`` and ``dst``.
100 Examples::
101
102 src=/foo dst=/foo
103 src={zfs[backup]} dst=/bak
104 src={zfs[data]}/{name} dst=/mnt/data create=true
105 src={zfs[static]} dst=/mnt/static ro=true
106
107``no-terminate``
108 If set to ``yes``, the jail can't be terminated via ploy until the setting is changed to ``no`` or removed entirely.
109
110``startup_script``
111 Path to a local script (relative to the location of the configuration file) which will be run inside the jail right after creation and first start of the jail.
112
113``rc_require``
114 String that indicates which other jails this jail requires to start up, effectively allowing you to define the startup order of jails.
115 See ``rcorder(8)`` for more details.
116 This value is written upon each startup of the jail not just when it is created initially, so to have changes take effect, it's sufficient to restart it.
117 **Optional**
118
119``rc_provide``
120 String that indicates what this jail provides.
121 ``ezjail`` itself always sets its jails to provide ``standard_ezjail`` to which ``ploy_ezjail`` adds the name of the jail.
122 IOW if you simply want to build a startup order using the names of the jails, you will not need to set this value.
123 If you want this jail to provide any additional values, set them here.
124 This value is written upon each startup of the jail not just when it is created initially, so to have changes take effect, it's sufficient to restart it.
125 **Optional**
126
127
128ZFS sections
129============
130
131You can specify ZFS filesystems via ``[ez-zfs:name]`` sections.
132This is used in mounts of jails to get the mountpoint and verify that the path exists and is it's own ZFS filesystem.
133You can also create new ZFS filesystems with the ``create`` option.
134
135
136Options
137-------
138
139``create``
140 If set to ``yes``, the filesystem is created when first used.
141
142``path``
143 Specifies the path of this filesystem.
144 This is not the mountpoint, but the ZFS path.
145 You can reference other ZFS sections with ``{zfs[name][path]}``.
146 The ``name`` is the name of the referenced ZFS section.
147 The ``[path]`` at the end is mandatory, as otherwise you would get the mountpoint of the referenced ZFS section.
148 Examples::
149
150 [ez-zfs:data]
151 path = tank/data
152
153 [ez-zfs:shared]
154 path = {zfs[data][path]}/shared
155
156 [ez-zfs:jails]
157 path = {zfs[data][path]}/jails
158
159 [ez-zfs:backup]
160 create = true
161 path = tank/backup
162