[libvirt] [PATCH] esx: Add documentation about certificates and connection problems
Matthias Bolte
matthias.bolte at googlemail.com
Fri Oct 22 13:04:43 UTC 2010
---
docs/drvesx.html.in | 103 +++++++++++++++++++++++++++++++++++++++++++++++++-
docs/remote.html.in | 8 +++-
2 files changed, 107 insertions(+), 4 deletions(-)
diff --git a/docs/drvesx.html.in b/docs/drvesx.html.in
index dfc91bb..a0f87c1 100644
--- a/docs/drvesx.html.in
+++ b/docs/drvesx.html.in
@@ -74,7 +74,7 @@ vpx://example-vcenter.com/dc1/cluster1/example-esx.com
</pre>
- <h4>Extra parameters</h4>
+ <h4><a name="extraparams">Extra parameters</h4>
<p>
Extra parameters can be added to a URI as part of the query string
(the part following <code>?</code>). A single parameter is formed by a
@@ -117,7 +117,7 @@ vpx://example-vcenter.com/dc1/cluster1/example-esx.com
In order to perform a migration the driver needs to know the
VMware vCenter for the ESX server. If set to <code>*</code>,
the driver connects to the vCenter known to the ESX server.
- This paramater in useful when connecting to an ESX server only.
+ This parameter in useful when connecting to an ESX server only.
</td>
</tr>
<tr>
@@ -129,7 +129,9 @@ vpx://example-vcenter.com/dc1/cluster1/example-esx.com
</td>
<td>
If set to 1, this disables libcurl client checks of the server's
- SSL certificate. The default value it 0.
+ SSL certificate. The default value it 0. See the
+ <a href="#certificates">Certificates for HTTPS</a> section for
+ details.
</td>
</tr>
<tr>
@@ -187,6 +189,101 @@ vpx://example-vcenter.com/dc1/cluster1/example-esx.com
</p>
+ <h3><a name="certificates">Certificates for HTTPS</a></h3>
+ <p>
+ By default the ESX driver uses HTTPS to communicate with an ESX server.
+ Proper HTTPS communication requires correctly configured SSL
+ certificates. This certificates are different from the ones libvirt
+ uses for <a href="remote.html">secure communication over TLS</a> to a
+ libvirtd one a remote server.
+ </p>
+ <p>
+ By default the driver tries to verify the server's SSL certificate
+ using the CA certificate pool installed on your client computer. With
+ an out-of-the-box installed ESX server this won't work, because a newly
+ installed ESX server uses auto-generated self-signed certificates.
+ Those are singed by a CA certificate that is typically not known to your
+ client computer and libvirt will report an error like this one:
+ </p>
+<pre>
+error: internal error curl_easy_perform() returned an error: Peer certificate cannot be authenticated with known CA certificates (60)
+</pre>
+ <p>
+ Where are two ways to solve this problem:
+ </p>
+ <ul>
+ <li>
+ Use the <code>no_verify=1</code> <a href="#extraparams">extra parameter</a>
+ to disable server certificate verification.
+ </li>
+ <li>
+ Generate new SSL certificates signed by a CA known to your client
+ computer and replace the original ones on your ESX server. See the
+ section <i>Replace a Default Certificate with a CA-Signed Certificate</i>
+ in the <a href="http://www.vmware.com/pdf/vsphere4/r40/vsp_40_esx_server_config.pdf">ESX Configuration Guide</a>
+ </li>
+ </ul>
+
+
+ <h3><a name="connproblems">Connection problems</a></h3>
+ <p>
+ There are also other causes for connection problems than the
+ <a href="#certificates">HTTPS certificate</a> related ones.
+ </p>
+ <ul>
+ <li>
+ As stated before the ESX driver doesn't need the
+ <a href="remote.html">remote transport mechanism</a>
+ provided by the remote driver and libvirtd, nor does the ESX driver
+ support it. Therefore, using an URI including a transport in the
+ scheme won't work. Only <a href="#uriformat">URIs as described</a>
+ are supported by the ESX driver. Here's a collection of possible
+ error messages:
+<pre>
+$ virsh -c esx+tcp://example.com/
+error: unable to connect to libvirtd at 'example.com': Connection refused
+</pre>
+<pre>
+$ virsh -c esx+tls://example.com/
+error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
+</pre>
+<pre>
+$ virsh -c esx+ssh://example.com/
+error: cannot recv data: ssh: connect to host example.com port 22: Connection refused
+</pre>
+<pre>
+$ virsh -c esx+ssh://example.com/
+error: cannot recv data: Resource temporarily unavailable
+</pre>
+ </li>
+ <li>
+ <span class="since">Since 0.7.0</span> libvirt contains the ESX
+ driver. Earlier versions of libvirt will report a misleading error
+ about missing certificates when you try to connect to an ESX server.
+<pre>
+$ virsh -c esx://example.com/
+error: Cannot access CA certificate '/etc/pki/CA/cacert.pem': No such file or directory
+</pre>
+ <p>
+ Don't let this error message confuse you. Setting up certificates
+ as described on the <a href="remote.html#Remote_certificates">remote transport mechanism</a> page
+ does not help, as this is not a certificate related problem.
+ </p>
+ <p>
+ To fix this problem you need to update your libvirt to 0.7.0 or newer.
+ You may also see this error when you use a libvirt version that
+ contains the ESX driver but you or your distro disabled the ESX
+ driver during compilation. <span class="since">Since 0.8.3</span>
+ the error message has been improved in this case:
+ </p>
+<pre>
+$ virsh -c esx://example.com/
+error: invalid argument in libvirt was built without the 'esx' driver
+</pre>
+ </li>
+ </ul>
+
+
<h2><a name="questions">Questions blocking tasks</a></h2>
<p>
Some methods of the VI API start tasks, for example
diff --git a/docs/remote.html.in b/docs/remote.html.in
index 37b019b..b0fdb7c 100644
--- a/docs/remote.html.in
+++ b/docs/remote.html.in
@@ -61,11 +61,17 @@ machines through authenticated and encrypted connections.
<a name="Remote_basic_usage">Basic usage</a>
</h3>
<p>
-On the remote machine, <code>libvirtd</code> should be running.
+On the remote machine, <code>libvirtd</code> should be running in general.
See <a href="#Remote_libvirtd_configuration">the section
on configuring libvirtd</a> for more information.
</p>
<p>
+ Not all hypervisors supported by libvirt require a running
+ <code>libvirtd</code>. If you want to connect to a VMware ESX/ESXi or
+ GSX server then <code>libvirtd</code> is not necessary. See the
+ <a href="drvesx.html">VMware ESX page</a> for details.
+ </p>
+ <p>
To tell libvirt that you want to access a remote resource,
you should supply a hostname in the normal <a href="uri.html">URI</a> that is passed
to <code>virConnectOpen</code> (or <code>virsh -c ...</code>).
--
1.7.0.4
More information about the libvir-list
mailing list