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

[Richard W.M. Jones]

On Wed, May 18, 2022 at 08:49:30AM +0200, Laszlo Ersek wrote:
> 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

Acked-by: Richard W.M. Jones <rjones at redhat.com>

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v