[Tools] testbot: Document how to use powered off snapshots.

[Francois Gouget]

RevertToSnapshot() will automatically boot up the VM if necessary. So
all that is needed to use a powered off snapshot is making sure it will
boot up to a usable state and making sure 3*$WaitForToolsInVM will give
enough time to the VM to boot.

Signed-off-by: Francois Gouget <fgouget at codeweavers.com>
---
 testbot/bin/LibvirtTool.pl               |  3 +++
 testbot/doc/INSTALL.txt                  | 15 +++++++++++----
 testbot/lib/WineTestBot/Config.pm        |  5 +++--
 testbot/lib/WineTestBot/LibvirtDomain.pm |  1 +
 4 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/testbot/bin/LibvirtTool.pl b/testbot/bin/LibvirtTool.pl
index 358eebf4..149e8503 100755
--- a/testbot/bin/LibvirtTool.pl
+++ b/testbot/bin/LibvirtTool.pl
@@ -243,6 +243,7 @@ sub Revert()
     LogMsg "Trying the revert anyway...\n";
   }
 
+  # Revert the VM (and power it on if necessary)
   Debug(Elapsed($Start), " Reverting $VMKey to ", $VM->IdleSnapshot, "\n");
   $ErrMessage = $Domain->RevertToSnapshot();
   if (defined $ErrMessage)
@@ -253,6 +254,8 @@ sub Revert()
   # The VM is now sleeping which may allow some tasks to run
   return 1 if (!ChangeStatus("reverting", "sleeping"));
 
+  # Check the TestAgent connection. Note that this may take some time
+  # if the VM needs to boot first.
   Debug(Elapsed($Start), " Trying the TestAgent connection\n");
   LogMsg "Waiting for ". $VM->Name ." (up to ${WaitForToolsInVM}s per attempt)\n";
   my $TA = $VM->GetAgent();
diff --git a/testbot/doc/INSTALL.txt b/testbot/doc/INSTALL.txt
index 07919a3c..0b956562 100644
--- a/testbot/doc/INSTALL.txt
+++ b/testbot/doc/INSTALL.txt
@@ -141,8 +141,11 @@ Dependencies:
   Where PORT is the $AgentPort that was configured in ConfigLocal.pl
   on the WineTestBot server, and SRCHOST is either omitted or the hostname
   of the WineTestBot server.
-- Take a snapshot of the running VM. Make sure restoring this snapshot
-  will result in a running build VM.
+- Take a snapshot of the VM. The shorter the revert time the better. This
+  usually implies taking a snapshot of the running VM as set up in the previous
+  step. However it is also possible to use snapshots of the powered off VM. In
+  that case make sure booting the VM will automatically start the TestAgent
+  server in the right configuration.
 - Register this VM as a build VM on the web site.
 
 
@@ -156,8 +159,12 @@ Dependencies:
   Where PORT is the $AgentPort that was configured in ConfigLocal.pl
   on the WineTestBot server, and SRCHOST is either omitted or the hostname
   of the WineTestBot server.
-- Take a snapshot of the running VM. Make sure restoring this snapshot
-  will result in a running Windows VM.
+- Take a snapshot of the VM. The shorter the revert time the better. This
+  usually implies taking a snapshot of the running VM as set up in the previous
+  step. However it is also possible to use snapshots of the powered off VM. In
+  that case make sure booting the VM will automatically log in and start the
+  TestAgent server in the right configuration and with the appropriate
+  privileges.
 - Register this VM on the web site. On a production WineTestBot server
   you would likely want to make it an 'extra' VM until you have
   confirmed that it works as expected.
diff --git a/testbot/lib/WineTestBot/Config.pm b/testbot/lib/WineTestBot/Config.pm
index c5586c73..4f38633b 100644
--- a/testbot/lib/WineTestBot/Config.pm
+++ b/testbot/lib/WineTestBot/Config.pm
@@ -71,8 +71,9 @@ $MaxRevertsWhileRunningVMs = 1;
 $MaxActiveVMs = 2;
 $MaxVMsWhenIdle = undef;
 
-# How long to wait when connecting to the VM's TestAgent server after a revert
-# (in seconds).
+# How long to wait for each of the 3 connection attempts to the VM's TestAgent
+# server after a revert (in seconds). If there are powered off snapshots this
+# must be long enough for the VM to boot up first.
 $WaitForToolsInVM = 30;
 # How long to let the VM settle down after the revert before starting a task on
 # it (in seconds).
diff --git a/testbot/lib/WineTestBot/LibvirtDomain.pm b/testbot/lib/WineTestBot/LibvirtDomain.pm
index d449f9d0..5fbff186 100644
--- a/testbot/lib/WineTestBot/LibvirtDomain.pm
+++ b/testbot/lib/WineTestBot/LibvirtDomain.pm
@@ -210,6 +210,7 @@ sub RevertToSnapshot($)
   my ($ErrMessage, $Domain, $Snapshot) = $self->_GetSnapshot($SnapshotName);
   return $ErrMessage if (defined $ErrMessage);
 
+  # Note that if the snapshot was of a powered off domain, this boots it up
   eval { $Snapshot->revert_to(Sys::Virt::DomainSnapshot::REVERT_RUNNING) };
   return $@ ? $self->_Reset(_eval_err()) : $self->_UpdateStatus($Domain);
 }
-- 
2.14.2