1. About

This tool allows load testing of an OBM installation, it uses Gatling to perform requests against most of OBM components. The OBM Core-Team uses it to check that the product does not lose performance and robustness between releases but it is also useful to verify that the capacity of an installation is enough to support a "chosen" load.

2. Installing on Debian

System Requirements

The only requirement is a Java 7 JRE, note that the openjdk-7 is officially packaged for Wheezy or greater Debian versions.

You want to install it on Squeeze

Please add our openjdk-7 backport repository to your apt sources.list file

deb http://deb.obm.org/squeeze-backports squeeze main
Installation

Modify your /etc/apt/sources.list file to add the repository:

deb http://deb.obm.org/obm-load-testing/stable obm obm

Add the OBM GPG public key:

$ wget -q  http://deb.obm.org/obmgpg.pub -O - | apt-key  add -

Update your package manager tool and install obm-loadtest

$ aptitude update
$ aptitude install obm-loadtest

3. Installing on RHEL/CentOS

Add the tool repository by creating the file /etc/yum.repos.d/opush.repo

[obm-load-testing]
name=obm-load-testing
baseurl=http://packages.obm.org/rpm/obm-load-testing/stable/$releasever
enabled=1
gpgcheck=0

Then install it with yum and you are done!

$ yum install obm-loadtest

4. Getting Started

The following section guides you step-by-step to know how you can use it with an OBM installation:

  1. Have a working OBM

  2. Have a configured domain

  3. Ensure that your installation is healthy

  4. Create test users in your domain
    This step is required because the tool runs simulations using real users. You can of course drop them as soon as you are done with those tests. The tool needs to have a bunch of available users, to avoid to create it one-by-one import them from a CSV file through "OBM-UI > Users > Import > Browse". You can see on this page what fields are expected in the file, its format looks like:

Monsieur;u1;u1;u1;user;;;u1;1234;PLAIN;X;1;u1;300;;;;;Chef;+33 0 11 22 33 44;;06 06 06 06 06;05 05 05 05 05;;OBM corp;IT;SI;Avenue des Champs-Élysées;;;75000;Paris;cedex 5;description;X;\home\mydir;E;mylogon.bat;1
Monsieur;u2;u2;u2;user;;;u2;1234;PLAIN;X;1;u2;300;;;;;Chef;+33 0 11 22 33 44;;06 06 06 06 06;05 05 05 05 05;;OBM corp;IT;SI;Avenue des Champs-Élysées;;;75000;Paris;cedex 5;description;X;\home\mydir;E;mylogon.bat;2

  1. Apply users creations using the "Yellow Pill"

  2. Launch a run

obm-loadtest --csv /tmp/users.csv --base-url https://MY_OBM/ --user-domain myobm.org

  1. When the run is done it creates a folder ./results/obm-loadtest_DATE-TIME on your working directory. It contains a browsable html page where informations of the run are given as statistics and graphs. Please read the official documentation to have more informations about reports understanding.

5. Usage

Try to execute obm-loadtest without any argument to see its usage.

Usage: obm-loadtest [options]

  --init-max-attempts <value> (default value: 5)
        Maximum number of attempt per request to initialize a user
  --init-parallelism <value> (default value: 2)
        Number of users initialized in parallel
  --csv <value>
        User feeder CSV file with header respecting the format: username,password
  --base-url <value>
        OBM http server
  --user-domain <value>
        User domain
  --scenario <value> (default value: default)
        The scenarios to run, possible values: smtp, opush-calendar, imap,
        opush-send-email, opush-meeting-creation, opush-folder-sync, obm-ui,
        opush-default, opush-meeting-invitation, default, obm-sync,
        opush-meeting-modification, opush-contact, opush-meeting-cancelation,
        opush-calendar-sync
  --users-per-sec <value> (default value: 1)
        Amount of users per seconds running the scenario, it can be a decimal as 0.3
  --duration <value> (default value: 1)
        How long will take the run, see duration-unit
  --duration-unit <value> (default value: seconds)
        Run duration unit, possible values: nanoseconds, microseconds,
        milliseconds, seconds, minutes, hours, days
  --lemon-sso
        Use LemonLDAP SSO

5.1. Required Arguments

--csv

Is a path to a comma separated value file which contains definition of users that can be used in obm-loadtest simulations. Its format is strict, the first line must be username,password followed by users rows.

username,password
user1,1234
user2,1234
user3,1234
user4,1234
user5,1234

If too few users are given in this file, the tool will sometimes have two distinct simulations running with the same user. In this situation the responses of Opush are not always exactly what is expected by our tool making a false negative.
We suggest to have 100 users and even more for heavy runs. Mind that those users must really exist in your OBM.

--csv /tmp/users.csv
--user-domain

You noted that the csv file does not embed users domain, specify it with this option.

--user-domain myobm.org
--base-url

The frontend address of your OBM installation, you must specify here the protocol to use (http or https).

--base-url https://apache.myobm.org

5.2. Optional Arguments

--init-max-attempts

The initialization of users is performed at the beginning of the run to prepare the OBM server as this tool. As this preparation step performs requests which can fail, this parameter allows to change the max attempts per request.

--init-parallelism

How many users are initialized concurrently, bigger is faster as long as the OBM server is able to reply.

--scenario

Depending on the scenario to run the tool will exercise different OBM components. By default it run against obm-ui, obm-sync, opush, the smtp and the imap servers.

--scenario obm-ui
--users-per-sec

Understand it as "how much you will load your OBM". In fact this option specifies the count of new-simulation-per-second the tool will introduce in the run. A decimal value is expected here as "0.3".

Mind that obm-loadtest will not care about the status of the target server. As the OBM server become slow, it will take longer to reply to requests so running simulations will also be longer to finish. The tool will constantly continue to introduce new simulation in the run, so the number of concurrent requests will grow.

--duration --duration-unit

How long the run will be, for a two hours long run use:

--duration 2 --duration-unit hours
--lemon-sso

You need to provide this option when your OBM is protected by LemonLDAP.