r18414: This README file should help to explain what is needed to setup a Windows VM for testing using this framework.

Let me know if there's anything that looks strange or could use clarification.

vm_setup.tar.gz is currently located at the root of my SVN branch, svn://svnanon.samba.org/samba/branches/SOC/bnh.
(This used to be commit 849fe757bb908842844ab482b8669694157550cd)

source4/script/tests/win/README

@@ -0,0 +1,121 @@
+This framework uses a VMware Server hosted Windows guest VM to test the
+behaviour of Windows -> Samba and Samba -> Windows interactions. To setup a
+Windows host for testing, vm_setup.tar.gz contain some scripts which create
+an administrative user account, and enable and start the installed telnet
+service on the Windows host. Optionally, the hostname and workgroup name can
+also be set. vm_setup.tar.gz is currently located in the SOC/bnh branch of
+Samba's SVN repository.
+
+PREREQUISITES
+
+To use these scripts, VMware Server needs to be running with a Windows guest
+VM installed, IP addressed, and VMware tools needs to be installed and running
+on the guest VM. The Windows OS I used to test with was Windows Server 2003,
+but I think this should work with any version of Windows that has the
+Microsoft telnet service installed. The VMware Server versions I used for
+testing was 1.0.0 build-27828, and 1.0.0 build-28343.
+
+PLEASE NOTE: Due to problems with my original revert_snapshot() code, the initial
+setup now requires that the VM configuration setting 'When Powering Off' is
+manually set to 'Revert to snapshot' (snapshot.action="autoRevert" in the
+guest's .vmx file).  This should not be a permanent change, but the original
+revert_snapshot() code I wrote no longer works and i'm not sure why.
+
+On the machine that these scripts are running on (this need not be the same
+machine as the VMware host), the VMware perl scripting api needs to be
+installed, as well as the vix-perl api. These come with the VMware Server
+console package.
+
+After unzipping this file, the libraries are installed by extracting the
+VMware-vix-e.x.p-<revision number>.tar.gz and
+VMware-VmPerlAPI-e.x.p-<revision number>.tar.gz archives, and running the
+vmware-install.pl scripts inside their respective directories.
+
+On Slackware 10.2, I encountered a problem in that when I tried to use the vix
+api libraries, I would get the following error:
+
+SSLLoadSharedLibrary: Failed to load library /<client program directory>/libcrypto.so.0.9.7:/<client program directory>/libcrypto.so.0.9.7: cannot open a shared object file: No such file or directory.
+
+The fix found on the VMware knowledge base (search http://kb.vmware.com for
+Doc ID: 1837104) states that it's a known problem with the scripting libraries,
+and can be resolved by installing VMware Server on the host, which properly
+sets up the SSL module loader. This is what I would suggest if you encounter
+this, as it solved the problem for me (I don't have VMware Server actually
+running on that host though).
+
+INSTALLATION
+
+To use these scripts, modify initial_setup.conf to match your environment. The
+GUEST_HOSTNAME, GUEST_WORKGROUP, HOST_SERVER_NAME, HOST_SERVER_PORT,
+HOST_USERNAME, and HOST_PASSWORD variables are optional, and are commented out
+in this release.
+
+Running initial_setup.sh will:
+*  Get the IP address of the Windows guest VM.
+*  Take a snapshot of the pristine Windows guest.
+*  Copy the windows scripts from the windows-scripts directory on the unix host
+        to the directory on the Windows guest specified by the
+        GUEST_SCRIPT_PATH option. This path will be created on the guest if
+        it does not already exist.
+*  Execute win_setup.wsf on the Windows guest in order to create the
+        administrator account specified by GUEST_USERNAME and GUEST_PASSWORD,
+        enable and start the telnet service, and set the GUEST_HOSTNAME and
+        GUEST_WORKGROUP if configured.
+*  If these operations are successful so far, another snapshot is taken at this
+	point. This is the snapshot which is restored if the tests encounter
+	problems they are unable to recover from.
+
+These operations leave the Windows guest in a state such that it can be
+remotely administered with telnet. Specifically, this will allow us to use
+'make wintest' in Samba 4 to perform smbtorture tests against a Windows host,
+and perform tests from a Windows client to a Samba server.
+
+INTEGRATING WITH THE BUILD FARM
+
+Follow the standard steps to add a host to the build farm. The major
+difference is that we will need to run these tests as root. To run the
+Windows tests in the build farm, a .fns file will need to be created for
+your new host that exports a WINTESTCONF environment variable pointing to a
+config file used by 'make wintest'. An example of this config file can be
+found at source/script/tests/win/test_win.conf in the Samba 4 source tree. 
+
+I've also included the bnhtest.fns file that I'm using for my build farm host
+below, as an example. It was modified from generic.fns.
+
+action_test_windows() {
+        do_make wintest
+        w_status=$?
+        echo "WINTEST STATUS: $w_status"
+        return $w_status;
+}
+
+per_run_hook
+
+system=`uname`
+
+export WINTESTCONF="/home/build/win/test_win.conf"
+
+for compiler in gcc cc icc; do
+
+  # arrgh, "which" gives no err code on solaris
+  path=`which $compiler`
+  if [ -x "$path" ]; then
+
+    if $compiler -v 2>&1 | grep gcc.version > /dev/null; then
+       isgcc=1
+       CFLAGS="-Wall"
+       export CFLAGS
+    else
+       CFLAGS=""
+       export CFLAGS
+       isgcc=0
+    fi
+    if [ $compiler = gcc -o $isgcc = 0 ]; then
+
+      # only attempt samba4 if we have perl
+      if which perl > /dev/null; then
+        test_tree samba4 source $compiler configure build install test_windows test
+      fi
+    fi
+  fi
+done