File: auth.html

package info (click to toggle)
libvirt 5.6.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 240,844 kB
  • sloc: ansic: 584,521; xml: 176,725; sh: 9,912; python: 4,731; perl: 4,343; makefile: 3,321; ml: 465
file content (489 lines) | stat: -rw-r--r-- 20,885 bytes parent folder | download | duplicates (2)
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
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <!--
        This file is autogenerated from auth.html.in
        Do not edit this file. Changes will be lost.
      -->
  <!--
        This page was generated at Tue Jul 30 02:04:26 UTC 2019.
      -->
  <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: Connection authentication</title>
    <meta name="description" content="libvirt, virtualization, virtualization API"/>
    <script type="text/javascript" src="js/main.js">
      <!--// forces non-empty element-->
    </script>
  </head>
  <body onload="pageload()">
    <div id="body">
      <div id="content">
        <h1>Connection authentication</h1>
        <p>
      When connecting to libvirt, some connections may require client
      authentication before allowing use of the APIs. The set of possible
      authentication mechanisms is administrator controlled, independent
      of applications using libvirt. Once authenticated, libvirt can apply
      fine grained <a href="acl.html">access control</a> to the operations
      performed by a client.
    </p>
        <ul>
          <li>
            <a href="#Auth_client_config">Client configuration</a>
          </li>
          <li>
            <a href="#ACL_server_config">Server configuration</a>
          </li>
          <li>
            <a href="#ACL_server_unix_perms">UNIX socket permissions/group</a>
          </li>
          <li>
            <a href="#ACL_server_polkit">UNIX socket PolicyKit auth</a>
          </li>
          <li>
            <a href="#ACL_server_sasl">SASL pluggable authentication</a>
            <ul>
              <li>
                <a href="#ACL_server_username">Username/password auth</a>
              </li>
              <li>
                <a href="#ACL_server_kerberos">GSSAPI/Kerberos auth</a>
              </li>
            </ul>
          </li>
        </ul>
        <h2>
          <a id="Auth_client_config">Client configuration</a>
          <a class="headerlink" href="#Auth_client_config" title="Permalink to this headline">¶</a>
        </h2>
        <p>
      When connecting to a remote hypervisor which requires authentication,
most libvirt applications will prompt the user for the credentials. It is
also possible to provide a client configuration file containing all the
authentication credentials, avoiding any interaction. Libvirt will look
for the authentication file using the following sequence:
    </p>
        <ol>
          <li>The file path specified by the $LIBVIRT_AUTH_FILE environment
        variable.</li>
          <li>The file path specified by the "authfile=/some/file" URI
        query parameter</li>
          <li>The file $XDG_CONFIG_HOME/libvirt/auth.conf</li>
          <li>The file /etc/libvirt/auth.conf</li>
        </ol>
        <p>
      The auth configuration file uses the traditional <code>".ini"</code>
      style syntax. There are two types of groups that can be present in
      the config. First there are one or more <strong>credential</strong>
      sets, which provide the actual authentication credentials. The keys
      within the group may be:
    </p>
        <ul>
          <li><code>username</code>: the user login name to act as. This
        is relevant for ESX, Xen, HyperV and SSH, but probably not
        the one you want to libvirtd with SASL.</li>
          <li><code>authname</code>: the name to authorize as. This is
        what is commonly required for libvirtd with SASL.</li>
          <li><code>password</code>: the secret password</li>
          <li><code>realm</code>: the domain realm for SASL, mostly
        unused</li>
        </ul>
        <p>
      Each set of credentials has a name, which is part of the group
      entry name. Overall the syntax is
    </p>
        <pre>
[credentials-$NAME]
credname1=value1
credname2=value2</pre>
        <p>
      For example, to define two sets of credentials used for production
      and test machines, using libvirtd, and a further ESX server for dev:
    </p>
        <pre>
[credentials-test]
authname=fred
password=123456

[credentials-prod]
authname=bar
password=letmein

[credentials-dev]
username=joe
password=hello

[credentials-defgrp]
username=defuser
password=defpw</pre>
        <p>
      The second set of groups provide mappings of credentials to
      specific machine services. The config file group names compromise
      the service type and host:
    </p>
        <pre>
[auth-$SERVICE-$HOSTNAME]
credentials=$CREDENTIALS</pre>
        <p>
      For example, following the previous example, here is how to
      map some machines. For convenience libvirt supports a default
      mapping of credentials to machines:
    </p>
        <pre>
[auth-libvirt-test1.example.com]
credentials=test

[auth-libvirt-test2.example.com]
credentials=test

[auth-libvirt-demo3.example.com]
credentials=test

[auth-libvirt-prod1.example.com]
credentials=prod

[auth-libvirt-default]
credentials=defgrp

[auth-esx-dev1.example.com]
credentials=dev

[auth-esx-default]
credentials=defgrp</pre>
        <p>
      The following service types are known to libvirt
    </p>
        <ol>
          <li><code>libvirt</code> - used for connections to a libvirtd
        server, which is configured with SASL auth</li>
          <li><code>ssh</code> - used for connections to a Phyp server
        over SSH</li>
          <li><code>esx</code> - used for connections to an ESX or
        VirtualCenter server</li>
          <li><code>xen</code> - used for connections to a Xen Enterprise
        sever using XenAPI</li>
        </ol>
        <p>
      Applications using libvirt are free to use this same configuration
      file for storing other credentials. For example, it can be used
      to storage VNC or SPICE login credentials
    </p>
        <h2>
          <a id="ACL_server_config">Server configuration</a>
          <a class="headerlink" href="#ACL_server_config" title="Permalink to this headline">¶</a>
        </h2>
        <p>
The libvirt daemon allows the administrator to choose the authentication
mechanisms used for client connections on each network socket independently.
This is primarily controlled via the libvirt daemon master config file in
<code>/etc/libvirt/libvirtd.conf</code>. Each of the libvirt sockets can
have its authentication mechanism configured independently. There is
currently a choice of <code>none</code>, <code>polkit</code>, and <code>sasl</code>.
The SASL scheme can be further configured to choose between a large
number of different mechanisms.
</p>
        <h2>
          <a id="ACL_server_unix_perms">UNIX socket permissions/group</a>
          <a class="headerlink" href="#ACL_server_unix_perms" title="Permalink to this headline">¶</a>
        </h2>
        <p>
If libvirt does not contain support for PolicyKit, then access control for
the UNIX domain socket is done using traditional file user/group ownership
and permissions. There are 2 sockets, one for full read-write access, the
other for read-only access. The RW socket will be restricted (mode 0700) to
only allow the <code>root</code> user to connect. The read-only socket will
be open access (mode 0777) to allow any user to connect.
</p>
        <p>
To allow non-root users greater access, the <code>libvirtd.conf</code> file
can be edited to change the permissions via the <code>unix_sock_rw_perms</code>,
config parameter and to set a user group via the <code>unix_sock_group</code>
parameter. For example, setting the former to mode <code>0770</code> and the
latter <code>wheel</code> would let any user in the wheel group connect to
the libvirt daemon.
</p>
        <h2>
          <a id="ACL_server_polkit">UNIX socket PolicyKit auth</a>
          <a class="headerlink" href="#ACL_server_polkit" title="Permalink to this headline">¶</a>
        </h2>
        <p>
If libvirt contains support for PolicyKit, then access control options are
more advanced. The <code>auth_unix_rw</code> parameter will default to
<code>polkit</code>, and the file permissions will default to <code>0777</code>
even on the RW socket. Upon connecting to the socket, the client application
will be required to identify itself with PolicyKit. The default policy for the
RW daemon socket will require any application running in the current desktop
session to authenticate using the user's password. This is akin to <code>sudo</code>
auth, but does not require that the client application ultimately run as root.
Default policy will still allow any application to connect to the RO socket.
</p>
        <p>
The default policy can be overridden by creating a new policy file in the
<code>/etc/polkit-1/rules.d</code> directory. Information on the options
available can be found by reading the <code>polkit(8)</code> man page. The
two libvirt actions are named <code>org.libvirt.unix.manage</code> for full
management access, and <code>org.libvirt.unix.monitor</code> for read-only
access.
</p>
        <p>
As an example, creating <code>/etc/polkit-1/rules.d/80-libvirt-manage.rules</code>
with the following gives the user <code>fred</code> full management access
when accessing from an active local session:
    </p>
        <pre>polkit.addRule(function(action, subject) {
  if (action.id == "org.libvirt.unix.manage" &amp;&amp;
      subject.local &amp;&amp; subject.active &amp;&amp; subject.user == "fred") {
      return polkit.Result.YES;
  }
});</pre>
        <p>
Older versions of PolicyKit used policy files ending with .pkla in the
local override directory <code>/etc/polkit-1/localauthority/50-local.d/</code>.
Compatibility with this older format is provided by <a href="https://pagure.io/polkit-pkla-compat">polkit-pkla-compat</a>. As an
example, this gives the user <code>fred</code> full management access:
    </p>
        <pre>[Allow fred libvirt management permissions]
Identity=unix-user:fred
Action=org.libvirt.unix.manage
ResultAny=yes
ResultInactive=yes
ResultActive=yes</pre>
        <h2>
          <a id="ACL_server_sasl">SASL pluggable authentication</a>
          <a class="headerlink" href="#ACL_server_sasl" title="Permalink to this headline">¶</a>
        </h2>
        <p>
Libvirt integrates with the cyrus-sasl library to provide a pluggable authentication
system using the SASL protocol. SASL can be used in combination with libvirtd's TLS
or TCP socket listeners. When used with the TCP listener, the SASL mechanism is
rqeuired to provide session encryption in addition to authentication. Only a very
few SASL mechanisms are able to do this, and of those that can do it, only the
GSSAPI plugin is considered acceptably secure by modern standards:
    </p>
        <dl>
          <dt>GSSAPI</dt>
          <dd><strong>This is the current default mechanism to use with libvirtd</strong>.
        It uses the Kerberos v5 authentication protocol underneath, and assuming
        the Kerberos client/server are configured with modern ciphers (AES),
        it provides strong session encryption capabilities.</dd>
          <dt>DIGEST-MD5</dt>
          <dd>This was previously set as the default mechanism to use with libvirtd.
        It provides a simple username/password based authentication mechanism
        that includes session encryption.
        <a href="https://tools.ietf.org/html/rfc6331">RFC 6331</a>, however,
        documents a number of serious security flaws with DIGEST-MD5 and as a
        result marks it as <code>OBSOLETE</code>. Specific concerns are that
        it is vulnerable to MITM attacks and the MD5 hash can be brute-forced
        to reveal the password. A replacement is provided via the SCRAM mechanism,
        however, note that this does not provide encryption, so the SCRAM
        mechanism can only be used on the libvirtd TLS listener.
      </dd>
          <dt>PASSDSS-3DES-1</dt>
          <dd>This provides a simple username/password based authentication
        mechanism that includes session encryption. The current cyrus-sasl
        implementation does not provide a way to validate the server's
        public key identity, thus it is susceptible to a MITM attacker
        impersonating the server. It is also not enabled in many OS
        distros when building SASL libraries.</dd>
          <dt>KERBEROS_V4</dt>
          <dd>This uses the obsolete Kerberos v4 protocol to provide both authentication
        and session encryption. Kerberos v4 protocol has been obsolete since the
        early 1990's and has known security vulnerabilities so this will never be
        used in practice.</dd>
        </dl>
        <p>
      Other SASL mechanisms, not listed above, can only be used when the libvirtd
      TLS or UNIX socket listeners.
    </p>
        <h3>
          <a id="ACL_server_username">Username/password auth</a>
          <a class="headerlink" href="#ACL_server_username" title="Permalink to this headline">¶</a>
        </h3>
        <p>
As noted above, the DIGEST-MD5 mechanism is considered obsolete and should
not be used anymore. To provide a simple username/password auth scheme on
the libvirt UNIX socket or TLS listeners, however, it is possible to use
the SCRAM mechanism. The <code>auth_unix_ro</code>, <code>auth_unix_rw</code>,
<code>auth_tls</code> config params in <code>libvirt.conf</code> can be used
to turn on SASL auth in these listeners.
    </p>
        <p>
Since the libvirt SASL config file defaults to using GSSAPI (Kerberos), a
config change is rquired to enable plain password auth. This is done by
editting <code>/etc/sasl2/libvirt.conf</code> to set the <code>mech_list</code>
parameter to <code>scram-sha-1</code>.
    </p>
        <p>
Out of the box, no user accounts are defined, so no clients will be able to authenticate
on the TCP socket. Adding users and setting their passwords is done with the <code>saslpasswd2</code>
command. When running this command it is important to tell it that the appname is <code>libvirt</code>.
As an example, to add a user <code>fred</code>, run
</p>
        <pre>
# saslpasswd2 -a libvirt fred
Password: xxxxxx
Again (for verification): xxxxxx
</pre>
        <p>
To see a list of all accounts the <code>sasldblistusers2</code> command can be used.
This command expects to be given the path to the libvirt user database, which is kept
in <code>/etc/libvirt/passwd.db</code>
</p>
        <pre>
# sasldblistusers2 -f /etc/libvirt/passwd.db
fred@t60wlan.home.berrange.com: userPassword
</pre>
        <p>
Finally, to disable a user's access, the <code>saslpasswd2</code> command can be used
again:
</p>
        <pre>
# saslpasswd2 -a libvirt -d fred
</pre>
        <h3>
          <a id="ACL_server_kerberos">GSSAPI/Kerberos auth</a>
          <a class="headerlink" href="#ACL_server_kerberos" title="Permalink to this headline">¶</a>
        </h3>
        <p>
The plain TCP listener of the libvirt daemon defaults to using SASL for authentication.
The libvirt SASL config also defaults to GSSAPI, so there is no need to edit the
SASL config when using GSSAPI. If the libvirtd TLS or UNIX listeners are used,
then the Kerberos session encryption will be disabled since it is not required
in these scenarios - only the plain TCP listener needs encryption
</p>
        <p>
Some operating systems do not install the SASL kerberos plugin by default. It
may be necessary to install a sub-package such as <code>cyrus-sasl-gssapi</code>.
To check whether the Kerberos plugin is installed run the <code>pluginviewer</code>
program and verify that <code>gssapi</code> is listed,eg:
</p>
        <pre>
# pluginviewer
...snip...
Plugin "gssapiv2" [loaded],     API version: 4
        SASL mechanism: GSSAPI, best SSF: 56
        security flags: NO_ANONYMOUS|NO_PLAINTEXT|NO_ACTIVE|PASS_CREDENTIALS|MUTUAL_AUTH
        features: WANT_CLIENT_FIRST|PROXY_AUTHENTICATION|NEED_SERVER_FQDN
</pre>
        <p>
Next it is necessary for the administrator of the Kerberos realm to
issue a principal for the libvirt server. There needs to be one
principal per host running the libvirt daemon. The principal should be
named <code>libvirt/full.hostname@KERBEROS.REALM</code>.  This is
typically done by running the <code>kadmin.local</code> command on the
Kerberos server, though some Kerberos servers have alternate ways of
setting up service principals.  Once created, the principal should be
exported to a keytab, copied to the host running the libvirt daemon
and placed in <code>/etc/libvirt/krb5.tab</code>
</p>
        <pre>
# kadmin.local
kadmin.local: add_principal libvirt/foo.example.com
Enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
Re-enter password for principal "libvirt/foo.example.com@EXAMPLE.COM":
Principal "libvirt/foo.example.com@EXAMPLE.COM" created.

kadmin.local:  ktadd -k /root/libvirt-foo-example.tab libvirt/foo.example.com@EXAMPLE.COM
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:/root/libvirt-foo-example.tab.
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:/root/libvirt-foo-example.tab.
Entry for principal libvirt/foo.example.com@EXAMPLE.COM with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:/root/libvirt-foo-example.tab.

kadmin.local: quit

# scp /root/libvirt-foo-example.tab root@foo.example.com:/etc/libvirt/krb5.tab
# rm /root/libvirt-foo-example.tab
</pre>
        <p>
Any client application wishing to connect to a Kerberos enabled libvirt server
merely needs to run <code>kinit</code> to gain a user principal. This may well
be done automatically when a user logs into a desktop session, if PAM is setup
to authenticate against Kerberos.
</p>
      </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 id="simplesearch" action="https://www.google.com/search" enctype="application/x-www-form-urlencoded" method="get">
          <div>
            <input id="searchsite" name="sitesearch" type="hidden" value="libvirt.org"/>
            <input id="searchq" name="q" type="text" size="12" value=""/>
            <input name="submit" type="submit" value="Go"/>
          </div>
        </form>
        <div id="advancedsearch">
          <span>
            <input type="radio" name="what" id="whatwebsite" checked="checked" value="website"/>
            <label for="whatwebsite">Website</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatwiki" value="wiki"/>
            <label for="whatwiki">Wiki</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatdevs" value="devs"/>
            <label for="whatdevs">Developers list</label>
          </span>
          <span>
            <input type="radio" name="what" id="whatusers" value="users"/>
            <label for="whatusers">Users list</label>
          </span>
        </div>
      </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="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>