Re: [libvirt] [PATCH 07/13] esx: Extend documentation about 'vcenter' and add some about 'auto_answer'

--- docs/drvesx.html.in | 52 ++++++++++++++++++++++++++++++++++++++++++++------ src/esx/README | 8 +++--- 2 files changed, 49 insertions(+), 11 deletions(-) diff --git a/docs/drvesx.html.in b/docs/drvesx.html.in index 362659c..b7909ff 100644 --- a/docs/drvesx.html.in +++ b/docs/drvesx.html.in @@ -15,7 +15,7 @@ installed on the ESX server. The driver uses version 2.5 of the remote, SOAP based <a href="http://www.vmware.com/support/developer/vc-sdk/visdk25pubs/Ref... - VMware Virtual Infrastructure API</a> to communicate with the + VMware Virtual Infrastructure API</a> (VI API) to communicate with the ESX server, like the VMware Virtual Infrastructure Client does. Since version 4.0 this API is called <a href="http://www.vmware.com/support/developer/vc-sdk/visdk400pubs/Re... @@ -78,11 +78,12 @@ type://[username@]hostname[:port]/[?extraparameters] <code>vcenter</code> </td> <td> - Hostname of a VMware vCenter + Hostname of a VMware vCenter or <code>*</code> </td> <td> In order to perform a migration the driver needs to know the - VMware vCenter for the ESX server. + VMware vCenter for the ESX server. If set to <code>*</code>, + the driver connects to the vCenter known to the ESX server. </td> </tr> <tr> @@ -97,6 +98,20 @@ type://[username@]hostname[:port]/[?extraparameters] SSL certificate. The default value it 0. </td> </tr> + <tr> + <td> + <code>auto_answer</code> + </td> + <td> + <code>0</code> or <code>1</code> + </td> + <td> + If set to 1, the driver answers all + <a href="#questions">questions</a> with the default answer. + If set to 0, questions are reported as errors. The default + value it 0. + </td> + </tr> </table> @@ -120,6 +135,25 @@ type://[username@]hostname[:port]/[?extraparameters] </p> + <h2><a name="questions">Questions blocking tasks</a></h2> + <p> + Some methods of the VI API start tasks, for example + <code>PowerOnVM_Task()</code>. Such tasks may be blocked by questions + if the ESX server detects an issue with the domain that requires user + interaction. The ESX driver cannot prompt the user to answer a + question, libvirt doesn't have an API for something like this. + </p> + <p> + The VI API provides the <code>AnswerVM()</code> method to + programmatically answer a questions. So the driver has two options + how to handle such a situation: either answer the questions with the + default answer or report the question as an error and cancel the + blocked task if possible. The + <a href="#uriformat"><code>auto_answer</code></a> query parameter + controls the answering behavior. + </p> + + <h2><a name="xmlspecial">Specialties in the domain XML config</a></h2> <p> There are several specialties in the domain XML config for ESX domains. @@ -404,8 +438,12 @@ ethernet0.address = "00:50:56:25:48:C7" <h2><a name="migration">Migration</a></h2> <p> A migration cannot be initiated on an ESX server directly, a VMware - vCenter is necessary for this. The vCenter hostname has to be passed - to the driver via the <code>vcenter</code> query parameter. + vCenter is necessary for this. The <code>vcenter</code> query + parameter must be set either to the hostname or IP address of the + vCenter managing the ESX server or to <code>*</code>. Setting it + to <code>*</code> causes the driver to connect to the vCenter known to + the ESX server. If the ESX server is not managed by a vCenter an error + is reported. </p> <pre> esx://example.com/?vcenter=example-vcenter.com @@ -413,11 +451,11 @@ esx://example.com/?vcenter=example-vcenter.com <p> Here an example how to migrate the domain <code>Fedora11</code> from ESX server <code>example-src.com</code> to ESX server - <code>example-dst.com</code> involving vCenter + <code>example-dst.com</code> implicitly involving vCenter <code>example-vcenter.com</code> using <code>virsh</code>. </p> <pre> -$ virsh -c esx://example-src.com/?vcenter=example-vcenter.com migrate Fedora11 esx://example-dst.com/?vcenter=example-vcenter.com +$ virsh -c esx://example-src.com/?vcenter=* migrate Fedora11 esx://example-dst.com/?vcenter=* Enter username for example-src.com [root]: Enter root password for example-src.com: Enter username for example-vcenter.com [administrator]: diff --git a/src/esx/README b/src/esx/README index 3619054..51e49e3 100644 --- a/src/esx/README +++ b/src/esx/README @@ -18,8 +18,8 @@ Automatic question handling What is a question in the ESX context? -------------------------------------- -The VI API contains calls that start tasks, for example PowerOnVM_Task(). Such -tasks may be blocked by a question if the ESX host detects an issue with the +The VI API contains methods that start tasks, for example PowerOnVM_Task(). Such +tasks may be blocked by questions if the ESX host detects an issue with the virtual machine that requires user interaction. An example: If a virtual machine has a serial port that is realized via a file, @@ -29,8 +29,8 @@ Until this question is answered the power-on task is blocked and the virtual machine won't get powered on. The ESX driver cannot prompt the user to answer a question, libvirt doesn't -have an API for something like this. The VI API provides a AnswerVM() method to -programmatically answer such questions. A question comes together with a list +have an API for something like this. The VI API provides the AnswerVM() method +to programmatically answer such questions. A question comes together with a list of possible answers. One of this answers is marked as the default one. For all questions I've seen so far the default answer is always a non-destructive one.