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

[Laszlo Ersek]

On 05/18/22 12:05, Richard W.M. Jones wrote:
> 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.
> 

Commit f8c564333057 ("-i vmx -it ssh: document percent encoding in ssh
URIs in more detail", 2022-05-19).

Thanks!
Laszlo