.. _toastd-plugin:

The |toasts| consists of |scmaster| and its plugin |toastd| (|toastdaemon|).
|scmaster| is the central process in any |scname| installation.
It provides messaging and database write access.

The |toastd| plugin extends |scmaster| by the ability to execute |toast| specific
tasks like the automatic triggering of incidents and simulations.
It includes the |toast| data model which is necessary to store |toast| objects in
the database.

It acts as a processor for all messages sent to its queues.
The main purpose is to respond to journal entries sent from clients in order to
queue and serialize concurrent operations from multiple clients.

The |toastd| plugin can furthermore connect to a |scname| processing queue and
create and update |toast| incidents based on configured rules automatically
whenever a new |scname| event is created or updated.

The plugin configuration also holds the configuration of the templates
(bulletins), the automatic simulation profiles, the trigger criteria and others.
The configuration of |scmaster| and also its plugins is done in the file
*scmaster.cfg* (look for *toastd* in the queues).


Queue Configuration
===================

The |toastd| plugin must be loaded into |scmaster| in order to be able to use it
as message processor. This can be either done globally or per queue in
:file:`scmaster.cfg`. It is assumed that the processing queue is called *toast*
in the following examples.

.. code::

   plugins = ${plugins}, toastd

or

.. code::

   queues.toast.plugins = toastd

Furthermore the processor has to be added to the message processors of the
queue. Loading the plugin above only makes the processor known to |scmaster| but
it does not use it. This has to be done explicitly:

.. code::

   queues.toast.processors.messages = dbstore, toastd

It is recommended to append the |toastd| processor after the *dbstore* processor.
This will ensure that objects are persistently stored in the database when
|toastd| receives them.


Processor Configuration
=======================

The |toastdaemon| needs some additional information in order to work correctly.
There are three categories:

* Database
* |scname| connection for automatic incident synchronization
* |gss| connection

By default the |toast| database connection string is received via the messaging connection.
|scname| supports two kinds of connections:

* Direct connection to the database backend
* Proxy connection tunneled through the messaging connection

The latter one has the advantage that the |toastc| needs no extra connection
to the database backend.

.. code::

   queues.toast.processors.messages.toastd.database = mysql://sysop:sysop@localhost/toast

The |scname| connection is configured with the source variable:

.. code::

   queues.toast.processors.messages.toastd.source = scmp://host/production

With this setting, the |toastd| will connect to the production queue of host and
import |scname| events into the *toast* database as |toast| incidents according
to its configuration.

In order to run simulations, the |gss| (|gssfull|) has to be configured.
The configured URL is used from within |toastd| as well from the |toastc| which
connects to this queue.
So make sure to give it a fully qualified domain name or an IP:

.. code::

   queues.toast.processors.messages.toastd.gss.url = gsss://host:19011


Template Configuration
======================

|toast| uses templates to generate bulletins for dissemination.
As templates may be subject to modifications per incident, they are stored in
the database per incident together with a set of freely configurable template 
variables which are evaluated to create the bulletins.

.. note::

   The syntax used in the following example is a valid alternative to the
   standard |scname| syntax.
   When modifying and saving using scconfig standard syntax is employed.

.. code::

   queues.toast.processors.messages.toastd.bulletins {
       variables = A, B
       variable.A {
           name = "A"
           value = "Text A"
       }
       variable.B {
           name = "B"
           value = "Text B"
       }

       groups = 1, 2
       group {
           1 {
               name = "Group One"
               templates = 1, 2
               template {
                   1 {
                       name = "One"
                       file = /path/to/template/file-1-1
                   }

                   2 {
                       name = "Two"
                       file = /path/to/template/file-1-2
                   }
               }
           }

           2 {
               name = "Group Two"
               templates = 1, 2
               template {
                   1 {
                       name = "One"
                       file = /path/to/template/file-2-1
                   }

                   2 {
                       name = "Two"
                       file = /path/to/template/file-2-2
                   }
               }
           }

       }
   }

.. hint::

   For more information consult the |toast| documentation at:
   Installation and Configuration -> Setup -> Templates configuration
   :ref:`toast_template_config`.


Incident Synchronization
========================

If a |scname| source has been configured then incidents will be automatically created and
updated if |scname| reports new and updated events if the event fulfills the trigger
criteria.

.. code::

   queues.toast.processors.messages.toastd.trigger {
       incident {
           enable = true
           minimumMagnitude = 5.0
           maximumDepth = 100
       }
   }


If an incident exists already then it will be updated in any case, regardless of the trigger criteria.

Furthermore simulations will be triggered if an incident has been created or updated
based on simulation trigger criteria:

.. code::

   queues.toast.processors.messages.toastd.trigger {
       simulation {
           maximumAge = 1800 # Half an hour
           minimumMagnitude = 6.0
           origin.mode = "" # manual | automatic
       }
   }


These criteria will be checked whenever an incident receives new source values. Furthermore
to reduce the number of simulations, a new simulation will only be started if the source
of an existing simulation deviates from the new incident source outside allowed limits:

.. code::

   queues.toast.processors.messages.toastd.matching {
       magnitude.variance = 0.1
       depth.variance = 30 # km
       location.variance = 0.1 # degrees
       nodalPlane.variance = 1.0 # degrees
   }