This file is indexed.

/usr/share/doc/libvirt-doc/internals.html is in libvirt-doc 4.0.0-1ubuntu8.

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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <!--
        This file is autogenerated from internals.html.in
        Do not edit this file. Changes will be lost.
      -->
  <!--
        This page was generated at Mon Nov 13 21:46:26 UTC 2017.
      -->
  <head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <link rel="stylesheet" type="text/css" href="main.css"/>
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png"/>
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/>
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/>
    <link rel="manifest" href="/manifest.json"/>
    <meta name="theme-color" content="#ffffff"/>
    <title>libvirt: libvirt internals</title>
    <meta name="description" content="libvirt, virtualization, virtualization API"/>
    <script type="text/javascript">
      <!--
          
      function init() {
      window.addEventListener('scroll', function(e){
              var distanceY = window.pageYOffset || document.documentElement.scrollTop,
              shrinkOn = 94
              home = document.getElementById("home");
              links = document.getElementById("jumplinks");
              search = document.getElementById("search");
              body = document.getElementById("body");
              if (distanceY > shrinkOn) {
                  if (home.className != "navhide") {
                      body.className = "navhide"
                      home.className = "navhide"
                      links.className = "navhide"
                      search.className = "navhide"
                  }
              } else {
                  if (home.className == "navhide") {
                      body.className = ""
                      home.className = ""
                      links.className = ""
                      search.className = ""
                  }
              }
      });
      }
      window.onload = init();
           
          -->
    </script>
  </head>
  <body>
    <div id="body">
      <div id="content">
        <h1>libvirt internals</h1>
        <p>
      This section provides documents useful to those working on the libvirt
      internals, adding new public APIs, new hypervisor drivers or extending
      the libvirtd daemon code.
    </p>
        <ul>
          <li>Introduction to basic rules and guidelines for
      <a href="hacking.html">hacking</a> on libvirt code</li>
          <li>Guide to adding <a href="api_extension.html">public APIs</a></li>
          <li>Insight into libvirt <a href="internals/eventloop.html">event loop and worker pool</a></li>
          <li>Approach for <a href="internals/command.html">spawning commands</a>
      from libvirt driver code</li>
          <li>The libvirt <a href="internals/rpc.html">RPC infrastructure</a></li>
          <li>The <a href="internals/locking.html">Resource Lock Manager</a></li>
        </ul>
        <p>Before adding new code it will be important to get a basic understanding
    of the many elements involved with making any call or change to the libvirt
    code. The architecture <a href="goals.html">goals</a> must be adhered to
    when submitting new code. Understanding the many places that need to be
    touched and the interactions between various subsystems within libvirt
    will directly correlate to the ability to be successful in getting new
    code accepted.</p>
        <p>The following diagram depicts code flow from a client application, in
    this case the libvirt provided <code>virsh</code> command through the
    various layers to elicit a response from some chosen hypervisor.
    </p>
        <p class="image">
          <img alt="virConnectOpen calling sequence" src="libvirt-virConnect-example.png"/>
        </p>
        <ul>
          <li>"virsh -c qemu:///system list --all"
        <p>After the virsh code processes the input arguments, it eventually
        will make a call to open the connection using a default set of
        authentication credentials (virConnectAuthDefault). </p></li>
          <li>virConnectOpenAuth()
        <p>Each of the virConnectOpen APIs will first call virInitialize() and
        then revector through the local "do_open():" call.</p>
          <ul><li>virInitialize()
            <p>Calls the registration API for each of the drivers with
            client-side only capabilities and then call the remoteRegister()
            API last. This ensures the virDriverTab[] tries local drivers
            first before using the remote driver.</p></li><li>Loop through virDriverTab[] entries trying to call their
            respective "open" entry point (in our case remoteOpen())</li><li>After successful return from the virDriverTab[] open()
            API, attempt to find and open other drivers (network, interface,
            storage, etc.)</li></ul>
        </li>
          <li>remoteOpen()
        <p>After a couple of URI checks, a call to doRemoteOpen() is made</p>
          <ul><li>Determine network transport and host/port to use from URI
            <p>The transport will be either tls, unix, ssh, libssh2, ext,
            or tcp with the default of tls. Decode the host/port if provided
            or default to "localhost".</p></li><li>virNetClientRegisterAsyncIO()
            <p>Register an I/O callback mechanism to get returned data via
            virNetClientIncomingEvent()</p></li><li>"call(...REMOTE_PROC_OPEN...)"
            <p>Eventually routes into virNetClientProgramCall() which will
            call virNetClientSendWithReply() and eventually uses
            virNetClientIO()to send the message to libvirtd and
            then waits for a response using virNetClientIOEventLoop()</p></li><li>virNetClientIncomingEvent()
            <p>Receives the returned packet and processes through
            virNetClientIOUpdateCallback()</p></li></ul>
        </li>
          <li>libvirtd Daemon
        <p/>
          <ul><li>Daemon Startup
              <p>The daemon initialization processing will declare itself
              as a daemon via a virNetDaemonNew() call, then creates new server
              using virNetServerNew() and adds that server to the main daemon
              struct with virNetDaemonAddServer() call.  It will then use
              virDriverLoadModule() to find/load all known drivers,
              set up an RPC server program using the <code>remoteProcs[]</code>
              table via a virNetServerProgramNew() call. The table is the
              corollary to the <code>remote_procedure</code> enum list in
              the client. It lists all the functions to be called in
              the same order. Once RPC is set up, networking server sockets
              are opened, the various driver state initialization routines
              are run from the <code>virStateDriverTab[]</code>, the network
              links are enabled, and the daemon waits for work.</p></li><li>RPC
              <p>When a message is received, the <code>remoteProcs[]</code>
              table is referenced for the 'REMOTE_PROC_OPEN' call entry.
              This results in remoteDispatchOpen() being called via the
              virNetServerProgramDispatchCall().</p></li><li>remoteDispatchOpen()
              <p>The API will read the argument passed picking out the
              <code>name</code> of the driver to be opened. The code
              will then call virConnectOpen() or virConnectOpenReadOnly()
              depending on the argument <code>flags</code>.</p></li><li>virConnectOpen() or virConnectOpenReadOnly()
              <p>Just like the client except that upon entry the URI
              is what was passed from the client and will be found
              and opened to process the data.</p>
              <p>The returned structure data is returned via the
              virNetServer interfaces to the remote driver which then
              returns it to the client application.</p></li></ul>
        </li>
        </ul>
      </div>
    </div>
    <div id="nav">
      <div id="home">
        <a href="index.html">Home</a>
      </div>
      <div id="jumplinks">
        <ul>
          <li>
            <a href="downloads.html">Download</a>
          </li>
          <li>
            <a href="contribute.html">Contribute</a>
          </li>
          <li>
            <a href="docs.html">Docs</a>
          </li>
        </ul>
      </div>
      <div id="search">
        <form action="search.php" enctype="application/x-www-form-urlencoded" method="get">
          <div>
            <input name="query" type="text" size="12" value=""/>
            <input name="submit" type="submit" value="Go"/>
          </div>
        </form>
      </div>
    </div>
    <div id="footer">
      <div id="contact">
        <h3>Contact</h3>
        <ul>
          <li>
            <a href="contact.html#email">email</a>
          </li>
          <li>
            <a href="contact.html#irc">irc</a>
          </li>
        </ul>
      </div>
      <div id="community">
        <h3>Community</h3>
        <ul>
          <li>
            <a href="https://twitter.com/hashtag/libvirt">twitter</a>
          </li>
          <li>
            <a href="https://plus.google.com/communities/109522598353007505282">google+</a>
          </li>
          <li>
            <a href="http://stackoverflow.com/questions/tagged/libvirt">stackoverflow</a>
          </li>
          <li>
            <a href="http://serverfault.com/questions/tagged/libvirt">serverfault</a>
          </li>
        </ul>
      </div>
      <div id="conduct">
            Participants in the libvirt project agree to abide by <a href="governance.html#codeofconduct">the project code of conduct</a></div>
      <br class="clear"/>
    </div>
  </body>
</html>