.. highlight:: rst .. _gds: ### gds ### **Gempa Dissemination Server (GDS)** Description =========== .. _sec-be-gds: coming soon .. - Listen for event updates - Determine subscriptions - Create bulletins - Generate previews - Call Spooler - Update Log .. _sec-be-gds-arch: Architecture ------------ coming soon .. _sec-be-gds-fil: Content Filter -------------- coming soon .. - protocol filter .. _sec-be-gds-bul: Bulletins --------- coming soon .. - address + content files - wie und in welcher reihenfolge generiert - gempa bulletin format siehe tools/bulletin - reihenfolge in address file .. _sec-be-gds-spool: Spooler ------- coming soon .. Protocol spooler .. _sec-be-gds-cli: Command interface ----------------- .. code-block:: none telnet localhost 20000 help [COMMANDS] HELP [command] Show this/command help HELLO Test server version ADDSUBSCRIPTION [params] Add subscription prior to dissemination ADDQUEUE [params] Add queue prior to dissemination ADDATTACHMENT [params] Add attachment prior to dissemination ADDBULLETIN [params] Add bulletin prior to dissemination DISSEMINATE [params] Trigger dissemination of data SEND [params] Sends bulletins PREVIEW Get bulletin previews GETSUBSCRIPTIONS [params] Get subscriptions for XML data GETBULLETINS [params] Get subscriptions and bulletins for XML data RESET Resets session BYE Close the session Module Configuration ==================== | :file:`etc/defaults/global.cfg` | :file:`etc/defaults/gds.cfg` | :file:`etc/global.cfg` | :file:`etc/gds.cfg` | :file:`~/.seiscomp/global.cfg` | :file:`~/.seiscomp/gds.cfg` gds 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:: database Default: ``mysql://sysop:sysop@localhost/gds`` Type: *string* Connection string to database which contains the dissemination configuration setup. Format: [service:\/\/][user:pwd\@]host[:port]\/database .. confval:: dbSequencePrefix Type: *string* By default a database sequence is named after the table, suffixed by \"_seq\": \"[tablename]_seq\". Sometimes the column name is used as well, e.g. when using postgresql_psycopg2 as Django database back\-end. If set, the value of this parameter will be added to the sequence suffix: \"[tablename][dbSequencePrefix]_seq\" .. confval:: bind Default: ``127.0.0.1:20000`` Type: *host-with-port* IP and port to bind the command interface to. Use 0.0.0.0 to bind to all interfaces. Either the port or the IP address may be omitted, e.g. \"0.0.0.0\" or \":1234\". If set to an empty string the application will run without providing a command interface. .. confval:: sbind Type: *host-with-port* IP and port to listen for data requests with SSL. .. confval:: connections Default: ``200`` Type: *int* Maximum number of clients connected simultaneously to the command interface. .. confval:: backlog Default: ``3600.0`` Unit: *s* Type: *double* Backlog time \(in seconds\) to fetch and process event data right after the start. Note: The Dissemination Server also stores the update time of the last successfully processed event in LOG_DIR\/gds.last_update. The start time of the time window to fetch data from the QuakeLink server \(at startup\) is calculated from the maximum of both values: max\(lastUpdateTime, NOW\-backlogSeconds\). .. confval:: cleanupInterval Default: ``0`` Unit: *s* Type: *int* Interval in seconds to trigger DB cleanup routine. The type of information to clean up is configured in Service section of the web front\-end. .. confval:: spoolOnly Default: ``false`` Type: *boolean* Sets the GDS to exclusive spooler mode. In this mode no quakelink and database connection is established. Also the command interface is not available. If enabled external services need to be configured. .. confval:: externalServices Type: *list:string* List of services managed outside the GDS. Triggering and content generation is done by an external application. The GDS will only serve as a spooler. Consequently no result is written to the GDS database. .. confval:: id Type: *string* ID of the GDS instance. Will be added to the event log. Used in HA configurations to distinguish triggering instance. .. confval:: SSL.certificate Type: *path* Path to SSL certificate file .. confval:: SSL.key Type: *path* Path to SSL private key file .. note:: **requestLimits.\*** *Definition of limits for dissemination request at the GDS* *command interface.* .. confval:: requestLimits.queues Default: ``100`` Type: *int* Maximum number of queues to trigger, see ADDQUEUE command. .. confval:: requestLimits.subscriptions Default: ``1000`` Type: *int* Maximum number of subscriptions to trigger, see ADDSUBSCRIPTION command. .. confval:: requestLimits.bulletins Default: ``100`` Type: *int* Maximum number of bulletins to attach, see ADDBULLETIN command. .. confval:: requestLimits.attachments Default: ``100`` Type: *int* Maximum number of attachments, see ADDATTACHMENT command. .. confval:: requestLimits.attachments Default: ``100`` Type: *int* Maximum number of attachments, see ADDATTACHMENT command. .. confval:: requestLimits.docSize Default: ``10`` Unit: *MiB* Type: *double* Maximum document size, see ADDBULLETIN and DISSEMINATE commands. .. confval:: requestLimits.totalAttachmentSize Default: ``30`` Unit: *MiB* Type: *double* Total size of all attachments, see ADDATTACHMENT command. .. note:: **ha.\*** *Two or more GDS instances may operate in a high* *availability (HA) configuration sharing one database.* *Slave instances will only trigger if the master instance* *fails to disseminate an event after a given timeout.* *For maximum reliability the database should be redundant* *too, e.g. by using a cluster configuration or master-master* *replication.* .. confval:: ha.enable Default: ``false`` Type: *boolean* Enable HA feature. .. confval:: ha.slave Default: ``false`` Type: *boolean* Mark this GDS instance as slave. .. confval:: ha.timeout Default: ``10.0`` Unit: *s* Type: *double* Timeout in seconds a GDS slave instance will wait for the master to disseminate an event. .. note:: **quakelink.\*** *The Dissemination Server connects to the gempa QuakeLink* *service to obtain archived and continuous event* *information in SCML (SeisComP Markup Language) format.* .. confval:: quakelink.url Default: ``ql://localhost:18010`` Type: *string* URL of the QuakeLink service, the scheme 'qls' enables SSL. Format: [ql[s]:\/\/][user:pwd\@][host][:port]. If set to an empty string the application will run without any QuakeLink ## connection attempt. .. confval:: quakelink.gzip Default: ``false`` Type: *boolean* Enables\/disables GZip \(GNU zip\) compression. .. confval:: quakelink.native Default: ``false`` Type: *boolean* Request native data instead of XML format. Native data export may be disabled on some hosts. .. confval:: quakelink.keepAlive Default: ``false`` Type: *boolean* Request server to send keep alive message every 30s to prevent connection reset by firewalls on long idle periods. If activated the client will reset the connection if no alive message is received within 60s. The default timeout maybe overridden with the 'keepAliveTimeout' parameter. .. confval:: quakelink.keepAliveTimeout Default: ``60`` Unit: *s* Type: *int* Timeout in seconds to wait for a server response when listening for updates with active keep alive messages \(see parameter 'keepAlive'\). The response might be a alive message or a message containing actual data. The value defined here should be larger than the value configured in the QuakeLink server's 'keepAliveInterval' parameter. If undefined a server interval of 30 is assumed and a timeout value of 60s is used. Set the value to 0 to deactivate the timeout entirely. .. confval:: quakelink.filter Type: *string* SQL like WHERE clause to filter the result set. Example: \"AGENCY \= 'GFZ' AND MAG > 3\" Variables: MAG, DEPTH, LAT, LON, PHASES, UPDATED, OTIME, AGENCY, STATUS, TYPE, REGION, MAG_T .. note:: **quakelink.data.\*** *QuakeLink options specifying which XML components to fetch.* *Note: These options are not used if 'native' data is requested.* .. confval:: quakelink.data.indent Default: ``false`` Type: *boolean* Activate XML indentation \(pretty print\) .. confval:: quakelink.data.picks Default: ``true`` Type: *boolean* Include picks .. confval:: quakelink.data.amplitudes Default: ``true`` Type: *boolean* Include amplitudes .. confval:: quakelink.data.arrivals Default: ``true`` Type: *boolean* Include origin arrivals .. confval:: quakelink.data.staMags Default: ``true`` Type: *boolean* Include origin station magnitudes .. confval:: quakelink.data.staMts Default: ``false`` Type: *boolean* Include moment tensor station contributions and phase settings .. confval:: quakelink.data.preferred Default: ``true`` Type: *boolean* Include only preferred origin and magnitude information .. note:: **service.$name.\*** *For each service found in the configuration database a* *service configuration with the same name must exist in* *the configuration file.* $name is a placeholder for the name to be used. .. confval:: service.$name.directory Type: *string* Service directory \(mandatory\). For each service a folder must exist where ID.content and ID.address files are stored. .. note:: **service.$name.filter.primary.\*** *Defines the 1st stage message filter. A message* *filter application reads SeisComP XML on stdin* *and writes filtered data on stdout.* .. confval:: service.$name.filter.primary.cmd Type: *string* The full path to the filter application. .. confval:: service.$name.filter.primary.mimetype Type: *string* Optional MIME type of the filter output. This is necessary to display the output correctly in the web front\-end. If empty then either raw, a Python dictionary \(as string\) or the internal message format is tested for. .. confval:: service.$name.filter.primary.timeout Default: ``10.0`` Unit: *s* Type: *float* Timeout in seconds after which the command is aborted. Use a negative value to indicate an infinite timeout. .. note:: **service.$name.filter.secondary.\*** *Defines the 2nd stage message filter. This* *filter takes the output of the 1st stage and* *creates the final message to be send. This can* *be useful if the final output is a binary* *format, e.g. PDF or image where the output of* *the 1st stage must be editable in the web* *front-end.* .. confval:: service.$name.filter.secondary.cmd Type: *string* The full path to the filter application. .. confval:: service.$name.filter.secondary.mimetype Type: *string* Optional MIME type of the filter output. This is necessary to display the output correctly in the web front\-end. .. confval:: service.$name.filter.secondary.timeout Default: ``10.0`` Unit: *s* Type: *float* Timeout in seconds after which the command is aborted. Use a negative value to indicate an infinite timeout. .. note:: **service.$name.spooler.\*** *A Spooler (optional) is launched by the server in a* *separate thread and polls the spool directory for* *new data. If an address file is found the* *configured spooler application is executed passing* *the base name of the address file as a command line* *parameter.* .. confval:: service.$name.spooler.cmd Type: *string* Spool command to execute. .. confval:: service.$name.spooler.maxFileAge Default: ``3600`` Unit: *s* Type: *int* Maximum file age in seconds. Files older this timespan will be deleted without processing. .. confval:: service.$name.spooler.interval Default: ``10.0`` Unit: *s* Type: *float* Polling interval in seconds the spooler will scan the service directory for new files. .. confval:: service.$name.spooler.timeout Default: ``-1.0`` Unit: *s* Type: *float* Timeout in seconds after which the command is aborted. Use a negative value to indicate an infinite timeout. .. note:: **filter.\*** *Custom filter application. The default filter application* *defined by 'service.$name.filter' may be overridden for each* *subscription. These custom filter applications must be* *declared in the configuration database and the binary must* *be configured here. Without a valid configuration parameter* *the default service filter (if any) is executed.* .. note:: **filter.$name.\*** $name is a placeholder for the name to be used. .. note:: **filter.$name.primary.\*** *Defines the 1st stage message filter. A message* *filter application reads SeisComP XML on stdin and* *writes filtered data on stdout.* .. confval:: filter.$name.primary.cmd Type: *string* The full path to the filter application. .. confval:: filter.$name.primary.mimetype Type: *string* Optional MIME type of the filter output. This is necessary to display the output correctly in the web front\-end. .. confval:: filter.$name.primary.timeout Default: ``10.0`` Unit: *s* Type: *float* Timeout in seconds after which the command is aborted. Use a negative value to indicate an infinite timeout. .. note:: **filter.$name.secondary.\*** *Defines the 2nd stage message filter. This filter* *takes the output of the 1st stage and creates the* *final message to be send. This can be useful if the* *final output is a binary format, e.g. PDF or image* *where the output of the 1st stage must be editable* *in the web front-end.* .. confval:: filter.$name.secondary.cmd Type: *string* The full path to the filter application. .. confval:: filter.$name.secondary.mimetype Type: *string* Optional MIME type of the filter output. This is necessary to display the output correctly in the web front\-end. .. confval:: filter.$name.secondary.timeout Default: ``10.0`` Unit: *s* Type: *float* Timeout in seconds after which the command is aborted. Use a negative value to indicate an infinite timeout. .. note:: **criterion.$name.\*** *Typically criteria are defined in the GDS front-end. If* *the configuration options available in the front-end do* *not suffice, custom criterion scripts may be used. A* *custom criterion script is feed by SCML on stdin and* *must exit with code 0 indicating a match.* $name is a placeholder for the name to be used. .. confval:: criterion.$name.cmd Type: *string* The full path to the criterion application. .. confval:: criterion.$name.timeout Default: ``10.0`` Unit: *s* Type: *float* Timeout in seconds after which the command is aborted. Use a negative value to indicate an infinite timeout. Command-Line Options ==================== 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 \&. 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. Dissemination ------------- .. option:: -b, --bind arg Overrides configuration parameter :confval:`bind`. .. option:: -B, --backlog arg Overrides configuration parameter :confval:`backlog`. .. option:: -d, --database arg Overrides configuration parameter :confval:`database`. Test Mode --------- .. option:: --xml arg File to read SCML event data from. Supports ZLIB \(\*.zip\) and GZIP \(\*.gz, \*.gzip, \*.gzxml\) compressed files. In test mode only one particular event is disseminated and afterwards the server is shutdown. Neither a connection to the QuakeLink server is established nor the command interface is bound. .. option:: --contact arg Read contacts from file, works only in combination with \-\-xml. If unset query contacts from database. QuakeLink --------- .. option:: -Q, --quakelink arg Overrides configuration parameter :confval:`quakelink.url`. .. option:: -z, --gzip Overrides configuration parameter :confval:`quakelink.gzip`.