.. highlight:: rst

.. _caps:

####
caps
####

**Realtime and archive waveform server**


Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/caps.cfg`
| :file:`etc/global.cfg`
| :file:`etc/caps.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/caps.cfg`

caps inherits :ref:`global options<global-configuration>`.

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



.. _AS:


.. note::

   **AS.\***
   *CAPS server control parameters*


.. confval:: AS.filebase

   Default: ``@ROOTDIR@/var/lib/caps/archive``

   Type: *string*

   Defines the path to the archive directory.


.. confval:: AS.port

   Default: ``18002``

   Type: *int*

   Defines the server port for client requests.


.. confval:: AS.clientBufferSize

   Default: ``16384``

   Unit: *B*

   Type: *int*

   Size of the client buffer in bytes. In case the client fails to read the buffered data
   in time \(buffer overflow\) the connection falls back to archive requests.


.. confval:: AS.minDelay

   Default: ``-1``

   Unit: *s*

   Type: *int*

   Limits the retrieval of real\-time data. The value
   specifies the maximum relative end time of the time range
   to be requested. The maximum absolute end time is
   now \- minDelay. This is only valid for FDSNWS and WWS.


.. confval:: AS.inventory

   Type: *path*

   The path to an optional inventory XML file with SeisComP3
   schema. This inventory information is used by WWS to populate
   the channel coordinates. In future possibly more endpoints
   will make use of it.


.. confval:: AS.logRequests

   Default: ``false``

   Type: *boolean*

   Whether to maintain a request log file or not. Each request
   will be logged and partly traced.


.. confval:: AS.logAnonymousIP

   Default: ``false``

   Type: *boolean*

   Log only parts of the IP to respect users privacy.


.. confval:: AS.logPurge

   Default: ``false``

   Type: *boolean*

   Whether to maintain a purge log file or not. Each purge
   operation will be logged.


.. confval:: AS.allow

   Type: *list:string*

   List of IPs which are allowed to access the caps\(s\) port.
   By default access is unrestricted.


.. confval:: AS.deny

   Type: *list:string*

   List of IPs which are not allowed to access the caps\(s\) port.
   By default access is unrestricted.


.. _AS.filebase:


.. note::

   **AS.filebase.\***
   *File buffer control parameters*


.. confval:: AS.filebase.logFile

   Type: *path*

   The path to the archive log file which contains the
   stream start and end times. By default it is written
   to \$filebase\/archive.log.


.. confval:: AS.filebase.keep

   Default: ``*.*.*.*:-1``

   Type: *list:string*

   Number of days to keep data per stream ID before
   \"AS.filebase.purge.referenceTime\". For
   stream\-specific configuration create a list of pairs
   consisting of stream ID : days. Separate pairs by
   comma. The first occurrence in the list takes priority.
   
   Example keeping all streams but AM.\* and GR.\* for 14 days:
   
   GR.\*:\-1, AM.\*.\*.\*:365, \*.\*.\*.\*:14
   
   Default \(empty parameter\) or \-1: keep all data forever.


.. confval:: AS.filebase.preallocationSize

   Default: ``65535``

   Unit: *B*

   Type: *int*

   Preallocation size of data files in bytes. Some file system allow to reserve
   disk space for files in advance. Especially on spinning disks the read
   performance will be improved if data can be read sequentially. The speed is
   traded for disk space consumed by the file since its size will be a multiple
   of the specified value. Set the value to 0 to disable this feature.


.. _AS.filebase.cache:


.. note::

   **AS.filebase.cache.\***
   *CAPS does not keep all files of all streams open. It*
   *tries to keep open the most frequently used files and closes*
   *all others. The more files CAPS can keep open the faster*
   *the population of the archive. The limit of open*
   *files depends on the security settings of the user under*
   *which CAPS is running.*


.. confval:: AS.filebase.cache.openFileLimit

   Default: ``250``

   Type: *int*

   The maximum number of open files. Because a stream
   file can have an associated index file this value
   is half of the physically opened files in worst case.


.. confval:: AS.filebase.cache.unusedFileLimit

   Default: ``1000``

   Type: *int*

   Limit of cached files in total. This value affects also
   files that are actually explicitly closed by the
   application. CAPS will keep them open \(respecting
   the openFileLimit parameter\) as long as possible and
   preserve a file handle to speed up reopening the
   file later.


.. _AS.filebase.params:


.. confval:: AS.filebase.params.writeMetaOnClose

   Default: ``false``

   Type: *boolean*

   This is an optimization to write the datafile meta record only
   on file close and not every time a new record has been added
   to a file. To save IO bandwidth when handling many channels,
   this could be helpful.


.. confval:: AS.filebase.params.alignIndexPages

   Default: ``false``

   Type: *boolean*

   This forces to align index pages in the file at 4k boundaries.
   In order to achieve that, NULL chunks must be inserted to
   allow padding. This will lead to less device page updates
   but slightly larger data files.


.. confval:: AS.filebase.params.priority

   Default: ``0``

   Type: *int*

   A value greater than 0 will raise the write thread
   priority to the given value. This value is in
   accordance to the pthread_setschedparam function.


.. confval:: AS.filebase.params.q

   Default: ``1000``

   Type: *int*

   The real\-time notification queue size.


.. confval:: AS.filebase.params.concurrency

   Default: ``1``

   Type: *int*

   The number of concurrent writes to the database. The
   higher the value the more concurrent write operations
   are issued distributed across the files. A single file
   can only be updated sequentially. This value is most
   effective if many records of different channels are
   pushed, like the output of scmssort.


.. _AS.filebase.purge:


.. note::

   **AS.filebase.purge.\***
   *Parameters controlling IO resources occupied by the purge operation.*
   *The deletion of many data files at once may have a significant impact*
   *on the server performance. E.g. if the server did not run for a while*
   *or the keep parameter was reduced significantly, the purge operation*
   *may slow down the processing of real-time data.*


.. confval:: AS.filebase.purge.referenceTime

   Default: ``EndTime``

   Type: *string*

   Values: ``EndTime,Now``

   The reference time defining the end of the time window
   to keep the data. The window length is set by
   \"AS.filebase.keep\".
   Data outside the window will be purged. Available values:
   
   EndTime: The reference time is the end time per stream.
   This keeps older data if no more recent data arrive.
   
   Now: The reference time is current time. This
   deletes old data even if no recent data arrive.


.. confval:: AS.filebase.purge.idleTime

   Default: ``5``

   Unit: *s*

   Type: *double*

   Idle time between two purge runs.


.. confval:: AS.filebase.purge.initIdleTime

   Default: ``0``

   Unit: *s*

   Type: *double*

   Idle time before the first purge run starts. Normally
   after a start the server tries to catch up all data which
   might be an IO intensive operation. In case of a huge archive the purge
   operation slow downs the read\/write performace of the system too. To
   reduce the load at start it is a good idea to postpone this operation.


.. confval:: AS.filebase.purge.maxProcessTime

   Default: ``1``

   Unit: *s*

   Type: *double*

   Maximum processing time for one purge run. If exceeded the
   purge task will pause for AS.filebase.purge.idleTime
   seconds freeing IO resources.


.. confval:: AS.filebase.purge.startTime

   Default: ``00:30``

   Type: *string*

   Time of the day when to run the daily purge run. Time is in UTC.


.. _AS.SSL:


.. note::

   **AS.SSL.\***
   *Parameters for SSL-based data requests*


.. confval:: AS.SSL.port

   Type: *int*

   Defines the SSL server port for client requests. By default
   SSL requests are disabled.


.. confval:: AS.SSL.certificate

   Type: *string*

   Defines the path to the SSL certificate to use.


.. confval:: AS.SSL.key

   Type: *string*

   Defines the path to the private SSL key to use. This key
   is not shared with clients.


.. _AS.auth:


.. note::

   **AS.auth.\***
   *Parameters controlling the authentication system for data requests*
   *based on user ID, IP addresses, access roles and access control lists.*


.. confval:: AS.auth.backend

   Default: ``basic``

   Type: *string*

   The server provides an authentication plug\-in interface. An authentication plugin
   implements access control checks. It is free where it gets the access information from e.g
   from a local database\/file or a remote server. The option sets which authentication plugin
   should be used for authentication. Don't forget to load the plugin in the plugin section.
   The basic plugin is built\-in.


.. _AS.auth.basic:


.. note::

   **AS.auth.basic.\***
   *Basic authentication parameters. The configuration can*
   *be reloaded without restarting the server. Use*
   *"seiscomp reload caps`" to reload the*
   *authentication parameters without a restart.*


.. confval:: AS.auth.basic.access-list

   Default: ``@SYSTEMCONFIGDIR@/caps/access.cfg``

   Type: *file*

   Path to the access control list controlling access based on rules.
   By default access is unrestricted. Allow rules are evaluated first.
   
   AM.DENY \= 127.0.0.1
   
   AM.ALLOW \= 127.0.0.1
   
   This example rule set prohibits all AM network stations for localhost because
   the DENY rule is evaluated after the ALLOW rule.
   
   IP restrictions apply to the guest user only. In addition to IPs the access can
   be also restricted by user or group. In the latter case
   the \"%\" must be placed in front of the group name. Here an example:
   
   AM.ALLOW \= %users
   
   AM.R44F5.ALLOW \= sysop
   
   Rules are evaluated on the basis of one another. This can lead to misunderstandings. Here an
   example:
   
   AM.ALLOW \= sysop
   
   This rule will allow the AM network for sysop only. But
   
   DENY \= %users
   AM.ALLOW \= sysop
   
   will allow the access to the AM network for all users except those are member of the group users.


.. _AS.auth.basic.users:


.. confval:: AS.auth.basic.users.shadow

   Default: ``@SYSTEMCONFIGDIR@/caps/shadow.cfg``

   Type: *file*

   Location of the users authentication file. For each user one line
   of the following format must exist:
   
   username:encrypted_pwd
   
   To encrypt the password mkpasswd can be used. It is recommended to
   apply a strong algorithm such as sha\-256 or sha\-512. The command
   
   u\=sysop pw\=`mkpasswd \-m sha\-512` \&\& echo \$u:\$pw
   
   generates one line for user \"sysop\".
   Add the line to the authentication file.


.. confval:: AS.auth.basic.users.passwd

   Default: ``@SYSTEMCONFIGDIR@/caps/passwd.cfg``

   Type: *file*

   Location of the users access control file. Each
   line starts with a user ID \(uid\) or a group ID \(gid\)
   and a list of access properties in the form:
   
   uid:prop1,prop2
   
   or
   
   %gid:prop1,prop2
   
   \"%\" indicates a gid instead of a uid.
   The properties grant access to certain CAPS
   features. Supported access property values are:
   read, write, admin.


.. confval:: AS.auth.basic.users.group

   Default: ``@SYSTEMCONFIGDIR@/caps/group.cfg``

   Type: *file*

   Location of the optional group file. Each line maps a group id
   to a list of users in format
   
   gid:user1,user2,user3


.. _AS.plugins:


.. confval:: AS.plugins.port

   Default: ``18003``

   Type: *int*

   Defines the server port to use for plugin connections.


.. confval:: AS.plugins.allow

   Type: *list:string*

   List of IPs which are allowed to access the plugin port.
   By default access is unrestricted.


.. confval:: AS.plugins.deny

   Type: *list:string*

   List of IPs which are not allowed to access the plugin port.
   By default access is unrestricted.


.. _AS.plugins.SSL:


.. confval:: AS.plugins.SSL.port

   Type: *int*

   Defines the SSL server port to use for plugin SSL connections.
   The SSL port is disabled by default.


.. confval:: AS.plugins.SSL.certificate

   Type: *string*

   Defines the path to the SSL certificate to use.


.. confval:: AS.plugins.SSL.key

   Type: *string*

   Defines the path to the private SSL key to use. This key
   is not shared with clients.


.. _AS.http:


.. note::

   **AS.http.\***
   *Web interface control parameters*


.. confval:: AS.http.port

   Type: *int*

   Defines the server port for HTTP connections. By default the Web interface is disabled.
   
   Typical value: 18081


.. confval:: AS.http.allow

   Type: *list:string*

   List of IPs which are allowed to access the http\(s\) port.
   By default access is unrestricted.


.. confval:: AS.http.deny

   Type: *list:string*

   List of IPs which are not allowed to access the http\(s\) port.
   By default access is unrestricted.


.. confval:: AS.http.resolveProxyClient

   Default: ``false``

   Type: *boolean*

   Sets if the X\-Forwarded\-For HTTP header is evaluated to
   retrieve the real client IP address from a proxy server.
   This is important if the web frontend is behind a proxy,
   e.g. Apache. Since data access is configured per IP, the
   real IP is required to grant access to requested channels.
   Enabling this opens a possible security hole as clients
   can then easily spoof their IP if the proxy does not
   correctly maintain this header or if CAPS does not run
   behind a proxy.


.. confval:: AS.http.disableBasicAuthorization

   Default: ``false``

   Type: *boolean*

   Controls whether basic authorization is enabled or not.
   In case you are running CAPS behind a proxy which already
   configures basic authorization then enable this flag.
   If basic authorization is disabled then the default
   HTTP user should have access without a password.


.. confval:: AS.http.fdsnws

   Type: *string*

   Sets the optional relative FDSNWS path which is being
   used by the CAPS frontend client. Do not append
   \"fdsnws\/dataselect\/1\/query\" as this is done
   automatically. Set it to \"\/\" if the CAPS
   frontend is running with a relative path behind e.g.
   Nginx.


.. _AS.http.SSL:


.. note::

   **AS.http.SSL.\***
   *Use https instead of http when setting the following parameters*


.. confval:: AS.http.SSL.port

   Type: *int*

   Defines the server port for HTTPS connections.
   By default the SSL Web interface is disabled.


.. confval:: AS.http.SSL.certificate

   Type: *string*

   Defines the path to the SSL certificate to use.


.. confval:: AS.http.SSL.key

   Type: *string*

   Defines the path to the private SSL key to use. This
   key is not shared with clients.


.. _AS.FDSNWS:


.. note::

   **AS.FDSNWS.\***
   *FDSNWS control parameters for dataselect. The FDSNWS service*
   *is provided through the "AS.http.port".*


.. confval:: AS.FDSNWS.maxTimeWindow

   Default: ``0``

   Unit: *s*

   Type: *int*

   Maximum length of time window per request. A value
   greater than zero limits the maximum request time window
   including all data. 0 disables the limit.


.. confval:: AS.FDSNWS.maxRequests

   Default: ``1000``

   Type: *int*

   Maximum number of requests per post. A value greater than
   or equal to zero limits the number
   of request lines per POST request.


.. _AS.WWS:


.. note::

   **AS.WWS.\***
   *Winston waveform server (WWS) control parameters. When set,*
   *CAPS will also serve WWS.*


.. confval:: AS.WWS.port

   Type: *int*

   Server port for WWS connections. Please note that
   inventory information \(see AS.inventory\) is required to
   fully support WWS requests otherwise empty values for
   the channel location and unit will be returned.
   
   Default \(no value\): The WWS interface is disabled.


.. confval:: AS.WWS.maxTimeWindow

   Default: ``90000``

   Unit: *s*

   Type: *int*

   Maximum length of time window in seconds per request.
   A value greater than zero limits the maximum request time window
   including all data. 0 disables the limit.


.. confval:: AS.WWS.maxRequests

   Default: ``100``

   Type: *int*

   A value greater than or equal to zero limits the number
   of request lines per POST request.


.. confval:: AS.WWS.allow

   Type: *list:string*

   List of IPs which are allowed to access the WWS port.
   By default access is unrestricted.


.. confval:: AS.WWS.deny

   Type: *list:string*

   List of IPs which are not allowed to access the WWS port.
   By default access is unrestricted.




Command-Line Options
====================

:program:`caps [options]`

.. _Generic:


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:


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.


.. _Server:


Server
------

.. option:: -p, --server-port int

   Overrides configuration parameter :confval:`AS.port`.


.. option:: --server-ssl-port int

   Overrides configuration parameter :confval:`AS.SSL.port`.


.. option:: -P, --plugin-port int

   Overrides configuration parameter :confval:`AS.plugins.port`.


.. option:: --http-port int

   Overrides configuration parameter :confval:`AS.http.port`.


.. option:: --read-only

   Do not store any packets.


.. _Test:


Test
----

.. option:: --configtest

   Run a configuration file syntax test. It parses the
   configuration files and either reports Syntax Ok or detailed
   information about the particular syntax error.

.. option:: --print-access

   Print access information for one or more channels from a
   given IP and a user with password, format: NET.STA.LOC.CHA,
   e.g.,
   
   IP check
   
   caps \-\-print\-access GE.\*.\*.\* 127.0.0.1
   
   IP and user:password check
   
   caps \-\-print\-access GE.APE.\*.\* \-\-user gempa:gempa 127.0.0.1
   
   The stream ID filter supports wildcards. Use option \-v to
   enable the trace mode to get detailed information about the
   rule evaluation.

.. option:: -u, --user

   Server user and password. Format: user:password .


