[libvirt] [PATCH 0/6] docs: some refactoring and new docs about RPM deployment
This refactors existing docs related to the remote driver/daemon and URIs. It then also adds a kbase page about RPM package options. This introduces the use of RST for docs as a replacement for HTML. The intent is that all new docs should use RST from this point. Existing HTML docs are candidates for conversion to RST by anyone interested. Daniel P. Berrangé (6): docs: split TLS certificate setup into its own file docs: move docs about remote driver URIs into URI docs build: introduce rst2html as a mandatory build tool docs: adapt filling of <head> section for rst2html output docs: add a kbase page about RPM packaging options docs: add page describing the libvirt daemons .gitignore | 1 + docs/Makefile.am | 21 +- docs/daemons.rst | 209 +++++++++++ docs/docs.html.in | 6 + docs/kbase.html.in | 4 + docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++ docs/page.xsl | 4 +- docs/remote.html.in | 684 +--------------------------------- docs/tlscerts.html.in | 413 ++++++++++++++++++++ docs/uri.html.in | 263 +++++++++++-- libvirt.spec.in | 2 + m4/virt-external-programs.m4 | 5 + mingw-libvirt.spec.in | 1 + 13 files changed, 1309 insertions(+), 714 deletions(-) create mode 100644 docs/daemons.rst create mode 100644 docs/kbase/rpm-deployment.rst create mode 100644 docs/tlscerts.html.in -- 2.23.0
The generation and deployment of x509 certificates for TLS is complex and verbose and thus deserves its own standalone page. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/docs.html.in | 3 + docs/remote.html.in | 408 +---------------------------------------- docs/tlscerts.html.in | 413 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 417 insertions(+), 407 deletions(-) create mode 100644 docs/tlscerts.html.in diff --git a/docs/docs.html.in b/docs/docs.html.in index 6cf09f51bc..4b59162e0f 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -18,6 +18,9 @@ <dt><a href="remote.html">Remote access</a></dt> <dd>Enable remote access over TCP</dd> + <dt><a href="tlscerts.html">TLS certs</a></dt> + <dd>Generate and deploy x509 certificates for TLS</dd> + <dt><a href="auth.html">Authentication</a></dt> <dd>Configure authentication for the libvirt daemon</dd> diff --git a/docs/remote.html.in b/docs/remote.html.in index 78e071a898..5a0ebe4790 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -61,7 +61,7 @@ Remote libvirt supports a range of transports: <dd><a href="http://en.wikipedia.org/wiki/Transport_Layer_Security" title="Transport Layer Security">TLS</a> 1.0 (SSL 3.1) authenticated and encrypted TCP/IP socket, usually listening on a public port number. To use this you will need to - <a href="#Remote_certificates" title="Generating TLS certificates">generate client and + <a href="tlscerts.html" title="Generating TLS certificates">generate client and server certificates</a>. The standard port is 16514. </dd> @@ -382,412 +382,6 @@ Note that parameter values must be <td> Example: <code>sshauth=privkey,agent</code> </td> </tr> </table> - <h2> - <a id="Remote_certificates">Generating TLS certificates</a> - </h2> - <h3> - <a id="Remote_PKI">Public Key Infrastructure set up</a> - </h3> - <p> -If you are unsure how to create TLS certificates, skip to the -next section. -</p> - <table class="top_table"> - <tr> - <th> Location </th> - <th> Machine </th> - <th> Description </th> - <th> Required fields </th> - </tr> - <tr> - <td> - <code>/etc/pki/CA/cacert.pem</code> - </td> - <td> Installed on the client and server </td> - <td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td> - <td> n/a </td> - </tr> - <tr> - <td> - <code>$HOME/.pki/cacert.pem</code> - </td> - <td> Installed on the client </td> - <td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td> - <td> n/a </td> - </tr> - <tr> - <td> - <code>/etc/pki/libvirt/private/serverkey.pem</code> - </td> - <td> Installed on the server </td> - <td> Server's private key (<a href="#Remote_TLS_server_certificates">more info</a>)</td> - <td> n/a </td> - </tr> - <tr> - <td> - <code>/etc/pki/libvirt/servercert.pem</code> - </td> - <td> Installed on the server </td> - <td> Server's certificate signed by the CA. - (<a href="#Remote_TLS_server_certificates">more info</a>) </td> - <td> CommonName (CN) must be the hostname of the server as it - is seen by clients. All hostname and IP address variants that might - be used to reach the server should be listed in Subject Alt Name - fields.</td> - </tr> - <tr> - <td> - <code>/etc/pki/libvirt/private/clientkey.pem</code> - </td> - <td> Installed on the client </td> - <td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td> - <td> n/a </td> - </tr> - <tr> - <td> - <code>/etc/pki/libvirt/clientcert.pem</code> - </td> - <td> Installed on the client </td> - <td> Client's certificate signed by the CA - (<a href="#Remote_TLS_client_certificates">more info</a>) </td> - <td> Distinguished Name (DN) can be checked against an access - control list (<code>tls_allowed_dn_list</code>). - </td> - </tr> - <tr> - <td> - <code>$HOME/.pki/libvirt/clientkey.pem</code> - </td> - <td> Installed on the client </td> - <td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td> - <td> n/a </td> - </tr> - <tr> - <td> - <code>$HOME/.pki/libvirt/clientcert.pem</code> - </td> - <td> Installed on the client </td> - <td> Client's certificate signed by the CA - (<a href="#Remote_TLS_client_certificates">more info</a>) </td> - <td> Distinguished Name (DN) can be checked against an access - control list (<code>tls_allowed_dn_list</code>). - </td> - </tr> - </table> - <p> - If 'pkipath' is specified in URI, then all the client - certificates must be found in the path specified, otherwise the - connection will fail with a fatal error. If 'pkipath' is not - specified: - </p> - <ul> - <li> For a non-root user, libvirt tries to find the certificates - in $HOME/.pki/libvirt first. If the required CA certificate cannot - be found, then the global default location - (/etc/pki/CA/cacert.pem) will be used. - Likewise, if either the client certificate - or the client key cannot be found, then the global default - locations (/etc/pki/libvirt/clientcert.pem, - /etc/pki/libvirt/private/clientkey.pem) will be used. - </li> - <li> For the root user, the global default locations will always be used.</li> - </ul> - <h3> - <a id="Remote_TLS_background">Background to TLS certificates</a> - </h3> - <p> -Libvirt supports TLS certificates for verifying the identity -of the server and clients. There are two distinct checks involved: -</p> - <ul> - <li> The client should know that it is connecting to the right -server. Checking done by client by matching the certificate that -the server sends to the server's hostname. May be disabled by adding -<code>?no_verify=1</code> to the -<a href="#Remote_URI_parameters">remote URI</a>. -</li> - <li> The server should know that only permitted clients are -connecting. This can be done based on client's IP address, or on -client's IP address and client's certificate. Checking done by the -server. May be enabled and disabled in the <a href="#Remote_libvirtd_configuration">libvirtd.conf file</a>. -</li> - </ul> - <p> -For full certificate checking you will need to have certificates -issued by a recognised <a href="http://en.wikipedia.org/wiki/Certificate_authority">Certificate -Authority (CA)</a> for your server(s) and all clients. To avoid the -expense of getting certificates from a commercial CA, you can set up -your own CA and tell your server(s) and clients to trust certificates -issues by your own CA. Follow the instructions in the next section. -</p> - <p> -Be aware that the <a href="#Remote_libvirtd_configuration">default -configuration for libvirtd</a> allows any client to connect provided -they have a valid certificate issued by the CA for their own IP -address. You may want to change this to make it less (or more) -permissive, depending on your needs. -</p> - <h3> - <a id="Remote_TLS_CA">Setting up a Certificate Authority (CA)</a> - </h3> - <p> -You will need the <a href="http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html">GnuTLS -certtool program documented here</a>. In Fedora, it is in the -<code>gnutls-utils</code> package. -</p> - <p> -Create a private key for your CA: -</p> - <pre> -certtool --generate-privkey > cakey.pem -</pre> - <p> -and self-sign it by creating a file with the -signature details called -<code>ca.info</code> containing: -</p> - <pre> -cn = <i>Name of your organization</i> -ca -cert_signing_key -</pre> - <pre> -certtool --generate-self-signed --load-privkey cakey.pem \ - --template ca.info --outfile cacert.pem -</pre> - <p> -(You can delete <code>ca.info</code> file now if you -want). -</p> - <p> -Now you have two files which matter: -</p> - <ul> - <li><code>cakey.pem</code> - Your CA's private key (keep this very secret!) -</li> - <li><code>cacert.pem</code> - Your CA's certificate (this is public). -</li> - </ul> - <p><code>cacert.pem</code> has to be installed on clients and -server(s) to let them know that they can trust certificates issued by -your CA. -</p> - <p> -The normal installation directory for <code>cacert.pem</code> -is <code>/etc/pki/CA/cacert.pem</code> on all clients and servers. -</p> - <p> -To see the contents of this file, do: -</p> - <pre><b>certtool -i --infile cacert.pem</b> - -X.509 certificate info: - -Version: 3 -Serial Number (hex): 00 -Subject: CN=Libvirt Project -Issuer: CN=Libvirt Project -Signature Algorithm: RSA-SHA -Validity: - Not Before: Mon Jun 18 16:22:18 2007 - Not After: Tue Jun 17 16:22:18 2008 -<i>[etc]</i> -</pre> - <p> -This is all that is required to set up your CA. Keep the CA's private -key carefully as you will need it when you come to issue certificates -for your clients and servers. -</p> - <h3> - <a id="Remote_TLS_server_certificates">Issuing server certificates</a> - </h3> - <p> -For each server (libvirtd) you need to issue a certificate -containing one or more hostnames and/or IP addresses. -Historically the CommonName (CN) field would contain the -hostname of the server and would match the hostname used -in the URI that clients pass to libvirt. In most TLS implementations -the CN field is considered legacy data. The preferential mechanism -is to use Subject Alt Name (SAN) extension fields to validate -against. In the future use of the CN field for validation may be -discontinued entirely, so it is strongly recommended to -include the SAN fields. -</p> - <p> -In the example below, clients will be connecting to the -server using a <a href="#Remote_URI_reference">URI</a> of -<code>qemu://compute1.libvirt.org/system</code>, so the CN -must be "<code>compute1.libvirt.org</code>". -</p> - <p> -Make a private key for the server: -</p> - <pre> -certtool --generate-privkey > serverkey.pem -</pre> - <p> -and sign that key with the CA's private key by first -creating a template file called <code>server.info</code>. -The template file will contain a number of fields to define -the server as follows: -</p> - <pre> -organization = <i>Name of your organization</i> -cn = compute1.libvirt.org -dns_name = compute1 -dns_name = compute1.libvirt.org -ip_address = 10.0.0.74 -ip_address = 192.168.1.24 -ip_address = 2001:cafe::74 -ip_address = fe20::24 -tls_www_server -encryption_key -signing_key -</pre> -<p> -The 'cn' field should refer to the fully qualified public -hostname of the server. For the SAN extension data, there -must also be one or more 'dns_name' fields that contain all -possible hostnames that can be reasonably used by clients -to reach the server, both with and without domain name -qualifiers. If clients are likely to connect to the server -by IP address, then one or more 'ip_address' fields should -also be added. -</p> - <p> -Use the template file as input to a <code>certtool</code> -command to sign the server certificate: -</p> - <pre> -certtool --generate-certificate --load-privkey serverkey.pem \ - --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \ - --template server.info --outfile servercert.pem -</pre> - <p> -This gives two files: -</p> - <ul> - <li><code>serverkey.pem</code> - The server's private key. -</li> - <li><code>servercert.pem</code> - The server's public key. -</li> - </ul> - <p> -We can examine this certificate and its signature: -</p> - <pre><b>certtool -i --infile servercert.pem</b> -X.509 certificate info: - -Version: 3 -Serial Number (hex): 00 -Subject: O=Libvirt Project,CN=compute1.libvirt.org -Issuer: CN=Libvirt Project -Signature Algorithm: RSA-SHA -Validity: - Not Before: Wed Oct 04 09:09:44 UTC 2017 - Not After: Thu Oct 04 09:09:44 UTC 2018 -Extensions: - Basic Constraints (critical): - Certificate Authority (CA): FALSE - Subject Alternative Name (not critical): - DNSname: compute1 - DNSname: compute1.libvirt.org - IPAddress: 10.0.0.74 - IPAddress: 192.168.1.24 - IPAddress: 2001:cafe::74 - IPAddress: fe20::24 -</pre> - <p> -Note the "Issuer" CN is "Libvirt Project" (the CA) and -the "Subject" CN is "compute1.libvirt.org" (the server). -Notice that the hostname listed in the CN must also -be duplicated as a DNSname entry -</p> - <p> -Finally we have two files to install: -</p> - <ul> - <li><code>serverkey.pem</code> is -the server's private key which should be copied to the -server <i>only</i> as -<code>/etc/pki/libvirt/private/serverkey.pem</code>. -</li> - <li><code>servercert.pem</code> is the server's certificate -which can be installed on the server as -<code>/etc/pki/libvirt/servercert.pem</code>. -</li> - </ul> - <h3> - <a id="Remote_TLS_client_certificates">Issuing client certificates</a> - </h3> - <p> -For each client (ie. any program linked with libvirt, such as -<a href="http://virt-manager.org/">virt-manager</a>) -you need to issue a certificate with the X.509 Distinguished Name (DN) -set to a suitable name. You can decide this on a company / organisation -policy. For example: -</p> - <pre> -C=GB,ST=London,L=London,O=Libvirt Project,CN=<i>name_of_client</i> -</pre> - <p> -The process is the same as for -<a href="#Remote_TLS_server_certificates">setting up the -server certificate</a> so here we just briefly cover the -steps. -</p> - <ol> - <li> -Make a private key: -<pre> -certtool --generate-privkey > clientkey.pem -</pre> -</li> - <li> -Act as CA and sign the certificate. Create client.info containing: -<pre> -country = GB -state = London -locality = London -organization = Libvirt Project -cn = client1 -tls_www_client -encryption_key -signing_key -</pre> -and sign by doing: -<pre> -certtool --generate-certificate --load-privkey clientkey.pem \ - --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \ - --template client.info --outfile clientcert.pem -</pre> -</li> - <li> -Install the certificates on the client machine: -<pre> -cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem -cp clientcert.pem /etc/pki/libvirt/clientcert.pem -</pre> -</li> - </ol> - <h3> - <a id="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a> - </h3> - <dl> - <dt> failed to verify client's certificate </dt> - <dd> - <p> -On the server side, run the libvirtd server with -the '--listen' and '--verbose' options while the -client is connecting. The verbose log messages should -tell you enough to diagnose the problem. -</p> - </dd> - </dl> - <p> You can use the virt-pki-validate shell script -to analyze the setup on the client or server machines, preferably as root. -It will try to point out the possible problems and provide solutions to -fix the set up up to a point where you have secure remote access.</p> <h2> <a id="Remote_libvirtd_configuration">libvirtd configuration file</a> </h2> diff --git a/docs/tlscerts.html.in b/docs/tlscerts.html.in new file mode 100644 index 0000000000..3eea686daa --- /dev/null +++ b/docs/tlscerts.html.in @@ -0,0 +1,413 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml"> + <body> + <h1>TLS x509 certificate setup</h1> + + <ul id="toc"></ul> + + <h2> + <a id="Remote_PKI">Public Key Infrastructure set up</a> + </h2> + <p> +If you are unsure how to create TLS certificates, skip to the +next section. +</p> + <table class="top_table"> + <tr> + <th> Location </th> + <th> Machine </th> + <th> Description </th> + <th> Required fields </th> + </tr> + <tr> + <td> + <code>/etc/pki/CA/cacert.pem</code> + </td> + <td> Installed on the client and server </td> + <td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td> + <td> n/a </td> + </tr> + <tr> + <td> + <code>$HOME/.pki/cacert.pem</code> + </td> + <td> Installed on the client </td> + <td> CA's certificate (<a href="#Remote_TLS_CA">more info</a>)</td> + <td> n/a </td> + </tr> + <tr> + <td> + <code>/etc/pki/libvirt/private/serverkey.pem</code> + </td> + <td> Installed on the server </td> + <td> Server's private key (<a href="#Remote_TLS_server_certificates">more info</a>)</td> + <td> n/a </td> + </tr> + <tr> + <td> + <code>/etc/pki/libvirt/servercert.pem</code> + </td> + <td> Installed on the server </td> + <td> Server's certificate signed by the CA. + (<a href="#Remote_TLS_server_certificates">more info</a>) </td> + <td> CommonName (CN) must be the hostname of the server as it + is seen by clients. All hostname and IP address variants that might + be used to reach the server should be listed in Subject Alt Name + fields.</td> + </tr> + <tr> + <td> + <code>/etc/pki/libvirt/private/clientkey.pem</code> + </td> + <td> Installed on the client </td> + <td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td> + <td> n/a </td> + </tr> + <tr> + <td> + <code>/etc/pki/libvirt/clientcert.pem</code> + </td> + <td> Installed on the client </td> + <td> Client's certificate signed by the CA + (<a href="#Remote_TLS_client_certificates">more info</a>) </td> + <td> Distinguished Name (DN) can be checked against an access + control list (<code>tls_allowed_dn_list</code>). + </td> + </tr> + <tr> + <td> + <code>$HOME/.pki/libvirt/clientkey.pem</code> + </td> + <td> Installed on the client </td> + <td> Client's private key. (<a href="#Remote_TLS_client_certificates">more info</a>) </td> + <td> n/a </td> + </tr> + <tr> + <td> + <code>$HOME/.pki/libvirt/clientcert.pem</code> + </td> + <td> Installed on the client </td> + <td> Client's certificate signed by the CA + (<a href="#Remote_TLS_client_certificates">more info</a>) </td> + <td> Distinguished Name (DN) can be checked against an access + control list (<code>tls_allowed_dn_list</code>). + </td> + </tr> + </table> + <p> + If 'pkipath' is specified in URI, then all the client + certificates must be found in the path specified, otherwise the + connection will fail with a fatal error. If 'pkipath' is not + specified: + </p> + <ul> + <li> For a non-root user, libvirt tries to find the certificates + in $HOME/.pki/libvirt first. If the required CA certificate cannot + be found, then the global default location + (/etc/pki/CA/cacert.pem) will be used. + Likewise, if either the client certificate + or the client key cannot be found, then the global default + locations (/etc/pki/libvirt/clientcert.pem, + /etc/pki/libvirt/private/clientkey.pem) will be used. + </li> + <li> For the root user, the global default locations will always be used.</li> + </ul> + <h2> + <a id="Remote_TLS_background">Background to TLS certificates</a> + </h2> + <p> +Libvirt supports TLS certificates for verifying the identity +of the server and clients. There are two distinct checks involved: +</p> + <ul> + <li> The client should know that it is connecting to the right +server. Checking done by client by matching the certificate that +the server sends to the server's hostname. May be disabled by adding +<code>?no_verify=1</code> to the +<a href="#Remote_URI_parameters">remote URI</a>. +</li> + <li> The server should know that only permitted clients are +connecting. This can be done based on client's IP address, or on +client's IP address and client's certificate. Checking done by the +server. May be enabled and disabled in the <a href="#Remote_libvirtd_configuration">libvirtd.conf file</a>. +</li> + </ul> + <p> +For full certificate checking you will need to have certificates +issued by a recognised <a href="http://en.wikipedia.org/wiki/Certificate_authority">Certificate +Authority (CA)</a> for your server(s) and all clients. To avoid the +expense of getting certificates from a commercial CA, you can set up +your own CA and tell your server(s) and clients to trust certificates +issues by your own CA. Follow the instructions in the next section. +</p> + <p> +Be aware that the <a href="#Remote_libvirtd_configuration">default +configuration for libvirtd</a> allows any client to connect provided +they have a valid certificate issued by the CA for their own IP +address. You may want to change this to make it less (or more) +permissive, depending on your needs. +</p> + <h2> + <a id="Remote_TLS_CA">Setting up a Certificate Authority (CA)</a> + </h2> + <p> +You will need the <a href="http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html">GnuTLS +certtool program documented here</a>. In Fedora, it is in the +<code>gnutls-utils</code> package. +</p> + <p> +Create a private key for your CA: +</p> + <pre> +certtool --generate-privkey > cakey.pem +</pre> + <p> +and self-sign it by creating a file with the +signature details called +<code>ca.info</code> containing: +</p> + <pre> +cn = <i>Name of your organization</i> +ca +cert_signing_key +</pre> + <pre> +certtool --generate-self-signed --load-privkey cakey.pem \ + --template ca.info --outfile cacert.pem +</pre> + <p> +(You can delete <code>ca.info</code> file now if you +want). +</p> + <p> +Now you have two files which matter: +</p> + <ul> + <li><code>cakey.pem</code> - Your CA's private key (keep this very secret!) +</li> + <li><code>cacert.pem</code> - Your CA's certificate (this is public). +</li> + </ul> + <p><code>cacert.pem</code> has to be installed on clients and +server(s) to let them know that they can trust certificates issued by +your CA. +</p> + <p> +The normal installation directory for <code>cacert.pem</code> +is <code>/etc/pki/CA/cacert.pem</code> on all clients and servers. +</p> + <p> +To see the contents of this file, do: +</p> + <pre><b>certtool -i --infile cacert.pem</b> + +X.509 certificate info: + +Version: 3 +Serial Number (hex): 00 +Subject: CN=Libvirt Project +Issuer: CN=Libvirt Project +Signature Algorithm: RSA-SHA +Validity: + Not Before: Mon Jun 18 16:22:18 2007 + Not After: Tue Jun 17 16:22:18 2008 +<i>[etc]</i> +</pre> + <p> +This is all that is required to set up your CA. Keep the CA's private +key carefully as you will need it when you come to issue certificates +for your clients and servers. +</p> + <h2> + <a id="Remote_TLS_server_certificates">Issuing server certificates</a> + </h2> + <p> +For each server (libvirtd) you need to issue a certificate +containing one or more hostnames and/or IP addresses. +Historically the CommonName (CN) field would contain the +hostname of the server and would match the hostname used +in the URI that clients pass to libvirt. In most TLS implementations +the CN field is considered legacy data. The preferential mechanism +is to use Subject Alt Name (SAN) extension fields to validate +against. In the future use of the CN field for validation may be +discontinued entirely, so it is strongly recommended to +include the SAN fields. +</p> + <p> +In the example below, clients will be connecting to the +server using a <a href="#Remote_URI_reference">URI</a> of +<code>qemu://compute1.libvirt.org/system</code>, so the CN +must be "<code>compute1.libvirt.org</code>". +</p> + <p> +Make a private key for the server: +</p> + <pre> +certtool --generate-privkey > serverkey.pem +</pre> + <p> +and sign that key with the CA's private key by first +creating a template file called <code>server.info</code>. +The template file will contain a number of fields to define +the server as follows: +</p> + <pre> +organization = <i>Name of your organization</i> +cn = compute1.libvirt.org +dns_name = compute1 +dns_name = compute1.libvirt.org +ip_address = 10.0.0.74 +ip_address = 192.168.1.24 +ip_address = 2001:cafe::74 +ip_address = fe20::24 +tls_www_server +encryption_key +signing_key +</pre> +<p> +The 'cn' field should refer to the fully qualified public +hostname of the server. For the SAN extension data, there +must also be one or more 'dns_name' fields that contain all +possible hostnames that can be reasonably used by clients +to reach the server, both with and without domain name +qualifiers. If clients are likely to connect to the server +by IP address, then one or more 'ip_address' fields should +also be added. +</p> + <p> +Use the template file as input to a <code>certtool</code> +command to sign the server certificate: +</p> + <pre> +certtool --generate-certificate --load-privkey serverkey.pem \ + --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \ + --template server.info --outfile servercert.pem +</pre> + <p> +This gives two files: +</p> + <ul> + <li><code>serverkey.pem</code> - The server's private key. +</li> + <li><code>servercert.pem</code> - The server's public key. +</li> + </ul> + <p> +We can examine this certificate and its signature: +</p> + <pre><b>certtool -i --infile servercert.pem</b> +X.509 certificate info: + +Version: 3 +Serial Number (hex): 00 +Subject: O=Libvirt Project,CN=compute1.libvirt.org +Issuer: CN=Libvirt Project +Signature Algorithm: RSA-SHA +Validity: + Not Before: Wed Oct 04 09:09:44 UTC 2017 + Not After: Thu Oct 04 09:09:44 UTC 2018 +Extensions: + Basic Constraints (critical): + Certificate Authority (CA): FALSE + Subject Alternative Name (not critical): + DNSname: compute1 + DNSname: compute1.libvirt.org + IPAddress: 10.0.0.74 + IPAddress: 192.168.1.24 + IPAddress: 2001:cafe::74 + IPAddress: fe20::24 +</pre> + <p> +Note the "Issuer" CN is "Libvirt Project" (the CA) and +the "Subject" CN is "compute1.libvirt.org" (the server). +Notice that the hostname listed in the CN must also +be duplicated as a DNSname entry +</p> + <p> +Finally we have two files to install: +</p> + <ul> + <li><code>serverkey.pem</code> is +the server's private key which should be copied to the +server <i>only</i> as +<code>/etc/pki/libvirt/private/serverkey.pem</code>. +</li> + <li><code>servercert.pem</code> is the server's certificate +which can be installed on the server as +<code>/etc/pki/libvirt/servercert.pem</code>. +</li> + </ul> + <h2> + <a id="Remote_TLS_client_certificates">Issuing client certificates</a> + </h2> + <p> +For each client (ie. any program linked with libvirt, such as +<a href="http://virt-manager.org/">virt-manager</a>) +you need to issue a certificate with the X.509 Distinguished Name (DN) +set to a suitable name. You can decide this on a company / organisation +policy. For example: +</p> + <pre> +C=GB,ST=London,L=London,O=Libvirt Project,CN=<i>name_of_client</i> +</pre> + <p> +The process is the same as for +<a href="#Remote_TLS_server_certificates">setting up the +server certificate</a> so here we just briefly cover the +steps. +</p> + <ol> + <li> +Make a private key: +<pre> +certtool --generate-privkey > clientkey.pem +</pre> +</li> + <li> +Act as CA and sign the certificate. Create client.info containing: +<pre> +country = GB +state = London +locality = London +organization = Libvirt Project +cn = client1 +tls_www_client +encryption_key +signing_key +</pre> +and sign by doing: +<pre> +certtool --generate-certificate --load-privkey clientkey.pem \ + --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \ + --template client.info --outfile clientcert.pem +</pre> +</li> + <li> +Install the certificates on the client machine: +<pre> +cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem +cp clientcert.pem /etc/pki/libvirt/clientcert.pem +</pre> +</li> + </ol> + <h2> + <a id="Remote_TLS_troubleshooting">Troubleshooting TLS certificate problems</a> + </h2> + <dl> + <dt> failed to verify client's certificate </dt> + <dd> + <p> +On the server side, run the libvirtd server with +the '--listen' and '--verbose' options while the +client is connecting. The verbose log messages should +tell you enough to diagnose the problem. +</p> + </dd> + </dl> + <p> You can use the virt-pki-validate shell script +to analyze the setup on the client or server machines, preferably as root. +It will try to point out the possible problems and provide solutions to +fix the set up up to a point where you have secure remote access.</p> + </body> +</html> -- 2.23.0
The docs about remote URIs in uri.html are somewhat sparse with the full docs being in remote.html. Move all the URI content from remote.html into uri.html so the user only needs to look in one place for URI info. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/remote.html.in | 278 +------------------------------------------- docs/uri.html.in | 263 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 238 insertions(+), 303 deletions(-) diff --git a/docs/remote.html.in b/docs/remote.html.in index 5a0ebe4790..0b0dc87f6f 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -34,7 +34,7 @@ the system-wide QEMU daemon on a remote machine called <code>qemu://compute1.libvirt.org/system</code>. </p> <p> -The <a href="#Remote_URI_reference">section on remote URIs</a> +The <a href="uri.html#URI_remote">section on remote URIs</a> describes in more detail these remote URIs. </p> <p> @@ -109,279 +109,9 @@ even with graphical management applications. As with the classic ssh transport netcat is required on the remote side.</dd> </dl> <p> -The default transport, if no other is specified, is <code>tls</code>. -</p> - <h2> - <a id="Remote_URI_reference">Remote URIs</a> - </h2> - <p> -See also: <a href="uri.html">documentation on ordinary ("local") URIs</a>. -</p> - <p> -Remote URIs have the general form ("[...]" meaning an optional part): -</p> - <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>] -</p> - <p> -Either the transport or the hostname must be given in order -to distinguish this from a local URI. -</p> - <p> -Some examples: -</p> - <ul> - <li><code>xen+ssh://rjones@towada/system</code><br/> — Connect to a -remote Xen hypervisor on host <code>towada</code> using ssh transport and ssh -username <code>rjones</code>. -</li> - <li><code>xen://towada/system</code><br/> — Connect to a -remote Xen hypervisor on host <code>towada</code> using TLS. -</li> - <li><code>xen://towada/system?no_verify=1</code><br/> — Connect to a -remote Xen hypervisor on host <code>towada</code> using TLS. Do not verify -the server's certificate. -</li> - <li><code>qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock</code><br/> — -Connect to the local qemu instances over a non-standard -Unix socket (the full path to the Unix socket is -supplied explicitly in this case). -</li> - <li><code>test+tcp://localhost:5000/default</code><br/> — -Connect to a libvirtd daemon offering unencrypted TCP/IP connections -on localhost port 5000 and use the test driver with default -settings. -</li> -<li><code>qemu+libssh2://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> — -Connect to a remote host using a ssh connection with the libssh2 driver -and use a different known_hosts file.</li> -<li><code>qemu+libssh://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> — -Connect to a remote host using a ssh connection with the libssh driver -and use a different known_hosts file.</li> - </ul> - <h3> - <a id="Remote_URI_parameters">Extra parameters</a> - </h3> - <p> -Extra parameters can be added to remote URIs as part -of the query string (the part following <q><code>?</code></q>). -Remote URIs understand the extra parameters shown below. -Any others are passed unmodified through to the back end. -Note that parameter values must be -<a href="http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr">URI-escaped</a>. -</p> - <table class="top_table"> - <tr> - <th> Name </th> - <th> Transports </th> - <th> Meaning </th> - </tr> - <tr> - <td> - <code>name</code> - </td> - <td> - <i>any transport</i> - </td> - <td> - The name passed to the remote virConnectOpen function. The - name is normally formed by removing transport, hostname, port - number, username and extra parameters from the remote URI, but in certain - very complex cases it may be better to supply the name explicitly. -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>name=qemu:///system</code> </td> - </tr> - <tr> - <td> - <code>tls_priority</code> - </td> - <td> tls </td> - <td> - A vaid GNUTLS priority string -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>tls_priority=NORMAL:-VERS-SSL3.0</code> </td> - </tr> - <tr> - <td> - <code>mode</code> - </td> - <td> unix, ssh, libssh, libssh2 </td> - <td> - <dl> - <dt><code>auto</code></dt><dd>automatically determine the daemon</dd> - <dt><code>direct</code></dt><dd>connect to per-driver daemons</dd> - <dt><code>legacy</code></dt><dd>connect to libvirtd</dd> - </dl> - Can also be set in <code>libvirt.conf</code> as <code>remote_mode</code> - </td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>mode=direct</code> </td> - </tr> - <tr> - <td> - <code>command</code> - </td> - <td> ssh, ext </td> - <td> - The external command. For ext transport this is required. - For ssh the default is <code>ssh</code>. - The PATH is searched for the command. -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>command=/opt/openssh/bin/ssh</code> </td> - </tr> - <tr> - <td> - <code>socket</code> - </td> - <td> unix, ssh, libssh2, libssh </td> - <td> - The path to the Unix domain socket, which overrides the - compiled-in default. For ssh transport, this is passed to - the remote netcat command (see next). -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td> - </tr> - <tr> - <td> - <code>netcat</code> - </td> - <td> ssh, libssh2, libssh </td> - <td> - The name of the netcat command on the remote machine. - The default is <code>nc</code>. For ssh transport, libvirt - constructs an ssh command which looks like: - -<pre><i>command</i> -p <i>port</i> [-l <i>username</i>] <i>hostname</i> <i>netcat</i> -U <i>socket</i> -</pre> - - where <i>port</i>, <i>username</i>, <i>hostname</i> can be - specified as part of the remote URI, and <i>command</i>, <i>netcat</i> - and <i>socket</i> come from extra parameters (or - sensible defaults). - -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>netcat=/opt/netcat/bin/nc</code> </td> - </tr> - - <tr> - <td> - <code>keyfile</code> - </td> - <td> ssh, libssh2, libssh </td> - <td> - The name of the private key file to use to authentication to the remote - machine. If this option is not used the default keys are used. - </td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>keyfile=/root/.ssh/example_key</code> </td> - </tr> - - <tr> - <td> - <code>no_verify</code> - </td> - <td> ssh, tls </td> - <td> - SSH: If set to a non-zero value, this disables client's strict host key - checking making it auto-accept new host keys. Existing host keys will - still be validated. - <br/> - <br/> - TLS: If set to a non-zero value, this disables client checks of the - server's certificate. Note that to disable server checks of - the client's certificate or IP address you must - <a href="#Remote_libvirtd_configuration">change the libvirtd - configuration</a>. -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>no_verify=1</code> </td> - </tr> - <tr> - <td> - <code>no_tty</code> - </td> - <td> ssh </td> - <td> - If set to a non-zero value, this stops ssh from asking for - a password if it cannot log in to the remote machine automatically - (eg. using ssh-agent etc.). Use this when you don't have access - to a terminal - for example in graphical programs which use libvirt. -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>no_tty=1</code> </td> - </tr> - <tr> - <td> - <code>pkipath</code> - </td> - <td> tls</td> - <td> - Specifies x509 certificates path for the client. If any of - the CA certificate, client certificate, or client key is - missing, the connection will fail with a fatal error. - </td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>pkipath=/tmp/pki/client</code> </td> - </tr> - <tr> - <td> - <code>known_hosts</code> - </td> - <td> libssh2, libssh </td> - <td> - Path to the known_hosts file to verify the host key against. LibSSH2 and - libssh support OpenSSH-style known_hosts files, although LibSSH2 does not - support all key types, so using files created by the OpenSSH binary may - result into truncating the known_hosts file. Thus, with LibSSH2 it's - recommended to use the default known_hosts file is located in libvirt's - client local configuration directory e.g.: ~/.config/libvirt/known_hosts. - Note: Use absolute paths. -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>known_hosts=/root/.ssh/known_hosts</code> </td> - </tr> - <tr> - <td> - <code>sshauth</code> - </td> - <td> libssh2, libssh </td> - <td> - A comma separated list of authentication methods to use. Default (is - "agent,privkey,password,keyboard-interactive". The order of the methods - is preserved. Some methods may require additional parameters. -</td> - </tr> - <tr> - <td colspan="2"/> - <td> Example: <code>sshauth=privkey,agent</code> </td> - </tr> - </table> + The choice of transport is determined by the <a href="uri.html#URI_remote">URI scheme</a>, + with <code>tls</code> as the default if no explicit transport is requested. + </p> <h2> <a id="Remote_libvirtd_configuration">libvirtd configuration file</a> </h2> diff --git a/docs/uri.html.in b/docs/uri.html.in index 6da9eb9746..49f92773f8 100644 --- a/docs/uri.html.in +++ b/docs/uri.html.in @@ -153,65 +153,270 @@ here</a>. <a id="URI_remote">Remote URIs</a> </h2> <p> -Remote URIs are formed by taking ordinary local URIs and adding a -hostname and/or transport name. As a special case, using a URI -scheme of 'remote', will tell the remote libvirtd server to probe -for the optimal hypervisor driver. This is equivalent to passing -a NULL URI for a local connection. For example: +Remote URIs have the general form ("[...]" meaning an optional part): +</p> + <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>] +</p> + <p> +Either the transport or the hostname must be given in order +to distinguish this from a local URI. +</p> + <p> +Some examples: +</p> + <ul> + <li><code>xen+ssh://rjones@towada/system</code><br/> — Connect to a +remote Xen hypervisor on host <code>towada</code> using ssh transport and ssh +username <code>rjones</code>. +</li> + <li><code>xen://towada/system</code><br/> — Connect to a +remote Xen hypervisor on host <code>towada</code> using TLS. +</li> + <li><code>xen://towada/system?no_verify=1</code><br/> — Connect to a +remote Xen hypervisor on host <code>towada</code> using TLS. Do not verify +the server's certificate. +</li> + <li><code>qemu+unix:///system?socket=/opt/libvirt/run/libvirt/libvirt-sock</code><br/> — +Connect to the local qemu instances over a non-standard +Unix socket (the full path to the Unix socket is +supplied explicitly in this case). +</li> + <li><code>test+tcp://localhost:5000/default</code><br/> — +Connect to a libvirtd daemon offering unencrypted TCP/IP connections +on localhost port 5000 and use the test driver with default +settings. +</li> +<li><code>qemu+libssh2://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> — +Connect to a remote host using a ssh connection with the libssh2 driver +and use a different known_hosts file.</li> +<li><code>qemu+libssh://user@host/system?known_hosts=/home/user/.ssh/known_hosts</code><br/> — +Connect to a remote host using a ssh connection with the libssh driver +and use a different known_hosts file.</li> + </ul> + <h3> + <a id="Remote_URI_parameters">Extra parameters</a> + </h3> + <p> +Extra parameters can be added to remote URIs as part +of the query string (the part following <q><code>?</code></q>). +Remote URIs understand the extra parameters shown below. +Any others are passed unmodified through to the back end. +Note that parameter values must be +<a href="http://xmlsoft.org/html/libxml-uri.html#xmlURIEscapeStr">URI-escaped</a>. </p> <table class="top_table"> <tr> - <th> Local URI </th> - <th> Remote URI </th> + <th> Name </th> + <th> Transports </th> <th> Meaning </th> </tr> <tr> <td> - <code>xen:///system</code> + <code>name</code> </td> <td> - <code>xen://oirase/system</code> + <i>any transport</i> </td> - <td> Connect to the Xen hypervisor running on host <code>oirase</code> - using TLS. </td> + <td> + The name passed to the remote virConnectOpen function. The + name is normally formed by removing transport, hostname, port + number, username and extra parameters from the remote URI, but in certain + very complex cases it may be better to supply the name explicitly. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>name=qemu:///system</code> </td> </tr> <tr> <td> - <code>NULL</code> + <code>tls_priority</code> </td> + <td> tls </td> <td> - <code>remote://oirase/</code> + A vaid GNUTLS priority string +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>tls_priority=NORMAL:-VERS-SSL3.0</code> </td> + </tr> + <tr> + <td> + <code>mode</code> + </td> + <td> unix, ssh, libssh, libssh2 </td> + <td> + <dl> + <dt><code>auto</code></dt><dd>automatically determine the daemon</dd> + <dt><code>direct</code></dt><dd>connect to per-driver daemons</dd> + <dt><code>legacy</code></dt><dd>connect to libvirtd</dd> + </dl> + Can also be set in <code>libvirt.conf</code> as <code>remote_mode</code> </td> - <td> Connect to the "default" hypervisor running on host <code>oirase</code> - using TLS. </td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>mode=direct</code> </td> </tr> <tr> <td> - <code>xen:///system</code> + <code>command</code> </td> + <td> ssh, ext </td> <td> - <code>xen+ssh://oirase/system</code> + The external command. For ext transport this is required. + For ssh the default is <code>ssh</code>. + The PATH is searched for the command. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>command=/opt/openssh/bin/ssh</code> </td> + </tr> + <tr> + <td> + <code>socket</code> </td> - <td> Connect to the Xen hypervisor running on host <code>oirase</code> - by going over an <code>ssh</code> connection. </td> + <td> unix, ssh, libssh2, libssh </td> + <td> + The path to the Unix domain socket, which overrides the + compiled-in default. For ssh transport, this is passed to + the remote netcat command (see next). +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>socket=/opt/libvirt/run/libvirt/libvirt-sock</code> </td> </tr> <tr> <td> - <code>test:///default</code> + <code>netcat</code> </td> + <td> ssh, libssh2, libssh </td> <td> - <code>test+tcp://oirase/default</code> + The name of the netcat command on the remote machine. + The default is <code>nc</code>. For ssh transport, libvirt + constructs an ssh command which looks like: + +<pre><i>command</i> -p <i>port</i> [-l <i>username</i>] <i>hostname</i> <i>netcat</i> -U <i>socket</i> +</pre> + + where <i>port</i>, <i>username</i>, <i>hostname</i> can be + specified as part of the remote URI, and <i>command</i>, <i>netcat</i> + and <i>socket</i> come from extra parameters (or + sensible defaults). + +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>netcat=/opt/netcat/bin/nc</code> </td> + </tr> + + <tr> + <td> + <code>keyfile</code> + </td> + <td> ssh, libssh2, libssh </td> + <td> + The name of the private key file to use to authentication to the remote + machine. If this option is not used the default keys are used. + </td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>keyfile=/root/.ssh/example_key</code> </td> + </tr> + + <tr> + <td> + <code>no_verify</code> + </td> + <td> ssh, tls </td> + <td> + SSH: If set to a non-zero value, this disables client's strict host key + checking making it auto-accept new host keys. Existing host keys will + still be validated. + <br/> + <br/> + TLS: If set to a non-zero value, this disables client checks of the + server's certificate. Note that to disable server checks of + the client's certificate or IP address you must + <a href="#Remote_libvirtd_configuration">change the libvirtd + configuration</a>. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>no_verify=1</code> </td> + </tr> + <tr> + <td> + <code>no_tty</code> + </td> + <td> ssh </td> + <td> + If set to a non-zero value, this stops ssh from asking for + a password if it cannot log in to the remote machine automatically + (eg. using ssh-agent etc.). Use this when you don't have access + to a terminal - for example in graphical programs which use libvirt. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>no_tty=1</code> </td> + </tr> + <tr> + <td> + <code>pkipath</code> + </td> + <td> tls</td> + <td> + Specifies x509 certificates path for the client. If any of + the CA certificate, client certificate, or client key is + missing, the connection will fail with a fatal error. + </td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>pkipath=/tmp/pki/client</code> </td> + </tr> + <tr> + <td> + <code>known_hosts</code> + </td> + <td> libssh2, libssh </td> + <td> + Path to the known_hosts file to verify the host key against. LibSSH2 and + libssh support OpenSSH-style known_hosts files, although LibSSH2 does not + support all key types, so using files created by the OpenSSH binary may + result into truncating the known_hosts file. Thus, with LibSSH2 it's + recommended to use the default known_hosts file is located in libvirt's + client local configuration directory e.g.: ~/.config/libvirt/known_hosts. + Note: Use absolute paths. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>known_hosts=/root/.ssh/known_hosts</code> </td> + </tr> + <tr> + <td> + <code>sshauth</code> </td> - <td> Connect to the test driver on host <code>oirase</code> - using an unsecured TCP connection. </td> + <td> libssh2, libssh </td> + <td> + A comma separated list of authentication methods to use. Default (is + "agent,privkey,password,keyboard-interactive". The order of the methods + is preserved. Some methods may require additional parameters. +</td> + </tr> + <tr> + <td colspan="2"/> + <td> Example: <code>sshauth=privkey,agent</code> </td> </tr> </table> - <p> -Remote URIs in libvirt offer a rich syntax and many features. -We refer you to <a href="remote.html#Remote_URI_reference">the libvirt -remote URI reference</a> and <a href="remote.html">full documentation -for libvirt remote support</a>. -</p> <h2> <a id="URI_test">test:///... Test URIs</a> </h2> -- 2.23.0
The rst2html tool is provided by python docutils, and as the name suggests, it converts RST documents into HTML. This enables us to start writing docs on our website in RST format instead of HTML, without changing the rest of our website templating system away from XSLT yet. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- libvirt.spec.in | 2 ++ m4/virt-external-programs.m4 | 5 +++++ mingw-libvirt.spec.in | 1 + 3 files changed, 8 insertions(+) diff --git a/libvirt.spec.in b/libvirt.spec.in index dcad08cb5f..84efe47ffc 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -260,6 +260,8 @@ BuildRequires: automake BuildRequires: gettext-devel BuildRequires: libtool BuildRequires: /usr/bin/pod2man +# Replace with python3-docutils when we drop py2 support +BuildRequires: /usr/bin/rst2html %endif BuildRequires: gcc BuildRequires: git diff --git a/m4/virt-external-programs.m4 b/m4/virt-external-programs.m4 index 0f995998c3..b7779f159e 100644 --- a/m4/virt-external-programs.m4 +++ b/m4/virt-external-programs.m4 @@ -33,6 +33,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [ then AC_MSG_ERROR("xsltproc is required to build libvirt") fi + AC_PATH_PROG([RST2HTML], [rst2html], []) + if test -z "$RST2HTML" + then + AC_MSG_ERROR("rst2html is required to build libvirt") + fi AC_PATH_PROG([AUGPARSE], [augparse], [/usr/bin/augparse]) AC_PROG_MKDIR_P AC_PROG_LN_S diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in index c29f3eeed2..35f1abc13d 100644 --- a/mingw-libvirt.spec.in +++ b/mingw-libvirt.spec.in @@ -82,6 +82,7 @@ BuildRequires: automake BuildRequires: gettext-devel BuildRequires: libtool %endif +BuildRequires: python3-docutils BuildRequires: mingw32-libssh2 BuildRequires: mingw64-libssh2 -- 2.23.0
On Fri, Nov 08, 2019 at 11:21:09AM +0000, Daniel P. Berrangé wrote:
The rst2html tool is provided by python docutils, and as the name suggests, it converts RST documents into HTML.
This enables us to start writing docs on our website in RST format instead of HTML, without changing the rest of our website templating system away from XSLT yet.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- libvirt.spec.in | 2 ++ m4/virt-external-programs.m4 | 5 +++++ mingw-libvirt.spec.in | 1 + 3 files changed, 8 insertions(+)
diff --git a/libvirt.spec.in b/libvirt.spec.in index dcad08cb5f..84efe47ffc 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -260,6 +260,8 @@ BuildRequires: automake BuildRequires: gettext-devel BuildRequires: libtool BuildRequires: /usr/bin/pod2man +# Replace with python3-docutils when we drop py2 support +BuildRequires: /usr/bin/rst2html %endif BuildRequires: gcc BuildRequires: git diff --git a/m4/virt-external-programs.m4 b/m4/virt-external-programs.m4 index 0f995998c3..b7779f159e 100644 --- a/m4/virt-external-programs.m4 +++ b/m4/virt-external-programs.m4 @@ -33,6 +33,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [ then AC_MSG_ERROR("xsltproc is required to build libvirt") fi + AC_PATH_PROG([RST2HTML], [rst2html], [])
The program is called 'rst2html.py' on my Gentoo system (from the dev-python/docutils package) Jano
+ if test -z "$RST2HTML" + then + AC_MSG_ERROR("rst2html is required to build libvirt") + fi AC_PATH_PROG([AUGPARSE], [augparse], [/usr/bin/augparse]) AC_PROG_MKDIR_P AC_PROG_LN_S
On Mon, Nov 11, 2019 at 02:59:20PM +0100, Ján Tomko wrote:
On Fri, Nov 08, 2019 at 11:21:09AM +0000, Daniel P. Berrangé wrote:
The rst2html tool is provided by python docutils, and as the name suggests, it converts RST documents into HTML.
This enables us to start writing docs on our website in RST format instead of HTML, without changing the rest of our website templating system away from XSLT yet.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- libvirt.spec.in | 2 ++ m4/virt-external-programs.m4 | 5 +++++ mingw-libvirt.spec.in | 1 + 3 files changed, 8 insertions(+)
diff --git a/libvirt.spec.in b/libvirt.spec.in index dcad08cb5f..84efe47ffc 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -260,6 +260,8 @@ BuildRequires: automake BuildRequires: gettext-devel BuildRequires: libtool BuildRequires: /usr/bin/pod2man +# Replace with python3-docutils when we drop py2 support +BuildRequires: /usr/bin/rst2html %endif BuildRequires: gcc BuildRequires: git diff --git a/m4/virt-external-programs.m4 b/m4/virt-external-programs.m4 index 0f995998c3..b7779f159e 100644 --- a/m4/virt-external-programs.m4 +++ b/m4/virt-external-programs.m4 @@ -33,6 +33,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [ then AC_MSG_ERROR("xsltproc is required to build libvirt") fi + AC_PATH_PROG([RST2HTML], [rst2html], [])
The program is called 'rst2html.py' on my Gentoo system (from the dev-python/docutils package)
It is rst2html-3 on RHEL-7 with EPEL too. So we'll need to search the list of possible names.
Jano
+ if test -z "$RST2HTML" + then + AC_MSG_ERROR("rst2html is required to build libvirt") + fi AC_PATH_PROG([AUGPARSE], [augparse], [/usr/bin/augparse]) AC_PROG_MKDIR_P AC_PROG_LN_S
Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
The HTML from rst2html doesn't have <h1> immediately under the <body> tag, instead there is at least one <div> in between. There are also many things added in the <head> section that we don't want to have copied over, since our templating system already adds suitable <head> elements. We only need to copy the <script> to make index.html work. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/page.xsl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/page.xsl b/docs/page.xsl index 65ddeb2bb7..8faea07e65 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -95,9 +95,9 @@ <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: <xsl:value-of select="html:html/html:body/html:h1"/></title> + <title>libvirt: <xsl:value-of select="html:html/html:body//html:h1"/></title> <meta name="description" content="libvirt, virtualization, virtualization API"/> - <xsl:apply-templates select="/html:html/html:head/*" mode="content"/> + <xsl:apply-templates select="/html:html/html:head/html:script" mode="content"/> <script type="text/javascript" src="{$href_base}js/main.js"> <xsl:comment>// forces non-empty element</xsl:comment> -- 2.23.0
The libvirt RPM packaging is quite fine grained but it is not obvious to users which package is best to install. Add a kbase doc that describes the different RPMs, and illustrates some example deployment use cases. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- .gitignore | 1 + docs/Makefile.am | 14 +- docs/kbase.html.in | 4 + docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++++++++++++++++ 4 files changed, 427 insertions(+), 2 deletions(-) create mode 100644 docs/kbase/rpm-deployment.rst diff --git a/.gitignore b/.gitignore index c45b8bd098..cc6b19a7bf 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,7 @@ /docs/apibuild.py.stamp /docs/devhelp/libvirt.devhelp /docs/hvsupport.html.in +/docs/kbase/rpm-deployment.html.in /docs/libvirt-admin-*.xml /docs/libvirt-api.xml /docs/libvirt-lxc-*.xml diff --git a/docs/Makefile.am b/docs/Makefile.am index 0311bbedd8..2b04f3b362 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -114,7 +114,13 @@ internals_html = $(internals_html_in:%.html.in=%.html) kbase_html_in = \ $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.html.in)) -kbase_html = $(kbase_html_in:%.html.in=%.html) +kbase_rst = \ + $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.rst)) +kbase_rst_html_in = \ + $(kbase_rst:%.rst=%.html.in) +kbase_html = \ + $(kbase_html_in:%.html.in=%.html) \ + $(kbase_rst_html_in:%.html.in=%.html) # Generate hvsupport.html and news.html first, since they take one extra step. dot_html_generated_in = \ @@ -170,7 +176,7 @@ EXTRA_DIST= \ $(fig) $(png) $(css) \ $(javascript) $(logofiles) \ $(internals_html_in) $(fonts) \ - $(kbase_html_in) \ + $(kbase_html_in) $(kbase_rst) \ aclperms.htmlinc \ hvsupport.pl \ $(schema_DATA) @@ -186,6 +192,7 @@ CLEANFILES = \ $(apihtml) \ $(internals_html) \ $(kbase_html) \ + $(kbase_rst_html_in) \ $(xml) \ $(qemu_xml) \ $(lxc_xml) \ @@ -235,6 +242,9 @@ EXTRA_DIST += \ %.png: %.fig convert -rotate 90 $< $@ +%.html.in: %.rst + $(AM_V_GEN)rst2html $< > $@ + %.html.tmp: %.html.in site.xsl subsite.xsl page.xsl \ $(acl_generated) $(AM_V_GEN)name=`echo $@ | sed -e 's/.tmp//'`; \ diff --git a/docs/kbase.html.in b/docs/kbase.html.in index 97d3f4c384..a5504a540f 100644 --- a/docs/kbase.html.in +++ b/docs/kbase.html.in @@ -21,6 +21,10 @@ capture</a></dt> <dd>Comparison between different methods of capturing domain state</dd> + + <dt><a href="kbase/rpm-deployment.html">RPM deployment</a></dt> + <dd>Explanation of the different RPM packages and illustration of + which to pick for installation</dd> </dl> </div> diff --git a/docs/kbase/rpm-deployment.rst b/docs/kbase/rpm-deployment.rst new file mode 100644 index 0000000000..8f1584d7ea --- /dev/null +++ b/docs/kbase/rpm-deployment.rst @@ -0,0 +1,410 @@ +======================= +RPM Deployment Guidance +======================= + +.. contents:: + +A complete libvirt build includes a wide range of features, many of which are +dynamically loadable at runtime. Applications using libvirt typically only +need to use a subset of these features, and so do not require a full install +of all libvirt RPM packages. + +This document provides some guidance on the RPM packages available with libvirt +on Fedora and related distributions, to enable applications and administrators +to pick the optimal set for their needs. + +The RHEL and CentOS distributions use the same RPM packaging split, but many +of the drivers will be disabled at build time, so not all of the packages +listed on this page will exist. + + +RPM packages +============ + +* libvirt + + This is an empty package that exists solely as a convenient way to install + every other libvirt RPM package. Almost every deployment scenario would be + better served by picking one of the other RPMs listed below. + +* libvirt-admin + + The virt-admin tool, used for administrative operations on any libvirt + daemons. Most usefully it allows for logging filters and outputs to be + reconfigured on a running daemon without a restart. This is recommended + to be installed on any host running a libvirt daemon. + + +* libvirt-bash-completion + + Argument auto-completion support for the Bash shell. This is shared code that + is pulled in by either the libvirt-admin or libvirt-clients RPMs, so there is + no need to explicitly ask for this package to be installed. + + +* libvirt-client + + The virsh tool, used for interacting with any libvirt driver, both primary + virt drivers and secondary drivers for storage, networking, etc. All libvirt + installs should have this installed as it provides a useful way to view and + debug what is being done by other applications using libvirt. + + +* libvirt-daemon + + The monolithic libvirtd daemon, traditionally used for running all the + stateful drivers. This package does not contain any drivers, so further + packages need to be installed to provide the desired drivers. + + +* libvirt-daemon-config-network + + The sample configuration file providing the 'default' virtual network that + enables outbound NAT based connectivity for virtual machines. This is useful + on desktop installations, but is not typically desired on server + installations where VMs will use full bridged connectivity. + + +* libvirt-daemon-config-nwfilter + + The sample configuration files providing the network filters for protecting + against common malicious guest traffic. This includes protection against ARP, + MAC and IP spoofing. This is typically desired on server installations, if + the mgmt app is using libvirt's network filtering features. + + +* libvirt-daemon-driver-interface + + The dynamically loadable driver providing an implementation of the host + network interface management APIs, as well as the virtinterfaced daemon + binary. + + +* libvirt-daemon-driver-libxl + + The dynamically loadable driver providing an implementation of the hypervisor + APIs for Xen using the libxl library, as well as the virtxend daemon + binary. + + Note that this is a minimal package so does not actually pull in the full + Xen hypervisor package set. This be must requested separately. + + +* libvirt-daemon-driver-lxc + + The dynamically loadable driver providing an implementation of the hypervisor + APIs for Linux containers, as well as the virtlxcd daemon binary. + + +* libvirt-daemon-driver-network + + The dynamically loadable driver providing an implementation of the virtual + network interface management APIs, as well as the virtinterfaced daemon + binary. Typically the libvirt-daemon-config-network RPM will also be desired + when this is installed. + + +* libvirt-daemon-driver-nodedev + + The dynamically loadable driver providing an implementation of the host + device management APIs, as well as the virtnodedevd daemon binary. + + +* libvirt-daemon-driver-nwfilter + + The dynamically loadable driver providing an implementation of the host + network firewall management APIs, as well as the virtnwfilterd daemon + binary. + + +* libvirt-daemon-driver-qemu + + The dynamically loadable driver providing an implementation of the hypervisor + network interface management APIs, as well as the virtqemud daemon + binary. + + Note that this is a minimal package so does not actually pull in the full + QEMU or KVM package set. This be must requested separately. + + +* libvirt-daemon-driver-secret + The dynamically loadable driver providing an implementation of the secret + data management APIs, as well as the virtsecretd daemon binary. + + +* libvirt-daemon-driver-storage + + This is an empty package that exists only as a convenient way to request + installation of all the storage pool drivers. + + If the application only supports a subset of storage pool types, then + a smaller install footprint can be obtained by requesting the individual + drivers. + + +* libvirt-daemon-driver-storage-core + + The dynamically loadable driver providing an implementation of the host + storage pool/volume management APIs, as well as the virtstoraged daemon + binary. + + Note that this is a minimal package so does not actually pull in any pool + implementations. + + +* libvirt-daemon-driver-storage-disk + + The dynamically loadable driver providing an implementation of the disk + partition storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-gluster + + The dynamically loadable driver providing an implementation of the GlusterFS + file storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-iscsi + + The dynamically loadable driver providing an implementation of the ISCSI + disk storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-iscsi-direct + + The dynamically loadable driver providing an implementation of the ISCSI + network storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-logical + + The dynamically loadable driver providing an implementation of the LVM + storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-mpath + + The dynamically loadable driver providing an implementation of the multipath + disk storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-rbd + + The dynamically loadable driver providing an implementation of the RBD + network storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-scsi + + The dynamically loadable driver providing an implementation of the SCSI + disk storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-sheepdog + + The dynamically loadable driver providing an implementation of the SheepDog + network storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-storage-zfs + + The dynamically loadable driver providing an implementation of the ZFS + file storage pool type, for the storage pool management APIs. + + +* libvirt-daemon-driver-vbox + + The dynamically loadable driver providing an implementation of the host + network interface management APIs, as well as the virtinterfaced daemon + binary. + + +* libvirt-daemon-kvm + + This is an empty package that exists only as a convenient way to request + installation of all the libvirt features that are relevant to the management + of KVM guests. This includes the QEMU driver, and the secondary drivers for + secrets, storage pools, virtual networks, host interfaces, host devices + and network filtering. + + It will also pull in the full set of QEMU features that can be utilized with + native architecture KVM guests. + + This is a good default for an installation to use KVM if the specific set of + required features is not known. To have finer grained control over the + features, the subset of libvirt-daemon-driver-XXX packages should be used + instead. + + +* libvirt-daemon-lxc + + This is an empty package that exists only as a convenient way to request + installation of all the libvirt features that are relevant to the management + of Linux containers. This includes the LXC driver, and the secondary drivers + for secrets, storage pools, virtual networks, host interfaces, host devices + and network filtering. + + This is a good default for an installation to use LXC if the specific set of + required features is not known. To have finer grained control over the + features, the subset of libvirt-daemon-driver-XXX packages should be used + instead. + + +* libvirt-daemon-qemu + + This is an empty package that exists only as a convenient way to request + installation of all the libvirt features that are relevant to the management + of QEMU guests. This includes the QEMU driver, and the secondary drivers for + secrets, storage pools, virtual networks, host interfaces, host devices + and network filtering. + + It will also pull in the full set of QEMU features that can be utilized to + emulate any guests architecture supported by QEMU. + + This is a good default for an installation to use QEMU if the specific set of + required features is not known. To have finer grained control over the + features, the subset of libvirt-daemon-driver-XXX packages should be used + instead. + + +* libvirt-daemon-vbox + + This is an empty package that exists only as a convenient way to request + installation of all the libvirt features that are relevant to the management + of KVM guests. This includes the QEMU driver, and the secondary drivers for + secrets, storage pools, virtual networks, host interfaces, host devices + and network filtering. + + This is a good default for an installation to use VirtualBox if the specific + set of required features is not known. To have finer grained control over the + features, the subset of libvirt-daemon-driver-XXX packages should be used + instead. + + +* libvirt-daemon-xen + + This is an empty package that exists only as a convenient way to request + installation of all the libvirt features that are relevant to the management + of KVM guests. This includes the QEMU driver, and the secondary drivers for + secrets, storage pools, virtual networks, host interfaces, host devices + and network filtering. + + It will also pull in the full set of Xen features that can be utilized with + Xen guests. + + This is a good default for an installation to use Xen if the specific set of + required features is not known. To have finer grained control over the + features, the subset of libvirt-daemon-driver-XXX packages should be used + instead. + + +* libvirt-devel + + The header files required to build applications, or language bindings against + the libvirt C library. This should never be required on a production host, + only development hosts. + +* libvirt-docs + + A local copy of the `libvirt website <https://libvirt.org>`_ website content + that matches the deployed version of libvirt. + +* libvirt-libs + + The ELF libraries providing the main application interface to libvirt. These + have stateless drivers (VMWare ESX, HyperV, etc) built-in, and are able to + take to the libvirt daemons to utilize stateful drivers (QEMU, Xen, BHyve, + LXC, VZ, etc). This is needed on all libvirt hosts, both client and server. + +* libvirt-lock-sanlock + + A plugin for locking disks that communicates with the sanlock daemon. It is + optional and only relevant to hosts with the QEMU driver and oVirt management + application. + +* libvirt-login-shell + + A simple login shell that automatically spawns an LXC container for the user + logging in and places them in a shell inside that container. + + +* libvirt-nss + + A NSS plugin that provides hostname resolution for guests attached to a + libvirt virtual network. It is recommended to be installed on any host with + guests using the libvirt virtual network connectivity. + + +* libvirt-wireshark + + A wireshark plugin that allows for dissecting the XDR based RPC protocol used + between libvirt and its daemons. Since production deployments should all be + using a TLS encrypted, this only useful for development hosts with a libvirt + daemon configured without encryption. + + +Deployment choices +================== + +Client only install +------------------- + +If an application is capable of using multiple different virtualization drivers +it is undesirable to force the installation of a specific set of drivers. In +this case the application will merely wish to request a client only install + +Alternatively if an application is intended to communicate with a hypervisor on +a remote host there is no need to install drivers locally, only a client is +needed + +The only required package is the `libvirt-libs`, however, it is useful to +also install `libvirt-client`. + + +Every possible virt driver +-------------------------- + +There is rarely a need to install every virt driver at once on a given host. +In the unlikely event that this is needed, however, the `libvirt` package +should be installed. + +Note that this doesn't actually pull in the hypervisors, only the libvirt +code to talk to the hypervisors. + + +Full features for one virt driver +--------------------------------- + +This is a common default installation profile when there is no need to minimise +the on-disk footprint. + +This is achieved by installing the `libvirt-daemon-XXXX` package for the +virtualization driver that is desired. This will also pull in the default +set of hypervisor packages too. + +Since this installs every possible libvirt feature for the virtualization +driver in question, the on-disk footprint is quite large. The in-memory +footprint of the daemons is also relatively large since alot of code is +loaded. + + +Minimal features for one virt driver +------------------------------------ + +This is the best installation profile when it is desired to minimize the +on-disk footprint. + +This is achieved by installing the individual `libvirt-daemon-driver-XXX` +packages needed for the features that will be used. This will not pull in the +hypervisor packages, allowing a fine grained set of hypervisor features to be +chosen separately. + +Since this allows fine grained installation of individual libvirt drivers, +this results in the lowest on-disk footprint. The in-memory footprint of +the daemons is also minimized by reducing the code loaded. + +As an example, the smallest possible installation for running KVM guests can +be achieved by installing `libvirt-daemon-driver-qemu` and `qemu-kvm-core`. +This will exclude all the secondary libvirt drivers for storage, networking +and host devices, leaving only the bare minimum functionality for managing +KVM guests. -- 2.23.0
Now that we have more than just the libvirtd daemon, we should be explaining to users what they are all for & important aspects of their configuration. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/Makefile.am | 7 +- docs/daemons.rst | 209 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 + 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 docs/daemons.rst diff --git a/docs/Makefile.am b/docs/Makefile.am index 2b04f3b362..3dd61640b5 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -128,9 +128,14 @@ dot_html_generated_in = \ news.html.in dot_html_in = \ $(notdir $(wildcard $(srcdir)/*.html.in)) +dot_rst = \ + $(notdir $(wildcard $(srcdir)/*.rst)) +dot_rst_html_in = \ + $(dot_rst:%.rst=%.html) dot_html = \ $(dot_html_generated_in:%.html.in=%.html) \ - $(dot_html_in:%.html.in=%.html) + $(dot_html_in:%.html.in=%.html) \ + $(dot_rst_html_in:%.html.in=%.html) xml = \ libvirt-api.xml \ diff --git a/docs/daemons.rst b/docs/daemons.rst new file mode 100644 index 0000000000..51d4153b99 --- /dev/null +++ b/docs/daemons.rst @@ -0,0 +1,209 @@ +=============== +Libvirt Daemons +=============== + +.. contents:: Topics + +A libvirt deployment for accessing one of the stateful drivers will require +one or more daemons to be deployed on the virtualization host. There are a +number of ways the daemons can be configured which will be outlined in this +page + +Monolithic driver daemon +======================== + +Traditionally libvirt has provided a single monolithic daemon called `libvirtd` +which exposed support for all the stateful drivers, both primary hypervisor +drivers and secondary supporting drivers. It also enables secure remote access +from clients running off host. + +Operating modes +--------------- + +The daemon can operate in two modes + +* *System mode* - `libvirtd` is running as the root user account, enabling + access to its full range of functionality. A read-write connection to + `libvirtd` in system mode **implies privileges equivalent to having a root + shell**. Suitable `authentication mechanisms <auth.html>`_ **must be enabled** + to secure it against untrustworthy clients/users. + +* *Session mode* - `libvirtd` is running as any non-root user account, enabling + access to a more restricted range of functionality. Only client apps/users + running under **the same UID are permitted to connect**, thus a connection + does not imply any elevation of privileges. + + +Sockets +------- + +When running in system mode, `libvirtd` exposes three UNIX domain sockets, and +optionally, one or two TCP sockets + +* `/var/run/libvirt/libvirt-sock` - the primary socket for accessing libvirt + APIs, with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. This is the + socket that most management applications connect to by default. + +* `/var/run/libvirt/libvirt-sock-ro` - the secondary socket for accessing + libvirt APIs, with limited read-only privileges. A connection to this socket + gives the ability to query the existance of objects and monitor some aspects + of their operation. This is the socket that most management applications + connect to when requesting read only mode. Typically this is what a + monitoring app would use. + +* `/var/run/libvirt/libvirt-sock-admin` - the administrative socket for + controlling operation of the daemon itself (as opposed to drivers it is + running). This can be used to dynamically reconfigure some aspects of the + daemon and monitor/control connected clients. + +* `TCP 16509` - the non-TLS socket for remotely accessing the libvirt APIs, + with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. Since it does + not use TLS, an `authentication mechanism <auth.html>`_ that provides + encryption must be used. Only the GSSAPI/Kerberos mechanism is capable of + satisfying this requirement. In general applications should not use this + socket except for debugging in a development/test environment. + +* `TCP 16514` - the TLS socket for remotely accessing the libvirt APIs, + with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. Access control + can be enforced either through validation of `x509 certificates + <tlscerts.html>`_, and/or by enabling an `authentication mechanism + <auth.html>`_. + +When running in session mode, `libvirtd` exposes two UNIX domain sockets + +* `$XDG_RUNTIME_DIR/libvirt/libvirt-sock` - the primary socket for accessing + libvirt APIs, with full read-write privileges. A connection to this socket + does not alter the privileges that the client already has. This is the + socket that most management applications connect to by default. + +* `$XDG_RUNTIME_DIR/libvirt/libvirt-sock-admin` - the administrative socket for + controlling operation of the daemon itself (as opposed to drivers it is + running). This can be used to dynamically reconfigure some aspects of the + daemon and monitor/control connected clients. + +Notice that the session mode does not have a separate read-only socket. Since +the clients must be running as the same user as the daemon itself, there is +not any security benefit from attempting to enforce a read-only mode. + +`$XDG_RUNTIME_DIR` commonly points to a per-user private location on tmpfs, +such as `/run/user/$UID`. + +Systemd Integration +------------------- + +When the `libvirtd` daemon is managed by `systemd` a number of desirable +features are available, most notably socket activation. + +Libvirt ships a number of unit files for controlling libvirtd + +* `libvirtd.service` - the main unit file for launching the libvirtd daemon + in system mode. The command line arguments passed can be configured by + editting `/etc/sysconfig/libvirtd`. This is typically only needed to control + the use of the auto shutdown timeout value. It is recommended that this + the service unit be configured to start on boot. This is because various + libvirt drivers support autostart of their objects. If it is known that + autostart is not required, this unit can be left to start on demand. + +* `libvirtd.socket` - the unit file corresponding to the main read-write + UNIX socket `/var/run/libvirt/libvirt-sock`. This socket is recommended to + be started on boot by default. + +* `libvirtd-ro.socket` - the unit file corresponding to the main read-write + UNIX socket `/var/run/libvirt/libvirt-sock-ro`. This socket is recommended + to be started on boot by default. + +* `libvirtd-admin.socket` - the unit file corresponding to the administrative + UNIX socket `/var/run/libvirt/libvirt-sock-admin`. This socket is recommended + to be started on boot by default. + +* `libvirt-tcp.socket` - the unit file corresponding to the TCP 16509 port for + non-TLS remote access. This socket should not be configured to start on boot + until the administrator has configured a suitable authentication mechanism. + +* `libvirt-tls.socket` - the unit file corresponding to the TCP 16509 port for + TLS remote access. This socket should not be configured to start on boot + until the administrator has deployed x509 certificates and optionally + configured a suitable authentication mechanism. + +The socket unit files are newly introduced in 5.6.0. On newly installed hosts +the UNIX socket units should be enabled by default. When upgrading an existing +host from a previous version of libvirt, the socket unit files will be masked +if libvirtd is currently configured to use the `--listen` argument, since the +`--listen` argument is mutually exclusive with use of socket activation. + +When systemd socket activation is used a number of configuration settings in +`libvirtd.conf` are no longer honoured. Instead these settings must be +controlled via the system unit files + +* `listen_tcp` - TCP socket usage is enabled by starting the + `libvirtd-tcp.socket` unit file. + +* `listen_tls` - TLS socket usage is enabled by starting the + `libvirtd-tls.socket` unit file. + +* `tcp_port` - Port for the non-TLS TCP socket, controlled via the + `ListenStream` parameter in the `libvirtd-tcp.socket` unit file. + +* `tls_port` - Port for the TLS TCP socket, controlled via the + `ListenStream` parameter in the `libvirtd-tls.socket` unit file. + +* `listen_addr` - IP address to listen on, independently controlled via the + `ListenStream` parameter in the `libvirtd-tcp.socket` or + `libvirtd-tls.socket` unit files. + +* `unix_sock_group` - UNIX socket group owner, controlled via the `SocketGroup` + parameter in the `libvirtd.socket` and `libvirtd-ro.socket` unit files + +* `unix_sock_ro_perms` - read-only UNIX socket permissions, controlled via the + `SocketMode` parameter in the `libvirtd-ro.socket` unit file + +* `unix_sock_rw_perms` - read-write UNIX socket permissions, controlled via the + `SocketMode` parameter in the `libvirtd.socket` unit file + +* `unix_sock_admin_perms` - admin UNIX socket permissions, controlled via the + `SocketMode` parameter in the `libvirtd-admin.socket` unit file + +* `unix_sock_dir` - directory in which all UNIX sockets are created + independently controlled via the `ListenStream` parameter in any of the + `libvirtd.socket`, `libvirtd-ro.socket` and `libvirtd-admin.socket` unit + files. + + +Systemd releases prior to version 227 lacked support for passing the activation +socket unit names into the service. When using these old versions, the +`tcp_port`, `tls_port` and `unix_sock_dir` settings in `libvirtd.conf` must +be changed in lock-step with the equivalent settings in the unit files to +ensure that `libvirtd` can identify the sockets. + +Modular driver daemons +====================== + +Helper daemons +============== + +There are some other special purpose daemons used for certain administrative +tasks in libvirt + +Logging daemon +-------------- + +The `virtlogd` daemon provides a service for managing log files associated with +QEMU virtual machines. The QEMU process is given one or more pipes, the other +end of which are owned by the `virtlogd` daemon. It will then write data on +those pipes to log files, while enforcing a maximum file size and performing +log rollover at the size limit. + +Since the daemon holds open anoymous pipe file descriptors, it must never be +stopped while any QEMU virtual machines are running. To enable software updates +to be applied, the daemon is capable of re-executing itself while keeping all +file descriptors open. This can be triggered by sending the daemon `SIGUSR1` + +Systemd integration +~~~~~~~~~~~~~~~~~~~ + +Locking daemon +-------------- + diff --git a/docs/docs.html.in b/docs/docs.html.in index 4b59162e0f..e378279827 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -15,6 +15,9 @@ <dt><a href="migration.html">Migration</a></dt> <dd>Migrating guests between machines</dd> + <dt><a href="daemons.html">Daemons</a></dt> + <dd>Overview of the daemons provided by libvirt</dd> + <dt><a href="remote.html">Remote access</a></dt> <dd>Enable remote access over TCP</dd> -- 2.23.0
On Fri, Nov 08, 2019 at 11:21:12AM +0000, Daniel P. Berrangé wrote:
Now that we have more than just the libvirtd daemon, we should be explaining to users what they are all for & important aspects of their configuration.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/Makefile.am | 7 +- docs/daemons.rst | 209 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 + 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 docs/daemons.rst
diff --git a/docs/daemons.rst b/docs/daemons.rst new file mode 100644 index 0000000000..51d4153b99 --- /dev/null +++ b/docs/daemons.rst
[...]
+Sockets +------- + +When running in system mode, `libvirtd` exposes three UNIX domain sockets, and +optionally, one or two TCP sockets + +* `/var/run/libvirt/libvirt-sock` - the primary socket for accessing libvirt
All the stuff in backticks are rendered in italics for me. A fixed-width font would look better.
+ APIs, with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. This is the + socket that most management applications connect to by default. + +* `/var/run/libvirt/libvirt-sock-ro` - the secondary socket for accessing + libvirt APIs, with limited read-only privileges. A connection to this socket + gives the ability to query the existance of objects and monitor some aspects + of their operation. This is the socket that most management applications + connect to when requesting read only mode. Typically this is what a + monitoring app would use. + +* `/var/run/libvirt/libvirt-sock-admin` - the administrative socket for + controlling operation of the daemon itself (as opposed to drivers it is + running). This can be used to dynamically reconfigure some aspects of the + daemon and monitor/control connected clients. +
[...]
+Logging daemon +-------------- + +The `virtlogd` daemon provides a service for managing log files associated with +QEMU virtual machines. The QEMU process is given one or more pipes, the other +end of which are owned by the `virtlogd` daemon. It will then write data on +those pipes to log files, while enforcing a maximum file size and performing +log rollover at the size limit. + +Since the daemon holds open anoymous pipe file descriptors, it must never be +stopped while any QEMU virtual machines are running. To enable software updates +to be applied, the daemon is capable of re-executing itself while keeping all +file descriptors open. This can be triggered by sending the daemon `SIGUSR1` + +Systemd integration +~~~~~~~~~~~~~~~~~~~
Empty sections. Also, the '¶' character with a tooltip of 'Permalink to this headline' is no longer rendered here. Jano
+ +Locking daemon +-------------- +
Jano
On Mon, Nov 11, 2019 at 03:24:28PM +0100, Ján Tomko wrote:
On Fri, Nov 08, 2019 at 11:21:12AM +0000, Daniel P. Berrangé wrote:
Now that we have more than just the libvirtd daemon, we should be explaining to users what they are all for & important aspects of their configuration.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- docs/Makefile.am | 7 +- docs/daemons.rst | 209 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 + 3 files changed, 218 insertions(+), 1 deletion(-) create mode 100644 docs/daemons.rst
diff --git a/docs/daemons.rst b/docs/daemons.rst new file mode 100644 index 0000000000..51d4153b99 --- /dev/null +++ b/docs/daemons.rst
[...]
+Sockets +------- + +When running in system mode, `libvirtd` exposes three UNIX domain sockets, and +optionally, one or two TCP sockets + +* `/var/run/libvirt/libvirt-sock` - the primary socket for accessing libvirt
All the stuff in backticks are rendered in italics for me. A fixed-width font would look better.
+ APIs, with full read-write privileges. A connection to this socket gives the + client privileges that are equivalent to having a root shell. This is the + socket that most management applications connect to by default. + +* `/var/run/libvirt/libvirt-sock-ro` - the secondary socket for accessing + libvirt APIs, with limited read-only privileges. A connection to this socket + gives the ability to query the existance of objects and monitor some aspects + of their operation. This is the socket that most management applications + connect to when requesting read only mode. Typically this is what a + monitoring app would use. + +* `/var/run/libvirt/libvirt-sock-admin` - the administrative socket for + controlling operation of the daemon itself (as opposed to drivers it is + running). This can be used to dynamically reconfigure some aspects of the + daemon and monitor/control connected clients. +
[...]
+Logging daemon +-------------- + +The `virtlogd` daemon provides a service for managing log files associated with +QEMU virtual machines. The QEMU process is given one or more pipes, the other +end of which are owned by the `virtlogd` daemon. It will then write data on +those pipes to log files, while enforcing a maximum file size and performing +log rollover at the size limit. + +Since the daemon holds open anoymous pipe file descriptors, it must never be +stopped while any QEMU virtual machines are running. To enable software updates +to be applied, the daemon is capable of re-executing itself while keeping all +file descriptors open. This can be triggered by sending the daemon `SIGUSR1` + +Systemd integration +~~~~~~~~~~~~~~~~~~~
Empty sections.
Sorry, I didn't mean to send patch 6 yet - it is obviously incomplete :-)
Also, the '¶' character with a tooltip of 'Permalink to this headline' is no longer rendered here.
I'll think about how to handle this... Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Mon, Nov 11, 2019 at 03:24:28PM +0100, Ján Tomko wrote:
On Fri, Nov 08, 2019 at 11:21:12AM +0000, Daniel P. Berrangé wrote:
[...]
+Sockets +------- + +When running in system mode, `libvirtd` exposes three UNIX domain sockets, and +optionally, one or two TCP sockets + +* `/var/run/libvirt/libvirt-sock` - the primary socket for accessing libvirt
All the stuff in backticks are rendered in italics for me. A fixed-width font would look better.
That (the "inline literals") requires replacing single backticks with double backticks: ``foo`` [...] -- /kashyap
On Fri, 2019-11-08 at 11:21 +0000, Daniel P. Berrangé wrote:
+Systemd Integration +------------------- + +When the `libvirtd` daemon is managed by `systemd` a number of desirable +features are available, most notably socket activation. + +Libvirt ships a number of unit files for controlling libvirtd + +* `libvirtd.service` - the main unit file for launching the libvirtd daemon + in system mode. The command line arguments passed can be configured by + editting `/etc/sysconfig/libvirtd`. This is typically only needed to control + the use of the auto shutdown timeout value. It is recommended that this + the service unit be configured to start on boot. This is because
I see that you didn't intend to send patch 6 yet, but since I noticed this minor issue, I thought I'd point it out: "...that this the service unit..." Jonathon
On Fri, Nov 08, 2019 at 11:21:06AM +0000, Daniel P. Berrangé wrote:
This refactors existing docs related to the remote driver/daemon and URIs. It then also adds a kbase page about RPM package options.
This introduces the use of RST for docs as a replacement for HTML. The intent is that all new docs should use RST from this point.
Existing HTML docs are candidates for conversion to RST by anyone interested.
Unlike the Perl -> Python conversion, where we already had a mixture of both, this actually fulfills the prophecy of XKCD #927 [0] It would be nice if the first usage of RST actually converted existing HTML docs, to lead by example, but mostly to demonstrate that it is reasonably capable of replacing XSLT. Jano [0] https://xkcd.com/927/
Daniel P. Berrangé (6): docs: split TLS certificate setup into its own file docs: move docs about remote driver URIs into URI docs build: introduce rst2html as a mandatory build tool docs: adapt filling of <head> section for rst2html output docs: add a kbase page about RPM packaging options docs: add page describing the libvirt daemons
.gitignore | 1 + docs/Makefile.am | 21 +- docs/daemons.rst | 209 +++++++++++ docs/docs.html.in | 6 + docs/kbase.html.in | 4 + docs/kbase/rpm-deployment.rst | 410 ++++++++++++++++++++ docs/page.xsl | 4 +- docs/remote.html.in | 684 +--------------------------------- docs/tlscerts.html.in | 413 ++++++++++++++++++++ docs/uri.html.in | 263 +++++++++++-- libvirt.spec.in | 2 + m4/virt-external-programs.m4 | 5 + mingw-libvirt.spec.in | 1 + 13 files changed, 1309 insertions(+), 714 deletions(-) create mode 100644 docs/daemons.rst create mode 100644 docs/kbase/rpm-deployment.rst create mode 100644 docs/tlscerts.html.in
-- 2.23.0
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Mon, Nov 11, 2019 at 03:28:28PM +0100, Ján Tomko wrote:
On Fri, Nov 08, 2019 at 11:21:06AM +0000, Daniel P. Berrangé wrote:
This refactors existing docs related to the remote driver/daemon and URIs. It then also adds a kbase page about RPM package options.
This introduces the use of RST for docs as a replacement for HTML. The intent is that all new docs should use RST from this point.
Existing HTML docs are candidates for conversion to RST by anyone interested.
Unlike the Perl -> Python conversion, where we already had a mixture of both, this actually fulfills the prophecy of XKCD #927 [0]
It would be nice if the first usage of RST actually converted existing HTML docs, to lead by example, but mostly to demonstrate that it is reasonably capable of replacing XSLT.
I'm happy to convert some existing docs & in fact have already done some work at converting the .pod man pages to .rst with reasonable success. Eliminating POD matches the goals of eliminating perl in general. Personally I don't mind the POD format in terms of its markup / complexity, but RST is better known especially in the python world. So converting the POD to RST addresses XKCD 927. Converting the main docs/*.html is a fairly large job, that I was going look at incrementally over a long time. Possibly it might be possible to use pandoc to autoconvert, as long as the resulting RST isn't too ugly. TBD. I don't think this is neccessary as a blocker for using RST for newly authored docs though. NB writing content is RST is independent of eliminating XSLT as the templating system. Elimination oif XSLT depends what templating system we use, either Sphinx or Pelican - I've not delved into it to figure out which is better, but I don't see any problem with either replacing XSLT as it is not as if we do anything especially clever in XSLT. We're basically just substituting the .html.in files into a single template and generating a table of contents. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Mon, Nov 11, 2019 at 02:39:35PM +0000, Daniel P. Berrangé wrote: [...]
NB writing content is RST is independent of eliminating XSLT as the templating system. Elimination oif XSLT depends what templating system we use, either Sphinx or Pelican - I've not delved into it to figure out which is better,
FWIW, Sphinx seems to be the "preferred" choice for Linux[*], QEMU. (OpenStack upstream also uses it heavily.) [...] [*] https://www.kernel.org/doc/html/v4.11/doc-guide/sphinx.html -- /kashyap
On Wed, Nov 13, 2019 at 02:53:21PM +0100, Kashyap Chamarthy wrote:
On Mon, Nov 11, 2019 at 02:39:35PM +0000, Daniel P. Berrangé wrote:
[...]
NB writing content is RST is independent of eliminating XSLT as the templating system. Elimination oif XSLT depends what templating system we use, either Sphinx or Pelican - I've not delved into it to figure out which is better,
FWIW, Sphinx seems to be the "preferred" choice for Linux[*], QEMU. (OpenStack upstream also uses it heavily.)
Yep, but there's a difference for libvirt's needs. IIUC those projects are all building the docs into a manual. Libvirt is building its docs into a website with a series of pages. I've not investigated in a lot of detail, but my first impressions are that Pelican is better suited for building websites, while Sphinx is better suited for building manuals. Both use RST as their input though, so the decision of which to use mostly impacts the way we later replace the XSLT with a new page template, so I've not spent much time on it yet. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
participants (4)
-
Daniel P. Berrangé -
Jonathon Jongsma -
Ján Tomko -
Kashyap Chamarthy