Laszlo Ersek
2022-May-18 06:49 UTC
[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 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
Richard W.M. Jones
2022-May-18 10:05 UTC
[Libguestfs] [v2v PATCH 2/2] -i vmx -it ssh: document percent encoding in ssh URIs in more detail
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 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 guestAcked-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