Access Data on a CAPS Server

A range of tools is available to access data and information on a CAPS server.

Name	SW Package	Description
capstool	caps-tools	A command-line tool for retrieving data and meta information from a CAPS server
rifftool	caps-tools	A command-line tool for data inspection and extraction from individual CAPS data files (RIFF), e.g., in a CAPS archive
caps_plugin	seiscomp	The plugin fetches miniSEED and RAW data from a CAPS server and provides the data to seedlink
caps / capss	seiscomp	The RecordStream implementations for CAPS
cap2caps	caps-plugins	Automatic or interactive synchronization of two CAPS servers
web interface	caps-server	The web interface provided by the CAPS server
FDSNWS	caps-server	FDSNWS dataselect interface provided by the CAPS server
WWS	caps-server	Winston Waveform Server interface provided by the CAPS server
scardac	seiscomp	A command-line tool for generating availability information from CAPS archive

RecordStream: caps/capss

SeisComP applications access waveform data through the RecordStream interface. To fetch data from a CAPS server specific RecordStream implementations may be used:

• caps: regular RecordStream implementation to access the CAPS server,

• capss: RecordStream implementation to access the CAPS server secured by SSL, user name and password. Similar to https, capss will establish a Secure Socket Layer (SSL) communication.

Configuration

In order to make use of the caps or the capss RecordStream configure the RecordStream URL in recordstream. Let it point to the CAPS server providing the data. Examples for caps and capss:

recordstream = caps://server:18002
recordstream = capss://foo:bar@server:18022

Optional parameters are available for caps/capss.

Note

While the caps/capss RecordStream provides data in real time and from archive, some modules, e.g., scart [12], fdsnws [9] or GIS [3] should be strictly limited to reading from archive only by the option arch:

recordstream = caps://server:18002?arch
recordstream = capss://foo:bar@server:18022?arch

Otherwise requests attempting to fetch missing data may hang forever.

Optional Parameters

Optional RecordStream parameters which can be combined:

• arch - read from CAPS archive only,

• ooo - out of order, data are fetched and provided in the order of their arrival in the CAPS server, useful for analysing if data have arrived out of order,

• pass - password if server requires authentication,

• request-file - file specifying the streams to be requested. One stream per line. Per line: net sta loc stream startTime endTime,

• timeout - timeout of acquisition in seconds. Data acquisition will be restarted,

• user - user name if server requires authentication.

URL	Description
caps://server:18002?arch	Read data from CAPS archive. Stop data acquisition when all available waveforms are fetched.
caps://server:18002?ooo	Fetch data in the original order of arrival.
caps://server:18002?request-file=request.txt	Request only streams in time intervals given in request.txt
caps://server:18002?timeout=5	Apply a timeout of 5 seconds.
capss://server:18022?user=foo&pass=bar	Use secure protocol (SSL) with user name and password. Read the section on Authentication by user name and password (shadow file) for details on the generation of user names and passwords.

Combination with other RecordStream interfaces

The caps and the capss RecordStream may be combined with other RecordStream interfaces.

Examples:

1. Decimation

   Use the decimation RecordStream [4] interface to fetch data from a CAPS server running on localhost decimated to 1 sample per second.

   global configuration:

   recordstream = dec://caps/localhost:18002?rate=1
   

   command line parameter:

   -I dec://caps/localhost:18002?rate=1
   

2. Resample

   Use the resample RecordStream [4] interface to fetch data from a CAPS server running on localhost resampled to 16 samples per second.

   global configuration:

   recordstream = resample://caps/localhost:18002?rate=16
   

   command line parameter:

   -I resample://caps/localhost:18002?rate=16
   

Direct file access: capstool/rifftool

The data files in the CAPS archive contain a small additional header describing the data format. Read the format documentation for more details. In contrast to miniSEED files in SDS archives created, e.g., by slarchive [18] or scart [12], the original miniSEED files stored in the CAPS archive cannot be directly read by applications.

You may access data files directly:

• Test and retrieve data files using rifftool. rifftool addresses individual files directly and does not require the CAPS server to be running.

• Fetch data streams from a CAPS server based on time windows using the command-line tool capstool. capstool will read the data, strip the header. The data are provide in their original format on stdout or, with -o as a single file. capstool can also be used for testing the server as it provides information on available streams with their time window (-Q).

Synchronize with another CAPS server: caps2caps

Use caps2caps to synchronize your CAPS server with another one. You may push or pull data on either side. In contrast to the generation of regular SDS archives, e.g., by scart, the CAPS server will not generate duplicate data records if executing caps2caps multiple times. While synchronizing observe the web interface for the statistics of received, written or rejected data packages.

Connect from SeedLink: caps_plugin

The caps_plugin plugin fetches data from a CAPS server and provides the data to seedlink. The plugin can be configured and started as any other plugin for seedlink or executed on demand. Select caps when choosing the plugin in the seedlink binding configuration.

Examples:

• Fetch data from a remote CAPS server and make them available in your seedlink instance:

  1. configure the caps_plugin plugin in the bindings configuration of your seedlink instance pointing to the remote CAPS server

  2. enable and start seedlink

     seiscomp enable seedlink
     seiscomp start seedlink
     

• Provide data from a CAPS server by seedlink on the same machine to external clients:

  1. create another seedlink instance, e.g., seedlinkP:

     seiscomp alias create seedlinkP seedlink
     

  2. configure the caps_plugin in the bindings configuration of seedlinkP pointing to the local CAPS server.

  3. enable and start seedlinkP:

     seiscomp enable seedlinkP
     seiscomp start seedlinkP
     

Web interface

The CAPS server ships with a web interface. Beside allowing you to view server statistics, data stored stored on the server can be downloaded for any time if the original format is miniSEED.

For downloading miniSEED data

1. Select the stream(s) of interest.

2. Zoom in to the period of interest. Zooming in and out in time works by right-mouse button actions just like in other SeisComP GUI applications like scrttv [15].

3. Click on the download button to download the miniSEED file. An error message will be printed in case the original format is not miniSEED.

Stream perspective of CAPS Web interface allowing to download miniSEED data for selected streams.

Built-in FDSNWS

CAPS speaks natively FDSN Web Services, FDSNWS [1] providing waveform data via dataselect. Information on events and stations are not delivered. The waveform data will be delivered through the port configured in AS.http.port or the port configured by your Apache server, if available. Contact your system administrator for information on the Apache server. Read the documentation of the CAPS server for the configuration.

Built-in Winston waveform server

CAPS speeks natively Winston Waveform Server protocol, WWS, [7], e.g., to SWARM [5] by USGS. Read the documentation of the CAPS server for the configuration.

Data availability information

Web interface

The Channels perspective of the CAPS web interface indicates periods of availability and of gaps on level of network, station, sensor location and channel. The resolution of colors and percentages is linked to the granularity of the data detection which increases with shorter time windows in order to optimize the speed of the calculation.

capstool

The CAPS server stores information on received data segments including their start and end times. Information on resulting gaps can be retrieved by capstool. Example:

echo "2023,05,01,12,00,00 2023,05,03,00,00,00 NET * * *" | capstool -G --tolerance=0.5 -H localhost

scardac

The availability of data in the caps archive can be analyzed and written to the SeisComP database by the SeisComP module scardac [11]. For availability analysis add the plugin daccaps to the list of plugins and URL of the caps archive to the archive configuration of scardac [11]. The daccaps plugin ships with the gempa package caps-server.

Example configuration of scardac [11] (scardac.cfg):

plugins = ${plugins}, daccaps
archive = caps:///home/data/archive/caps/

Example call:

scardac --plugins="daccaps, dbmysql" -d localhost -a caps:///home/data/archive/caps/ --debug

Note

As of SeisComP in version 6, scardac has received significant optimization. Instead of scanning the full archive, only files which have changed since the last scan will be examined. This means that when scanning the entire archive, the first run may be more time consuming than subsequent ones when executed within reasonable intervals.

The data availability information can be retrieved from the database, e.g., using fdsnws [9] or scxmldump [16].