323 lines
8.0 KiB
ReStructuredText
323 lines
8.0 KiB
ReStructuredText
.. highlight:: rst
|
|
|
|
.. _capstool:
|
|
|
|
########
|
|
capstool
|
|
########
|
|
|
|
**CAPS command-line interface (CLI) client.**
|
|
|
|
|
|
Description
|
|
===========
|
|
|
|
capstool is a CAPS client application for retrieving data and listing available
|
|
streams from an operational CAPS server.
|
|
|
|
Applications
|
|
============
|
|
|
|
* Connectivity test to a CAPS server (:option:`-P`).
|
|
* Request of available streams (:option:`-Q`, :option:`-I`). The result set may
|
|
vary depending on the client's IP address or the user name used for the
|
|
connection.
|
|
* Data retrieval to stdout or individual files (:option:`-o`). Data may be
|
|
requested in order of sampling time or time of arrival (:option:`--ooo`). It may
|
|
also be retrieved downsampled to 1Hz (:option:`--heli`).
|
|
* Data quality control by listing gaps (:option:`-G`), continous data segments
|
|
(:option:`-S`) or record arrival times (:option:`-M`).
|
|
* Data cleanup on the server side (:option:`--purge`).
|
|
* Retrieval of server statistics (:option:`-X`).
|
|
|
|
|
|
Input
|
|
=====
|
|
|
|
The program reads requests from file or from standard input if no file is specified.
|
|
The request format is defined as follows:
|
|
|
|
.. code-block:: params
|
|
|
|
YYYY,MM,DD,HH,MM,SS YYYY,MM,DD,HH,MM,SS Network Station [Location] Channel
|
|
|
|
Each request line contains a start and an end time followed by a stream id. The
|
|
fields Network, Station, Channel and Location support wild cards (*). The latter
|
|
one is optional. For matching all locations please use the '*' symbol, if empty
|
|
it assumes that only empty locations are being requested.
|
|
|
|
.. note::
|
|
|
|
The request lines can be generated for a particular event using
|
|
:cite:t:`scevtstreams` as of the SeisComP3 release Jakarta-2018.xxx.
|
|
|
|
Example:
|
|
|
|
.. code-block:: params
|
|
|
|
2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
|
|
2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU 00 BH*
|
|
|
|
|
|
Output
|
|
======
|
|
|
|
The output format differs by record type. Below is an overview of the available
|
|
formats.
|
|
|
|
.. csv-table::
|
|
:header: "Record type", "Output data format"
|
|
:widths: 1,1
|
|
|
|
RAW, ASCII SLIST
|
|
MSEED, MSEED
|
|
ANY, Stored data format
|
|
|
|
.. note::
|
|
|
|
When retrieving miniSEED data the records are not necessarily sorted by time.
|
|
However, sorting by time is required, e.g., for processing in playbacks.
|
|
Use :cite:t:`scmssort` for sorting the records by time. Example:
|
|
|
|
.. code-block:: sh
|
|
|
|
scmssort -E -u data.mseed > data_sorted.mseed
|
|
|
|
|
|
Examples
|
|
========
|
|
|
|
* **List available streams:**
|
|
|
|
.. code-block:: sh
|
|
|
|
capstool -H localhost:18002 -Q
|
|
|
|
* **Secured connection:**
|
|
|
|
Connect via Secure Sockets Layer (SSL) and supply credentials for
|
|
authentication.
|
|
|
|
.. code-block:: sh
|
|
|
|
capstool -H localhost:18002 -s -c user:password -Q
|
|
|
|
* **Time-based request without request file:**
|
|
|
|
Request file to load miniSEED data for some GE stations:
|
|
|
|
.. code-block:: params
|
|
|
|
2010,02,18,12,00,00 2010,02,18,12,10,00 GE WLF BH*
|
|
2010,02,18,12,00,00 2010,02,18,12,10,00 GE VSU BH*
|
|
|
|
Submit the request in :file:`req.txt` to the CAPS server, and download miniSEED
|
|
data to the file :file:`data.mseed`.
|
|
|
|
.. code-block:: sh
|
|
|
|
capstool -H localhost:18002 -o data.mseed req.txt
|
|
|
|
* **Time-based request without request file:**
|
|
|
|
Request miniSEED data from a CAPS server. Provide request parameters from
|
|
standard input. Write the miniSEED data to standard output. Re-direct the
|
|
output and append it to a file, e.g., :file:`data.mseed`:
|
|
|
|
.. code-block:: sh
|
|
|
|
echo "2015,11,08,10,47,00 2015,11,08,11,00,00 * * BH?" |\
|
|
capstool -H localhost:18002 >> data.mseed
|
|
|
|
* **Event-based request:**
|
|
|
|
Request miniSEED data from a CAPS server for a particular event with ID <eventID>.
|
|
Provide the request file using :cite:t:`scevtstreams`. Write the miniSEED data
|
|
to standard output. Re-direct the output to a file, e.g., :file:`<eventID>.mseed`.
|
|
|
|
.. code-block:: sh
|
|
|
|
scevtstreams -d mysql://sysop:sysop@localhost/seiscomp -E <eventID> --caps > req.txt
|
|
capstool -H localhost:18002 req.txt > <eventID>.mseed
|
|
|
|
* **Video data:**
|
|
|
|
Request to load video data from Station HILO. Request file:
|
|
|
|
.. code-block:: params
|
|
|
|
2013,08,01,00,00,00 2013,08,01,00,30,00 VZ HILO WLS CAM
|
|
2013,08,01,00,00,00 2013,08,01,00,30,00 VZ HILO WLS CAM
|
|
|
|
Submit the request in :file:`req.txt` to the CAPS server, and download the video data
|
|
to files using the given pattern:
|
|
|
|
.. code-block:: sh
|
|
|
|
capstool -H localhost:18002 -o "%H%M%S.%f" req.txt
|
|
|
|
|
|
|
|
|
|
Command-Line Options
|
|
====================
|
|
|
|
:program:`capstool [options]`
|
|
|
|
.. _Options:
|
|
|
|
|
|
Options
|
|
-------
|
|
|
|
.. option:: -h, --help
|
|
|
|
Show a help message and exit.
|
|
|
|
.. option:: -H, --host HOST[:PORT]
|
|
|
|
Default: ``localhost:18002``
|
|
|
|
Host and optionally port of the CAPS server \(default is localhost:18002\).
|
|
|
|
.. option:: -s, --ssl
|
|
|
|
Use secure socket layer \(SSL\).
|
|
|
|
.. option:: -c, --credentials USER[:PASSWORD]
|
|
|
|
Authentication credentials. If the password is omitted, it is asked for on command\-line.
|
|
|
|
.. option:: -P, --ping
|
|
|
|
Retrieve server version information and exit.
|
|
|
|
.. option:: -Q
|
|
|
|
Print availability extents of all data streams.
|
|
|
|
.. option:: -I, --info-streams FILTER
|
|
|
|
Like \-Q but with a use a regular filter expression for the requested streams, e.g., AM.\*.
|
|
|
|
.. option:: --filter-list
|
|
|
|
Identical to \-I.
|
|
|
|
.. option:: --mtime [start]:[end]
|
|
|
|
Restrict request to record modification time window. Time format:
|
|
%Y,%m,%d[,%H[,%M[,%S[,%f]]]]
|
|
|
|
.. option:: -X, --info-server
|
|
|
|
Request server statistics in JSON format.
|
|
|
|
.. option:: --modified-after TIME
|
|
|
|
Limit server statistics request to data modified after specific time. Time format:
|
|
%Y,%m,%d[,%H[,%M[,%S[,%f]]]]
|
|
|
|
.. option:: --force
|
|
|
|
Disable any confirmation prompts.
|
|
|
|
|
|
.. _Options (request file, no data download):
|
|
|
|
|
|
Options (request file, no data download)
|
|
----------------------------------------
|
|
|
|
.. option:: -G, --print-gaps
|
|
|
|
Request list of data gaps.
|
|
|
|
.. option:: -S, --print-segments
|
|
|
|
Request list of continuous data segments.
|
|
|
|
.. option:: --tolerance SECONDS
|
|
|
|
Default: ``0``
|
|
|
|
Threshold in seconds defining a data gap \(decimal point, microsecond precision\).
|
|
|
|
.. option:: -R, --Resolution DAYS
|
|
|
|
Default: ``0``
|
|
|
|
The resolution in multiple of days of the returned data segments or gaps. A value of 0 returns
|
|
segments based on stored data records. A value larger than zero will return the minimum and
|
|
maximum data time of one, two or more days. Consecutive segments will be merged if end and start
|
|
time are within the tolerance.
|
|
|
|
.. option:: --print-stat
|
|
|
|
Request storage information with a granularity of one day.
|
|
|
|
.. option:: --purge
|
|
|
|
Deletes data from CAPS archive with a granularity of one
|
|
day. Any data file intersecting with the time window
|
|
will be purged. The user requires the purge permission.
|
|
|
|
|
|
.. _Options (request file and data download):
|
|
|
|
|
|
Options (request file and data download)
|
|
----------------------------------------
|
|
|
|
.. option:: -o, --output-file FILE
|
|
|
|
Output file for received data \(default: \-\). The file name is used as a prefix with the
|
|
extension added based on the record type \(MSEED, RAW, ANY, META, HELI\). Multiple files are
|
|
created if mixed data types are received. For 'ANY' records the file name may contain the
|
|
following format controls: %Y \- year, %j \- day of year, %H \- hour, %M \- minute, %S \- second, %F
|
|
\- format.
|
|
|
|
.. option:: --any-date-format FORMAT
|
|
|
|
Default: ``%Y%m%d_%H%M%S``
|
|
|
|
Date format to use for any files, see 'man strftime'.
|
|
|
|
.. option:: -t, --temp-file FILE
|
|
|
|
Use temporary file to store data. On success move to output\-file.
|
|
|
|
.. option:: --rt
|
|
|
|
Enable real time mode.
|
|
|
|
.. option:: --ooo
|
|
|
|
Request data in order of transmission time instead of sampling time.
|
|
|
|
.. option:: --out-of-order
|
|
|
|
Identical to \-\-ooo.
|
|
|
|
.. option:: -D, --heli
|
|
|
|
Request down\-sampled data \(1Hz\). The server will taper, bandpass filter and re\-sample the data.
|
|
|
|
.. option:: --itaper SECONDS
|
|
|
|
Timespan in SECONDS for the one\-sided cosine taper.
|
|
|
|
.. option:: --bandpass RANGE
|
|
|
|
Corner frequency RANGE of the bandpass filter, e.g., 1.0:4.0.
|
|
|
|
.. option:: -M, --meta
|
|
|
|
Request record meta data only.
|
|
|
|
.. option:: -v, --version VERSION
|
|
|
|
Request a specific format version. Currently only supported in meta requests.
|
|
|
|
|