.. _plugins-failover:

failover RecordStream
=====================

**failover** is a :term:`RecordStream` implementation that switches the acquisition
to a fallback source in case of the connection to the first source is lost or no
records are received in a configurable interval.
The connection goes back to the primary stream as soon as data comes in again.
The **failover** RecordStream is provided by the gempa plugin *rsfailover* located
in :file:`@DATADIR@/plugins/rsfailover.so` of the recordstream software package.

.. note::

   This plugin requires at least the SeisComP3 release Jakarta-2017.334.
   Please check your installed version of SeisComP3, e.g. using **scm -V**.


Application
-----------

Data processing with redundant data sources.


Setup
-----

.. note::

   **failover** can be combined with other :term:`RecordStream` implementations
   available in SeisComP, :ref:`plugins-rsrouter` or
   `CAPS <https://docs.gempa.de/caps/current/>`_.

#. Add the plugin to the global module configuration (:file:`global.cfg`):

   .. code-block:: sh

      plugins = ${plugins}, rsfailover

#. Configure the record source (:file:`global.cfg`):

   .. code-block:: sh

      recordstream = failover://@SYSTEMCONFIGDIR@/failover.conf

   Available configuration Parameters are:

   .. csv-table::
      :header: "Parameter", "Default", "Description"

      "timeout", "5", "Failover timeout in seconds"
      "connectionTimeout", "5", "Initial connection timeout in seconds"


#. Create the failover list (:file:`@SYSTEMCONFIGDIR@/failover.conf`):

   The failover list is a simple text file where each line contains a
   target URI. The priority of the streams is from top to bottom in
   descending order, e.g.

   .. code-block:: sh

      caps://localhost:18002
      balanced://slink/geofon.gfz-potsdam.de;slink/service.iris.edu