diff --git a/docs/remote.html.in b/docs/remote.html.in index 9bafd9de67ea142e42368fd2177cb6b561e573fb..8c22778f53fa66fb6b22a450f3d2ff7ad075534f 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -30,7 +30,8 @@ to virConnectOpen (or virsh -c ...). For example, if you normally use qemu:///system to access the system-wide QEMU daemon, then to access the system-wide QEMU daemon on a remote machine called -oirase you would use qemu://oirase/system. +compute1.libvirt.org you would use +qemu://compute1.libvirt.org/system.

The section on remote URIs @@ -412,7 +413,9 @@ next section. Server's certificate signed by the CA. (more info) CommonName (CN) must be the hostname of the server as it - is seen by clients. + 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. @@ -564,8 +567,8 @@ X.509 certificate info: Version: 3 Serial Number (hex): 00 -Subject: CN=Red Hat Emerging Technologies -Issuer: CN=Red Hat Emerging Technologies +Subject: CN=Libvirt Project +Issuer: CN=Libvirt Project Signature Algorithm: RSA-SHA Validity: Not Before: Mon Jun 18 16:22:18 2007 @@ -582,14 +585,21 @@ for your clients and servers.

For each server (libvirtd) you need to issue a certificate -with the X.509 CommonName (CN) field set to the hostname -of the server. The CN must match the hostname which -clients will be using to connect to the server. +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 of -xen://oirase/, so the CN must be "oirase". +qemu://compute1.libvirt.org/system, so the CN +must be "compute1.libvirt.org".

Make a private key for the server: @@ -599,19 +609,36 @@ certtool --generate-privkey > serverkey.pem

and sign that key with the CA's private key by first -creating a template file called server.info -(only the CN field matters, which as explained above must -be the server's hostname): +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 = oirase
+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. +

-and sign: +Use the template file as input to a certtool +command to sign the server certificate: 

 certtool --generate-certificate --load-privkey serverkey.pem \
@@ -635,16 +662,28 @@ X.509 certificate info:
 
 Version: 3
 Serial Number (hex): 00
-Subject: O=Red Hat Emerging Technologies,CN=oirase
-Issuer: CN=Red Hat Emerging Technologies
+Subject: O=Libvirt Project,CN=compute1.libvirt.org
+Issuer: CN=Libvirt Project
 Signature Algorithm: RSA-SHA
 Validity:
-        Not Before: Mon Jun 18 16:34:49 2007
-        Not After: Tue Jun 17 16:34:49 2008
+        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 "Red Hat Emerging Technologies" (the CA) and -the "Subject" CN is "oirase" (the server). +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: @@ -665,13 +704,13 @@ which can be installed on the server as

For each client (ie. any program linked with libvirt, such as -virt-manager) +virt-manager) 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, I use: +policy. For example: 

-C=GB,ST=London,L=London,O=Red Hat,CN=name_of_client
+C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client

The process is the same as for @@ -692,7 +731,7 @@ Act as CA and sign the certificate. Create client.info containing: country = GB state = London locality = London -organization = Red Hat +organization = Libvirt Project cn = client1 tls_www_client encryption_key @@ -884,7 +923,7 @@ Blank lines and comments beginning with # are ignored. The default is that DNs are not checked.

- This list may contain wildcards such as "C=GB,ST=London,L=London,O=Red Hat,CN=*" + This list may contain wildcards such as "C=GB,ST=London,L=London,O=Libvirt Project,CN=*" See the POSIX fnmatch function for the format of the wildcards.