[libvirt] [PATCH] docs: added compiling page and significantly expanded windows page
Also added an additional menu placement for the windows page, in order to attract further potential testers. --- docs/compiling.html.in | 48 ++++++++++++++++++++++++ docs/downloads.html.in | 41 +-------------------- docs/sitemap.html.in | 10 +++++ docs/windows.html.in | 95 +++++++++++++++++++++++++++++++++++++++++------- 4 files changed, 142 insertions(+), 52 deletions(-) create mode 100644 docs/compiling.html.in diff --git a/docs/compiling.html.in b/docs/compiling.html.in new file mode 100644 index 0000000..471f52d --- /dev/null +++ b/docs/compiling.html.in @@ -0,0 +1,48 @@ +<?xml version="1.0"?> +<html> + <body> + <h1><a name="installation">libvirt Installation</a></h1> + + <ul id="toc"></ul> + + <h2><a name="Compilatio">Compiling a release tarball</a></h2> + + <p> + libvirt uses the standard configure/make/install steps: + </p> + + <pre> + gunzip -c libvirt-xxx.tar.gz | tar xvf - + cd libvirt-xxxx + ./configure --help</pre> + + <p> + To see the options, then the compilation/installation proper: + </p> + + <pre> + ./configure [possible options] + make + make install</pre> + + <p> + At that point you may have to rerun ldconfig or a similar utility to + update your list of installed shared libs. + </p> + + <h2><a name="build">Building from a GIT checkout</a></h2> + + <p> + The libvirt build process uses GNU autotools, so after obtaining a + checkout it is necessary to generate the configure script and Makefile.in + templates using the <code>autogen.sh</code> command, passing the extra + arguments as for configure. As an example, to do a complete build and + install it into your home directory run: + </p> + + <pre> + ./autogen.sh --prefix=$HOME/usr --enable-compile-warnings=error + make + make install</pre> + </body> +</html> diff --git a/docs/downloads.html.in b/docs/downloads.html.in index 709bee8..64a16c9 100644 --- a/docs/downloads.html.in +++ b/docs/downloads.html.in @@ -91,46 +91,9 @@ <br /> - <h1><a name="installation">libvirt Installation</a></h1> - - <h2><a name="Compilatio">Compiling a release tarball</a></h2> - - <p> - libvirt uses the standard configure/make/install steps: - </p> - - <pre> - gunzip -c libvirt-xxx.tar.gz | tar xvf - - cd libvirt-xxxx - ./configure --help</pre> - - <p> - To see the options, then the compilation/installation proper: - </p> - - <pre> - ./configure [possible options] - make - make install</pre> - <p> - At that point you may have to rerun ldconfig or a similar utility to - update your list of installed shared libs. + Once you've have obtained the libvirt source code, you can compile it + using the <a href="compiling.html">instructions here</a>. </p> - - <h2><a name="build">Building from a GIT checkout</a></h2> - - <p> - The libvirt build process uses GNU autotools, so after obtaining a - checkout it is necessary to generate the configure script and Makefile.in - templates using the <code>autogen.sh</code> command, passing the extra - arguments as for configure. As an example, to do a complete build and - install it into your home directory run: - </p> - - <pre> - ./autogen.sh --prefix=$HOME/usr --enable-compile-warnings=error - make - make install</pre> </body> </html> diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in index 692da29..bd39e10 100644 --- a/docs/sitemap.html.in +++ b/docs/sitemap.html.in @@ -21,12 +21,22 @@ <li> <a href="downloads.html">Downloads</a> <span>Get the latest source releases, binary builds and get access to the source repository</span> + <ul> + <li> + <a href="windows.html">Windows</a> + <span>Downloads for Windows</span> + </li> + </ul> </li> <li> <a href="docs.html">Documentation</a> <span>Information for users, administrators and developers</span> <ul> <li> + <a href="compiling.html">Compiling</a> + <span>How to compile libvirt</span> + </li> + <li> <a href="deployment.html">Deployment</a> <span>Information about deploying and using libvirt</span> <ul> diff --git a/docs/windows.html.in b/docs/windows.html.in index 8ca6b0d..f973d76 100644 --- a/docs/windows.html.in +++ b/docs/windows.html.in @@ -3,20 +3,93 @@ <body> <h1 >Windows support</h1> + <ul id="toc"></ul> + + <p> + Libvirt is known to work as a client (not server) on Windows XP + (32-bit), Windows 7 (64-bit), and other Windows variants. + </p> + + <h2><a name="installer">Experimental installation package</a></h2> + + <p> + A windows installation package is in development. An experimental + first version is available here: + </p> + + <a href="http://libvirt.org/sources/win32_experimental/Libvirt-0.8.5-0.exe">http://libvirt.org/sources/win32_experimental/Libvirt-0.8.5-0.exe</a> + <p> - Libvirt can be compiled on Windows - using the free <a href="http://www.mingw.org/">MinGW compiler</a>. - You can also cross-compile to a Windows target - from a Fedora machine using the packages available - <a href="http://hg.et.redhat.com/misc/fedora-mingw--devel/">from - the Fedora MinGW project</a> + <b>It is not production ready.</b> + </p> + + <p> + This version includes the libvirt development headers and libraries + for compiling against, the virsh shell with it's needed dependencies, + and untested Python bindings. + </p> + + <h3><a name="caveats">Caveats</h3> + + <ul> + <li> + This installer just repackages the files compiled using Matthias + Bolte's msys_setup scripting (described below). + </li> + <li> + This is a .exe installer, created using NSIS. We're looking into + something to create .msi installers as well. + </li> + <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li> + <li> + The script for the NSIS installer is available online + <a href="https://github.com/justinclift/nsis_libvirt_installer">here</a>. + </li> + </ul> + + <h3><a name="feedback">Feedback</h3> + + <p> + Feedback and suggestions on changes to make and what else to include + <a href="contact.html">are desired</a>. + + <h2><a name="compiling">Compiling yourself</a></h2> + + <p> + Libvirt can be compiled on Windows using the free + <a href="http://www.mingw.org/">MinGW compiler</a>. + </p> + + <h3><a name="msys_setup">MSYS Build script</a></h3> + + <p> + The easiest way is to use the <b>msys_setup</b> script, developed by + Matthias Bolte. This is actively developed and kept current with + libvirt releases: + </p> + + <a href="https://github.com/photron/msys_setup">https://github.com/photron/msys_setup</a> + + <h3><a name="cross-compile">Cross compiling</a></h3> + + <p> + You can also cross-compile to a Windows target from a Fedora machine + using the packages available + <a href="http://hg.et.redhat.com/misc/fedora-mingw--devel/">from the Fedora MinGW project</a> (which includes a working libvirt specfile). </p> + <h3><a name="configure">By hand</a></h3> + <p> - Libvirt can only be built as a client on Windows - allowing remote access to systems libvirt servers. - Configure libvirt like this: + Use these options when following the instructions on the + <a href="compiling.html">Compiling</a> page. </p> <pre> @@ -32,9 +105,5 @@ --without-libvirtd </pre> - <p> - We intend to supply Windows binaries on this page - later, but at the moment you have to compile from source. - </p> </body> </html> -- 1.7.3
2010/11/17 Justin Clift <jclift@redhat.com>:
Also added an additional menu placement for the windows page, in order to attract further potential testers. ---
+ <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here. As stated on IRC my initial assumption was wrong. The problem is probably not in GnuTLS, as gnutls-cli works fine. The problem is in the way libcurl and GnuTLS interact. Therefore libvirt's GnuTLS usage is not affected, only libcurl's. I know how to fix it, but I don't understand in detail yet why it works. Matthias
On Wed, Nov 17, 2010 at 02:53:15PM +0100, Matthias Bolte wrote:
2010/11/17 Justin Clift <jclift@redhat.com>:
Also added an additional menu placement for the windows page, in order to attract further potential testers. ---
+ <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here. As stated on IRC my initial assumption was wrong. The problem is probably not in GnuTLS, as gnutls-cli works fine. The problem is in the way libcurl and GnuTLS interact. Therefore libvirt's GnuTLS usage is not affected, only libcurl's.
Also this is mixing up two different drivers, the remote driver vs the ESX driver. The remote driver with TLS should in fact work, and is indeed the *only* transport for the driver which we can recommend using from Windows clients. qemu+tcp:// should not be recommended, because there is no SASL support yet and no one wants to be using this unencrypted with no auth. Regards, Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
On 18/11/2010, at 1:02 AM, "Daniel P. Berrange" <berrange@redhat.com> wrote:.
Also this is mixing up two different drivers, the remote driver vs the ESX driver. The remote driver with TLS should in fact work, and is indeed the *only* transport for the driver which we can recommend using from Windows clients. qemu+tcp:// should not be recommended, because there is no SASL support yet and no one wants to be using this unencrypted with no auth.
Good point, there should be some explicit warning about unencrypted tcp, and it's probably a good idea for point people towards TLS (after testing). Will adjust.
On Wed, Nov 17, 2010 at 02:53:15PM +0100, Matthias Bolte wrote:
2010/11/17 Justin Clift <jclift@redhat.com>:
Also added an additional menu placement for the windows page, in order to attract further potential testers. ---
+ <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here. As stated on IRC my initial assumption was wrong. The problem is probably not in GnuTLS, as gnutls-cli works fine. The problem is in the way libcurl and GnuTLS interact. Therefore libvirt's GnuTLS usage is not affected, only libcurl's.
I know how to fix it, but I don't understand in detail yet why it works.
Are you referring to this message ? "A TLS packet with unexpected length was received" The place you normally see this is from 'gnutls_handshake()', and it is an indication that the handshake has been aborted by either the client or server. Typical problems include bad certificates, bad choice of encryption ciphers, bad TLS protocol, etc. It is pretty hard to debug, likely want to turn on the verbose GnuTLS debugging options in the code, and also verify how the ESX server is configured and all your certificates In particular, by default GnuTLS will reject certificates issued by openssl which default to x509 v1, and thus lack the 'Basic Constraints' extension from x509 v3. Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
2010/11/17 Daniel P. Berrange <berrange@redhat.com>:
On Wed, Nov 17, 2010 at 02:53:15PM +0100, Matthias Bolte wrote:
2010/11/17 Justin Clift <jclift@redhat.com>:
Also added an additional menu placement for the windows page, in order to attract further potential testers. ---
+ <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here. As stated on IRC my initial assumption was wrong. The problem is probably not in GnuTLS, as gnutls-cli works fine. The problem is in the way libcurl and GnuTLS interact. Therefore libvirt's GnuTLS usage is not affected, only libcurl's.
I know how to fix it, but I don't understand in detail yet why it works.
Are you referring to this message ?
"A TLS packet with unexpected length was received"
The place you normally see this is from 'gnutls_handshake()', and it is an indication that the handshake has been aborted by either the client or server. Typical problems include bad certificates, bad choice of encryption ciphers, bad TLS protocol, etc. It is pretty hard to debug, likely want to turn on the verbose GnuTLS debugging options in the code, and also verify how the ESX server is configured and all your certificates
In particular, by default GnuTLS will reject certificates issued by openssl which default to x509 v1, and thus lack the 'Basic Constraints' extension from x509 v3.
Daniel
Well, yes that's the problem and it is the handshake. As I can tell from Wireshark the client sends a RST package directly after the Client Hello. So this is not certificate related or something like that. This problem also occurs with curl -kv https://www.google.com and other HTTPS websites. This only happens when curl is compiled with GnuTLS. curl compiled with OpenSSL or PolarSSL works just fine. Also this only happens on Windows. I tried to find precompiled curl binaries that use GnuTLS to check if the problem is in the way I compile curl, but all binaries I could find use OpenSSL, even the Fedora mingw32-curl package uses OpenSSL. I traced the problem down to this libcurl commit https://github.com/bagder/curl/commit/fcccf9aa0d93c666e8ae31ebdde716cddd6b44... from 2006. This commit makes sure that GnuTLS calls send() with the MSG_NOSIGNAL flag to avoid SIGPIPE. If I revert this commit curl works just fine with GnuTLS. Also this commit as is has no use on Windows, because there is no MSG_NOSIGNAL flag for send() on Windows. But this commit triggers the handshake problem and I didn't understand yet why it does so. Matthias
On Wed, Nov 17, 2010 at 03:42:18PM +0100, Matthias Bolte wrote:
2010/11/17 Daniel P. Berrange <berrange@redhat.com>:
On Wed, Nov 17, 2010 at 02:53:15PM +0100, Matthias Bolte wrote:
2010/11/17 Justin Clift <jclift@redhat.com>:
Also added an additional menu placement for the windows page, in order to attract further potential testers. ---
+ <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here. As stated on IRC my initial assumption was wrong. The problem is probably not in GnuTLS, as gnutls-cli works fine. The problem is in the way libcurl and GnuTLS interact. Therefore libvirt's GnuTLS usage is not affected, only libcurl's.
I know how to fix it, but I don't understand in detail yet why it works.
Are you referring to this message ?
"A TLS packet with unexpected length was received"
The place you normally see this is from 'gnutls_handshake()', and it is an indication that the handshake has been aborted by either the client or server. Typical problems include bad certificates, bad choice of encryption ciphers, bad TLS protocol, etc. It is pretty hard to debug, likely want to turn on the verbose GnuTLS debugging options in the code, and also verify how the ESX server is configured and all your certificates
In particular, by default GnuTLS will reject certificates issued by openssl which default to x509 v1, and thus lack the 'Basic Constraints' extension from x509 v3.
Daniel
Well, yes that's the problem and it is the handshake. As I can tell from Wireshark the client sends a RST package directly after the Client Hello. So this is not certificate related or something like that.
This problem also occurs with
curl -kv https://www.google.com
and other HTTPS websites. This only happens when curl is compiled with GnuTLS. curl compiled with OpenSSL or PolarSSL works just fine. Also this only happens on Windows. I tried to find precompiled curl binaries that use GnuTLS to check if the problem is in the way I compile curl, but all binaries I could find use OpenSSL, even the Fedora mingw32-curl package uses OpenSSL.
I traced the problem down to this libcurl commit
https://github.com/bagder/curl/commit/fcccf9aa0d93c666e8ae31ebdde716cddd6b44...
from 2006. This commit makes sure that GnuTLS calls send() with the MSG_NOSIGNAL flag to avoid SIGPIPE. If I revert this commit curl works just fine with GnuTLS. Also this commit as is has no use on Windows, because there is no MSG_NOSIGNAL flag for send() on Windows. But this commit triggers the handshake problem and I didn't understand yet why it does so.
I'm not convinced that they should be calling 'gnutls_transport_set_lowat' so try removing that. Also, I think they might have broken the errno handling. The gnutls push/pull funcs are returned to return '-1' and set 'errno' upon failure. The windows send/recvmsg functions don't set errno though, and you need to use WSAGetLastError() instead. If you don't set custom push/pull funcs GNUTLs does the WSAGetLastError() -> errno conversion itself. So their custom push/pull functions probably need to manually set 'errno' based on WSAGetLastError() values, unless some other part of the curl code already takes care of that Regards, Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
2010/11/17 Daniel P. Berrange <berrange@redhat.com>:
On Wed, Nov 17, 2010 at 03:42:18PM +0100, Matthias Bolte wrote:
2010/11/17 Daniel P. Berrange <berrange@redhat.com>:
On Wed, Nov 17, 2010 at 02:53:15PM +0100, Matthias Bolte wrote:
2010/11/17 Justin Clift <jclift@redhat.com>:
Also added an additional menu placement for the windows page, in order to attract further potential testers. ---
+ <li> + The working connection types at the moment are very limited. Only + <b>qemu+tcp://</b> is known to work for sure. Anything using SSH, + such as <b>qemu+ssh://</b>, definitely doesn't work. Connecting + to ESX servers doesn't yet work either, due to a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here. As stated on IRC my initial assumption was wrong. The problem is probably not in GnuTLS, as gnutls-cli works fine. The problem is in the way libcurl and GnuTLS interact. Therefore libvirt's GnuTLS usage is not affected, only libcurl's.
I know how to fix it, but I don't understand in detail yet why it works.
Are you referring to this message ?
"A TLS packet with unexpected length was received"
The place you normally see this is from 'gnutls_handshake()', and it is an indication that the handshake has been aborted by either the client or server. Typical problems include bad certificates, bad choice of encryption ciphers, bad TLS protocol, etc. It is pretty hard to debug, likely want to turn on the verbose GnuTLS debugging options in the code, and also verify how the ESX server is configured and all your certificates
In particular, by default GnuTLS will reject certificates issued by openssl which default to x509 v1, and thus lack the 'Basic Constraints' extension from x509 v3.
Daniel
Well, yes that's the problem and it is the handshake. As I can tell from Wireshark the client sends a RST package directly after the Client Hello. So this is not certificate related or something like that.
This problem also occurs with
curl -kv https://www.google.com
and other HTTPS websites. This only happens when curl is compiled with GnuTLS. curl compiled with OpenSSL or PolarSSL works just fine. Also this only happens on Windows. I tried to find precompiled curl binaries that use GnuTLS to check if the problem is in the way I compile curl, but all binaries I could find use OpenSSL, even the Fedora mingw32-curl package uses OpenSSL.
I traced the problem down to this libcurl commit
https://github.com/bagder/curl/commit/fcccf9aa0d93c666e8ae31ebdde716cddd6b44...
from 2006. This commit makes sure that GnuTLS calls send() with the MSG_NOSIGNAL flag to avoid SIGPIPE. If I revert this commit curl works just fine with GnuTLS. Also this commit as is has no use on Windows, because there is no MSG_NOSIGNAL flag for send() on Windows. But this commit triggers the handshake problem and I didn't understand yet why it does so.
I'm not convinced that they should be calling 'gnutls_transport_set_lowat' so try removing that.
Also, I think they might have broken the errno handling. The gnutls push/pull funcs are returned to return '-1' and set 'errno' upon failure. The windows send/recvmsg functions don't set errno though, and you need to use WSAGetLastError() instead. If you don't set custom push/pull funcs GNUTLs does the WSAGetLastError() -> errno conversion itself. So their custom push/pull functions probably need to manually set 'errno' based on WSAGetLastError() values, unless some other part of the curl code already takes care of that
Regards, Daniel
Ah, the missing errno handling is the problem. When I use the same WSAGetLastError() to errno translation as GnuTLS in libcurl's custom send/recv functions then it works. Removing the call to gnutls_transport_set_lowat makes no difference. Thank you for this hint :) Matthias
On 18/11/2010, at 12:53 AM, Matthias Bolte <matthias.bolte@googlemail.com> wrote:
2010/11/17 Justin Clift <jclift@redhat.com>: <snip>
a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here.
Heh. Wasn't blaming GnuTLS in this page. It says "involving", rather than "caused by". :) Anyway, happy to substitute libcurl or whatever if that's a better idea?
2010/11/17 <jclift@redhat.com>:
On 18/11/2010, at 12:53 AM, Matthias Bolte <matthias.bolte@googlemail.com> wrote:
2010/11/17 Justin Clift <jclift@redhat.com>: <snip>
a bug involving + GnuTLS, which should be fixed in the next release. + </li>
Don't blame GnuTLS here.
Heh. Wasn't blaming GnuTLS in this page. It says "involving", rather than "caused by". :)
Anyway, happy to substitute libcurl or whatever if that's a better idea?
Yes, make it say "involving libcurl". Matthias
participants (4)
-
Daniel P. Berrange -
jclift＠redhat.com -
Justin Clift
-
Matthias Bolte