.. index:: options
.. _sec-options-label:

Setting options
===============

.. index:: override
.. index:: thinktime
.. index:: ssl_ciphers
.. index:: ssl_versions
.. index:: ssl_reuse_sessions
.. index:: tcp_snd_buffer
.. index:: tcp_rcv_buffer
.. index:: udp_snd_buffer
.. index:: udp_rcv_buffer
.. index:: max_ssh_startup

Thinktimes, SSL, Buffers
------------------------

Default values can be set-up globally: ``thinktime`` between requests
in the scenario, SSL cipher algorithms (use ssl:cipher_suites(openssl). to get a
list of available ciphers), TCP/UDP buffer sizes (the default value is 32KB).
These values overrides those set in session configuration tags if override is true.

.. code-block:: xml

 <option name="thinktime" value="3" random="false" override="true"/>
 <option name="ssl_ciphers"
         value="EXP1024-RC4-SHA,EDH-RSA-DES-CBC3-SHA"/>
 <option name="tcp_snd_buffer" value="16384"></option>
 <option name="tcp_rcv_buffer" value="16384"></option>
 <option name="udp_snd_buffer" value="16384"></option>
 <option name="udp_rcv_buffer" value="16384"></option>

.. versionadded:: 1.6.0

You can disable the SSL session cache (it is enabled by default)

.. code-block:: xml

 <option name="ssl_reuse_sessions" value="false"/>

You can specify which SSL protocol you want use. Use ssl:versions(). to get
a list of available ssl protocols.

.. code-block:: xml

 <option name="ssl_versions" value="'tlsv1.2'"/>

You can also use the command line option ``-L <value>`` to change the
session lifetime in the cache (10mn by default); value must be in seconds.

You can also change the way Tsung starts remote beams. By default,
Tsung will start at most 20 ssh process per core of the controller. If
you manage hundreds of clients, you may want to raise this value with
``max_ssh_startup_per_core`` (or decrease it if you wish)

.. code-block:: xml

 <option name="max_ssh_startup_per_core" value="100"/>


.. index:: idle_timeout
.. index:: global_ack_timeout

Timeout for TCP connections
---------------------------------------

.. versionadded:: 1.6.0

You can specify a timeout in milliseconds for establishing a TCP connection. The default is ``infinity``.

.. code-block:: xml

 <option name="connect_timeout" value="5000" />


You can also change the timeout on a per-session basis using ``set_option``.

.. code-block:: xml

 <set_option name="connect_timeout" value="1000" />

You can also enable the TCP REUSEADDR option globally:

.. code-block:: xml

   <option name="tcp_reuseaddr" value="true" />


IP transparent
---------------------------------------

.. versionadded:: 1.7.0

This option is used to set the IP_TRANSPARENT option on the TCP socket

.. code-block:: xml

 <option name="ip_transparent" value="true" />

This can be useful to use when IPs are not configured on the client host (see also :ref:`iprange-label`)

Retry Attempts and Timeouts
---------------------------------------

.. versionadded:: 1.6.0

You can specify the amount of retry attempts made by Tsung. The default is ``3``.

.. code-block:: xml

 <option name="max_retries" value="5" />

To disable retries entirely, set the value to ``0``.

In addition, the option ``retry_timeout`` (in milliseconds; defaults to ``10``) is used to implement a
simple back-off algorithm (``retry * retry_timeout``).

.. code-block:: xml

 <set_option name="retry_timeout" value="1000" />



Timeout for acknowledgments of messages
---------------------------------------

This is used to set the idle timeout(used for 'parse' and 'local' ack) and
global ack timeout(used for 'global' ack). By default, idle timeout will be
10min(600000) and global ack timeout will be ``infinity``. This value
can be changed like this:

.. code-block:: xml

 <option name="idle_timeout" value="300000"></option>
 <option name="global_ack_timeout" value="6000000"></option>


.. index:: hibernate

Hibernate
---------

.. versionadded:: 1.3.1

The option ``hibernate`` is used to reduced memory consumption of
simulated users during thinktimes. By default, hibernation will be
activated for thinktimes higher than 10sec. This value can be changed
like this:

.. code-block:: xml

  <option name="hibernate" value="5"></option>


To disable hibernation, you must set the value to ``infinity``.

.. index:: rate_limit

Rate_limit
----------

.. versionadded:: 1.4.0

``rate_limit``. This will limit the bandwidth of each client
(using a token bucket algorithm). The value is in KBytes per
second. You can also specify a maximum burst value
(eg. ``max='2048'``). By default the burst size is the same as
the rate (1024KB in the following example). Currently, only incoming
traffic is rate limited.

.. code-block:: xml

  <option name="rate_limit" value="1024"></option>


Ports_range
-----------

If you need to open more than 30000 simultaneous connections on a
client machine, you will be limited by the number of TCP client ports,
even if you use several IPs (this is true at least on Linux). To
bypass this limit, Tsung must not delegate the selection of client
ports and together with using several IP for each client,
you have to defined a range for available clients ports, for ex:

.. code-block:: xml

  <option name="ports_range" min="1025" max="65535"/>


.. index:: seed

Setting the seed for random numbers
------------------------------------

If you want to use a fixed seed for the random generator, you can use
the ``seed`` option, like this (by default, Tsung will use the
current time to set the seed, therefore random numbers should be
different for every test).

.. code-block:: xml

  <option name="seed" value="42"/>


Path for BOSH
------------------

You can use the following config option for setting the path to BOSH
request:

.. code-block:: xml

  <option name="bosh_path" value="/http-bind/"/>

.. _jabber-options-label:


Websocket options
------------------

When you use Websocket as a server type, you can set the following options
for Websocket:

.. code-block:: xml

  <option name="websocket_path" value="/chat"/>

  <!-- send websocket data with text frame, default binary-->
  <option name="websocket_frame" value="text"/>
  <option name="websocket_subprotocols" value="chat, superchat"/>

Use ``websocket_path`` for setting the path of the websocket request; use
``websocket_frame`` for setting the frame type(option type: binary and text,
and binary as default) of the sending websocket data. Use ``websocket_subprotocols`` for setting the ``Sec-WebSocket-Protocol`` header.


XMPP/Jabber options
-------------------


Default values for specific protocols can be defined. Here is an
example of option values for Jabber/XMPP:

.. code-block:: xml

  <option type="ts_jabber" name="global_number" value="5" />
  <option type="ts_jabber" name="userid_max" value="100" />
  <option type="ts_jabber" name="domain" value="jabber.org" />
  <option type="ts_jabber" name="username" value="myuser" />
  <option type="ts_jabber" name="passwd" value="mypasswd" />
  <option type="ts_jabber" name="muc_service" value="conference.localhost"/>


Using these values, users will be ``myuserXXX`` where *XXX* is an integer in
the interval *[1:userid_max]* and passwd ``mypasswdXXX``

If not set in the configuration file, the values will be set to:

* global_number = 100
* userid_max    = 10000
* domain   = erlang-projects.org
* username = tsunguser
* passwd   = sesame


Other options are available if you prefer to use a CSV file for
username/password, see :ref:`sec-read-user-jabber-csv-label`.


You can also set the ``muc_service`` here (see previous example).


HTTP options
------------

For HTTP, you can set the ``UserAgent`` values
(**available since Tsung 1.1.0**), using a probability for each
value (the sum of all probabilities must be equal to 100)

.. code-block:: xml

  <option type="ts_http" name="user_agent">
    <user_agent probability="80">
       Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.8) Gecko/20050513 Galeon/1.3.21
    </user_agent>
    <user_agent probability="20">
      Mozilla/5.0 (Windows; U; Windows NT 5.2; fr-FR; rv:1.7.8) Gecko/20050511 Firefox/1.0.4
    </user_agent>
  </option>

AMQP options
------------

You can set the AMQP heartbeat timeout; for example to set it to 30s
(default is 600s), add:

.. code-block:: xml

       <option type="ts_amqp" name="heartbeat" value="30" />
