This repository has been archived by the owner on Apr 4, 2024. It is now read-only.
/
advanced-use.html
308 lines (296 loc) · 18.2 KB
/
advanced-use.html
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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Advanced Usage — iocage 1.2 RC documentation</title>
<link rel="stylesheet" href="_static/agogo.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Using Templates" href="templates.html" />
<link rel="prev" title="Best Practices" href="best-practices.html" />
</head><body>
<div class="header-wrapper" role="banner">
<div class="header">
<div class="headertitle"><a
href="index.html">iocage 1.2 RC documentation</a></div>
<div class="rel" role="navigation" aria-label="related navigation">
<a href="best-practices.html" title="Best Practices"
accesskey="P">previous</a> |
<a href="templates.html" title="Using Templates"
accesskey="N">next</a> |
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="genindex.html" title="General Index"
accesskey="I">index</a>
</div>
</div>
</div>
<div class="content-wrapper">
<div class="content">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="advanced-usage">
<span id="index-0"></span><span id="id1"></span><h1>Advanced Usage<a class="headerlink" href="#advanced-usage" title="Permalink to this headline">¶</a></h1>
<div class="section" id="clones">
<span id="index-1"></span><span id="id2"></span><h2>Clones<a class="headerlink" href="#clones" title="Permalink to this headline">¶</a></h2>
<p>When a jail is cloned, iocage creates a ZFS clone filesystem.
Essentially, clones are cheap, lightweight, and writable snapshots.</p>
<p>A clone depends on its source snapshot and filesystem. To destroy the
source jail and preserve its clones, the clone must be promoted first.</p>
<div class="section" id="create-a-clone">
<span id="index-2"></span><span id="id3"></span><h3>Create a Clone<a class="headerlink" href="#create-a-clone" title="Permalink to this headline">¶</a></h3>
<p>To clone <strong>www01</strong> to <strong>www02</strong>, run:</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">clone</span> <span class="pre">www01</span> <span class="pre">--name</span> <span class="pre">www02</span></code></p>
<p>Clone a jail from an existing snapshot with:</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">clone</span> <span class="pre">www01@snapshotname</span> <span class="pre">--name</span> <span class="pre">www03</span></code></p>
</div>
<div class="section" id="promoting-a-clone">
<span id="index-3"></span><span id="id4"></span><h3>Promoting a Clone<a class="headerlink" href="#promoting-a-clone" title="Permalink to this headline">¶</a></h3>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This functionality isn’t fully added to iocage, and may not
function as expected.</p>
</div>
<p><strong>To promote a cloned jail, run:</strong></p>
<p><strong class="command">iocage promote [UUID | NAME]</strong></p>
<p>This reverses the <em>clone</em> and <em>source</em> jail relationship. The clone
becomes the source and the source jail is demoted to a clone.</p>
<p><strong>The demoted jail can now be removed:</strong></p>
<p><strong class="command">iocage destroy [UUID | NAME]</strong></p>
</div>
</div>
<div class="section" id="updating-jails">
<span id="index-4"></span><span id="id5"></span><h2>Updating Jails<a class="headerlink" href="#updating-jails" title="Permalink to this headline">¶</a></h2>
<p>Updates are handled with the freebsd-update(8) utility. Jails can be
updated while they are stopped or running.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The command <strong class="command">iocage update [UUID | NAME]</strong>
automatically creates a backup snapshot of the jail given.</p>
</div>
<p>To create a backup snapshot manually, run:</p>
<p><strong class="command">iocage snapshot -n [snapshotname] [UUID | NAME]</strong></p>
<p>To update a jail to latest patch level, run:</p>
<p><strong class="command">iocage update [UUID | NAME]</strong></p>
<p>When updates are finished and the jail appears to function properly,
remove the snapshot:</p>
<p><strong class="command">iocage snapremove [UUID|NAME]@[snapshotname]</strong></p>
<p>To test updating without affecting a jail, create a clone and update the
clone the same way as outlined above.</p>
<p>To clone a jail, run:</p>
<p><strong class="command">iocage clone [UUID|NAME] --name [testupdate]</strong></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <strong>[-n | –name]</strong> flag is optional. <strong class="command">iocage</strong>
assigns an UUID to the jail if <strong>[-n | –name]</strong> is not used.</p>
</div>
</div>
<div class="section" id="upgrading-jails">
<span id="index-5"></span><span id="id6"></span><h2>Upgrading Jails<a class="headerlink" href="#upgrading-jails" title="Permalink to this headline">¶</a></h2>
<p>Upgrades are handled with the freebsd-update(8) utility. By default, the
user must supply the new RELEASE for the jail’s upgrade. For example:</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">upgrade</span> <span class="pre">examplejail</span> <span class="pre">-r</span> <span class="pre">11.0-RELEASE</span></code></p>
<p>Tells jail <em>examplejail</em> to upgrade its RELEASE to <em>11.0-RELEASE</em>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It is recommended to keep the iocage host and jails RELEASE
synchronized.</p>
</div>
<p>To upgrade a jail to the host’s RELEASE, run:</p>
<p><strong class="command">iocage upgrade -r [11.1-RELEASE] [UUID | NAME]</strong></p>
<p>This upgrades the jail to the same RELEASE as the host. This method also
applies to basejails.</p>
</div>
<div class="section" id="auto-boot">
<span id="autoboot"></span><span id="index-6"></span><h2>Auto-boot<a class="headerlink" href="#auto-boot" title="Permalink to this headline">¶</a></h2>
<p>Make sure <strong class="command">iocage_enable="YES"</strong> is set in <code class="file docutils literal notranslate"><span class="pre">/etc/rc.conf</span></code>.</p>
<p>To enable a jail to auto-boot during a system boot, simply run:</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">set</span> <span class="pre">boot=on</span> <span class="pre">UUID|NAME</span></code></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Setting <strong class="command">boot=on</strong> during jail creation starts the
jail after the jail is created.</p>
</div>
<div class="section" id="boot-priority">
<span id="index-7"></span><span id="id7"></span><h3>Boot Priority<a class="headerlink" href="#boot-priority" title="Permalink to this headline">¶</a></h3>
<p>Boot order can be specified by setting the priority value:</p>
<p><strong class="command">iocage set priority=[20] [UUID|NAME]</strong></p>
<p><em>Lower</em> values are higher in the boot priority.</p>
</div>
<div class="section" id="depends-property">
<span id="index-8"></span><span id="id8"></span><h3>Depends Property<a class="headerlink" href="#depends-property" title="Permalink to this headline">¶</a></h3>
<p>Use the <code class="docutils literal notranslate"><span class="pre">depends</span></code> property to require other jails to start
before this one. It is space delimited. Jails listed as dependents
also wait to start if those jails have listed <code class="docutils literal notranslate"><span class="pre">depends</span></code>.</p>
<p>Example: <strong class="command">iocage set depends=“foo bar” baz</strong></p>
</div>
</div>
<div class="section" id="snapshot-management">
<span id="index-9"></span><span id="id9"></span><h2>Snapshot Management<a class="headerlink" href="#snapshot-management" title="Permalink to this headline">¶</a></h2>
<p>iocage supports transparent ZFS snapshot management out of the box.
Snapshots are point-in-time copies of data, a safety point to which a
jail can be reverted at any time. Initially, snapshots take up almost no
space, as only changing data is recorded.</p>
<p>List snapshots for a jail:</p>
<p><strong class="command">iocage snaplist [UUID|NAME]</strong></p>
<p>Create a new snapshot:</p>
<p><strong class="command">iocage snapshot [UUID|NAME]</strong></p>
<p>This creates a snapshot based on the current time.</p>
</div>
<div class="section" id="resource-limits-legacy-only">
<span id="resource-limits"></span><span id="index-10"></span><h2>Resource Limits (Legacy ONLY)<a class="headerlink" href="#resource-limits-legacy-only" title="Permalink to this headline">¶</a></h2>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This functionality is only available for legacy versions of
<strong class="command">iocage</strong>. It is not yet implemented in the current version.
This applies to all subsections of <em>Resource Limits</em>.</p>
</div>
<p><strong class="command">iocage</strong> can enable optional resource limits for a jail. The
outlined procedure here is meant to provide a starting point for the
user.</p>
<div class="section" id="limit-cores-or-threads">
<span id="index-11"></span><span id="id10"></span><h3>Limit Cores or Threads<a class="headerlink" href="#limit-cores-or-threads" title="Permalink to this headline">¶</a></h3>
<p>Limit a jail to a single thread or core #1:</p>
<p><strong class="command">iocage set cpuset=1 [UUID|TAG]</strong>
<strong class="command">iocage start [UUID|TAG]</strong></p>
</div>
<div class="section" id="list-applied-limits">
<span id="list-applied-rules"></span><span id="index-12"></span><h3>List Applied Limits<a class="headerlink" href="#list-applied-limits" title="Permalink to this headline">¶</a></h3>
<p>List applied limits:</p>
<p><strong class="command">iocage limits [UUID|TAG]</strong></p>
</div>
<div class="section" id="limit-dram-use">
<span id="limit-dram-usage"></span><span id="index-13"></span><h3>Limit DRAM use<a class="headerlink" href="#limit-dram-use" title="Permalink to this headline">¶</a></h3>
<p>This example limits a jail to using 4 Gb DRAM memory (limiting RSS
memory use can be done on-the-fly):</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">set</span> <span class="pre">memoryuse=4G:deny</span> <span class="pre">examplejail</span></code></p>
</div>
<div class="section" id="turn-on-resource-limits">
<span id="index-14"></span><span id="id11"></span><h3>Turn on Resource Limits<a class="headerlink" href="#turn-on-resource-limits" title="Permalink to this headline">¶</a></h3>
<p>Turn on resource limiting for a jail with:</p>
<p><strong class="command">iocage set rlimits=on [UUID|TAG]</strong></p>
</div>
<div class="section" id="apply-limits">
<span id="index-15"></span><span id="id12"></span><h3>Apply limits<a class="headerlink" href="#apply-limits" title="Permalink to this headline">¶</a></h3>
<p>Apply limits to a running jail with:</p>
<p><strong class="command">iocage cap [UUID | TAG]</strong></p>
</div>
<div class="section" id="check-limits">
<span id="index-16"></span><span id="id13"></span><h3>Check Limits<a class="headerlink" href="#check-limits" title="Permalink to this headline">¶</a></h3>
<p>Check the currently active limits on a jail with:</p>
<p><strong class="command">iocage limits [UUID | TAG]</strong></p>
</div>
<div class="section" id="limit-cpu-usage-by">
<span id="limit-cpu-usage-by-percentage"></span><span id="index-17"></span><h3>Limit CPU Usage by %<a class="headerlink" href="#limit-cpu-usage-by" title="Permalink to this headline">¶</a></h3>
<p>In this example, <strong class="command">iocage</strong> limits <em>testjail</em> CPU execution to
20%, then applies the limitation to the active jail:</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">set</span> <span class="pre">pcpu=20:deny</span> <span class="pre">testjail</span></code>
<code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">cap</span> <span class="pre">testjail</span></code></p>
<p>Double check the jail’s current limits to confirm the functionality:</p>
<p><code class="samp docutils literal notranslate"><span class="pre">#</span> <span class="pre">iocage</span> <span class="pre">limits</span> <span class="pre">testjail</span></code></p>
</div>
</div>
<div class="section" id="automatic-package-installation">
<span id="index-18"></span><span id="id14"></span><h2>Automatic Package Installation<a class="headerlink" href="#automatic-package-installation" title="Permalink to this headline">¶</a></h2>
<p>Packages can be installed automatically at creation time!</p>
<p>Use the [-p | –pkglist] option at creation time, which needs to point
to a JSON file containing one package name per line.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>An Internet connection is required for automatic package
installations, as <strong class="command">pkg install</strong> obtains packages from online
repositories.</p>
</div>
<p>Create a <code class="file docutils literal notranslate"><span class="pre">pkgs.json</span></code> file and add package names to it.</p>
<p><code class="file docutils literal notranslate"><span class="pre">pkgs.json</span></code>:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="nt">"pkgs"</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">"nginx"</span><span class="p">,</span>
<span class="s2">"tmux"</span>
<span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Now, create a jail and supply <code class="file docutils literal notranslate"><span class="pre">pkgs.json</span></code>:</p>
<p><strong class="command">iocage create -r [RELEASE] -p [path-to/pkgs.json] -n [NAME]</strong></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <strong>[-n | –name]</strong> flag is optional. <strong class="command">iocage</strong>
assigns an UUID to the jail if <strong>[-n | –name]</strong> is not used.</p>
</div>
<p>This installs <strong>nginx</strong> and <strong>tmux</strong> in the newly created jail.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sidebar">
<h3>Table of Contents</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install iocage</a></li>
<li class="toctree-l1"><a class="reference internal" href="basic-use.html">Basic Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="plugins.html">Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="networking.html">Networking</a></li>
<li class="toctree-l1"><a class="reference internal" href="jailtypes.html">Jail Types</a></li>
<li class="toctree-l1"><a class="reference internal" href="best-practices.html">Best Practices</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Advanced Usage</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#clones">Clones</a></li>
<li class="toctree-l2"><a class="reference internal" href="#updating-jails">Updating Jails</a></li>
<li class="toctree-l2"><a class="reference internal" href="#upgrading-jails">Upgrading Jails</a></li>
<li class="toctree-l2"><a class="reference internal" href="#auto-boot">Auto-boot</a></li>
<li class="toctree-l2"><a class="reference internal" href="#snapshot-management">Snapshot Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="#resource-limits-legacy-only">Resource Limits (Legacy ONLY)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#automatic-package-installation">Automatic Package Installation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="templates.html">Using Templates</a></li>
<li class="toctree-l1"><a class="reference internal" href="debian.html">Create a Debian Squeeze Jail (GNU/kFreeBSD)</a></li>
<li class="toctree-l1"><a class="reference internal" href="known-issues.html">Known Issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>
<div role="search">
<h3 style="margin-top: 1.5em;">Search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
<div class="footer-wrapper">
<div class="footer">
<div class="left">
<div role="navigation" aria-label="related navigaton">
<a href="best-practices.html" title="Best Practices"
>previous</a> |
<a href="templates.html" title="Using Templates"
>next</a> |
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |
<a href="genindex.html" title="General Index"
>index</a>
</div>
<div role="note" aria-label="source link">
</div>
</div>
<div class="right">
<div class="footer" role="contentinfo">
© Copyright 2014-2019, iocage.
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</body>
</html>