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