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
+ <kbase/tlscerts.html>`__, and/or by enabling an `authentication mechanism
<auth.html>`__.
NB, some distros will use ``/run`` instead of ``/var/run``.
<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>
Examination of the security protections used for QEMU and how they need
configuring to allow use of QEMU passthrough with host files/devices.
+`TLS certificates <tlscerts.html>`__
+ Generate and deploy x509 certificates for TLS.
+
`RPM deployment <rpm-deployment.html>`__
Explanation of the different RPM packages and illustration of which to
pick for installation
'secureusage',
'snapshots',
'systemtap',
+ 'tlscerts',
'virtiofs',
]
--- /dev/null
+==========================
+TLS x509 certificate setup
+==========================
+
+.. contents::
+
+Public Key Infrastructure set up
+--------------------------------
+
+If you are unsure how to create TLS certificates, skip to the next section.
+
+.. list-table::
+ :header-rows: 1
+
+ * - Location
+ - Machine
+ - Description
+ - Required fields
+
+ * - ``/etc/pki/CA/cacert.pem``
+ - Installed on the client and server
+ - CA's certificate
+ - n/a
+
+ * - ``$HOME/.pki/cacert.pem``
+ - Installed on the client
+ - CA's certificate
+ - n/a
+
+ * - ``/etc/pki/libvirt/private/serverkey.pem``
+ - Installed on the server
+ - Server's private key
+ - n/a
+
+ * - ``/etc/pki/libvirt/servercert.pem``
+ - Installed on the server
+ - Server's certificate signed by the CA
+ - 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.
+
+ * - ``/etc/pki/libvirt/private/clientkey.pem``
+ - Installed on the client
+ - Client's private key
+ - n/a
+
+ * - ``/etc/pki/libvirt/clientcert.pem``
+ - Installed on the client
+ - Client's certificate signed by the CA
+ - Distinguished Name (DN) can be checked against an access control list
+ (``tls_allowed_dn_list``).
+
+ * - ``$HOME/.pki/libvirt/clientkey.pem``
+ - Installed on the client
+ - Client's private key
+ - n/a
+
+ * - ``$HOME/.pki/libvirt/clientcert.pem``
+ - Installed on the client
+ - Client's certificate signed by the CA
+ (`more info <#Remote_TLS_client_certificates>`__)
+ - Distinguished Name (DN) can be checked against an access control list
+ (``tls_allowed_dn_list``).
+
+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:
+
+- 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.
+
+- For the root user, the global default locations will always be used.
+
+Background to TLS certificates
+------------------------------
+
+Libvirt supports TLS certificates for verifying the identity of the server and
+clients. There are two distinct checks involved:
+
+- 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 ``?no_verify=1`` to the `remote
+ URI <uri.html#Remote_URI_parameters>`__.
+
+- 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
+ `libvirtd.conf file <remote.html#Remote_libvirtd_configuration>`__.
+
+For full certificate checking you will need to have certificates issued by a
+recognised `Certificate Authority
+(CA) <https://en.wikipedia.org/wiki/Certificate_authority>`__ 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.
+
+Be aware that the `default configuration for
+libvirtd <remote.html#Remote_libvirtd_configuration>`__ 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.
+
+Setting up a Certificate Authority (CA)
+---------------------------------------
+
+You will need the `GnuTLS certtool program documented
+here <https://www.gnutls.org/manual/html_node/certtool-Invocation.html>`__. In
+Fedora, it is in the ``gnutls-utils`` package.
+
+Create a private key for your CA:
+
+::
+
+ certtool --generate-privkey > cakey.pem
+
+and self-sign it by creating a file with the signature details called
+``ca.info`` containing:
+
+::
+
+ cn = Name of your organization
+ ca
+ cert_signing_key
+
+::
+
+ certtool --generate-self-signed --load-privkey cakey.pem \
+ --template ca.info --outfile cacert.pem
+
+(You can delete ``ca.info`` file now if you want).
+
+Now you have two files which matter:
+
+- ``cakey.pem`` - Your CA's private key (keep this very secret!)
+
+- ``cacert.pem`` - Your CA's certificate (this is public).
+
+``cacert.pem`` has to be installed on clients and server(s) to let them know
+that they can trust certificates issued by your CA.
+
+The normal installation directory for ``cacert.pem`` is
+``/etc/pki/CA/cacert.pem`` on all clients and servers.
+
+To see the contents of this file, do:
+
+::
+
+ certtool -i --infile cacert.pem
+
+ 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
+ [etc]
+
+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.
+
+Issuing server certificates
+---------------------------
+
+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.
+
+In the example below, clients will be connecting to the server using a
+`URI <uri.html#URI_remote>`__ of ``qemu://compute1.libvirt.org/system``, so the
+CN must be "``compute1.libvirt.org``".
+
+Make a private key for the server:
+
+::
+
+ certtool --generate-privkey > serverkey.pem
+
+and sign that key with the CA's private key by first creating a template file
+called ``server.info``. The template file will contain a number of fields to
+define the server as follows:
+
+::
+
+ organization = Name of your organization
+ 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
+
+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.
+
+Use the template file as input to a ``certtool`` command to sign the server
+certificate:
+
+::
+
+ certtool --generate-certificate --load-privkey serverkey.pem \
+ --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
+ --template server.info --outfile servercert.pem
+
+This gives two files:
+
+- ``serverkey.pem`` - The server's private key.
+
+- ``servercert.pem`` - The server's public key.
+
+We can examine this certificate and its signature:
+
+::
+
+ certtool -i --infile servercert.pem
+ 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
+
+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
+
+Finally we have two files to install:
+
+- ``serverkey.pem`` is the server's private key which should be copied to the
+ server *only* as ``/etc/pki/libvirt/private/serverkey.pem``.
+
+- ``servercert.pem`` is the server's certificate which can be installed on the
+ server as ``/etc/pki/libvirt/servercert.pem``.
+
+Issuing client certificates
+---------------------------
+
+For each client (ie. any program linked with libvirt, such as
+`virt-manager <https://virt-manager.org/>`__) 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:
+
+::
+
+ C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client
+
+The process is the same as for `setting up the server
+certificate <#Remote_TLS_server_certificates>`__ so here we just briefly cover
+the steps.
+
+#. Make a private key:
+
+ ::
+
+ certtool --generate-privkey > clientkey.pem
+
+#. Act as CA and sign the certificate. Create client.info containing:
+
+ ::
+
+ country = GB
+ state = London
+ locality = London
+ organization = Libvirt Project
+ cn = client1
+ tls_www_client
+ encryption_key
+ signing_key
+
+ and sign by doing:
+
+ ::
+
+ certtool --generate-certificate --load-privkey clientkey.pem \
+ --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
+ --template client.info --outfile clientcert.pem
+
+#. Install the certificates on the client machine:
+
+ ::
+
+ cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
+ cp clientcert.pem /etc/pki/libvirt/clientcert.pem
+
+Troubleshooting TLS certificate problems
+----------------------------------------
+
+failed to verify client's certificate
+ 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.
+
+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.
'testapi',
'testsuites',
'testtck',
- 'tlscerts',
]
# list of web targets to build for docs/web rule
<dd><a href="https://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="tlscerts.html" title="Generating TLS certificates">generate client and
+ <a href="kbase/tlscerts.html" title="Generating TLS certificates">generate client and
server certificates</a>.
The standard port is 16514.
</dd>
+++ /dev/null
-==========================
-TLS x509 certificate setup
-==========================
-
-.. contents::
-
-Public Key Infrastructure set up
---------------------------------
-
-If you are unsure how to create TLS certificates, skip to the next section.
-
-.. list-table::
- :header-rows: 1
-
- * - Location
- - Machine
- - Description
- - Required fields
-
- * - ``/etc/pki/CA/cacert.pem``
- - Installed on the client and server
- - CA's certificate
- - n/a
-
- * - ``$HOME/.pki/cacert.pem``
- - Installed on the client
- - CA's certificate
- - n/a
-
- * - ``/etc/pki/libvirt/private/serverkey.pem``
- - Installed on the server
- - Server's private key
- - n/a
-
- * - ``/etc/pki/libvirt/servercert.pem``
- - Installed on the server
- - Server's certificate signed by the CA
- - 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.
-
- * - ``/etc/pki/libvirt/private/clientkey.pem``
- - Installed on the client
- - Client's private key
- - n/a
-
- * - ``/etc/pki/libvirt/clientcert.pem``
- - Installed on the client
- - Client's certificate signed by the CA
- - Distinguished Name (DN) can be checked against an access control list
- (``tls_allowed_dn_list``).
-
- * - ``$HOME/.pki/libvirt/clientkey.pem``
- - Installed on the client
- - Client's private key
- - n/a
-
- * - ``$HOME/.pki/libvirt/clientcert.pem``
- - Installed on the client
- - Client's certificate signed by the CA
- (`more info <#Remote_TLS_client_certificates>`__)
- - Distinguished Name (DN) can be checked against an access control list
- (``tls_allowed_dn_list``).
-
-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:
-
-- 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.
-
-- For the root user, the global default locations will always be used.
-
-Background to TLS certificates
-------------------------------
-
-Libvirt supports TLS certificates for verifying the identity of the server and
-clients. There are two distinct checks involved:
-
-- 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 ``?no_verify=1`` to the `remote
- URI <uri.html#Remote_URI_parameters>`__.
-
-- 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
- `libvirtd.conf file <remote.html#Remote_libvirtd_configuration>`__.
-
-For full certificate checking you will need to have certificates issued by a
-recognised `Certificate Authority
-(CA) <https://en.wikipedia.org/wiki/Certificate_authority>`__ 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.
-
-Be aware that the `default configuration for
-libvirtd <remote.html#Remote_libvirtd_configuration>`__ 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.
-
-Setting up a Certificate Authority (CA)
----------------------------------------
-
-You will need the `GnuTLS certtool program documented
-here <https://www.gnutls.org/manual/html_node/certtool-Invocation.html>`__. In
-Fedora, it is in the ``gnutls-utils`` package.
-
-Create a private key for your CA:
-
-::
-
- certtool --generate-privkey > cakey.pem
-
-and self-sign it by creating a file with the signature details called
-``ca.info`` containing:
-
-::
-
- cn = Name of your organization
- ca
- cert_signing_key
-
-::
-
- certtool --generate-self-signed --load-privkey cakey.pem \
- --template ca.info --outfile cacert.pem
-
-(You can delete ``ca.info`` file now if you want).
-
-Now you have two files which matter:
-
-- ``cakey.pem`` - Your CA's private key (keep this very secret!)
-
-- ``cacert.pem`` - Your CA's certificate (this is public).
-
-``cacert.pem`` has to be installed on clients and server(s) to let them know
-that they can trust certificates issued by your CA.
-
-The normal installation directory for ``cacert.pem`` is
-``/etc/pki/CA/cacert.pem`` on all clients and servers.
-
-To see the contents of this file, do:
-
-::
-
- certtool -i --infile cacert.pem
-
- 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
- [etc]
-
-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.
-
-Issuing server certificates
----------------------------
-
-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.
-
-In the example below, clients will be connecting to the server using a
-`URI <uri.html#URI_remote>`__ of ``qemu://compute1.libvirt.org/system``, so the
-CN must be "``compute1.libvirt.org``".
-
-Make a private key for the server:
-
-::
-
- certtool --generate-privkey > serverkey.pem
-
-and sign that key with the CA's private key by first creating a template file
-called ``server.info``. The template file will contain a number of fields to
-define the server as follows:
-
-::
-
- organization = Name of your organization
- 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
-
-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.
-
-Use the template file as input to a ``certtool`` command to sign the server
-certificate:
-
-::
-
- certtool --generate-certificate --load-privkey serverkey.pem \
- --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
- --template server.info --outfile servercert.pem
-
-This gives two files:
-
-- ``serverkey.pem`` - The server's private key.
-
-- ``servercert.pem`` - The server's public key.
-
-We can examine this certificate and its signature:
-
-::
-
- certtool -i --infile servercert.pem
- 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
-
-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
-
-Finally we have two files to install:
-
-- ``serverkey.pem`` is the server's private key which should be copied to the
- server *only* as ``/etc/pki/libvirt/private/serverkey.pem``.
-
-- ``servercert.pem`` is the server's certificate which can be installed on the
- server as ``/etc/pki/libvirt/servercert.pem``.
-
-Issuing client certificates
----------------------------
-
-For each client (ie. any program linked with libvirt, such as
-`virt-manager <https://virt-manager.org/>`__) 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:
-
-::
-
- C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client
-
-The process is the same as for `setting up the server
-certificate <#Remote_TLS_server_certificates>`__ so here we just briefly cover
-the steps.
-
-#. Make a private key:
-
- ::
-
- certtool --generate-privkey > clientkey.pem
-
-#. Act as CA and sign the certificate. Create client.info containing:
-
- ::
-
- country = GB
- state = London
- locality = London
- organization = Libvirt Project
- cn = client1
- tls_www_client
- encryption_key
- signing_key
-
- and sign by doing:
-
- ::
-
- certtool --generate-certificate --load-privkey clientkey.pem \
- --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
- --template client.info --outfile clientcert.pem
-
-#. Install the certificates on the client machine:
-
- ::
-
- cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
- cp clientcert.pem /etc/pki/libvirt/clientcert.pem
-
-Troubleshooting TLS certificate problems
-----------------------------------------
-
-failed to verify client's certificate
- 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.
-
-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.
projects / libvirt.git / commitdiff