[Libguestfs] [v2v PATCH 2/2] -i vmx -it ssh: document percent encoding in ssh URIs in more detail

On the vmfs file system, ESXi encodes guest name characters that it considers reserved with fairly unpredictable, proprietary rules. For example, the ESXi webgui forbids backslash characters (\) completely, a percent sign (%) is encoded as %25, and a dollar sign ($) is replaced with underscore (_). Therefore the user can only construct the pathname part of the ssh:// URI in two steps: (1) determine the precise absolute pathname of the VMX file by way of logging in to the ESXi server interactively, and *reading* (not guessing) whatever ESXi chose for naming directories and files, (2) given the absolute, server-local pathname, percent-encode the characters that are reserved in URIs, following the open standard(s) that cover this. Document this procedure: reorder the paragraphs of the affected section so that they describe segments of the URI from the left to the right, and then elaborate on the pathname segment. Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1938954 Signed-off-by: Laszlo Ersek <lersek(a)redhat.com&gt; --- docs/virt-v2v-input-vmware.pod | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/virt-v2v-input-vmware.pod b/docs/virt-v2v-input-vmware.pod index 4f4af2a9d804..38a0b30cd5fc 100644 --- a/docs/virt-v2v-input-vmware.pod +++ b/docs/virt-v2v-input-vmware.pod @@ -167,14 +167,27 @@ C<ssh://...> URI pointing to the VMX file. A typical URI looks like: ssh://root@esxi.example.com/vmfs/volumes/datastore1/my%20guest/my%20guest.vmx -Any space must be escaped with C<%20> and other non-ASCII characters -may also need to be URI-escaped. - The username is not required if it is the same as your local username. You may optionally supply a port number after the hostname if the SSH server is not listening on the default port (22). +For determining the pathname component of the URI, log in to the ESXi +server via SSH interactively, and identify the absolute pathname of the +VMX file on the ESXi server, such as: + + /vmfs/volumes/datastore1/my guest/my guest.vmx + +Subsequently, on the virt-v2v command line, L<percent-encode any +reserved +characters|https://en.wikipedia.org/wiki/Percent-encoding#Reserved_characters> +that you find in the individual pathname components. For example, space +characters must be specified as C<%20>: + + /vmfs/volumes/datastore1/my%20guest/my%20guest.vmx + +Refer to L<https://bugzilla.redhat.com/1938954>;. + =head2 VMX: Importing a guest To import a vmx file from a local file or NFS, do: -- 2.19.1.3.g30247aa5d201