This file is indexed.

/usr/share/doc/ganeti/html/design-reason-trail.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
<!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>Ganeti reason trail &#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="Resource model changes" href="design-resource-model.html" />
    <link rel="prev" title="Splitting the query and job execution paths" href="design-query-splitting.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-resource-model.html" title="Resource model changes"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="design-query-splitting.html" title="Splitting the query and job execution paths"
             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="ganeti-reason-trail">
<h1><a class="toc-backref" href="#id1">Ganeti reason trail</a><a class="headerlink" href="#ganeti-reason-trail" 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">2013-Mar-15</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.9.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="#ganeti-reason-trail" id="id1">Ganeti reason trail</a><ul>
<li><a class="reference internal" href="#current-state-and-shortcomings" id="id2">Current state and shortcomings</a></li>
<li><a class="reference internal" href="#proposed-changes" id="id3">Proposed changes</a></li>
<li><a class="reference internal" href="#implementation" id="id4">Implementation</a></li>
</ul>
</li>
</ul>
</div>
<p>This is a design document detailing the implementation of a way for Ganeti to
track the origin and the reason of every executed command, from its starting
point (command line, remote API, some htool, etc.) to its actual execution
time.</p>
<div class="section" id="current-state-and-shortcomings">
<h2><a class="toc-backref" href="#id2">Current state and shortcomings</a><a class="headerlink" href="#current-state-and-shortcomings" title="Permalink to this headline"></a></h2>
<p>There is currently no way to track why a job and all the operations part of it
were executed, and who or what triggered the execution.
This is an inconvenience in general, and also it makes impossible to have
certain information, such as finding the reason why an instance last changed its
status (i.e.: why it was started/stopped/rebooted/etc.), or distinguishing
an admin request from a scheduled maintenance or an automated tool’s work.</p>
</div>
<div class="section" id="proposed-changes">
<h2><a class="toc-backref" href="#id3">Proposed changes</a><a class="headerlink" href="#proposed-changes" title="Permalink to this headline"></a></h2>
<p>We propose to introduce a new piece of information, that will be called “reason
trail”, to track the path from the issuing of a command to its execution.</p>
<p>The reason trail will be a list of 3-tuples <code class="docutils literal"><span class="pre">(source,</span> <span class="pre">reason,</span> <span class="pre">timestamp)</span></code>,
with:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">source</span></code></dt>
<dd>The entity deciding to perform (or forward) a command.
It is represented by an arbitrary string, but strings prepended by “gnt:”
are reserved for Ganeti components, and they will be refused by the
interfaces towards the external world.</dd>
<dt><code class="docutils literal"><span class="pre">reason</span></code></dt>
<dd>The reason why the entity decided to perform the operation.
It is represented by an arbitrary string. The string might possibly be empty,
because certain components of the system might just “pass on” the operation
(therefore wanting to be recorded in the trail) but without an explicit
reason.</dd>
<dt><code class="docutils literal"><span class="pre">timestamp</span></code></dt>
<dd>The time when the element was added to the reason trail. It has to be
expressed in nanoseconds since the unix epoch (0:00:00 January 01, 1970).
If not enough precision is available (or needed) it can be padded with
zeroes.</dd>
</dl>
<p>The reason trail will be attached at the OpCode level. When it has to be
serialized externally (such as on the RAPI interface), it will be serialized in
JSON format. Specifically, it will be serialized as a list of elements.
Each element will be a list with two strings (for <code class="docutils literal"><span class="pre">source</span></code> and <code class="docutils literal"><span class="pre">reason</span></code>)
and one integer number (the <code class="docutils literal"><span class="pre">timestamp</span></code>).</p>
<p>Any component the operation goes through is allowed (but not required) to append
it’s own reason to the list. Other than this, the list shouldn’t be modified.</p>
<p>As an example here is the reason trail for a shutdown operation invoked from
the command line through the gnt-instance tool:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[(</span><span class="s2">&quot;user&quot;</span><span class="p">,</span> <span class="s2">&quot;Cleanup of unused instances&quot;</span><span class="p">,</span> <span class="mi">1363088484000000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:client:gnt-instance&quot;</span><span class="p">,</span> <span class="s2">&quot;stop&quot;</span><span class="p">,</span> <span class="mi">1363088484020000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:opcode:shutdown&quot;</span><span class="p">,</span> <span class="s2">&quot;job=1234;index=0&quot;</span><span class="p">,</span> <span class="mi">1363088484026000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:daemon:noded:shutdown&quot;</span><span class="p">,</span> <span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="mi">1363088484135000000</span><span class="p">)]</span>
</pre></div>
</div>
<p>where the first 3-tuple is determined by a user-specified message, passed to
gnt-instance through a command line parameter.</p>
<p>The same operation, launched by an external GUI tool, and executed through the
remote API, would have a reason trail like:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">[(</span><span class="s2">&quot;user&quot;</span><span class="p">,</span> <span class="s2">&quot;Cleanup of unused instances&quot;</span><span class="p">,</span> <span class="mi">1363088484000000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;other-app:tool-name&quot;</span><span class="p">,</span> <span class="s2">&quot;gui:stop&quot;</span><span class="p">,</span> <span class="mi">1363088484000300000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:client:rapi:shutdown&quot;</span><span class="p">,</span> <span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="mi">1363088484020000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:library:rlib2:shutdown&quot;</span><span class="p">,</span> <span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="mi">1363088484023000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:opcode:shutdown&quot;</span><span class="p">,</span> <span class="s2">&quot;job=1234;index=0&quot;</span><span class="p">,</span> <span class="mi">1363088484026000000</span><span class="p">),</span>
 <span class="p">(</span><span class="s2">&quot;gnt:daemon:noded:shutdown&quot;</span><span class="p">,</span> <span class="s2">&quot;&quot;</span><span class="p">,</span> <span class="mi">1363088484135000000</span><span class="p">)]</span>
</pre></div>
</div>
</div>
<div class="section" id="implementation">
<h2><a class="toc-backref" href="#id4">Implementation</a><a class="headerlink" href="#implementation" title="Permalink to this headline"></a></h2>
<p>The OpCode base class will be modified to include a new parameter, “reason”.
This will receive the reason trail as built by all the previous steps.</p>
<p>When an OpCode is added to a job (in jqueue.py) the job number and the opcode
index will be recorded as the reason for the existence of that opcode.</p>
<p>From the command line tools down to the opcodes, the implementation of this
design will be shared by all the components of the system. After the opcodes
have been enqueued in a job queue and are dispatched for execution, the
implementation will have to be OpCode specific because of the current
structure of the ganeti backend.</p>
<p>The implementation of opcode-specific parts will start from the operations that
affect the instance status (as required by the design document about the
monitoring daemon, for the instance status data collector). Such opcodes will
be changed so that the “reason” is passed to them and they will then export
the reason trail on a file.</p>
<p>The implementation for other opcodes will follow when required.</p>
</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="#">Ganeti reason trail</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></li>
<li><a class="reference internal" href="#implementation">Implementation</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="design-query-splitting.html"
                        title="previous chapter">Splitting the query and job execution paths</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="design-resource-model.html"
                        title="next chapter">Resource model changes</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/design-reason-trail.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-resource-model.html" title="Resource model changes"
             >next</a></li>
        <li class="right" >
          <a href="design-query-splitting.html" title="Splitting the query and job execution paths"
             >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>