6.4. 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:

  1. Write the Actuator

  2. Add Actuator to Manager

  3. Add Actuator to Orchestrator

6.4.1. 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.

6.4.1.1. 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.

6.4.1.2. 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.

6.4.2. 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.

6.4.3. 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.

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