/usr/share/doc/ganeti/html/design-systemd.html is in ganeti-doc 2.16.0~rc2-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Systemd integration — Ganeti 2.16.0~rc2 documentation</title>
<link rel="stylesheet" href="_static/style.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.16.0~rc2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Automatized Upgrade Procedure for Ganeti" href="design-upgrade.html" />
<link rel="prev" title="Management of storage types and disk templates, incl. storage space reporting" href="design-storagetypes.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="design-upgrade.html" title="Automatized Upgrade Procedure for Ganeti"
accesskey="N">next</a></li>
<li class="right" >
<a href="design-storagetypes.html" title="Management of storage types and disk templates, incl. storage space reporting"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Ganeti 2.16.0~rc2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="systemd-integration">
<h1><a class="toc-backref" href="#id2">Systemd integration</a><a class="headerlink" href="#systemd-integration" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Created:</th><td class="field-body">2014-Mar-26</td>
</tr>
<tr class="field-even field"><th class="field-name">Status:</th><td class="field-body">Implemented</td>
</tr>
<tr class="field-odd field"><th class="field-name">Ganeti-Version:</th><td class="field-body">2.12.0</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#systemd-integration" id="id2">Systemd integration</a><ul>
<li><a class="reference internal" href="#current-state-and-shortcomings" id="id3">Current state and shortcomings</a></li>
<li><a class="reference internal" href="#proposed-changes" id="id4">Proposed changes</a><ul>
<li><a class="reference internal" href="#systemd-unit-files" id="id5">systemd unit files</a><ul>
<li><a class="reference internal" href="#installation" id="id6">Installation</a></li>
<li><a class="reference internal" href="#sysv-compatibility" id="id7">SysV compatibility</a></li>
</ul>
</li>
<li><a class="reference internal" href="#changes-to-daemon-util" id="id8">Changes to daemon-util</a></li>
<li><a class="reference internal" href="#changes-to-ganeti-watcher" id="id9">Changes to ganeti-watcher</a></li>
</ul>
</li>
<li><a class="reference internal" href="#future-work" id="id10">Future work</a><ul>
<li><a class="reference internal" href="#id1" id="id11">Socket activation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<p>This design document outlines the implementation of native systemd
support in Ganeti by providing systemd unit files. It also briefly
discusses the possibility of supporting socket activation.</p>
<div class="section" id="current-state-and-shortcomings">
<h2><a class="toc-backref" href="#id3">Current state and shortcomings</a><a class="headerlink" href="#current-state-and-shortcomings" title="Permalink to this headline">¶</a></h2>
<p>Ganeti currently ships an example init script, compatible with Debian
(and derivatives) and RedHat/Fedora (and derivatives). The initscript
treats the whole Ganeti system as a single service wrt. starting and
stopping (but allows starting/stopping/restarting individual daemons).</p>
<p>The initscript is aided by <code class="docutils literal"><span class="pre">daemon-util</span></code>, which takes care of correctly
ordering the startup/shutdown of daemons using an explicit order.</p>
<p>Finally, process supervision is achieved by (optionally) running
<code class="docutils literal"><span class="pre">ganeti-watcher</span></code> via cron every 5 minutes. <code class="docutils literal"><span class="pre">ganeti-watcher</span></code> will - among
other things - try to start services that should be running but are not.</p>
<p>The example initscript currently shipped with Ganeti will work with
systemd’s LSB compatibility wrappers out of the box, however there are
a number of areas where we can benefit from providing native systemd
unit files:</p>
<blockquote>
<div><ul class="simple">
<li>systemd is the <a class="reference external" href="https://en.wikipedia.org/wiki/Systemd#Adoption">de-facto choice</a> of almost all major Linux
distributions. Since it offers a stable API for service control,
providing our own systemd unit files means that Ganeti will run
out-of-the-box and in a predictable way in all distributions using
systemd.</li>
<li>systemd performs constant process supervision with immediate
service restarts and configurable back-off. Ganeti currently offers
supervision only via ganeti-watcher, running via cron in 5-minute
intervals and unconditionally starting missing daemons even if they
have been manually stopped.</li>
<li>systemd offers <a class="reference external" href="http://0pointer.de/blog/projects/socket-activation.html">socket activation</a> support, which may be of
interest for use at least with masterd, luxid and noded. Socket
activation offers two main advantages: no explicit service
dependencies or ordering needs to be defined as services will be
activated when needed; and seamless restarts / upgrades are possible
without rejecting new client connections.</li>
<li>systemd offers a number of <a class="reference external" href="http://0pointer.de/blog/projects/security.html">security features</a>, primarily using
the Linux kernel’s namespace support, which may be of interest to
better restrict daemons running as root (noded and mond).</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="proposed-changes">
<h2><a class="toc-backref" href="#id4">Proposed changes</a><a class="headerlink" href="#proposed-changes" title="Permalink to this headline">¶</a></h2>
<p>We propose to extend Ganeti to natively support systemd, in addition to
shipping the init-script as is. This requires the addition of systemd
unit files, as well as some changes in daemon-util and ganeti-watcher to
use <code class="docutils literal"><span class="pre">systemctl</span></code> on systems where Ganeti is managed by systemd.</p>
<div class="section" id="systemd-unit-files">
<h3><a class="toc-backref" href="#id5">systemd unit files</a><a class="headerlink" href="#systemd-unit-files" title="Permalink to this headline">¶</a></h3>
<p>Systemd uses unit files to store information about a service, device,
mount point, or other resource it controls. Each unit file contains
exactly one unit definition, consisting of a <code class="docutils literal"><span class="pre">Unit</span></code> an (optional)
<code class="docutils literal"><span class="pre">Install</span></code> section and an (optional) type-specific section (e.g.
<code class="docutils literal"><span class="pre">Service</span></code>). Unit files are dropped in pre-determined locations in the
system, where systemd is configured to read them from. Systemd allows
complete or partial overrides of the unit files, using overlay
directories. For more information, see <a class="reference external" href="http://www.freedesktop.org/software/systemd/man/systemd.unit.html">systemd.unit(5)</a>.</p>
<p>We will create one systemd <a class="reference external" href="http://www.freedesktop.org/software/systemd/man/systemd.service.html">service unit</a> per daemon (masterd, noded,
mond, luxid, confd, rapi) and an additional oneshot service for
ensure-dirs (<code class="docutils literal"><span class="pre">ganeti-common.service</span></code>). All services will <code class="docutils literal"><span class="pre">Require</span></code>
<code class="docutils literal"><span class="pre">ganeti-common.service</span></code>, which will thus run exactly once per
transaction (regardless of starting one or all daemons).</p>
<p>All daemons will run in the foreground (already implemented by the
<code class="docutils literal"><span class="pre">-f</span></code> flag), directly supervised by systemd, using
<code class="docutils literal"><span class="pre">Restart=on-failure</span></code> in the respective units. Master role units will
also treat <code class="docutils literal"><span class="pre">EXIT_NOTMASTER</span></code> as a successful exit and not trigger
restarts. Additionally, systemd’s conditional directives will be used to
avoid starting daemons when they will certainly fail (e.g. because of
missing configuration).</p>
<p>Apart from the individual daemon units, we will also provide three
<a class="reference external" href="http://www.freedesktop.org/software/systemd/man/systemd.target.html">target units</a> as synchronization points:</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">ganeti-node.target</span></code>: Regular node/master candidate functionality,
including <code class="docutils literal"><span class="pre">ganeti-noded.service</span></code>, <code class="docutils literal"><span class="pre">ganeti-mond.service</span></code> and
<code class="docutils literal"><span class="pre">ganeti-confd.service</span></code>.</li>
<li><code class="docutils literal"><span class="pre">ganeti-master.target</span></code>: Master node functionality, including
<code class="docutils literal"><span class="pre">ganeti-masterd.service</span></code>, <code class="docutils literal"><span class="pre">ganeti-luxid.service</span></code> and
<code class="docutils literal"><span class="pre">ganeti-rapi.service</span></code>.</li>
<li><code class="docutils literal"><span class="pre">ganeti.target</span></code>: A “meta-target” depending on
<code class="docutils literal"><span class="pre">ganeti-node.target</span></code> and <code class="docutils literal"><span class="pre">ganti-master.target</span></code>.
<code class="docutils literal"><span class="pre">ganeti.target</span></code> itself will be <code class="docutils literal"><span class="pre">WantedBy</span></code> <code class="docutils literal"><span class="pre">multi-user.target</span></code>,
so that Ganeti starts automatically on boot.</li>
</ul>
</div></blockquote>
<p>To allow starting/stopping/restarting the different roles, all units
will include a <code class="docutils literal"><span class="pre">PartOf</span></code> directive referencing their direct ancestor
target. In this way <code class="docutils literal"><span class="pre">systemctl</span> <span class="pre">restart</span> <span class="pre">ganeti-node.target</span></code> or <code class="docutils literal"><span class="pre">systemctl</span>
<span class="pre">restart</span> <span class="pre">ganeti.target</span></code> will work as expected, i.e. restart only the node
daemons or all daemons respectively.</p>
<p>The full dependency tree is as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span>ganeti.target
├─ganeti-master.target
│ ├─ganeti-luxid.service
│ │ └─ganeti-common.service
│ ├─ganeti-masterd.service
│ │ └─ganeti-common.service
│ └─ganeti-rapi.service
│ └─ganeti-common.service
└─ganeti-node.target
├─ganeti-confd.service
│ └─ganeti-common.service
├─ganeti-mond.service
│ └─ganeti-common.service
└─ganeti-noded.service
└─ganeti-common.service
</pre></div>
</div>
<div class="section" id="installation">
<h4><a class="toc-backref" href="#id6">Installation</a><a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h4>
<p>The systemd unit files will be built from templates under
doc/examples/systemd, much like what is currently done for the
initscript. They will not be installed with <code class="docutils literal"><span class="pre">make</span> <span class="pre">install</span></code>, but left
up to the distribution packagers to ship them at the appropriate
locations.</p>
</div>
<div class="section" id="sysv-compatibility">
<h4><a class="toc-backref" href="#id7">SysV compatibility</a><a class="headerlink" href="#sysv-compatibility" title="Permalink to this headline">¶</a></h4>
<p>Systemd automatically creates a service for each SysV initscript on the
system, appending <code class="docutils literal"><span class="pre">.service</span></code> to the initscript name, except if a
service with the given name already exists. In our case however, the
initscript’s functionality is implemented by <code class="docutils literal"><span class="pre">ganeti.target</span></code>.</p>
<p>Systemd provides the ability to <em>mask</em> a given service, rendering it
unusable, but in the case of SysV services this also results in
failure to use tools like <code class="docutils literal"><span class="pre">invoke-rc.d</span></code> or <code class="docutils literal"><span class="pre">service</span></code>. Thus we have
to ship a <code class="docutils literal"><span class="pre">ganeti.service</span></code> (calling <code class="docutils literal"><span class="pre">/bin/true</span></code>) of type
<code class="docutils literal"><span class="pre">oneshot</span></code>, that depends on <code class="docutils literal"><span class="pre">ganeti.target</span></code> for these tools to
continue working as expected. <code class="docutils literal"><span class="pre">ganeti.target</span></code> on the other hand will
be marked as <code class="docutils literal"><span class="pre">PartOf</span> <span class="pre">=</span> <span class="pre">ganeti.service</span></code> for stop and restart to be
propagated to the whole service.</p>
<p>The <code class="docutils literal"><span class="pre">ganeti.service</span></code> unit will not be marked to be enabled by systemd
(i.e. will not be started at boot), but will be available for manual
invocation and only be used for compatibility purposes.</p>
</div>
</div>
<div class="section" id="changes-to-daemon-util">
<h3><a class="toc-backref" href="#id8">Changes to daemon-util</a><a class="headerlink" href="#changes-to-daemon-util" title="Permalink to this headline">¶</a></h3>
<p><code class="docutils literal"><span class="pre">daemon-util</span></code> is used wherever daemon control is required:</p>
<blockquote>
<div><ul class="simple">
<li>In the sample initscript, to start and stop all daemons.</li>
<li>In <code class="docutils literal"><span class="pre">ganeti.backend</span></code> to start the master daemons on master failover and
to stop confd when leaving the cluster.</li>
<li>In <code class="docutils literal"><span class="pre">ganeti.bootstrap</span></code>, to start the daemons on cluster initialization.</li>
<li>In <code class="docutils literal"><span class="pre">ganeti.cli</span></code>, to control the daemon run state during certain
operations (e.g. renew-crypto).</li>
</ul>
</div></blockquote>
<p>Currently, <code class="docutils literal"><span class="pre">daemon-util</span></code> uses two auxiliary tools for managing daemons
<code class="docutils literal"><span class="pre">start-stop-daemon</span></code> and <code class="docutils literal"><span class="pre">daemon</span></code>, in this order of preference. In
order not to confuse systemd in its process supervision, <code class="docutils literal"><span class="pre">daemon-util</span></code>
will have to be modified to start and stop the daemons via <code class="docutils literal"><span class="pre">systemctl</span></code>
in preference to <code class="docutils literal"><span class="pre">start-stop-daemon</span></code> and <code class="docutils literal"><span class="pre">daemon</span></code>. This
will require a basic check against run-time environment integrity:</p>
<blockquote>
<div><ul class="simple">
<li>Make sure that <code class="docutils literal"><span class="pre">systemd</span></code> runs as PID 1, which is a <a class="reference external" href="http://www.freedesktop.org/software/systemd/man/sd_booted.html">simple
check</a> against the existence of <code class="docutils literal"><span class="pre">/run/systemd/system</span></code>.</li>
<li>Make sure <code class="docutils literal"><span class="pre">systemd</span></code> knows how to handle Ganeti natively. This can
be a check against the <code class="docutils literal"><span class="pre">LoadState</span></code> of the <code class="docutils literal"><span class="pre">ganeti.target</span></code> unit.</li>
</ul>
</div></blockquote>
<p>Unless both of these checks pass, <code class="docutils literal"><span class="pre">daemon-util</span></code> will fall back to its
current behavior.</p>
</div>
<div class="section" id="changes-to-ganeti-watcher">
<h3><a class="toc-backref" href="#id9">Changes to ganeti-watcher</a><a class="headerlink" href="#changes-to-ganeti-watcher" title="Permalink to this headline">¶</a></h3>
<p>Since the daemon process supervision will be systemd’s responsibility,
the watcher must detect systemd’s presence and not attempt to start any
missing services. Again, systemd can be detected by the existence of
<code class="docutils literal"><span class="pre">/run/systemd/system</span></code>.</p>
</div>
</div>
<div class="section" id="future-work">
<h2><a class="toc-backref" href="#id10">Future work</a><a class="headerlink" href="#future-work" title="Permalink to this headline">¶</a></h2>
<div class="section" id="id1">
<h3><a class="toc-backref" href="#id11">Socket activation</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
<p>Systemd offers support for <a class="reference external" href="http://0pointer.de/blog/projects/socket-activation.html">socket activation</a>. A daemon supporting
socket-based activation, can inherit its listening socket(s) by systemd.
This in turn means that the socket can be created and bound by systemd
during early boot and it can be used to provide implicit startup
ordering; as soon as a client connects to the listening socket, the
respective service (and all its dependencies) will be started and the
client will wait until its connection is accepted.</p>
<p>Also, because the socket remains bound even if the service is
restarting, new client connections will never be rejected, making
service restarts and upgrades seamless.</p>
<p>Socket activation support is trivial to implement (see
<a class="reference external" href="http://www.freedesktop.org/software/systemd/man/sd_listen_fds.html">sd_listen_fds(3)</a>) and relies on information passed by systemd via
environment variables to the started processes.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Systemd integration</a><ul>
<li><a class="reference internal" href="#current-state-and-shortcomings">Current state and shortcomings</a></li>
<li><a class="reference internal" href="#proposed-changes">Proposed changes</a><ul>
<li><a class="reference internal" href="#systemd-unit-files">systemd unit files</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#sysv-compatibility">SysV compatibility</a></li>
</ul>
</li>
<li><a class="reference internal" href="#changes-to-daemon-util">Changes to daemon-util</a></li>
<li><a class="reference internal" href="#changes-to-ganeti-watcher">Changes to ganeti-watcher</a></li>
</ul>
</li>
<li><a class="reference internal" href="#future-work">Future work</a><ul>
<li><a class="reference internal" href="#id1">Socket activation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="design-storagetypes.html"
title="previous chapter">Management of storage types and disk templates, incl. storage space reporting</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="design-upgrade.html"
title="next chapter">Automatized Upgrade Procedure for Ganeti</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/design-systemd.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="design-upgrade.html" title="Automatized Upgrade Procedure for Ganeti"
>next</a></li>
<li class="right" >
<a href="design-storagetypes.html" title="Management of storage types and disk templates, incl. storage space reporting"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Ganeti 2.16.0~rc2 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2018, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 Google Inc..
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|