SeisComP3

Table Of Contents

Previous topic

arclinktool

Next topic

ql2sc

This Page

fdsnws

Provides FDSN Web Services

Description

fdsnws is a server that provides FDSN Web Services from a SeisComP3 database and record source. The following services are available:

Service Retrieves this... In this format
fdsnws-dataselect time series data in miniSEED format miniSEED
fdsnws-station network, station, channel, response metadata FDSN Station XML, StationXML, SC3ML
fdsnws-event contributed earthquake origin and magnitude estimates QuakeML, SC3ML

If fdsnws is started, it accepts connections by default on port 8080 which can be changed in the configuration. Also please read Changing the service port for running the services on a privileged port, e.g. port 80 as requested by the specification.

Note

If you decide to run the service on a different URL than localhost:8080 you have to change the URL string in the *.wadl documents located under $DATADIR/fdsnws.

Data select

  • time series data in miniSEED format
  • request type: HTTP-GET, HTTP-POST

Example

http://localhost:8080/fdsnws/dataselect/1/query?net=GE&sta=BKNI&cha=BH?&start=2013-04-11T00:00:00&end=2013-04-11T12:00:00

To summit POST request the command line tool curl may be used.

sysop@host:~$ curl -X POST --data-binary @request.txt "http://localhost:8080/fdsnws/dataselect/1/query"

Feature Notes

  • quality parameter not implemented (information not available in SeisComP)
  • minimumlength parameter is not implemented
  • longestonly parameter is not implemented
  • access to restricted networks and stations is only granted through the queryauth method

Station

  • network, station, channel, response metadata
  • request type: HTTP-GET, HTTP-POST
  • stations may be filtered e.g. by geographic region and time, also the information depth level is selectable

Feature Notes

  • to enable FDSNXML or StationXML support the plugins fdsnxml resp. staxml have to be loaded
  • updatedafter request parameter not implemented: The last modification time in SeisComP is tracked on the object level. If a child of an object is updated the update time is not propagated to all parents. In order to check if a station was updated all children must be evaluated recursively. This operation would be much too expensive.
  • includeavailability request parameter not implemented
  • matchtimeseries request parameter not implemented
  • formatted: boolean, default: false
  • additional values of request parameters:
    • format:
      • standard: [xml, text]
      • additional: [fdsnxml (=xml), stationxml, sc3ml]
      • default: xml

Event

  • contributed earthquake origin and magnitude estimates
  • request type: HTTP-GET
  • events may be filtered e.g. by hypocenter, time and magnitude

Feature Notes

  • SeisComP does not distinguish between catalogs and contributors, but supports agencyIDs. Hence, if specified, the value of the contributor parameter is mapped to the agencyID. The file @DATADIR@/share/fdsn/contributors.xml has to be filled manually with all available agency ids
  • origin and magnitude filter parameters are always applied to preferred origin resp. preferred magnitude
  • updatedafter request parameter not implemented: The last modification time in SeisComP is tracked on the object level. If a child of an object is updated the update time is not propagated to all parents. In order to check if a station was updated all children must be evaluated recursively. This operation would be much too expensive.
  • additional request parameters:
    • includepicks: boolean, default: false, works only in combination with includearrivals set to true
    • includecomments: boolean, default: true
    • formatted: boolean, default: false
  • additional values of request parameters:
    • format:
      • standard: [xml, text]
      • additional: [qml (=xml), qml-rt, sc3ml, csv]
      • default: xml

Changing the service port

The FDSN Web service specification defines that the Service SHOULD be available under port 80. Typically SeisComP3 runs under a user without root permissions and therefore is not allowed to bind to privileged ports (<1024). To serve on port 80 you may for instance

  • run SeisComP3 with root privileged (not recommended)
  • use a proxy Webserver, e.g. Apache with mod-proxy module
  • configure and use Authbind
  • setup Firewall redirect rules

Authbind

authbind allows a program which does not or should not run as root to bind to low-numbered ports in a controlled way. Please refer to man authbind for program descriptions. The following lines show how to install and setup authbind for the user sysop under the Ubuntu OS.

sysop@host:~$ sudo apt-get install authbind
sysop@host:~$ sudo touch /etc/authbind/byport/80
sysop@host:~$ sudo chown sysop /etc/authbind/byport/80
sysop@host:~$ sudo chmod 500 /etc/authbind/byport/80

Once authbind is configured correctly the FDSN Web services may be started as follows:

sysop@host:~$ authbind --deep seiscomp exec fdsnws

In order use authbind when starting fdsnws as SeisComP service the last line in the ~/seiscomp3/etc/init/fdsnws.py have to be commented in.

Firewall

All major Linux distributions ship with their own firewall implementations which are front-ends for the iptables kernel functions. The following line temporary adds a firewall rule which redirects all incoming traffic on port 8080 to port 80.

sysop@host:~$ sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to 8080

Please refer to the documentation of your particular firewall solution on how to set up this rule permanently.

Configuration

etc/defaults/global.cfg
etc/defaults/fdsnws.cfg
etc/global.cfg
etc/fdsnws.cfg
~/.seiscomp3/global.cfg
~/.seiscomp3/fdsnws.cfg

fdsnws inherits global options.

listenAddress

Type: IP

Defines the bind address of the server. "0.0.0.0" allows any interface to connect to this server whereas "127.0.0.0" only allows connections from localhost. Default is 0.0.0.0.

port

Type: int

Server port to listen for incoming requests. Note: The FDSN Web service specification defines the service port 80. Please refer to the documentation on how to serve on privileged ports. Default is 8080.

connections

Type: int

Number of maximum simultaneous requests. Default is 5.

queryObjects

Type: int

Maximum number of objects per query, used in fdsnws-station and fdsnws-event to limit main memory consumption. Default is 10000.

realtimeGap

Type: int

Restricts end time of requests to current time - realtimeGap seconds. Negative values allowed. Used in fdsnws-dataselect. WARNING: If this value is unset and a realtime recordsource (e.g. slink) is used, requests may block if end time in future is requested.

samplesM

Type: float

Maximum number of samples (in units of million) per query, used in fdsnws-dataselect to prevent a single user to block one connection with a large request.

htpasswd

Type: string

Path to password file used in fdsnws-station/queryauth. The format is 'username:password' separated by lines. Because of the HTTP digest authentication method required by the FDSN specification, the passwords have to be stored in plain text. Default is @CONFIGDIR@/fdsnws.htpasswd.

accessLog

Type: string

Path to access log file. If unset no access log is created.

allowRestricted

Type: boolean

Enables/disables access to restricted inventory data Default is true.

serveDataSelect

Type: boolean

Enables/disables the DataSelect service. Default is true.

serveEvent

Type: boolean

Enables/disables the Event service. Default is true.

serveStation

Type: boolean

Enables/disables the Station service. Default is true.

fileNamePrefix

Type: string

Defines the prefix for the default filenames if downloading and saving data from within a browser. For data loaded using dataselect, it is thus fdsnws.mseed by default. Default is fdsnws.

Command-line

Generic

-h, --help

show help message.

-V, --version

show version information

--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, eg scautopick -> scautopick2.

--plugins arg

Load given plugins.

-D, --daemon

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

--auto-shutdown arg

Enable/disable self-shutdown because a master module shutdown. This only works when messaging is enabled and the master module sends a shutdown message (enabled with --start-stop-msg for the master module).

--shutdown-master-module arg

Sets the name of the master-module used for auto-shutdown. This is the application name of the module actually started. If symlinks are used then it is the name of the symlinked application.

--shutdown-master-username arg

Sets the name of the master-username of the messaging used for auto-shutdown. If "shutdown-master-module" is given as well this parameter is ignored.

Verbosity

--verbosity arg

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

-v, --v

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

-q, --quiet

Quiet mode: no logging output

--component arg

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

-s, --syslog

Use syslog logging back end. The output usually goes to /var/lib/messages.

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Debug mode: --verbosity=4 --console=1

--log-file arg

Use alternative log file.

Database

--db-driver-list

List all supported database drivers.

-d, --database arg

The database connection string, format: service://user:pwd@host/database. "service" is the name of the database driver which can be queried with "--db-driver-list".

--config-module arg

The configmodule to use.

--inventory-db arg

Load the inventory from the given database or file, format: [service://]location

--db-disable

Do not use the database at all

Records

--record-driver-list

List all supported record stream drivers

-I, --record-url arg

The recordstream source URL, format: [service://]location[#type]. "service" is the name of the recordstream driver which can be queried with "--record-driver-list". If "service" is not given "file://" is used.

--record-file arg

Specify a file as record source.

--record-type arg

Specify a type for the records being read.