Libguestfs - Sep 2022 - [p2v PATCH 15/15] virt-p2v.pod: explain how to bring iSCSI LUNs to the disk selection dialog

Setting up an iSCSI initiator is not without traps, so explain the basics
in a few paragraphs in the manual.

Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=2124538
Signed-off-by: Laszlo Ersek <lersek at redhat.com>
---
 virt-p2v.pod | 102 +++++++++++++++++++-
 1 file changed, 100 insertions(+), 2 deletions(-)

diff --git a/virt-p2v.pod b/virt-p2v.pod
index 6c9033ca250d..2260c6b44d84 100644
--- a/virt-p2v.pod
+++ b/virt-p2v.pod
@@ -225,8 +225,9 @@ drives.  (Note that the button will also reset the currently
active
 selections in both of those panels.)  This button is useful in
 combination with the C<XTerm> button on the L</SSH CONFIGURATION
 DIALOG>: in the XTerm window, you can expose further block devices to
-the kernel (such as LUNs from iSCSI targets), and the C<Refresh disks>
-button allows virt-p2v to learn about all the block devices again.
+the kernel (such as L<LUNs from iSCSI targets|/ACCESSING ISCSI
+DEVICES>), and the C<Refresh disks> button allows virt-p2v to learn
+about all the block devices again.
 
                                             ?
      Network interfaces                     ?
@@ -448,6 +449,103 @@ L<virt-p2v-make-disk(1)/ADDING AN SSH IDENTITY>
 
 L<virt-p2v-make-kickstart(1)/ADDING AN SSH IDENTITY>
 
+=head1 ACCESSING ISCSI DEVICES
+
+In case the disk that contains the operating system, or other disks that
+you want to convert, are LUNs of remote iSCSI targets, follow the steps
+below so that virt-p2v can learn about said disks.  Note that this
+procedure depends on the use of the GUI.
+
+The guide below is roughly based on the L<RHEL9 product
+documentation|https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/managing_storage_devices/configuring-an-iscsi-initiator_managing-storage-devices>.
+
+=over 4
+
+=item 1.
+
+Open a shell in an XTerm window, using the C<XTerm> button of the
L</SSH
+CONFIGURATION DIALOG>.
+
+(Note that the XTerm window(s) persist while you advance to further
+dialogs in virt-p2v, therefore it's unnecessary to jump back and forth
+between virt-p2v dialogs just for entering additional shell commands in
+the XTerm window(s).)
+
+=item 2.
+
+Using C<vi> or another text editor, set the iSCSI initiator name in
+F</etc/iscsi/initiatorname.iscsi>, for example:
+
+ InitiatorName=iqn.1994-05.com.redhat:846e82c634
+
+If the file does not exist, create it.  (Remember that this file is part
+of the virt-p2v Live environment, therefore saving it does not modify
+any hard disks.)
+
+=item 3.
+
+Configure any further iSCSI initiator details I<completely> that are
+required by the iSCSI target that you intend to log in to; that is,
+before you issue the first C<iscsiadm> command below.  This includes the
+CHAP user name and password if the target authenticates the initiator
+with CHAP, and the reverse direction CHAP user name and password too, if
+you want to ascertain the identity of the target on the initiator as
+well (this is called "mutual authentication").
+
+Completing the configuration at this stage is important because the
+first C<iscsiadm> command will start up the C<iscsid> service, and
+configuration changes with that service already running will not (or may
+not) take effect until/unless you restart the service using
+C<systemctl>.
+
+=item 4.
+
+Discover the iSCSI targets offered by the desired host:
+
+ iscsiadm -m discovery -t st -p IP_ADDRESS
+
+The command should respond with a two-column list of targets.  The
+symbolic target names are in the right hand side column, for example:
+
+     10.64.24.179:3260,1 iqn.2006-04.example:444
+
+=item 5.
+
+Picking an appropriate target from the right hand side column of the
+previous step's output, log in to the target:
+
+ iscsiadm -m node -T TARGET -l
+
+This command will inform you whether the login attempt was successful.
+
+=item 6.
+
+In case the login succeeds, a scan for LUNs on the iSCSI target will
+commence at once.  There are two pitfalls here.  One, dependent on
+network characteristics, the scan may take several (tens of) seconds.
+Two, even if the login succeeds, ACLs on the target may I<silently>
+prevent the initiator from seeing particular LUNs -- meaning that no new
+F</dev/sdX> nodes will appear.  This is why it is important to get the
+initiator name (and, potentially, CHAP authentication) correct at the
+very beginning of this procedure.
+
+Verify the results of the target scan with the C<dmesg> command, and/or
+with
+
+ ls -l /dev/disk/by-path/ip-*-iscsi-*-lun-*
+
+If these symlinks exist, containing the C<IP_ADDRESS> from step 4 and
+the C<TARGET> name from step 5 in their filenames, then the target scan
+has successfully found the corresponding LUNs.
+
+=item 7.
+
+Once the remote LUNs have been successfully enumerated, click the
+C<Refresh disks> button in the L</DISK AND NETWORK CONFIGURATION
+DIALOG>.
+
+=back
+
 =head1 COMMON PROBLEMS
 
 =head2 Timeouts

ACK series, but see my comment about patch 14.

A couple of other general points:

(1) You could copy the vector type from nbdkit if that would help with
handling lists of strings.

(2) Should we drop Gtk2 support?  I kept this around to allow virt-p2v
to be compiled on RHEL <= 6.  RHEL 5 in particular needs Gtk 2.10,
which even for Gtk 2 is an old version.  Those RHEL releases had
support for some old hardware, especially some old HP Smart Array
devices, which was dropped in newer RHEL, making it impossible to
convert physical machines using those devices.

However the move to PCRE2 means that we can no longer compile on RHEL 6
(RHEL 7 is still OK).  Gtk2 itself went out of support in 2021 [0],
although that is not very relevant.

If we had a customer who wanted support for the old devices, perhaps
it is better to look for a modern distro that still supports them and
would have Gtk 3, PCRE 2, etc.  Perhaps Fedora or Debian.

Rich.

[0] https://blog.gtk.org/2020/12/16/gtk-4-0/

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-builder quickly builds VMs from scratch
http://libguestfs.org/virt-builder.1.html