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

[Laszlo Ersek]

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 at redhat.com>
---
 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