.. highlight:: rst

.. _slink2caps:

##########
slink2caps
##########

**Data retrieval to CAPS using SeedLink plugins.**


Description
===========

*slink2caps* uses the available :term:`SeedLink` plugins to feed data from other
sources into :ref:`CAPS` server. Data can be retrieved from any sources for
which a :term:`SeedLink` plugin exists. The data will be converted into
:ref:`sec-pt-miniseed` format or other formats depending on the plugin itself.

For retrieving data from a :ref:`caps` server you may use :ref:`capstool` or
:ref:`rifftool`.


Transient Packets
=================

The plugin data acquisition and the CAPS outgoing connection is not
synchronized so that packets might be received by plugins but could not be forwarded to
CAPS since the plugin is not allowed to send data to the server or the server
is not reachable. In this case packets are in transient state and would be lost
on shutdown. To prevent packet loss the plugin stores all transient packets to
disk during shutdown by default. Configure :confval:`buffer` for using an
alternative location.

.. note::

   Keep in mind to remove the buffer file before starting the plugin in case you
   wish to reset the data acquisition completely.


Module Setup
============

Very few configuration steps are required as a minium to use slink2caps:

#. Identify the :term:`SeedLink` instance to consider. Let's assume in this
   description this instance is :program:`seedlink`. In general you may use any
   instance (alias) of :term:`SeedLink`.
#. Configure the :term:`SeedLink` instance to consider:

   * Disable the time tables in module configuration (:file:`@SYSTEMCONFIGDIR@/seedlink.cfg`):

     .. code-block:: properties

        plugins.chain.loadTimeTable = false

   * Create bindings as usual for :term:`SeedLink`.
#. If any other instance than :program:`seedlink` is considered, then you need
   to configure the parameters in the :ref:`seedlink` section of the module
   configuration of slink2caps.
#. Apply the configuration changes and stop the considered :term:`SeedLink`
   instance. Then, enable and start slink2caps:

   .. code-block:: sh

      seiscomp stop seedlink
      seiscomp disable seedlink
      seiscomp update-config seedlink
      seiscomp enable slink2caps
      seisomp start slink2caps


   .. warning::

     The seedlink instance which is considered must not be running while using
     slink2caps. E.g. when using :program:`seedlink` stop and disable this
     instance first.

.. note ::

   As for many other |scname| and gempa modules, you may create aliases from
   slink2caps for running multiple instances with different configurations at
   the same time. In this case you must adjust the :confval:`buffer` and the
   :ref:`journal.*` parameters.

   You may create or remove a module alias using the :program:`seiscomp` tool,
   e.g.:

   .. code-block:: sh

      seiscomp alias create slink2caps-alias slink2caps
      seiscomp --interactive alias remove slink2caps-alias



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/slink2caps.cfg`
| :file:`etc/global.cfg`
| :file:`etc/slink2caps.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/slink2caps.cfg`

slink2caps inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses



.. confval:: buffer

   Default: ``@ROOTDIR@/var/lib/slink2caps/buffer.mseed``

   Type: *path*

   Path to buffer file where transient packets are stored on disk during shutdown.
   Transient means packets that have been received from input plugins,
   e.g., chain_plugin but have not been acknowledged by CAPS. Without local storage
   on disk those packets would be lost. During start the plugin
   reads the buffer file and tries to send the packets again. Please keep in mind
   to remove the buffer file before plugin start in case of the data
   acquisition should be reset.


.. _seedlink:


.. note::

   **seedlink.\***
   *Data input control*


.. confval:: seedlink.config

   Default: ``@ROOTDIR@/var/lib/seedlink/seedlink.ini``

   Type: *path*

   Path to Seedlink configuration file. Use the respective name
   if seedlink runs as an alias.


.. confval:: seedlink.name

   Default: ``seedlink``

   Type: *string*

   Name of Seedlink configuration section. Use the respective name
   if seedlink runs as an alias.


.. _output:


.. note::

   **output.\***
   *Data output control*


.. confval:: output.stdout

   Default: ``false``

   Type: *boolean*

   Write miniSEED records to stdout instead of pushing them
   to CAPS.


.. confval:: output.address

   Default: ``localhost:18003``

   Type: *string*

   Data output URL [[caps\|capss]:\/\/][user:pass\@]host[:port]. This parameter
   superseds the host and port parameter of previous versions and takes precedence.


.. confval:: output.host

   Default: ``localhost``

   Type: *string*

   Data output host. Deprecated: Use output.address instead.


.. confval:: output.port

   Default: ``18003``

   Type: *int*

   Data output port. Deprecated: Use output.address instead.


.. confval:: output.timeout

   Default: ``60``

   Unit: *s*

   Type: *int*

   Timeout when sending a packet. If the timeout expires
   the connection will be closed and re\-established.


.. confval:: output.maxFutureEndTime

   Default: ``120``

   Unit: *s*

   Type: *int*

   Maximum allowed relative end time for packets. If the packet
   end time is greater than the current time plus this value,
   the packet will be discarded. By default this value is set
   to 120 seconds.


.. confval:: output.bufferSize

   Default: ``131072``

   Unit: *bytes*

   Type: *uint*

   Size \(bytes\) of the packet buffer


.. confval:: output.backFillingBufferSize

   Default: ``0``

   Unit: *s*

   Type: *int*

   Length of backfilling buffer. Whenever a gap is detected, records
   will be held in a buffer and not sent out. Records are flushed from
   front to back if the buffer size is exceeded.


.. _journal:


.. confval:: journal.file

   Default: ``@ROOTDIR@/var/run/rs2caps/journal``

   Type: *string*

   File to store stream states


.. confval:: journal.flush

   Default: ``10``

   Unit: *s*

   Type: *uint*

   Flush stream states to disk every n seconds


.. confval:: journal.waitForAck

   Default: ``60``

   Unit: *s*

   Type: *uint*

   Wait when a sync has been forced, up to n seconds


.. confval:: journal.waitForLastAck

   Default: ``5``

   Unit: *s*

   Type: *uint*

   Wait on shutdown to receive acknownledgement messages, up to n seconds


.. _statusLog:


.. confval:: statusLog.enable

   Default: ``false``

   Type: *boolean*

   Log information status information e.g.
   max bytes buffered


.. confval:: statusLog.flush

   Default: ``10``

   Type: *uint*

   Flush status every n seconds to disk




Command-Line Options
====================


.. _Generic:


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.

.. option:: -f, --seedlink-config arg

   Default: ``@ROOTDIR@/var/lib/seedlink/seedlink.ini``

   Path to Seedlink configuration file. Default: \@ROOTDIR\@\/var\/lib\/seedlink\/seedlink.ini

.. option:: -n, --section-name arg

   Default: ``seedlink``

   Name of Seedlink configuration section. Default: seedlink.


.. _Verbosity:


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --print-component arg

   For each log entry print the component right after the
   log level. By default the component output is enabled
   for file output but disabled for console output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --trace

   Execute in trace mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 \-\-print\-component\=1
   \-\-print\-context\=1 .

.. option:: --log-file arg

   Use alternative log file.


.. _Output:


Output
------

.. option:: -H, --host arg

   Default: ``localhost``

   Data output host. Default: localhost.

.. option:: -p, --port arg

   Default: ``18003``

   Data output port. Default: 18003.

.. option:: -c, --stdout

   Write records to stdout.

.. option:: --max-future-endtime arg

   Maximum allowed relative end time for packets. If the packet
   end time is greater than the current time plus this value,
   the packet will be discarded. By default this value is set
   to 120 seconds.


