Updated documentation for the integration tests
authorTobias Brunner <tobias@strongswan.org>
Thu, 17 Jan 2013 15:04:45 +0000 (16:04 +0100)
committerTobias Brunner <tobias@strongswan.org>
Thu, 17 Jan 2013 15:56:02 +0000 (16:56 +0100)
testing/INSTALL [deleted file]
testing/README

diff --git a/testing/INSTALL b/testing/INSTALL
deleted file mode 100644 (file)
index bb4272e..0000000
+++ /dev/null
@@ -1,145 +0,0 @@
-
-                 -------------------------------
-                 strongSwan UML - Installation
-                 -------------------------------
-
-
-Contents
---------
-
-   1. Making the host system UML-capable
-   2. Installing the required files
-   3. Creating the UML testing environment
-
-
-1. Making the host system UML-capable
-   ----------------------------------
-
-   UML instances can be run on both Linux 2.4 and Linux 2.6 kernels.
-   If you are using a vanilla kernel from kernel.org then you must first
-   apply the host SKAS patch available from
-
-    http://www.user-mode-linux.org/~blaisorblade/patches/
-
-   and recompile and reboot your host kernel. Some Linux distributions as e.g.
-   SuSE already include the SKAS patch in their kernels.
-
-   You will also need the UML utilities (uml_mconsole and uml_switch)
-   available from
-
-   http://prdownloads.sourceforge.net/user-mode-linux/uml_utilities_20040406.tar.bz2
-
-   Many Linux distributions offer the UML utilities as a package.
-
-
-2. Installing the required files
-   -----------------------------
-
-First create a directory where you want the strongSwan UML testing environment
-to be located.The default directory is "~/strongswan-testing". If you choose a
-different location, please adapt the UMLTESTDIR variable in "testing.conf"
-accordingly.
-
-    mkdir ~/strongswan-testing
-
-Now copy the "testing" subdirectory coming with the strongSwan distribution to
-the UML testing environment:
-
-    cp -r testing ~/strongswan-testing
-   
-Next you need to copy several files into the ~/strongswan-testing directory that
-are required for the strongSwan testing environment:
-
-    * A vanilla Linux kernel on which the UML kernel will be based on.
-      We recommend the use of
-
-      http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.36.tar.bz2
-
-    * The Linux kernel 2.6.36 does not require any patches for the uml guest kernel
-      to successfully start up.
-
-    * The matching .config file required to compile the UML kernel:
-
-      http://download.strongswan.org/uml/.config-2.6.36
-
-    * A gentoo-based UML file system (compressed size 130 MBytes) found at
-
-      http://download.strongswan.org/uml/gentoo-fs-20100830.tar.bz2
-
-    * The latest strongSwan distribution
-
-      http://download.strongswan.org/strongswan-4.5.1.tar.bz2
-
-
-3. Creating the environment
-   ------------------------
-
-Now change into the testing subdirectory
-
-    cd ~/strongswan-testing/testing
-
-and make the UML testing environment:
-
-    ./make-testing <hosts>
-
-The "make-testing" script calls a series of subscripts which can be
-enabled or disabled individually by setting the corresponding flags
-in "testing.conf":
-
-    if [ $ENABLE_BUILD_UMLKERNEL = "yes" ]
-    then
-        scripts/build-umlkernel
-    fi
-
-builds an UML kernel out of the vanilla Linux kernel and the corresponding
-UML kernel patch.
-
-    if [ $ENABLE_BUILD_HOSTCONFIG = "yes" ]
-    then
-        scripts/build-hostconfig
-    fi
-
-generates the default configurations for the UML hosts alice, venus, moon,
-carol, winnetou, dave, sun, and bob by replacing the wildcards PH_IP_ALICE,
-etc. by the actual IP addresses defined in "testing.conf".
-
-    if [ $ENABLE_BUILD_UMLROOTFS = "yes" ]
-    then
-        scripts/build-umlrootfs
-    fi
-
-takes the gentoo-based UML file system and compiles the latest strongSwan
-distribution into it.
-
-    if [ $ENABLE_BUILD_SSHKEYS = "yes" ]
-    then
-        scripts/build-sshkeys
-    fi
-
-adds the common RSA public key of the UML instances to your ~/.ssh/known_hosts
-directory so that you can log onto the UML instances using ssh without typing
-in a password. The "scripts/build-sshkeys" script should only be run once.
-
-    if [ $ENABLE_BUILD_UMLHOSTFS = "yes" ]
-    then
-        scripts/build-umlhostfs <hosts>
-    fi
-
-creates the customized UML file systems for the instances given as command line 
-arguments by adding the default host configurations to the UML root file system.
-If the "make-starting" scripts is called without any arguments then by default
-the UML file systems are created for the hosts alice, venus, moon, carol,
-winnetou, dave, sun, and bob. Each UML root file system has as size defined by
-the ROOTFSSIZE in testing.conf which by default is 544 MBytes. Thus all 8 UML
-hosts plus the master copy will require a total of 5 GBytes of disk space.
-
-    if [ $ENABLE_START_TESTING = "yes" ]
-    then
-       ./start-testing <hosts>
-    fi
-
-starts the automated testing. More details on the tests you'll find in the
-README document.
-
------------------------------------------------------------------------------
-
index 097b426..a624972 100644 (file)
 
-                 ------------------------------------
-                 strongSwan UML - Running the Tests
-                 ------------------------------------
+                 ------------------------------
+                  strongSwan Integration Tests
+                 ------------------------------
 
 
 Contents
 --------
 
-   1. Starting up the UML testing environment
-   2. Running the automated tests
-   3. Manual testing
+   1. Building the testing environment
+   2. Starting up the testing environment
+   3. Running the automated tests
+   4. Manual testing
 
 
-1. Starting up the UML testing environment
-   ---------------------------------------
-  
-When the strongSwan UML testing environment has been put into place by
-running the "make-testing" script then you are ready to start up the
-UML instances by calling
+1. Building the testing environment
+   --------------------------------
 
-    ./start-testing <hosts>
-    
-This main script first calls the subscript
+The testing environment can be built with the "make-testing" script after
+adjusting the variables in the testing.conf file.  By default everything is
+built when executing the script.  Setting any of the ENABLE_BUILD_* variables
+in the configuration file to "no" will not build those parts.
 
-    scripts/start-switches
 
-that starts the three UML switches umlswitch0, umlswitch1, and umlswitch2
-which are connecting the UML instances among each other and via tun/tap
-devices also make them accessible from the host system.
-      
-Then depending on the setting of the UMLSTARTMODE variable defined
-in "testing.conf", the UML instances given on the command line are started
-up with different terminals:
+2. Starting up the testing environment
+   -----------------------------------
 
-If you are running the KDE graphical environment then by setting
+When the strongSwan testing environment has been put into place by running
+the "make-testing" script you are ready to start up the KVM instances by
+executing the "start-testing" script.
 
-    UMLSTARTMODE=konsole
-    
-the script
 
-    scripts/kstart-umls <hosts>
-     
-is called which starts up each of the UML instances defined by <hosts> in
-a KDE konsole. If
-
-    UMLSTARTMODE=xterm
-
-is set then
-    scripts/xstart-umls <hosts>
-    
-starts up the UML instances in an xterm each. And with the choice
-
-    UMLSTARTMODE=screen
-   
-the instances are started up by
-
-    scripts/start-umls <hosts>
-    
-in the background but the Linux command "screen -r <host>" can be used to
-connect a terminal to the UML instance <host> if desired.
-
-
-    if [ $ENABLE_DO_TESTS = "yes" ]
-    then
-        do-tests
-    fi
-
-either executes all the tests defined in the "testing/tests" directory
-if the variable SELECTEDTESTSONLY in "testing.conf" is set to "no" or the
-selected tests defined by the string in SELELECTEDTESTS if SELECTEDTESTSONLY
-is set to "yes".
-
-    if [ $ENABLE_STOP_TESTING = "yes" ]
-    then
-        stop-testing <hosts>
-    fi
-
-stops the both the UML switches and the UML instances designated by the
-<hosts> argument.
-
-
-2. Running the automated tests
+3. Running the automated tests
    ---------------------------
 
 The script
 
     ./do-tests <testnames>
 
-runs the automated tests. With an empty <testnames> argument the tests
-as defined in "testing.conf" are executed, otherwise the tests enumerated
-by the <testnames> argument will be run as shown in the example below.
+runs the automated tests.  If the <testnames> argument is omitted all tests
+are executed, otherwise only the tests listed will be run as shown in the
+example below:
 
-    ./do-tests net2net-psk net2net-cert
+    ./do-tests ikev2/net2net-psk ikev2/net2net-cert
 
 Each test is divided into the following phases:
 
-    * scripts/load-testconfig <testname>
-      loads the UML hosts with test specific settings if such are provided.
-      
-    * next the "pretest.dat" script found in each test directory is executed.
-      Among other commands, strongSwan is started on the IPsec hosts.
+    * Load the test-specific guest configuration if any is provided.
 
-    * the "evaltest.dat" script evaluates if the test has been successful.
-      
-    * the "posttest.dat" script terminates the test e.g. by stopping
-      strongSwan on the IPsec hosts.
+    * Next the "pretest.dat" script found in each test directory is executed.
+      Among other commands, strongSwan is started on the IPsec hosts.
 
-    * scripts/restore-defaults <testname>
-      restores the default settings on the UML hosts.
+    * The "evaltest.dat" script evaluates if the test has been successful.
 
-The test results and configuration settings for all tests settings are stored
-in a folder labeled with the current date in the directory
-  
-    ~/strongswan-testing/testresults
-     
-the same results are also automatically transferred to the Apache server
-running on UML instance "winnetou" and can be accessed via the URL
+    * The "posttest.dat" script terminates the test e.g. by stopping
+      strongSwan on the IPsec hosts.  It is also responsible to cleaning up
+      things (e.g. firewall rules) set up in "pretest.dat".
 
-    http://192.168.0.150/testresults/
+    * Restore the default configuration on every host (new files have to be
+      deleted manually in "posttest.dat").
 
+The test results and configuration files for all tests are stored in a
+folder labeled with the current date and time in the $TESTRESULTSDIR directory.
 
-3. Manual testing
-   --------------
-   
-The greates flexibility can be achieved with manual testing. Just set
-   
-    ENABLE_DO_TESTS="no"
-    ENABLE_STOP_TESTING="no"
-       
-in "testing.conf" and start the UML instances that you want to experiment with
-by calling
+The same results are also automatically transferred to the Apache server
+running on guest "winnetou" and can be accessed via the URL
 
-    ./start-testing <hosts>
-    
-If you want to preload a test scenario with configurations differing from
-the default values, e.g. when using Preshared Keys then you can do this
-with the command
+    http://192.168.0.150/testresults/
 
-    scripts/load-testconfig net2net-psk
-    
-You can then log onto any UML instance using its konsole, xterm or screen
-terminal as root with the default password
 
-    tuxmux
-    
-You can then execute any commands the UML instances, including changing
-and recompiling the strongSwan source code located in the /root directory.
+4. Manual testing
+   --------------
 
-After you have finished testing, the default configuration settings can
-restored with the command
+Instead of running tests automatically with "do-tests" it is possible to
+preload a test scenario with the script:
 
-    scripts/restore-defaults net2net-psk
+    scripts/load-testconfig <testname>
 
+Individual configuration files can be changed and any command can be executed by
+logging into a guest host directly (via SSH or a console window).  No password
+is required to login as root.  The sources for every software built during
+"make-testing" are mounted at /root/shared/, which allows you to change and
+recompile these components.
 
------------------------------------------------------------------------------
+After you have finished testing, the default configuration can be restored
+with the following command (newly created files have to be deleted manually)
 
+    scripts/restore-defaults