caps¶
Realtime and archive waveform server
Module Configuration¶
etc/defaults/global.cfg
etc/defaults/caps.cfg
etc/global.cfg
etc/caps.cfg
~/.seiscomp/global.cfg
~/.seiscomp/caps.cfg
caps inherits global options.
Note
Modules/plugins may require a license file. The default path to license
files is @DATADIR@/licenses/
which can be overridden by global
configuration of the parameter gempa.licensePath
. Example:
gempa.licensePath = @CONFIGDIR@/licenses
Note
AS.* CAPS server control parameters
-
AS.filebase
¶ Type: string
Defines the path to the archive directory. Default is
@ROOTDIR@/var/lib/caps/archive
.
-
AS.port
¶ Type: int
Defines the server port for client requests. Default is
18002
.
-
AS.clientBufferSize
¶ Type: int
Unit: B
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. Default is
16384
.
-
AS.minDelay
¶ Type: int
Unit: s
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. Default is
-1
.
-
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.
-
AS.logRequests
¶ Type: boolean
Whether to maintain a request log file or not. Each request will be logged and partly traced. Default is
false
.
-
AS.logAnonymousIP
¶ Type: boolean
Log only parts of the IP to respect users privacy. Default is
false
.
-
AS.logPurge
¶ Type: boolean
Whether to maintain a purge log file or not. Each purge operation will be logged. Default is
false
.
-
AS.allow
¶ Type: list:string
List of IPs which are allowed to access the caps(s) port. By default access is unrestricted.
-
AS.deny
¶ Type: list:string
List of IPs which are not allowed to access the caps(s) port. By default access is unrestricted.
Note
AS.filebase.* File buffer control parameters
-
AS.filebase.keep
¶ Type: list:string
Number of days to keep data per stream ID before AS.filebase.purge.referenceTime. For stream-specifc configuration create a list of pairs consisting of stream ID : days. Separate pairs by comma. The first occurence 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. Default is
*.*.*.*:-1
.
-
AS.filebase.preallocationSize
¶ Type: int
Unit: B
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. Default is
65535
.
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.
-
AS.filebase.cache.openFileLimit
¶ 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. Default is
250
.
-
AS.filebase.cache.unusedFileLimit
¶ 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. Default is
1000
.
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.
-
AS.filebase.purge.referenceTime
¶ Type: string
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. Default is
EndTime
.
-
AS.filebase.purge.idleTime
¶ Type: double
Unit: s
Idle time between two purge runs. Default is
5
.
-
AS.filebase.purge.initIdleTime
¶ Type: double
Unit: s
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. Default is
0
.
-
AS.filebase.purge.maxProcessTime
¶ Type: double
Unit: s
Maximum processing time for one purge run. If exceeded the purge task will pause for AS.filebase.purge.idleTime seconds freeing IO resources. Default is
1
.
Note
AS.SSL.* Parameters for SSL-based data requests
-
AS.SSL.port
¶ Type: int
Defines the SSL server port for client requests. By default SSL requests are disabled.
-
AS.SSL.certificate
¶ Type: string
Defines the path to the SSL certificate to use.
-
AS.SSL.key
¶ Type: string
Defines the path to the private SSL key to use. This key is not shared with clients.
Note
AS.auth.* Parameters controlling the authentication system for data requests based on user ID, IP addresses, access roles and access control lists.
-
AS.auth.backend
¶ 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. Default is
basic
.
Note
AS.auth.basic.* Basic authentication parameters. The configuration can be reloaded without restarting the server. Use “kill -SIGUSR1 `pidof caps`” to trigger the reload from outside.
-
AS.auth.basic.access-list
¶ 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. Default is
@SYSTEMCONFIGDIR@/caps/access.cfg
.
-
AS.auth.basic.users.shadow
¶ 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. Default is
@SYSTEMCONFIGDIR@/caps/shadow.cfg
.
-
AS.auth.basic.users.passwd
¶ 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 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. Currently supported property values are:
read
write Default is
@SYSTEMCONFIGDIR@/caps/passwd.cfg
.
-
AS.auth.basic.users.group
¶ 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 Default is
@SYSTEMCONFIGDIR@/caps/group.cfg
.
-
AS.plugins.port
¶ Type: int
Defines the server port to use for plugin connections. Default is
18003
.
-
AS.plugins.allow
¶ Type: list:string
List of IPs which are allowed to access the plugin port. By default access is unrestricted.
-
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.port
¶ Type: int
Defines the SSL server port to use for plugin SSL connections. The SSL port is disabled by default.
-
AS.plugins.SSL.certificate
¶ Type: string
Defines the path to the SSL certificate to use.
-
AS.plugins.SSL.key
¶ Type: string
Defines the path to the private SSL key to use. This key is not shared with clients.
Note
AS.http.* Web interface control parameters
-
AS.http.port
¶ Type: int
Defines the server port for HTTP connections. By default the Web interface is disabled.
Typical value: 18081
-
AS.http.allow
¶ Type: list:string
List of IPs which are allowed to access the http(s) port. By default access is unrestricted.
-
AS.http.deny
¶ Type: list:string
List of IPs which are not allowed to access the http(s) port. By default access is unrestricted.
-
AS.http.resolveProxyClient
¶ 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. Default is
false
.
-
AS.http.disableBasicAuthorization
¶ 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. Default is
false
.
Note
AS.http.SSL.* Use https instead of http when setting the following parameters
-
AS.http.SSL.port
¶ Type: int
Defines the server port for HTTPS connections. By default the SSL Web interface is disabled.
-
AS.http.SSL.certificate
¶ Type: string
Defines the path to the SSL certificate to use.
-
AS.http.SSL.key
¶ Type: string
Defines the path to the private SSL key to use. This key is not shared with clients.
Note
AS.WS.* Websocket configuration. The websocket protocol is opened via HTTP requests but different in it’s general handling. The websocket interface implements the standard telnet CAPS protocol but returns JSON data instead of text messages for system requests such as the info request.
-
AS.WS.port
¶ Type: int
Defines the server port for HTTP connections. By default the Web interface is disabled. Default is
-1
.
-
AS.WS.SSL.port
¶ Type: int
Defines the server port for HTTPS connections. By default the SSL Web interface is disabled. Default is
-1
.
Note
AS.FDSNWS.* FDSNWS control parameters
-
AS.FDSNWS.maxTimeWindow
¶ Type: int
Unit: s
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. Default is
0
.
-
AS.FDSNWS.maxRequests
¶ 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. Default is
1000
.
Note
AS.WWS.* Winston waveform server (WWS) control parameters
-
AS.WWS.port
¶ Type: int
Server port for WWS connections.
Default (no value): The WWS interface is disabled.
-
AS.WWS.maxTimeWindow
¶ Type: int
Unit: s
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. Default is
90000
.
-
AS.WWS.maxRequests
¶ Type: int
A value greater than or equal to zero limits the number of request lines per POST request. Default is
100
.
-
AS.WWS.allow
¶ Type: list:string
List of IPs which are allowed to access the WWS port. By default access is unrestricted.
-
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¶
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, e.g. 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 &.
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
-
--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.
-
--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
-
--trace
¶
Trace mode: –verbosity=4 –console=1 –print-component=1 –print-context=1
-
--log-file
arg
¶ Use alternative log file.
Server¶
-
--server-ssl-port
int
¶ Overrides configuration parameter
AS.SSL.port
.
-
-P
,
--plugin-port
int
¶ Overrides configuration parameter
AS.plugins.port
.
-
--http-port
int
¶ Overrides configuration parameter
AS.http.port
.