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

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

Determining the ssh:// URI (for -i vmx -it ssh) is not intuitive if the
guest name includes characters outside of the portable filename
character set. Expand the "VMX: Construct the SSH URI" section of the
documentation.

Thanks,
Laszlo

Laszlo Ersek (2):
  docs/*.pod: strip trailing space characters
  -i vmx -it ssh: document percent encoding in ssh URIs in more detail

 docs/virt-v2v-hacking.pod      |  2 +-
 docs/virt-v2v-input-vmware.pod | 29 ++++++++++++++------
 docs/virt-v2v.pod              | 24 ++++++++--------
 3 files changed, 34 insertions(+), 21 deletions(-)


base-commit: e06cf5b5dcbfd3f0a798eaf75c8778502c9e3bc6
-- 
2.19.1.3.g30247aa5d201

Remove any space characters that directly precede a newline character.

Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1938954
Signed-off-by: Laszlo Ersek <lersek at redhat.com>
---

Notes:
    I've verified in the rendered HTMLs that this whitespace stripping does
    not break up indented blocks into smaller blocks -- the formatter keeps
    runs of indented lines coalesced into indented blocks.

 docs/virt-v2v-hacking.pod      |  2 +-
 docs/virt-v2v-input-vmware.pod | 10 ++++----
 docs/virt-v2v.pod              | 24 ++++++++++----------
 3 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/virt-v2v-hacking.pod b/docs/virt-v2v-hacking.pod
index 29b73fb6c3f8..da5e640d9c92 100644
--- a/docs/virt-v2v-hacking.pod
+++ b/docs/virt-v2v-hacking.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-virt-v2v-hacking - 
+virt-v2v-hacking -
 
 =head1 DESCRIPTION
 
diff --git a/docs/virt-v2v-input-vmware.pod b/docs/virt-v2v-input-vmware.pod
index ab2d28e41ff2..4f4af2a9d804 100644
--- a/docs/virt-v2v-input-vmware.pod
+++ b/docs/virt-v2v-input-vmware.pod
@@ -278,7 +278,7 @@ to list the guests on the server:
 
  $ virsh -c 'vpx://root at vcenter.example.com/Datacenter/esxi' list
--all
  Enter root's password for vcenter.example.com: ***
- 
+
   Id    Name                           State
  ----------------------------------------------------
   -     Fedora 20                      shut off
@@ -506,7 +506,7 @@ like this:
 
  $ virsh -c 'vpx://root at vcenter.example.com/Datacenter/esxi' list
--all
  Enter root's password for vcenter.example.com: ***
- 
+
   Id    Name                           State
  ----------------------------------------------------
   -     Fedora 20                      shut off
@@ -575,17 +575,17 @@ Enable (check) the following objects:
  Datastore:
   - Browse datastore
   - Low level file operations
- 
+
  Sessions:
   - Validate session
- 
+
  Virtual Machine:
    Interaction:
      - Guest operating system management by VIX API
    Provisioning:
      - Allow disk access
      - Allow read-only disk access
- 
+
  Cryptographic operations:
   - Decrypt
   - Direct Access
diff --git a/docs/virt-v2v.pod b/docs/virt-v2v.pod
index d627734b0dc3..8849aae86394 100644
--- a/docs/virt-v2v.pod
+++ b/docs/virt-v2v.pod
@@ -830,23 +830,23 @@ installed.  For some older Linux distributions, this means
installing
 a kernel from the table below:
 
  RHEL 3         (Does not apply, as there was no Xen PV kernel)
- 
+
  RHEL 4         i686 with > 10GB of RAM: install 'kernel-hugemem'
                 i686 SMP: install 'kernel-smp'
                 other i686: install 'kernel'
                 x86-64 SMP with > 8 CPUs: install 'kernel-largesmp'
                 x86-64 SMP: install 'kernel-smp'
                 other x86-64: install 'kernel'
- 
+
  RHEL 5         i686: install 'kernel-PAE'
                 x86-64: install 'kernel'
- 
+
  SLES 10        i586 with > 10GB of RAM: install 'kernel-bigsmp'
                 i586 SMP: install 'kernel-smp'
                 other i586: install 'kernel-default'
                 x86-64 SMP: install 'kernel-smp'
                 other x86-64: install 'kernel-default'
- 
+
  SLES 11+       i586: install 'kernel-pae'
                 x86-64: install 'kernel-default'
 
@@ -868,27 +868,27 @@ packages are installed I<before> conversion, by
consulting the table
 below.
 
  RHEL 3         No virtio drivers are available
- 
+
  RHEL 4         kernel >= 2.5.9-89.EL
                 lvm2 >= 2.02.42-5.el4
                 device-mapper >= 1.02.28-2.el4
                 selinux-policy-targeted >= 1.17.30-2.152.el4
                 policycoreutils >= 1.18.1-4.13
- 
+
  RHEL 5         kernel >= 2.6.18-128.el5
                 lvm2 >= 2.02.40-6.el5
                 selinux-policy-targeted >= 2.4.6-203.el5
- 
+
  RHEL 6+        All versions support virtio
- 
+
  Fedora         All versions support virtio
- 
+
  SLES 11+       All versions support virtio
- 
+
  SLES 10        kernel >= 2.6.16.60-0.85.1
- 
+
  OpenSUSE 11+   All versions support virtio
- 
+
  OpenSUSE 10    kernel >= 2.6.25.5-1.1
 
  Debian 6+      All versions support virtio
-- 
2.19.1.3.g30247aa5d201

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 at
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