libvirt/src/esx
Martin Kletzander 2e2c9797c5 esx: Do not return root objects in a lookup
The lookups in esx_vi work a bit differently that we are used to.  The filters
(travelsalSpec and selectSet) choose how to look up the objects, but given a
root object the lookup lists all the objects of a requested type inside it as
well as the root object itself.  We then go through the results and find the one
which has the same name as was requested.  However in a case with nested folders
of a same name this could break when the first returned object in the list is
the parent folder as we'd select it only based on the name.  To avoid this also
add a check that the candidate we are trying to pick is not exactly the same
object (reference) as the root object.

https://bugzilla.redhat.com/show_bug.cgi?id=1643868

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Tim Wiederhake <twiederh@redhat.com>
2022-01-24 09:54:24 +01:00
..
esx_driver.c lib: Use g_autoptr() for virDomainDef 2021-12-03 17:18:26 +01:00
esx_driver.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_interface_driver.c lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_interface_driver.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_network_driver.c src: network_conf: propagate only bool to virNetworkDefParseString() 2021-09-10 17:38:06 +02:00
esx_network_driver.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_private.h lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_storage_backend_iscsi.c lib: Drop intermediary return variables 2021-10-25 12:48:46 +02:00
esx_storage_backend_iscsi.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_storage_backend_vmfs.c lib: Drop intermediary return variables 2021-10-25 12:48:46 +02:00
esx_storage_backend_vmfs.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_storage_driver.c lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_storage_driver.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_stream.c Do not check return value of VIR_REALLOC_N 2021-03-22 12:44:18 +01:00
esx_stream.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_util.c lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_util.h lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_vi_generator.input esx: generator: add GuestNicInfo object 2020-09-15 10:00:29 +02:00
esx_vi_methods.c esx: use g_autofree for char* where it is trivially possible 2021-02-16 13:50:04 -05:00
esx_vi_methods.h src/esx: use #pragma once in headers 2019-06-13 17:05:09 +02:00
esx_vi_types.c lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_vi_types.h lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
esx_vi.c esx: Do not return root objects in a lookup 2022-01-24 09:54:24 +01:00
esx_vi.h lib: Drop internal virXXXPtr typedefs 2021-04-13 17:00:38 +02:00
meson.build meson: drop use of .path() for python args 2020-11-09 16:32:55 +00:00
README syntax-check: Only prohibit empty first lines in non-empty files 2021-06-15 14:15:42 +02:00

Some links to relevant documentation
====================================


VI/vSphere API:
  https://www.vmware.com/support/developer/vc-sdk/visdk25pubs/ReferenceGuide/
  https://www.vmware.com/support/developer/vc-sdk/visdk400pubs/ReferenceGuide/
  https://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/

VMX config:
  https://www.sanbarrow.com/vmx.html

CPUID:
  https://www.sandpile.org/ia32/cpuid.htm

Memory model:
  https://www.vmware.com/pdf/esx3_memory.pdf
  https://www.vmware.com/pdf/usenix_resource_mgmt.pdf

Virtual serial port (network backed):
  https://www.vmware.com/support/developer/vc-sdk/visdk41pubs/ApiReference/vim.vm.device.VirtualSerialPort.URIBackingInfo.html
  https://www.vmware.com/support/developer/vc-sdk/visdk41pubs/vsp41_usingproxy_virtual_serial_ports.pdf



Automatic question handling
===========================


What is a question in the ESX context?
--------------------------------------

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,
the ESX host will ask a question on power-on of this virtual machine whether
new content should be appended to this file or the file should be replaced.
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 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.

There are two options how to handle a question that is blocking a task: either
answer it automatically or report it as error and try to cancel the blocked
task.

The auto_answer query parameter defines how the driver should handle questions.
Possible values are 0 for the report-error-and-try-to-cancel option and 1 for
the automatic-answer option.


How is automatic question handling implemented?
-----------------------------------------------

Before any new task is started the driver checks if there is a pending task
blocked by a question. If automatic question handling is disabled the driver
reports an error that includes the question and returns from the driver
function. If automatic question handling is enabled the driver answers the
question with the default answer and returns from the driver function.

In both cases the actual desired task is not started. If the question was not
answered the blocked task is still blocked and because task can't be executed
in parallel in general it's of no use to start yet another task. If the
question was answered the blocked task may already perform the desired action
and one must wait for its completion, so it's of no use to start yet another
task.

If there is no question blocking a task or another pending task that had not
finished yet the driver starts the desired task and waits for its completion.
While polling for status updates of the task it also checks for question that
may have been triggered by the current task and handles them according to the
value of the auto_answer query parameter. If automatic question handling is
enabled the driver answers the question with the default answer and continues
polling for status updates. If automatic question handling is disabled the
driver reports an error that includes the question, tries to cancel the blocked
task and returns from the driver function.

It tries to cancel the blocked task, but this may not be possible, because
there are task like the power-on task that is marked as non-cancelable. So the
driver may leave blocked tasks behind if automatic question handling is
disabled.



Different escaping schemes used in different places
===================================================

A domain name in the vSphere API has [%/\] escaped as %XX (percent-encoding),
where XX is the ASCII code of the escaped char in hex.

A domainName entry in a VMX config file is percent-encoded and has [|"] escaped
as |XX (pipe-encoding).

A annotation entry in a VMX config file is pipe-encoded.

A datastore item name has the special Windows path characters ["*<>:|?]
replaced by underscores (_). The result is escaped using percent-encoding and
base64-encoding. This isn't a bijective encoding. Therefore, escaped datastore
item names cannot be unescaped completely.

For base64-encoding sequences of chars that don't match [a-zA-Z0-9'(),. _-]
are replaced by their base64 form (the padding is omitted). An encoded sequence
begins with a plus (+), ends with a minus (-) and can contain a plus (+). The
minus (-) is omitted if the string ends in a base64-encoded sequence. VMware
uses the comma (,) instead of the slash (/) in the base64 alphabet to avoid
conflicts with the slash as path separator.