"DRBD Testsuite" is designed to test the actual DRBDv8 release and to simplify
the testing procedure with predefined configuration files. It is a powerful and
easy to use tool.

Agents are used to execute and verify the given commands on a node of the DRBD
cluster. The Testsuite runs on a seperated client (or one of the nodes) and
includes all configuration files and the commands, that should be executed.

For further information about configuration read agent.conf and testsuite.conf.
Take a look at INSTALL for installation steps. If you want to know more about
the code of the Testsuite, also read COMMUNICATION.

Version 1.0
       This document is correct for version 1.0 of the DRBD Testsuite.

Written by:     Dworschak, Roland       <roland.dworschak@fh-hagenberg.at>
                Hofmann, Florian        <florian.hofmann@fh-hagenberg.at>
                Huber, Sabine           <sabine.huber@fh-hagenberg.at>
                Leitner, Alexander      <alexander.leitner@fh-hagenberg.at>     
                Poettinger, Joachim     <joachim.poettinger@fh-hagenberg.at> 


======================
= MODES OF OPERATION =
======================

./agent.pl

-h    show help

-D    Don't daemonize
      Runs agent in foreground

-c <config>
      Specify a configuration file other than the default (./agent.conf)





./testsuite.pl

-h    show help

-c <config>
      Specify a configuration file other than the default configuration file

-i    ignore time difference on agents
      Testsuite will not try to syncronize the agents if they are out of sync,
      the testing procedure continues even if the maximum time difference is
      exceeded.

-v    verbose mode
      Show detailed information about the testing procedure.

-d    Debug mode
      Detailed output on console

-l <logfile>
      Writes all information to specified logfile.



=================================
= CONFIGURATION OF SEQ_COMMANDS =
=================================

All seq_commands, which should be executed, have to be configured in 
testsuite.conf. There are also some predefined commands, that can be found at 
the beginning of the testsuite.pl. It is also possible to execute common perl 
commands like while, if, for, ...


== execute remote command:

Synopsis:

      cmd '<command>'[, on <nodeName>][, timeout <secs>][, rc <microseconds>];
      cmd <argument>[, on <nodeName>][, timeout <secs>][, rc <microseconds>];


cmd '<command>'
        execute command.


cmd <argument>
        execute specified argument.


on <nodeName>
        send request to given node. If no node is given, both nodes will be
        contacted.


timeout <secs>
        time given for execution in seconds - if the time runs out,
        there'll be a message displayed on the testsuite


rc <microseconds>
        if rc is 0, execution will be immediately, otherwise the command will
        be executed in <microseonds> from now on. Use rc in ms range (> 1000)
        if you want commands to be executed simultaneously.

__
Return Value:
        Returns true or false as if the command was successfully executed or
        timed out.

__
Example:
        cmd 'drbdadm create-md r0', on node1, timeout 10, rc 15000

        tries to run 'drbdadm create-md r0' on node1 in 15 ms for no longer
        than 10 seconds.

-------------------------------------------------------------------------

== sleep/wait for <n> seconds:

Synopsis:

        sleep <secs>;


sleep <secs>
        testsuite sleeps for <secs> seconds.

__
Return Value
        Returns the number of seconds actually slept. 

__
Example:
        sleep 15;

        the next command will be processed in 15 seconds.

-------------------------------------------------------------------------

== Test expected state:

Synopsis:

        expected '<type>', state '<state>'[, on <nodeName>][, timeout <secs>][, rc <microseconds>];


expected
        Indicator for request


<type>
        Available types (defined in $commands{state_XX}):
                cs ... Connection state
                ds ... Local data storage
                st ... Peer state

state <state>
        Expected state on node:
              cs:  StandAlone            st: Unknown
                   Unconnected               Primary
                   Timeout                   Secondary
                   BrokenPipe                role_mask
                   NetworkFailure            DontBlameDrbd
                   WFConnection
                   WFReportParams
                   TearDown
                   Connected             ds: Diskless
                   SkippedSyncS              Failed
                   SkippedSyncT              Attaching
                   WFBitMapS                 Inconsistent
                   WFBitMapT                 Outdated
                   SyncSource                DUnknown
                   SyncTarget                Consistent
                   PausedSyncS               UpToDate
                   PausedSyncT

            
on <nodeName>
        send request to given node. If no node is given, both nodes will be
        contacted.


timeout <secs>
        within this time the type has to change to the expected one.

rc <microseconds>
        if rc is 0, execution will be immediately, otherwise the command will
        be executed in <microseonds> from now on. Use rc in ms range (> 1000)
        if you want commands to be executed simultaneously.


__
Return Value:
        Returns true or false as if the expected state was reached within the
        timeout or not.


__
Example:
        expected 'cs', state 'Connected', on node1, timeout 10;

        Check if connection state is Connected within 10 seconds on node1. 


-------------------------------------------------------------------------

== Get command

Synopsis:

        get '<command>',[, on <nodeName>][, timeout <secs>][, rc <microseconds>];
        get <argument>[, on <nodeName>][, timeout <secs>][, rc <microseconds>];


get <argument>
get '<command>'
        get specified information


on <nodeName>
        send request to given node. If no node is given, both nodes will be
        contacted.


timeout <secs>
        time given for execution in seconds - if the time runs out,
        there'll be a message displayed on the testsuite


rc <microseconds>
        if rc is 0, execution will be immediately, otherwise the command will
        be executed in <microseonds> from now on. Use rc in ms range (> 1000)
        if you want commands to be executed simultaneously.

__
Return Value:
        Returns false in case of timeout otherwise output of the command

__
Example:
        get 'cat /proc/drbd', on node1;
        
        shows according to the requested command the output of cat /proc/drbd
        of node 1.

