From 232af2fab599831ca42f3c00ed71ae057ca1b063 Mon Sep 17 00:00:00 2001 From: Tobias Brunner Date: Thu, 17 Jan 2013 16:04:45 +0100 Subject: [PATCH] Updated documentation for the integration tests --- testing/INSTALL | 145 ----------------------------------------- testing/README | 170 ++++++++++++++---------------------------------- 2 files changed, 50 insertions(+), 265 deletions(-) delete mode 100644 testing/INSTALL diff --git a/testing/INSTALL b/testing/INSTALL deleted file mode 100644 index bb4272eaf..000000000 --- a/testing/INSTALL +++ /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 - -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 - 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 - fi - -starts the automated testing. More details on the tests you'll find in the -README document. - ------------------------------------------------------------------------------ - diff --git a/testing/README b/testing/README index 097b4264d..a62497269 100644 --- a/testing/README +++ b/testing/README @@ -1,158 +1,88 @@ - ------------------------------------ - 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 - -This main script first calls the subscript - - 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: - -If you are running the KDE graphical environment then by setting - - UMLSTARTMODE=konsole - -the script - - scripts/kstart-umls - -is called which starts up each of the UML instances defined by in -a KDE konsole. If - - UMLSTARTMODE=xterm - -is set then - - scripts/xstart-umls - -starts up the UML instances in an xterm each. And with the choice - - UMLSTARTMODE=screen - -the instances are started up by - - scripts/start-umls - -in the background but the Linux command "screen -r " can be used to -connect a terminal to the UML instance if desired. +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. - if [ $ENABLE_DO_TESTS = "yes" ] - then - do-tests - fi +2. Starting up the testing environment + ----------------------------------- -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 - fi - -stops the both the UML switches and the UML instances designated by the - argument. +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. -2. Running the automated tests +3. Running the automated tests --------------------------- The script ./do-tests -runs the automated tests. With an empty argument the tests -as defined in "testing.conf" are executed, otherwise the tests enumerated -by the argument will be run as shown in the example below. +runs the automated tests. If the 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 - loads the UML hosts with test specific settings if such are provided. - - * next the "pretest.dat" script found in each test directory is executed. + * Load the test-specific guest configuration if any is provided. + + * Next the "pretest.dat" script found in each test directory is executed. Among other commands, strongSwan is started on the IPsec hosts. - * 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. + * The "evaltest.dat" script evaluates if the test has been successful. - * scripts/restore-defaults - restores the default settings on the UML hosts. + * 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". -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 + * 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. + +The same results are also automatically transferred to the Apache server +running on guest "winnetou" and can be accessed via the URL http://192.168.0.150/testresults/ -3. Manual testing +4. 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 - ./start-testing - -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 +Instead of running tests automatically with "do-tests" it is possible to +preload a test scenario with the script: - 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 + scripts/load-testconfig - tuxmux - -You can then execute any commands the UML instances, including changing -and recompiling the strongSwan source code located in the /root directory. +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 settings can -restored with the command - - scripts/restore-defaults net2net-psk - - ------------------------------------------------------------------------------ +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