This file is indexed.

/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 &#8212; 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> &#187;</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> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; 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>