docs/remote.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1 >Remote support</h1>
   6     <p>
   7 Libvirt allows you to access hypervisors running on remote
   8 machines through authenticated and encrypted connections.
   9 </p>
  10     <ul id="toc"></ul>
  11
  12     <h2>
  13       <a id="Remote_basic_usage">Basic usage</a>
  14     </h2>
  15     <p>
  16 On the remote machine, <code>libvirtd</code> should be running in general.
  17 See <a href="#Remote_libvirtd_configuration">the section
  18 on configuring libvirtd</a> for more information.
  19 </p>
  20     <p>
  21     Not all hypervisors supported by libvirt require a running
  22     <code>libvirtd</code>. If you want to connect to a VMware ESX/ESXi or
  23     GSX server then <code>libvirtd</code> is not necessary. See the
  24     <a href="drvesx.html">VMware ESX page</a> for details.
  25     </p>
  26     <p>
  27 To tell libvirt that you want to access a remote resource,
  28 you should supply a hostname in the normal <a href="uri.html">URI</a> that is passed
  29 to <code>virConnectOpen</code> (or <code>virsh -c ...</code>).
  30 For example, if you normally use <code>qemu:///system</code>
  31 to access the system-wide QEMU daemon, then to access
  32 the system-wide QEMU daemon on a remote machine called
  33 <code>compute1.libvirt.org</code> you would use
  34 <code>qemu://compute1.libvirt.org/system</code>.
  35 </p>
  36     <p>
  37 The <a href="#Remote_URI_reference">section on remote URIs</a>
  38 describes in more detail these remote URIs.
  39 </p>
  40     <p>
  41 From an API point of view, apart from the change in URI, the
  42 API should behave the same.  For example, ordinary calls
  43 are routed over the remote connection transparently, and
  44 values or errors from the remote side are returned to you
  45 as if they happened locally.  Some differences you may notice:
  46 </p>
  47     <ul>
  48       <li> Additional errors can be generated, specifically ones
  49 relating to failures in the remote transport itself. </li>
  50       <li> Remote calls are handled synchronously, so they will be
  51 much slower than, say, direct hypervisor calls. </li>
  52     </ul>
  53     <h2>
  54       <a id="Remote_transports">Transports</a>
  55     </h2>
  56     <p>
  57 Remote libvirt supports a range of transports:
  58 </p>
  59     <dl>
  60       <dt><code>tls</code></dt>
  61       <dd><a href="http://en.wikipedia.org/wiki/Transport_Layer_Security" title="Transport Layer Security">TLS</a>
  62  1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually
  63  listening on a public port number.  To use this you will need to
  64  <a href="#Remote_certificates" title="Generating TLS certificates">generate client and
  65  server certificates</a>.
  66  The standard port is 16514.
  67  </dd>
  68       <dt><code>unix</code></dt>
  69       <dd> Unix domain socket.  Since this is only accessible on the
  70  local machine, it is not encrypted, and uses Unix permissions or
  71  SELinux for authentication.
  72  The standard socket names are
  73  <code>/var/run/libvirt/libvirt-sock</code> and
  74  <code>/var/run/libvirt/libvirt-sock-ro</code> (the latter
  75  for read-only connections).
  76  </dd>
  77       <dt><code>ssh</code></dt>
  78       <dd> Transported over an ordinary
  79  <a href="http://www.openssh.com/" title="OpenSSH homepage">ssh
  80  (secure shell)</a> connection.
  81  Requires <a href="http://netcat.sourceforge.net/">Netcat (nc)</a>
  82  installed and libvirtd should be running
  83  on the remote machine.  You should use some sort of
  84  ssh key management (eg.
  85  <a href="http://mah.everybody.org/docs/ssh" title="Using ssh-agent with ssh">ssh-agent</a>)
  86  otherwise programs which use
  87  this transport will stop to ask for a password. </dd>
  88       <dt><code>ext</code></dt>
  89       <dd> Any external program which can make a connection to the
  90  remote machine by means outside the scope of libvirt. </dd>
  91       <dt><code>tcp</code></dt>
  92       <dd> Unencrypted TCP/IP socket.  Not recommended for production
  93  use, this is normally disabled, but an administrator can enable
  94  it for testing or use over a trusted network.
  95  The standard port is 16509. </dd>
  96       <dt><code>libssh2</code></dt>
  97       <dd> Transport over the SSH protocol using
  98       <a href="http://libssh2.org/" title="libssh2 homepage">libssh2</a> instead
  99 of the OpenSSH binary. This transport uses the libvirt authentication callback for
 100 all ssh authentication calls and therefore supports keyboard-interactive authentication
 101 even with graphical management applications. As with the classic ssh transport
 102 netcat is required on the remote side.</dd>
 103       <dt><code>libssh</code></dt>
 104       <dd> Transport over the SSH protocol using
 105       <a href="http://libssh.org/" title="libssh homepage">libssh</a> instead
 106 of the OpenSSH binary. This transport uses the libvirt authentication callback for
 107 all ssh authentication calls and therefore supports keyboard-interactive authentication
 108 even with graphical management applications. As with the classic ssh transport
 109 netcat is required on the remote side.</dd>
 110     </dl>
 111     <p>
 112 The default transport, if no other is specified, is <code>tls</code>.
 113 </p>
 114     <h2>
 115       <a id="Remote_URI_reference">Remote URIs</a>
 116     </h2>
 117     <p>
 118 See also: <a href="uri.html">documentation on ordinary ("local") URIs</a>.
 119 </p>
 120     <p>
 121 Remote URIs have the general form ("[...]" meaning an optional part):
 122 </p>
 123     <p><code>driver</code>[<code>+transport</code>]<code>://</code>[<code>username@</code>][<code>hostname</code>][<code>:port</code>]<code>/</code>[<code>path</code>][<code>?extraparameters</code>]
 124 </p>
 125     <p>
 126 Either the transport or the hostname must be given in order
 127 to distinguish this from a local URI.
 128 </p>
 129     <p>
 130 Some examples:
 131 </p>
 132     <ul>
 133       <li><code>xen+ssh://rjones@towada/system</code><br/> &#x2014; Connect to a
 134 remote Xen hypervisor on host <code>towada</code> using ssh transport and ssh
 135 username <code>rjones</code>.
 136 </li>
 137       <li><code>xen://towada/system</code><br/> &#x2014; Connect to a
 138 remote Xen hypervisor on host <code>towada</code> using TLS.
 139 </li>
 140       <li><code>xen://towada/system?no_verify=1</code><br/> &#x2014; Connect to a
 141 remote Xen hypervisor on host <code>towada</code> using TLS.  Do not verify
 142 the server's certificate.
 143 </li>
 144       <li><code>qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock</code><br/> &#x2014;
 145 Connect to the local qemu instances over a non-standard
 146 Unix socket (the full path to the Unix socket is
 147 supplied explicitly in this case).
 148 </li>
 149       <li><code>test+tcp://localhost:5000/default</code><br/> &#x2014;
 150 Connect to a libvirtd daemon offering unencrypted TCP/IP connections
 151 on localhost port 5000 and use the test driver with default
 152 settings.
 153 </li>
 154 <li><code>qemu+libssh2://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> &#x2014;
 155 Connect to a remote host using a ssh connection with the libssh2 driver
 156 and use a different known_hosts file.</li>
 157 <li><code>qemu+libssh://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> &#x2014;
 158 Connect to a remote host using a ssh connection with the libssh driver
 159 and use a different known_hosts file.</li>
 160     </ul>
 161     <h3>
 162       <a id="Remote_URI_parameters">Extra parameters</a>
 163     </h3>
 164     <p>
 165 Extra parameters can be added to remote URIs as part
 166 of the query string (the part following <q><code>?</code></q>).
 167 Remote URIs understand the extra parameters shown below.
 168 Any others are passed unmodified through to the back end.
 169 Note that parameter values must be
 170 <a href="http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr">URI-escaped</a>.
 171 </p>
 172     <table class="top_table">
 173       <tr>
 174         <th> Name </th>
 175         <th> Transports </th>
 176         <th> Meaning </th>
 177       </tr>
 178       <tr>
 179         <td>
 180           <code>name</code>
 181         </td>
 182         <td>
 183           <i>any transport</i>
 184         </td>
 185         <td>
 186   The name passed to the remote virConnectOpen function.  The
 187   name is normally formed by removing transport, hostname, port
 188   number, username and extra parameters from the remote URI, but in certain
 189   very complex cases it may be better to supply the name explicitly.
 190 </td>
 191       </tr>
 192       <tr>
 193         <td colspan="2"/>
 194         <td> Example: <code>name=qemu:///system</code> </td>
 195       </tr>
 196       <tr>
 197         <td>
 198           <code>tls_priority</code>
 199         </td>
 200         <td> tls </td>
 201         <td>
 202   A vaid GNUTLS priority string
 203 </td>
 204       </tr>
 205       <tr>
 206         <td colspan="2"/>
 207         <td> Example: <code>tls_priority=NORMAL:-VERS-SSL3.0</code> </td>
 208       </tr>
 209       <tr>
 210         <td>
 211           <code>mode</code>
 212         </td>
 213         <td> unix, ssh, libssh, libssh2 </td>
 214         <td>
 215           <dl>
 216             <dt><code>auto</code></dt><dd>automatically determine the daemon</dd>
 217             <dt><code>direct</code></dt><dd>connect to per-driver daemons</dd>
 218             <dt><code>legacy</code></dt><dd>connect to libvirtd</dd>
 219           </dl>
 220           Can also be set in <code>libvirt.conf</code> as <code>remote_mode</code>
 221         </td>
 222       </tr>
 223       <tr>
 224         <td colspan="2"/>
 225         <td> Example: <code>mode=direct</code> </td>
 226       </tr>
 227       <tr>
 228         <td>
 229           <code>command</code>
 230         </td>
 231         <td> ssh, ext </td>
 232         <td>
 233   The external command.  For ext transport this is required.
 234   For ssh the default is <code>ssh</code>.
 235   The PATH is searched for the command.
 236 </td>
 237       </tr>
 238       <tr>
 239         <td colspan="2"/>
 240         <td> Example: <code>command=/opt/openssh/bin/ssh</code> </td>
 241       </tr>
 242       <tr>
 243         <td>
 244           <code>socket</code>
 245         </td>
 246         <td> unix, ssh, libssh2, libssh </td>
 247         <td>
 248   The path to the Unix domain socket, which overrides the
 249   compiled-in default.  For ssh transport, this is passed to
 250   the remote netcat command (see next).
 251 </td>
 252       </tr>
 253       <tr>
 254         <td colspan="2"/>
 255         <td> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td>
 256       </tr>
 257       <tr>
 258         <td>
 259           <code>netcat</code>
 260         </td>
 261         <td> ssh, libssh2, libssh </td>
 262         <td>
 263   The name of the netcat command on the remote machine.
 264   The default is <code>nc</code>.  For ssh transport, libvirt
 265   constructs an ssh command which looks like:
 266
 267 <pre><i>command</i> -p <i>port</i> [-l <i>username</i>] <i>hostname</i> <i>netcat</i> -U <i>socket</i>
 268 </pre>
 269
 270   where <i>port</i>, <i>username</i>, <i>hostname</i> can be
 271   specified as part of the remote URI, and <i>command</i>, <i>netcat</i>
 272   and <i>socket</i> come from extra parameters (or
 273   sensible defaults).
 274
 275 </td>
 276       </tr>
 277       <tr>
 278         <td colspan="2"/>
 279         <td> Example: <code>netcat=/opt/netcat/bin/nc</code> </td>
 280       </tr>
 281
 282       <tr>
 283         <td>
 284           <code>keyfile</code>
 285         </td>
 286         <td> ssh, libssh2, libssh </td>
 287         <td>
 288   The name of the private key file to use to authentication to the remote
 289   machine.  If this option is not used the default keys are used.
 290         </td>
 291       </tr>
 292       <tr>
 293         <td colspan="2"/>
 294         <td> Example: <code>keyfile=/root/.ssh/example_key</code> </td>
 295       </tr>
 296
 297       <tr>
 298         <td>
 299           <code>no_verify</code>
 300         </td>
 301         <td> ssh, tls </td>
 302         <td>
 303   SSH: If set to a non-zero value, this disables client's strict host key
 304   checking making it auto-accept new host keys.  Existing host keys will
 305   still be validated.
 306   <br/>
 307   <br/>
 308   TLS: If set to a non-zero value, this disables client checks of the
 309   server's certificate.  Note that to disable server checks of
 310   the client's certificate or IP address you must
 311   <a href="#Remote_libvirtd_configuration">change the libvirtd
 312   configuration</a>.
 313 </td>
 314       </tr>
 315       <tr>
 316         <td colspan="2"/>
 317         <td> Example: <code>no_verify=1</code> </td>
 318       </tr>
 319       <tr>
 320         <td>
 321           <code>no_tty</code>
 322         </td>
 323         <td> ssh </td>
 324         <td>
 325   If set to a non-zero value, this stops ssh from asking for
 326   a password if it cannot log in to the remote machine automatically
 327   (eg. using ssh-agent etc.).  Use this when you don't have access
 328   to a terminal - for example in graphical programs which use libvirt.
 329 </td>
 330       </tr>
 331       <tr>
 332         <td colspan="2"/>
 333         <td> Example: <code>no_tty=1</code> </td>
 334       </tr>
 335       <tr>
 336         <td>
 337           <code>pkipath</code>
 338         </td>
 339         <td> tls</td>
 340         <td>
 341           Specifies x509 certificates path for the client. If any of
 342           the CA certificate, client certificate, or client key is
 343           missing, the connection will fail with a fatal error.
 344         </td>
 345       </tr>
 346       <tr>
 347         <td colspan="2"/>
 348         <td> Example: <code>pkipath=/tmp/pki/client</code> </td>
 349       </tr>
 350       <tr>
 351         <td>
 352           <code>known_hosts</code>
 353         </td>
 354         <td> libssh2, libssh </td>
 355         <td>
 356   Path to the known_hosts file to verify the host key against. LibSSH2 and
 357   libssh support OpenSSH-style known_hosts files, although LibSSH2 does not
 358   support all key types, so using files created by the OpenSSH binary may
 359   result into truncating the known_hosts file. Thus, with LibSSH2 it's
 360   recommended to use the default known_hosts file is located in libvirt's
 361   client local configuration directory e.g.: ~/.config/libvirt/known_hosts.
 362   Note: Use absolute paths.
 363 </td>
 364       </tr>
 365       <tr>
 366         <td colspan="2"/>
 367         <td> Example: <code>known_hosts=/root/.ssh/known_hosts</code> </td>
 368       </tr>
 369       <tr>
 370         <td>
 371           <code>sshauth</code>
 372         </td>
 373         <td> libssh2, libssh </td>
 374         <td>
 375   A comma separated list of authentication methods to use. Default (is
 376   "agent,privkey,password,keyboard-interactive". The order of the methods
 377   is preserved. Some methods may require additional parameters.
 378 </td>
 379       </tr>
 380       <tr>
 381         <td colspan="2"/>
 382         <td> Example: <code>sshauth=privkey,agent</code> </td>
 383       </tr>
 384     </table>
 385     <h2>
 386       <a id="Remote_certificates">Generating TLS certificates</a>
 387     </h2>
 388     <h3>
 389       <a id="Remote_PKI">Public Key Infrastructure set up</a>
 390     </h3>
 391     <p>
 392 If you are unsure how to create TLS certificates, skip to the
 393 next section.
 394 </p>
 395     <table class="top_table">
 396       <tr>
 397         <th> Location </th>
 398         <th> Machine </th>
 399         <th> Description </th>
 400         <th> Required fields </th>
 401       </tr>
 402       <tr>
 403         <td>
 404           <code>/etc/pki/CA/cacert.pem</code>
 405         </td>
 406         <td> Installed on the client and server </td>
 407         <td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td>
 408         <td> n/a </td>
 409       </tr>
 410       <tr>
 411         <td>
 412           <code>$HOME/.pki/cacert.pem</code>
 413         </td>
 414         <td> Installed on the client </td>
 415         <td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td>
 416         <td> n/a </td>
 417       </tr>
 418       <tr>
 419         <td>
 420           <code>/etc/pki/libvirt/private/serverkey.pem</code>
 421         </td>
 422         <td> Installed on the server </td>
 423         <td> Server's private key (<a href="#Remote_TLS_server_certificates">more info</a>)</td>
 424         <td> n/a </td>
 425       </tr>
 426       <tr>
 427         <td>
 428           <code>/etc/pki/libvirt/servercert.pem</code>
 429         </td>
 430         <td> Installed on the server </td>
 431         <td> Server's certificate signed by the CA.
 432  (<a href="#Remote_TLS_server_certificates">more info</a>) </td>
 433         <td> CommonName (CN) must be the hostname of the server as it
 434           is seen by clients. All hostname and IP address variants that might
 435           be used to reach the server should be listed in Subject Alt Name
 436           fields.</td>
 437       </tr>
 438       <tr>
 439         <td>
 440           <code>/etc/pki/libvirt/private/clientkey.pem</code>
 441         </td>
 442         <td> Installed on the client </td>
 443         <td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td>
 444         <td> n/a </td>
 445       </tr>
 446       <tr>
 447         <td>
 448           <code>/etc/pki/libvirt/clientcert.pem</code>
 449         </td>
 450         <td> Installed on the client </td>
 451         <td> Client's certificate signed by the CA
 452   (<a href="#Remote_TLS_client_certificates">more info</a>) </td>
 453         <td> Distinguished Name (DN) can be checked against an access
 454   control list (<code>tls_allowed_dn_list</code>).
 455   </td>
 456       </tr>
 457       <tr>
 458         <td>
 459           <code>$HOME/.pki/libvirt/clientkey.pem</code>
 460         </td>
 461         <td> Installed on the client </td>
 462         <td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td>
 463         <td> n/a </td>
 464       </tr>
 465       <tr>
 466         <td>
 467           <code>$HOME/.pki/libvirt/clientcert.pem</code>
 468         </td>
 469         <td> Installed on the client </td>
 470         <td> Client's certificate signed by the CA
 471   (<a href="#Remote_TLS_client_certificates">more info</a>) </td>
 472         <td> Distinguished Name (DN) can be checked against an access
 473   control list (<code>tls_allowed_dn_list</code>).
 474   </td>
 475       </tr>
 476     </table>
 477     <p>
 478       If 'pkipath' is specified in URI, then all the client
 479       certificates must be found in the path specified, otherwise the
 480       connection will fail with a fatal error. If 'pkipath' is not
 481       specified:
 482     </p>
 483     <ul>
 484       <li> For a non-root user, libvirt tries to find the certificates
 485         in $HOME/.pki/libvirt first. If the required CA certificate cannot
 486         be found, then the global default location
 487         (/etc/pki/CA/cacert.pem) will be used.
 488         Likewise, if either the client certificate
 489         or the client key cannot be found, then the global default
 490         locations (/etc/pki/libvirt/clientcert.pem,
 491         /etc/pki/libvirt/private/clientkey.pem) will be used.
 492       </li>
 493       <li> For the root user, the global default locations will always be used.</li>
 494     </ul>
 495     <h3>
 496       <a id="Remote_TLS_background">Background to TLS certificates</a>
 497     </h3>
 498     <p>
 499 Libvirt supports TLS certificates for verifying the identity
 500 of the server and clients.  There are two distinct checks involved:
 501 </p>
 502     <ul>
 503       <li> The client should know that it is connecting to the right
 504 server.  Checking done by client by matching the certificate that
 505 the server sends to the server's hostname.  May be disabled by adding
 506 <code>?no_verify=1</code> to the
 507 <a href="#Remote_URI_parameters">remote URI</a>.
 508 </li>
 509       <li> The server should know that only permitted clients are
 510 connecting.  This can be done based on client's IP address, or on
 511 client's IP address and client's certificate.  Checking done by the
 512 server.  May be enabled and disabled in the <a href="#Remote_libvirtd_configuration">libvirtd.conf file</a>.
 513 </li>
 514     </ul>
 515     <p>
 516 For full certificate checking you will need to have certificates
 517 issued by a recognised <a href="http://en.wikipedia.org/wiki/Certificate_authority">Certificate
 518 Authority (CA)</a> for your server(s) and all clients.  To avoid the
 519 expense of getting certificates from a commercial CA, you can set up
 520 your own CA and tell your server(s) and clients to trust certificates
 521 issues by your own CA.  Follow the instructions in the next section.
 522 </p>
 523     <p>
 524 Be aware that the <a href="#Remote_libvirtd_configuration">default
 525 configuration for libvirtd</a> allows any client to connect provided
 526 they have a valid certificate issued by the CA for their own IP
 527 address.  You may want to change this to make it less (or more)
 528 permissive, depending on your needs.
 529 </p>
 530     <h3>
 531       <a id="Remote_TLS_CA">Setting up a Certificate Authority (CA)</a>
 532     </h3>
 533     <p>
 534 You will need the <a href="http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html">GnuTLS
 535 certtool program documented here</a>.  In Fedora, it is in the
 536 <code>gnutls-utils</code> package.
 537 </p>
 538     <p>
 539 Create a private key for your CA:
 540 </p>
 541     <pre>
 542 certtool --generate-privkey &gt; cakey.pem
 543 </pre>
 544     <p>
 545 and self-sign it by creating a file with the
 546 signature details called
 547 <code>ca.info</code> containing:
 548 </p>
 549     <pre>
 550 cn = <i>Name of your organization</i>
 551 ca
 552 cert_signing_key
 553 </pre>
 554     <pre>
 555 certtool --generate-self-signed --load-privkey cakey.pem \
 556   --template ca.info --outfile cacert.pem
 557 </pre>
 558     <p>
 559 (You can delete <code>ca.info</code> file now if you
 560 want).
 561 </p>
 562     <p>
 563 Now you have two files which matter:
 564 </p>
 565     <ul>
 566       <li><code>cakey.pem</code> - Your CA's private key (keep this very secret!)
 567 </li>
 568       <li><code>cacert.pem</code> - Your CA's certificate (this is public).
 569 </li>
 570     </ul>
 571     <p><code>cacert.pem</code> has to be installed on clients and
 572 server(s) to let them know that they can trust certificates issued by
 573 your CA.
 574 </p>
 575     <p>
 576 The normal installation directory for <code>cacert.pem</code>
 577 is <code>/etc/pki/CA/cacert.pem</code> on all clients and servers.
 578 </p>
 579     <p>
 580 To see the contents of this file, do:
 581 </p>
 582     <pre><b>certtool -i --infile cacert.pem</b>
 583
 584 X.509 certificate info:
 585
 586 Version: 3
 587 Serial Number (hex): 00
 588 Subject: CN=Libvirt Project
 589 Issuer: CN=Libvirt Project
 590 Signature Algorithm: RSA-SHA
 591 Validity:
 592         Not Before: Mon Jun 18 16:22:18 2007
 593         Not After: Tue Jun 17 16:22:18 2008
 594 <i>[etc]</i>
 595 </pre>
 596     <p>
 597 This is all that is required to set up your CA.  Keep the CA's private
 598 key carefully as you will need it when you come to issue certificates
 599 for your clients and servers.
 600 </p>
 601     <h3>
 602       <a id="Remote_TLS_server_certificates">Issuing server certificates</a>
 603     </h3>
 604     <p>
 605 For each server (libvirtd) you need to issue a certificate
 606 containing one or more hostnames and/or IP addresses.
 607 Historically the CommonName (CN) field would contain the
 608 hostname of the server and would match the hostname used
 609 in the URI that clients pass to libvirt. In most TLS implementations
 610 the CN field is considered legacy data. The preferential mechanism
 611 is to use Subject Alt Name (SAN) extension fields to validate
 612 against. In the future use of the CN field for validation may be
 613 discontinued entirely, so it is strongly recommended to
 614 include the SAN fields.
 615 </p>
 616     <p>
 617 In the example below, clients will be connecting to the
 618 server using a <a href="#Remote_URI_reference">URI</a> of
 619 <code>qemu://compute1.libvirt.org/system</code>, so the CN
 620 must be "<code>compute1.libvirt.org</code>".
 621 </p>
 622     <p>
 623 Make a private key for the server:
 624 </p>
 625     <pre>
 626 certtool --generate-privkey &gt; serverkey.pem
 627 </pre>
 628     <p>
 629 and sign that key with the CA's private key by first
 630 creating a template file called <code>server.info</code>.
 631 The template file will contain a number of fields to define
 632 the server as follows:
 633 </p>
 634     <pre>
 635 organization = <i>Name of your organization</i>
 636 cn = compute1.libvirt.org
 637 dns_name = compute1
 638 dns_name = compute1.libvirt.org
 639 ip_address = 10.0.0.74
 640 ip_address = 192.168.1.24
 641 ip_address = 2001:cafe::74
 642 ip_address = fe20::24
 643 tls_www_server
 644 encryption_key
 645 signing_key
 646 </pre>
 647 <p>
 648 The 'cn' field should refer to the fully qualified public
 649 hostname of the server. For the SAN extension data, there
 650 must also be one or more 'dns_name' fields that contain all
 651 possible hostnames that can be reasonably used by clients
 652 to reach the server, both with and without domain name
 653 qualifiers. If clients are likely to connect to the server
 654 by IP address, then one or more 'ip_address' fields should
 655 also be added.
 656 </p>
 657     <p>
 658 Use the template file as input to a <code>certtool</code>
 659 command to sign the server certificate:
 660 </p>
 661     <pre>
 662 certtool --generate-certificate --load-privkey serverkey.pem \
 663   --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
 664   --template server.info --outfile servercert.pem
 665 </pre>
 666     <p>
 667 This gives two files:
 668 </p>
 669     <ul>
 670       <li><code>serverkey.pem</code> - The server's private key.
 671 </li>
 672       <li><code>servercert.pem</code> - The server's public key.
 673 </li>
 674     </ul>
 675     <p>
 676 We can examine this certificate and its signature:
 677 </p>
 678     <pre><b>certtool -i --infile servercert.pem</b>
 679 X.509 certificate info:
 680
 681 Version: 3
 682 Serial Number (hex): 00
 683 Subject: O=Libvirt Project,CN=compute1.libvirt.org
 684 Issuer: CN=Libvirt Project
 685 Signature Algorithm: RSA-SHA
 686 Validity:
 687         Not Before: Wed Oct 04 09:09:44 UTC 2017
 688         Not After: Thu Oct 04 09:09:44 UTC 2018
 689 Extensions:
 690         Basic Constraints (critical):
 691                 Certificate Authority (CA): FALSE
 692         Subject Alternative Name (not critical):
 693                 DNSname: compute1
 694                 DNSname: compute1.libvirt.org
 695                 IPAddress: 10.0.0.74
 696                 IPAddress: 192.168.1.24
 697                 IPAddress: 2001:cafe::74
 698                 IPAddress: fe20::24
 699 </pre>
 700     <p>
 701 Note the "Issuer" CN is "Libvirt Project" (the CA) and
 702 the "Subject" CN is "compute1.libvirt.org" (the server).
 703 Notice that the hostname listed in the CN must also
 704 be duplicated as a DNSname entry
 705 </p>
 706     <p>
 707 Finally we have two files to install:
 708 </p>
 709     <ul>
 710       <li><code>serverkey.pem</code> is
 711 the server's private key which should be copied to the
 712 server <i>only</i> as
 713 <code>/etc/pki/libvirt/private/serverkey.pem</code>.
 714 </li>
 715       <li><code>servercert.pem</code> is the server's certificate
 716 which can be installed on the server as
 717 <code>/etc/pki/libvirt/servercert.pem</code>.
 718 </li>
 719     </ul>
 720     <h3>
 721       <a id="Remote_TLS_client_certificates">Issuing client certificates</a>
 722     </h3>
 723     <p>
 724 For each client (ie. any program linked with libvirt, such as
 725 <a href="http://virt-manager.org/">virt-manager</a>)
 726 you need to issue a certificate with the X.509 Distinguished Name (DN)
 727 set to a suitable name.  You can decide this on a company / organisation
 728 policy.  For example:
 729 </p>
 730     <pre>
 731 C=GB,ST=London,L=London,O=Libvirt Project,CN=<i>name_of_client</i>
 732 </pre>
 733     <p>
 734 The process is the same as for
 735 <a href="#Remote_TLS_server_certificates">setting up the
 736 server certificate</a> so here we just briefly cover the
 737 steps.
 738 </p>
 739     <ol>
 740       <li>
 741 Make a private key:
 742 <pre>
 743 certtool --generate-privkey &gt; clientkey.pem
 744 </pre>
 745 </li>
 746       <li>
 747 Act as CA and sign the certificate.  Create client.info containing:
 748 <pre>
 749 country = GB
 750 state = London
 751 locality = London
 752 organization = Libvirt Project
 753 cn = client1
 754 tls_www_client
 755 encryption_key
 756 signing_key
 757 </pre>
 758 and sign by doing:
 759 <pre>
 760 certtool --generate-certificate --load-privkey clientkey.pem \
 761   --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
 762   --template client.info --outfile clientcert.pem
 763 </pre>
 764 </li>
 765       <li>
 766 Install the certificates on the client machine:
 767 <pre>
 768 cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
 769 cp clientcert.pem /etc/pki/libvirt/clientcert.pem
 770 </pre>
 771 </li>
 772     </ol>
 773     <h3>
 774       <a id="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a>
 775     </h3>
 776     <dl>
 777       <dt> failed to verify client's certificate </dt>
 778       <dd>
 779         <p>
 780 On the server side, run the libvirtd server with
 781 the '--listen' and '--verbose' options while the
 782 client is connecting.  The verbose log messages should
 783 tell you enough to diagnose the problem.
 784 </p>
 785       </dd>
 786     </dl>
 787     <p> You can use the virt-pki-validate shell script
 788 to analyze the setup on the client or server machines, preferably as root.
 789 It will try to point out the possible problems and provide solutions to
 790 fix the set up up to a point where you have secure remote access.</p>
 791     <h2>
 792       <a id="Remote_libvirtd_configuration">libvirtd configuration file</a>
 793     </h2>
 794     <p>
 795 Libvirtd (the remote daemon) is configured from a file called
 796 <code>/etc/libvirt/libvirtd.conf</code>, or specified on
 797 the command line using <code>-f filename</code> or
 798 <code>--config filename</code>.
 799 </p>
 800     <p>
 801 This file should contain lines of the form below.
 802 Blank lines and comments beginning with <code>#</code> are ignored.
 803 </p>
 804     <pre>setting = value</pre>
 805     <p>The following settings, values and default are:</p>
 806     <table class="top_table">
 807       <tr>
 808         <th> Line </th>
 809         <th> Default </th>
 810         <th> Meaning </th>
 811       </tr>
 812       <tr>
 813         <td> listen_tls <i>[0|1]</i> </td>
 814         <td> 1 (on) </td>
 815         <td>
 816   Listen for secure TLS connections on the public TCP/IP port.
 817   Note: it is also necessary to start the server in listening mode by
 818   running it with --listen or editing /etc/sysconfig/libvirtd by uncommenting the LIBVIRTD_ARGS="--listen" line
 819   to cause the server to come up in listening mode whenever it is started.
 820 </td>
 821       </tr>
 822       <tr>
 823         <td> listen_tcp <i>[0|1]</i> </td>
 824         <td> 0 (off) </td>
 825         <td>
 826   Listen for unencrypted TCP connections on the public TCP/IP port.
 827   Note: it is also necessary to start the server in listening mode.
 828 </td>
 829       </tr>
 830       <tr>
 831         <td> tls_port <i>"service"</i> </td>
 832         <td> "16514" </td>
 833         <td>
 834   The port number or service name to listen on for secure TLS connections.
 835 </td>
 836       </tr>
 837       <tr>
 838         <td> tcp_port <i>"service"</i> </td>
 839         <td> "16509" </td>
 840         <td>
 841   The port number or service name to listen on for unencrypted TCP connections.
 842 </td>
 843       </tr>
 844       <tr>
 845         <td> unix_sock_group <i>"groupname"</i> </td>
 846         <td> "root" </td>
 847         <td>
 848   The UNIX group to own the UNIX domain socket. If the socket permissions allow
 849   group access, then applications running under matching group can access the
 850   socket. Only valid if running as root
 851 </td>
 852       </tr>
 853       <tr>
 854         <td> unix_sock_ro_perms <i>"octal-perms"</i> </td>
 855         <td> "0777" </td>
 856         <td>
 857   The permissions for the UNIX domain socket for read-only client connections.
 858   The default allows any user to monitor domains.
 859 </td>
 860       </tr>
 861       <tr>
 862         <td> unix_sock_rw_perms <i>"octal-perms"</i> </td>
 863         <td> "0700" </td>
 864         <td>
 865   The permissions for the UNIX domain socket for read-write client connections.
 866   The default allows only root to manage domains.
 867 </td>
 868       </tr>
 869       <tr>
 870         <td> tls_no_verify_certificate <i>[0|1]</i> </td>
 871         <td> 0 (certificates are verified) </td>
 872         <td>
 873   If set to 1 then if a client certificate check fails, it is not an error.
 874 </td>
 875       </tr>
 876       <tr>
 877         <td> tls_no_verify_address <i>[0|1]</i> </td>
 878         <td> 0 (addresses are verified) </td>
 879         <td>
 880   If set to 1 then if a client IP address check fails, it is not an error.
 881 </td>
 882       </tr>
 883       <tr>
 884         <td> key_file <i>"filename"</i> </td>
 885         <td> "/etc/pki/libvirt/ private/serverkey.pem" </td>
 886         <td>
 887   Change the path used to find the server's private key.
 888   If you set this to an empty string, then no private key is loaded.
 889 </td>
 890       </tr>
 891       <tr>
 892         <td> cert_file <i>"filename"</i> </td>
 893         <td> "/etc/pki/libvirt/ servercert.pem" </td>
 894         <td>
 895   Change the path used to find the server's certificate.
 896   If you set this to an empty string, then no certificate is loaded.
 897 </td>
 898       </tr>
 899       <tr>
 900         <td> ca_file <i>"filename"</i> </td>
 901         <td> "/etc/pki/CA/cacert.pem" </td>
 902         <td>
 903   Change the path used to find the trusted CA certificate.
 904   If you set this to an empty string, then no trusted CA certificate is loaded.
 905 </td>
 906       </tr>
 907       <tr>
 908         <td> crl_file <i>"filename"</i> </td>
 909         <td> (no CRL file is used) </td>
 910         <td>
 911   Change the path used to find the CA certificate revocation list (CRL) file.
 912   If you set this to an empty string, then no CRL is loaded.
 913 </td>
 914       </tr>
 915       <tr>
 916         <td> tls_allowed_dn_list ["DN1", "DN2"] </td>
 917         <td> (none - DNs are not checked) </td>
 918         <td>
 919           <p>
 920   Enable an access control list of client certificate Distinguished
 921   Names (DNs) which can connect to the TLS port on this server.
 922   </p>
 923           <p>
 924   The default is that DNs are not checked.
 925   </p>
 926           <p>
 927   This list may contain wildcards such as <code>"C=GB,ST=London,L=London,O=Libvirt Project,CN=*"</code>
 928   See the POSIX <code>fnmatch</code> function for the format
 929   of the wildcards.
 930   </p>
 931           <p>
 932   Note that if this is an empty list, <i>no client can connect</i>.
 933   </p>
 934           <p>
 935   Note also that GnuTLS returns DNs without spaces
 936   after commas between the fields (and this is what we check against),
 937   but the <code>openssl x509</code> tool shows spaces.
 938 </p>
 939         </td>
 940       </tr>
 941     </table>
 942     <h2>
 943       <a id="Remote_IPv6">IPv6 support</a>
 944     </h2>
 945     <p>
 946 The libvirtd service and libvirt remote client driver both use the
 947 <code>getaddrinfo()</code> functions for name resolution and are
 948 thus fully IPv6 enabled. ie, if a server has IPv6 address configured
 949 the daemon will listen for incoming connections on both IPv4 and IPv6
 950 protocols. If a client has an IPv6 address configured and the DNS
 951 address resolved for a service is reachable over IPv6, then an IPv6
 952 connection will be made, otherwise IPv4 will be used. In summary it
 953 should just 'do the right thing(tm)'.
 954 </p>
 955     <h2>
 956       <a id="Remote_limitations">Limitations</a>
 957     </h2>
 958     <ul>
 959       <li> Fine-grained authentication: libvirt in general,
 960 but in particular the remote case should support more
 961 fine-grained authentication for operations, rather than
 962 just read-write/read-only as at present.
 963 </li>
 964     </ul>
 965     <p>
 966 Please come and discuss these issues and more on <a href="https://www.redhat.com/mailman/listinfo/libvir-list" title="libvir-list mailing list">the mailing list</a>.
 967 </p>
 968   </body>
 969 </html>