.. _extending_mptgs:


Extending the MPTGS
===================

MPTGS allows many actuators to be scheduled and controlled.  Adding new
actuators is possible, so long as it conforms to some conventions and
then the MPTGS is told about the new actuator.  This section details
how to do that.  The general process is:

#. :ref:`write_actuator`
#. :ref:`add_actuator_to_manager`
#. :ref:`add_actuator_to_orchestrator`

.. _write_actuator:

Write the Actuator
------------------

An actuator can be any non-interactive application (though such an
application may wrap an interactive one).  The MPTGS will invoke the
application at the right time and will use signals to instruct it about
its control flow, and the actuator must be prepared to handle those.

Generally, an actuator will act as a user using a particular program.
The Orchestator will be arranging the global statistics of the program
use, and with the Manager will pass information about the user the
actuator is emulating.  The Manager will also use a wrapper to bind the
actuator to a particular IP address, and to redirect stdout and stderr
to predicatble locations.

Actuator Arguments
^^^^^^^^^^^^^^^^^^

The new actuator can do whatever is required, but has to conform to the
following expectations.  First, it must accept a specific set of
positional arguments.  Every actuator is invoked as
``executable logBase userid password srcIP randomSeed``

Where the arguments to the executable mean:

logBase
    This is the string that should be the base of any log files created

userid
    The name/ID of the user this instance should emulate.  This may be
    used to look up additional characteristics of the user.

password
    The password for the user

srcIP
    The IP address this user should be coming from

randomSeed
    The seed this instance's random number generator should be reseeded
    with to aid with reproducability.

Actuator Signals
^^^^^^^^^^^^^^^^

In addition, for actuators that may run for a while (instead of doing a
single task and exiting) there are two signals that could be sent.  The
actuator should handle ``SIGUSR1`` and that means the manager wants the
activity to termporarily stop.  That is, this user should not be active
any more, but it may resume later.  When it receives ``SIGUSR2`` the
actuator is to resume activity.

Looking at actuators referenced in ``/usr/local/tg/etc/bot_map.conf``
can give examples of these arguments and signal handling.

.. _add_actuator_to_manager:

Add Actuator to Manager
-----------------------

Adding a new actuator to a Manager is straightforward.  First,
naturally, the executable has to be put on the filesystem, typically
this is put in ``/usr/local/tg/bin``.

The only other requirement is to edit ``/usr/local/tg/etc/bot_map.conf``
to add a line telling the Manager what name the Orchestrator will use
for this actuator, and where the executable lives.  ``bot_map.conf``
defines key value pairs with the left being the name for the actuator
and the right being the path to execute.  The name should not contain
white space or punctuation, and the only other rule is that it has to
match the value in the database (see below) and in the schedule file.

.. _add_actuator_to_orchestrator:

Add Actuator to Orchestrator
----------------------------

The scheduler and the iniator will both need to know about the new
actuator.  The scheduler has no expectation of a list of valid names,
so adding a suitable column/entry to the schedule file(s) will suffice
for this.  The name added should match the one added to the
``bot_map.conf`` above.

Whatever names the scheduler identifies will be passed to the initiator
to look up available users.  This is done by looking in the postgres
database referenced in ``/usr/local/tg/etc/db.info`` in the
``user_info_new`` table.  A column exists for each type of actuator,
and the values in those columns identify for each time of day whether
a user is available to do this type of activity.

The initiator recognizes different times of the day identified by:

* M: Morning (0800 to 1200)
* L: Lunchtime (1200 to 1300)
* A: Afternoon (1300 to 1700)
* E: Evening (1700 to 2400)
* Q: Early morning (before 0800)
* W: Weekend (any time on Sat or Sun)

For each of those times a value from 0 to 9 to indicate how likely the
user is to do this activity in this window.  If a time identifier is
not present it means the user does not do that activity at that time.

A value in this column of ``M9L9A9E9Q9W9`` will make the user likely to
be chosen in every window.

The ``user_info__new`` table has to be altered to include a column for
the new actuator, and the users have to be told to use it.  The
following commands will do this, making each user equally likely to be
chosen.

.. code-block:: sql

    ALTER TABLE user_info_new ADD COLUMN <actuator_name> varchar(15);
    UPDATE user_info_new SET <actuator_name> = 'M9L9A9E9Q9W9';