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 (-P).

  • Request of available streams (-Q, -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 (-o). Data may be requested in order of sampling time or time of arrival (--ooo). It may also be retrieved downsampled to 1Hz (--heli).

  • Data quality control by listing gaps (-G), continous data segments (-S) or record arrival times (-M).

  • Data cleanup on the server side (--purge).

  • Retrieval of server statistics (-X).

  • Retrieval of telemetry statistics (-T).

Input

Datetime formats

The program supports the SeisComP as well as the native CAPS date time format for the various time parameters. Both formats may be mixed and may be reduced to the minimum precision required. The two formats are defined as follows:

SeisComP:            DATE[SEPARATOR[TIME[Z]]]
    Date:            YYYY-MM-DD, YYYY-DDD, YYYY, YY
    Separator:       T, " " (space, not sported in request lines)
    Time:            hh:mm:ss.ssssss, hh:mm:ss, hh:mm, hh
    Example:         2026-03-01T11:22:33

CAPS:                %Y,%m,%d[,%H[,%M[,%S[,%f]]]]
    Example:         2026,03,01,11,22,33

Request File Format

Some of the supported operations read request lines from file or from standard input if no file is specified. Each line of a request file defines a start time, an end time and a stream id in NSLC format. A space is used as a separator for all columns. An underscore (_) may be used to declare a time window with an open start and/or end time. The stream id supports * and ? wild cards for all components.

The default request line format is CAPS. Alternatively the FDSNWS format may be activated (--fdsnws). The two formats are defined as follows:

CAPS:                STARTTIME ENDTIME NET STA LOC CHA
    Time:            Represented in common or CAPS time format, see datetime
                     section above.
    Empty location   LOC column may be ommited.

FDSNWS:              NET STA LOC CHA STARTTIME ENDTIME
    Time:            Represented in common or CAPS time format, see datetime
                     section above.
    Empty location   Represented by: --

Note

The request lines can be generated for a particular event using scevtstreams [15] as of the SeisComP3 release Jakarta-2018.xxx.

Example:

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*

Note

  • capstool supports all time formats introduced with SeisComP in version 6.4.0. Hence , the request lines from above are equivalent to

    YYYY-MM-DDTHH:MM:SS YYYY-MM-DDTHH:MM:SS Network Station [Location] Channel

2010-02-18T12 2010-02-18T12:10 GE WLF BH*
2010-02-18T12 2010-02-18T12:10 GE VSU 00 BH*

Output

The output format differs by record type. Below is an overview of the available formats.

Record type

Output data format

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 scmssort [16] for sorting the records by time. Example:

scmssort -E -u data.mseed > data_sorted.mseed

Examples

  • List available streams:

    capstool -H localhost:18002 -Q

  • Secured connection:

    Connect via Secure Sockets Layer (SSL) and supply credentials for authentication.

    capstool -H localhost:18002 -s -c user:password -Q

  • Time-based request with request file:

    Request file to load miniSEED data for some GE stations:

    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 req.txt to the CAPS server, and download miniSEED data to the file data.mseed.

    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., data.mseed:

    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 scevtstreams [15]. Write the miniSEED data to standard output. Re-direct the output to a file, e.g., <eventID>.mseed.

    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:

    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 req.txt to the CAPS server, and download the video data to files using the given pattern:

    capstool -H localhost:18002 -o "%H%M%S.%f" req.txt

  • Stream statistics

    Fetch gap statistic for given stream and time window from local CAPS server

    echo "2022-05-01 2022-05-03 NET * * *" | capstool -G

    Fetch segment statistic for given stream and time window from local CAPS server using a gap threshold of 0.5 seconds

    echo "2022-05-01 2022-05-03 NET * * *" | capstool -G --tolerance=0.5

    Collect telemetry statistics for given streams and modification time window with a granularity of 15 min considering data that arrived up to 1 day after record time

    echo "_ _ NET * * *" | capstool -T --mtime=2026-02-17~2026-02-19 --resolution=900 --reltime 86400:0

    Fetch disk usage statistic for given stream and time window from local CAPS server

    echo "2022-05-01 2022-05-03 NET * * *" | capstool --print-stat

  • Purge data

    Purge data for given stream and time window from local CAPS server

    echo "2022-05-01 2022-05-03 NET * * *" | capstool --purge

Command-Line Options

capstool [options]

Options

-h, --help

Show a help message and exit.

Connection

-H, --host HOST[:PORT]

Default: localhost:18002

Host and optionally port of the CAPS server.

-s, --ssl

Use secure socket layer (SSL).

--ssl-no-cert

Do not verify the server certificate chain. Implicitly disables the hostname check.

--ssl-no-hostname

Do not verify the server’s hostname.

-c, --credentials USER[:PASSWORD]

Authentication credentials. If the password is omitted, it is asked for on command-line.

Server information

-P, --ping

Retrieve server version information and exit.

-Q

Print availability extents of all data streams.

-I, --info-streams FILTER

Like -Q but with a use a regular filter expression for the requested streams, e.g., AM.*.

--filter-list

Identical to -I.

-X, --info-server

Request server statistics in JSON format.

--modified-after TIME

Limit server statistics request to data modified after specific time. Refer to time section for supported formats.

Time options

--time [start]~[end]

Override requested time window for all streams in request file. See above for supported formats.

--mtime [start]~[end]

Restrict request to record modification time window. See above for supported formats.

--reltime [sec]~[sec]

Override requested time window for all streams as seconds before and after now (before:after). If used in combination with ‘--mtime’, the offsets are interpreted as seconds before and after the requested modification time window.

Stream statistic (request file required)

-G, --print-gaps

Request list of data gaps.

-S, --print-segments

Request list of continuous data segments.

--tolerance SECONDS

Default: 0

Threshold in seconds defining a data gap (decimal point, microsecond precision).

-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 0 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. Used differently in telemetry requests.

--print-stat

Request storage information with a granularity of one day.

-T, --print-telemetry

Calculate combined telemetry information of selected streams such as bandwidth, sample compression rate and delay. Considers neither transport nor application layer protocol overhead. Requires ‘--mtime’ parameter and CAPS API >= 6.

-R, --resolution SECONDS

Default: 60

Granularity of the telemetry statistics. Used differently in gaps and segment requests.

--stats-per-sec

Print bandwidth and packet count statistics per 1 s instead of per ‘--resolution’ seconds’.

Data download (request file required)

-o, --output-file FILE

Default: -

Output file name prefix for received data. An extension is 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 is set to PREFIX_STREAMID_DATE.TYPE.

--any-date-format FORMAT

Default: %Y%m%d_%H%M%S

Date format to use for any files, see ‘man strftime’.

-t, --temp-file FILE

Use temporary file to store data. On success move to output-file.

--rt

Enable real time mode.

--ooo

Request data in order of transmission time instead of sampling time.

--out-of-order

Identical to --ooo.

-D, --heli

Request down-sampled data (1Hz). The server will taper, bandpass filter and re-sample the data.

--itaper SECONDS

Timespan in SECONDS for the one-sided cosine taper.

--bandpass RANGE

Corner frequency RANGE of the bandpass filter, e.g., 1.0:4.0.

-M, --meta

Request record meta data only.

-v, --version VERSION

Request a specific format version. Currently only supported in meta requests.

Data cleanup (request file required)

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

--force

Disable any confirmation prompts.

Request file

----fdsnws

Read request lines in FDSNWS instead of CAPS format.