xen: encourage use of xen:///system URI as preferred format

Historically we have used a bare xen:/// URI for connecting to the
legacy Xen driver. The new libxl Xen driver follows the new practice
of allowing '/system' as a path, as well as bare '/' for compat with
the old Xen driver.

This documents xen:///system as the preferred format for Xen, leaving
xen:/// as an undocumented feature just for back-compat.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

docs/drvxen.html.in

@@ -43,11 +43,11 @@
     </p>
 
 <pre>
-xen:///                        (local access, direct)
-xen+unix:///                   (local access, via daemon)
-xen://example.com/             (remote access, TLS/x509)
-xen+tcp://example.com/         (remote access, SASl/Kerberos)
-xen+ssh://root@example.com/    (remote access, SSH tunnelled)
+xen:///system                     (local access, direct)
+xen+unix:///system                (local access, via daemon)
+xen://example.com/system          (remote access, TLS/x509)
+xen+tcp://example.com/system      (remote access, SASl/Kerberos)
+xen+ssh://root@example.com/system (remote access, SSH tunnelled)
 </pre>
 
     <h2><a id="imex">Import and export of libvirt domain XML configs</a></h2>
@@ -76,7 +76,7 @@ xen+ssh://root@example.com/    (remote access, SSH tunnelled)
       which can then be used by libvirt.
     </p>
 
-    <pre>$ virsh -c xen:/// domxml-from-native xen-xm rhel5.cfg
+    <pre>$ virsh -c xen:///system domxml-from-native xen-xm rhel5.cfg
 &lt;domain type='xen'&gt;
   &lt;name&gt;rhel5pv&lt;/name&gt;
   &lt;uuid&gt;8f07fe28-753f-2729-d76d-bdbd892f949a&lt;/uuid&gt;
@@ -122,7 +122,7 @@ xen+ssh://root@example.com/    (remote access, SSH tunnelled)
       format.
     </p>
 
-    <pre>$ virsh -c xen:/// domxml-to-native xen-xm rhel5pv.xml
+    <pre>$ virsh -c xen:///system domxml-to-native xen-xm rhel5pv.xml
 name = "rhel5pv"
 uuid = "8f07fe28-753f-2729-d76d-bdbd892f949a"
 maxmem = 2500

docs/remote.html.in

@@ -130,14 +130,14 @@ to distinguish this from a local URI.
 Some examples:
 </p>
     <ul>
-      <li><code>xen+ssh://rjones@towada/</code><br/> &#x2014; Connect to a
+      <li><code>xen+ssh://rjones@towada/system</code><br/> &#x2014; 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/</code><br/> &#x2014; Connect to a
+      <li><code>xen://towada/system</code><br/> &#x2014; Connect to a
 remote Xen hypervisor on host <code>towada</code> using TLS.
 </li>
-      <li><code>xen://towada/?no_verify=1</code><br/> &#x2014; Connect to a
+      <li><code>xen://towada/system?no_verify=1</code><br/> &#x2014; Connect to a
 remote Xen hypervisor on host <code>towada</code> using TLS.  Do not verify
 the server's certificate.
 </li>

docs/uri.html.in

@@ -107,7 +107,7 @@ In virt-install use the <code>--connect=</code><i>URI</i> option:
 virt-install <b>--connect=test:///default</b> <i>[other options]</i>
 </pre>
     <h2>
-      <a id="URI_xen">xen:/// URI</a>
+      <a id="URI_xen">xen:///system URI</a>
     </h2>
     <p>
       <i>This section describes a feature which is new in libvirt &gt;
@@ -115,7 +115,7 @@ virt-install <b>--connect=test:///default</b> <i>[other options]</i>
     </p>
     <p>
 To access a Xen hypervisor running on the local machine
-use the URI <code>xen:///</code>.
+use the URI <code>xen:///system</code>.
 </p>
     <h2>
       <a id="URI_qemu">qemu:///... QEMU and KVM URIs</a>
@@ -167,10 +167,10 @@ a NULL URI for a local connection. For example:
       </tr>
       <tr>
         <td>
-          <code>xen:///</code>
+          <code>xen:///system</code>
         </td>
         <td>
-          <code>xen://oirase/</code>
+          <code>xen://oirase/system</code>
         </td>
         <td> Connect to the Xen hypervisor running on host <code>oirase</code>
   using TLS. </td>
@@ -187,10 +187,10 @@ a NULL URI for a local connection. For example:
       </tr>
       <tr>
         <td>
-          <code>xen:///</code>
+          <code>xen:///system</code>
         </td>
         <td>
-          <code>xen+ssh://oirase/</code>
+          <code>xen+ssh://oirase/system</code>
         </td>
         <td> Connect to the Xen hypervisor running on host <code>oirase</code>
   by going over an <code>ssh</code> connection. </td>
@@ -251,7 +251,7 @@ In any case applications linked to libvirt can continue to pass
 user to override the URI, either by constructing one or by allowing
 the user to type a URI in directly (if that is appropriate).  If your
 application wishes to connect specifically to a Xen hypervisor, then
-for future proofing it should choose a full <a href="#URI_xen"><code>xen:///</code> URI</a>.
+for future proofing it should choose a full <a href="#URI_xen"><code>xen:///system</code> URI</a>.
 </p>
     <h3>
       <a id="URI_legacy_xen">Legacy: <code>"xen"</code></a>
@@ -259,7 +259,7 @@ for future proofing it should choose a full <a href="#URI_xen"><code>xen:///</co
     <p>
 Another legacy URI is to specify name as the string
 <code>"xen"</code>.  This will continue to refer to the Xen
-hypervisor.  However you should prefer a full <a href="#URI_xen"><code>xen:///</code> URI</a> in all future code.
+hypervisor.  However you should prefer a full <a href="#URI_xen"><code>xen:///system</code> URI</a> in all future code.
 </p>
   </body>
 </html>

src/libvirt.c

@@ -954,15 +954,15 @@ virConnectOpenInternal(const char *name,
         goto failed;
     }
 
-    /* Convert xen -> xen:/// for back compat */
+    /* Convert xen -> xen:///system for back compat */
     if (name && STRCASEEQ(name, "xen"))
-        name = "xen:///";
+        name = "xen:///system";
 
-    /* Convert xen:// -> xen:/// because xmlParseURI cannot parse the
+    /* Convert xen:// -> xen:///system because xmlParseURI cannot parse the
      * former.  This allows URIs such as xen://localhost to work.
      */
     if (name && STREQ(name, "xen://"))
-        name = "xen:///";
+        name = "xen:///system";
 
     /*
      * If no URI is passed, then check for an environment string if not

src/libxl/libxl_driver.c

@@ -839,7 +839,7 @@ libxlConnectOpen(virConnectPtr conn,
         if (libxl_driver == NULL)
             return VIR_DRV_OPEN_DECLINED;
 
-        if (!(conn->uri = virURIParse("xen:///")))
+        if (!(conn->uri = virURIParse("xen:///system")))
             return VIR_DRV_OPEN_ERROR;
     } else {
         /* Only xen scheme */
@@ -863,7 +863,7 @@ libxlConnectOpen(virConnectPtr conn,
             STRNEQ(conn->uri->path, "/") &&
             STRNEQ(conn->uri->path, "/system")) {
             virReportError(VIR_ERR_INTERNAL_ERROR,
-                           _("unexpected Xen URI path '%s', try xen:///"),
+                           _("unexpected Xen URI path '%s', try xen:///system"),
                            NULLSTR(conn->uri->path));
             return VIR_DRV_OPEN_ERROR;
         }

tools/libvirt-guests.sysconf

@@ -1,5 +1,5 @@
 # URIs to check for running guests
-# example: URIS='default xen:/// vbox+tcp://host/system lxc:///'
+# example: URIS='default xen:///system vbox+tcp://host/system lxc:///'
 #URIS=default
 
 # action taken on host boot

tools/virsh.pod

@@ -254,7 +254,7 @@ common are:
 
 =over 4
 
-=item xen:///
+=item xen:///system
 
 this is used to connect to the local Xen hypervisor