From 1ae3c3fa35e9801b69be59205fa1bf00913c391c Mon Sep 17 00:00:00 2001
Message-Id: <1ae3c3fa35e9801b69be59205fa1bf00913c391c.1391001809.git.jdenemar@redhat.com>
From: Osier Yang <jyang@redhat.com>
Date: Mon, 27 Jan 2014 20:39:30 +0800
Subject: [PATCH] storage: Add document for possible problem on volume
 detection

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

For pool which relies on remote resources, such as a "iscsi" type
pool, since how long it takes to export the corresponding devices
to host's sysfs is really depended, it could depend on the network
connection, it also could depend on the host's udev procedures. So
it's likely that the volumes are not able to be detected during pool
starting process, polling the sysfs doesn't work, since we don't
know how much time is best for the polling, and even worse, the
volumes could still be not detected or partly not detected even after
the polling.  So we end up with a documentation to prompt the fact,
in virsh manual.

And as a small improvement, let's explicitly say no LUNs found in
the debug log in that case.
(cherry picked from commit 6b29eb848f741742a0f393df40bbcc176520bf27)

Signed-off-by: Jiri Denemark <jdenemar@redhat.com>
---
 src/storage/storage_backend_scsi.c | 5 +++++
 tools/virsh.pod                    | 9 +++++++++
 2 files changed, 14 insertions(+)

diff --git a/src/storage/storage_backend_scsi.c b/src/storage/storage_backend_scsi.c
index 64b7843..7437488 100644
--- a/src/storage/storage_backend_scsi.c
+++ b/src/storage/storage_backend_scsi.c
@@ -492,6 +492,7 @@ virStorageBackendSCSIFindLUs(virStoragePoolObjPtr pool,
     DIR *devicedir = NULL;
     struct dirent *lun_dirent = NULL;
     char devicepattern[64];
+    bool found = false;
 
     VIR_DEBUG("Discovering LUs on host %u", scanhost);
 
@@ -513,11 +514,15 @@ virStorageBackendSCSIFindLUs(virStoragePoolObjPtr pool,
             continue;
         }
 
+        found = true;
         VIR_DEBUG("Found LU '%s'", lun_dirent->d_name);
 
         processLU(pool, scanhost, bus, target, lun);
     }
 
+    if (!found)
+        VIR_DEBUG("No LU found for pool %s", pool->def->name);
+
     closedir(devicedir);
 
     return retval;
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 6b25e99..e866217 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -2606,6 +2606,15 @@ Refresh the list of volumes contained in I<pool>.
 
 Start the storage I<pool>, which is previously defined but inactive.
 
+B<Note>: A storage pool that relies on remote resources such as an
+"iscsi" or a (v)HBA backed "scsi" pool may need to be refreshed multiple
+times in order to have all the volumes detected (see B<pool-refresh>).
+This is because the corresponding volume devices may not be present in
+the host's filesystem during the initial pool startup or the current
+refresh attempt. The number of refresh retries is dependant upon the
+network connection and the time the host takes to export the
+corresponding devices.
+
 =item B<pool-undefine> I<pool-or-uuid>
 
 Undefine the configuration for an inactive I<pool>.
-- 
1.8.5.3