NOAA/seiscomp-training
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[installation] Init with inital config for global

Browse Source
This commit is contained in:
Dirk Rössler
2025-10-30 15:08:17 +01:00
commit 7640b452ed
3678 changed files with 2200095 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
share/doc/caps/html/_sources/base/configuration.rst.txt Normal file
View File

@ -0,0 +1,435 @@
.. _sec-caps-config:
Execution and Automatic Startup
===============================
|appname| uses the
|scname| infrastructure for startup, configuration and logging. Please refer to
the |scname| `documentation <http://docs.gempa.de/seiscomp/current>`_ for a
comprehensive description of |scname|.
Figure :num:`fig-scconfig` shows a screen shot of ``scconfig``, which
is the central |scname| GUI allowing to configure, start and monitor the
|appname| server.
.. _fig-scconfig:
.. figure:: media/scconfig.png
:width: 18cm
:align: center
scconfig: |scname| utility allowing to configure, start and monitor :term:`CAPS`.
On the command line the following sequence may be used to enable, start and
monitor the |appname|:
.. code-block:: sh
seiscomp enable caps
seoscomp start caps
seiscomp check caps
Dependent on the configured log level :term:`CAPS` will log to
:file:`~/.seiscomp/log/caps`. For debugging purposes it is a good practice to
stop the :term:`CAPS` background process and run it in the foreground using
the :option:`--debug` switch:
.. code-block:: sh
seiscomp stop caps
seiscomp exec caps --debug
File System Tuning
==================
Depending on the number of streams a :term:`CAPS` server handles a number of
settings can improve the I/O throughput and overall performance. Since
channel data are organized in an archive structure where each stream is written
into a dedicated file, CAPS needs to open and close a lot of files if thousands
of streams are fed into it. In the default configuration CAPS caches up to
250 open files for later reuse. An open file here is not only the data file
for the CAPS stream but might also include the index file if records have
been received out-of-order. So in the default configuration CAPS need to open
500 file at the same time.
Operating systems control the maximum number of open file descriptors a process
might hold. Often a default value is 1024. If the maximum open files in CAPS
should be increased to 2000 (assuming CAPS manages 2000 streams) then the
limit for the user who runs CAPS should be increased to at least 4000. In
many Linux distributions :program:`ulimit` can be used for that.
Furthermore CAPS requires file descriptors for incoming connections. Each
active connection holds a socket descriptor for network communication and
a file descriptor (or two if index files are present) for reading data.
Depending on the number of concurrent connections one is expecting, it would
be safe to add this number times three to the user limit in the operating
system.
Example for 2000 streams:
.. code-block:: properties
# The maximum number of open files managed by CAPS.
# 2000 + margin
AS.filebase.cache.openFileLimit = 2100
.. code-block:: sh
# Set ulimit to 7500 files: 2100 * 2 + 1000 * 3 (network)
$ ulimit -n 7200
.. _sec-caps-security:
Security and Access Control
===========================
.. _sec-conf-access:
Access control
--------------
:term:`CAPS` provides access control on the
:ref:`service<sec-conf-access-serv>` and :ref:`stream<sec-conf-access-stream>`
level. On the service level access can be granted by client IP, on the stream
level by client IP or user/group name obtained during
:ref:`authentication<sec-conf-access-auth>`. In
addition :ref:`read and write permission<sec-conf-access-passwd>` may be
granted for individual users and groups. The configuration is described in the
following sections.
.. _sec-conf-access-serv:
Service level access
~~~~~~~~~~~~~~~~~~~~
Service level access is defined in the main caps configuration file, e.g.
``@SYSTEMCONFIGDIR@/caps.cfg``
The following services are availble:
* Plugin - Incoming data send by :ref:`CAPS plugins<sec-caps-plugins>`,
configuration prefix: ``AS.plugin``
* Client - Default CAPS client protocol, e.g. used by the
:ref:`CAPS recordstream<sec-caps-recstream>` or by the :ref:`capstool`,
configuration prefix: ``AS``
* HTTP - :ref:`Administrative web interface<sec-caps-web-interface>` and
:ref:`FDSNWS dataselect service<sec-caps-fdsnws>`, configuration prefix:
``AS.http``
* WWS - :ref:`sec-caps-wws`, configuration prefix: ``AS.WWS``
For each sevice access can be granted on IP level through allow and deny rule
sets. By default no restrictions are in place. If an allow rule is present
access is only granted to matching IPs. Deny rules may be used to override a
subset of the IP range defined in the allow set.
The formal definition of a rule is:
``IP_MASK[, IP_MASK[, ...]]``
where ``IP_MASK`` may be a single address or a subnet described by a network
mask.
Using the HTTP service as an example the configuration options
are ``AS.http.allow`` and ``AS.http.deny``.
Example:
.. code-block:: properties
AS.http.allow = 192.168.1.0/24
AS.http.deny = 192.168.1.42
These rules provide access to the HTTP service for all clients of the
192.168.1.0/24 subnet except for the IP 192.168.1.42.
.. _sec-conf-access-stream:
Stream level access
~~~~~~~~~~~~~~~~~~~
Stream level access is controlled by an access file defined by
``AS.auth.basic.access-list``.
Each line of the file consists of a ALLOW or DENY rule. The formal definition of
one rule is:
``STREAMID.ALLOW|DENY= IP_MASK|USER|%GROUP[, IP_MASK|USER|%GROUP[, ...]]``
where
* ``STREAMID`` is defined as: ``[NET[.STA[.LOC[.CHA]]]]``. Regular expressions
are not supported.
* ``USER`` is a user account defined in the :ref:`shadow<sec-conf-access-auth>`
file or the special id ``all``.
* ``GROUP`` is a user group definition from the :ref:`group<sec-conf-access-group>`
file. A ``%`` must be placed before the group name to distinguish it from
a user.
.. note::
For access control, two cases must be distinguished:
1. Client access without username and password
All client sessions have guest permissions when no login credentials are provided. By default
data can be read and written. The guest account can be restricted by IP rules only. Please have in
mind that for instance the rule DENY=all does not have any effect here.
2. Client access with username and password
In this case user rules will be evaluated only and IP restrictions have no effect. In addition
user rules does not apply to the guest user. This leads to that DENY=all prohibits access for
all users except the guest user. If the access should be denied for all users the following rule
must be used: DENY=all, 0.0.0.0/0.
This leads to that the rule DENY = all prohibits data access for all users but anonymous logins can still access data. If guest access should also be prohibited the rule must be extended by an IP address.
By default access is unrestricted. If a stream ID is not matched by any access
rule then access will be granted. This behavior is different from the service
level access where an allow rule will implicitly revoke access to any non
matching IP.
To restrict access by default you may add a global DENY rule which references no
stream id and which matches all IP addresses and all users using the special
user id ``all``:
.. code-block:: properties
DENY = 0.0.0.0/0, all
The rules in the access file are evaluated independent of the order in which
they are defined. A rule with more stream id components overrules a more generic
line. E.g., considering a request from the local machine the following rule set
would
* grant access to all networks except for AM
* grant access to station AM.R0000 except for the stream 00.ENN stream
.. code-block:: properties
AM.DENY = 127.0.0.1
AM.R0000.ALLOW = 127.0.0.1
AM.R0000.00.ENN.DENY = 127.0.0.1
The client IP is **only** evaluated in the absence of user authentication. E.g., the
following rule would block access to any anonymous user but still grant access
to any authenticated user:
.. code-block:: properties
DENY = 0.0.0.0/0
Please refer to :ref:`sec-conf-access-user-serv` for a definition of service
specific users.
The following example shows how anonymous access by IP and access by user name
may be combined:
.. code-block:: properties
AM.DENY = 0.0.0.0/0, all
AM.ALLOW = 127.0.0.1, %group1, user1
AM.R0000.ALLOW = user2
AM.R0000.DENY = user1
The example above
* grants access to anybody except for the AM network
* grants access to the AM network for
* anonymous users on the same machine
* users belonging to the ``group1`` group
* the user ``user1``
* in addition grants access to the station AM.R0000 to the user ``user2`` while
local anonymous users and authenticated users of the ``group1`` would still
have access
* explicitly denies access to station AM.R0000 for ``user1``
The stream level access can be tested and debugged on the command line by
specifying a stream and (optionally) an IP to test for:
.. code-block:: sh
$ caps -v --print-access AM.R0000.00.ENN 1.2.3.4
.. _sec-conf-access-auth:
Authentication by user name and password (shadow file)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Authentication can be used, e.g. together with the :ref:`capss RecordStream <sec-caps-recstream>`
or :ref:`capstool`.
It is performed against a shadow file defined by
``AS.auth.basic.users.shadow``. It contains the user name and password information
for the user accounts. Each line consist of a user name and password hash
separated by a colon (``:``). The formal definition of one line is:
``USER:PWD_HASH``.
To encrypt a password ``mkpasswd`` can be used. It is recommended to apply a
strong algorithm such as sha-256 or sha-512. The command
.. code-block:: sh
$ user=sysop pw=`mkpasswd -m sha-512` && echo $user:$pw
generates a password hash for user sysop.
An empty password is represented by an asterisk (``*``).
Example:
.. code-block:: properties
# The user name is equal to the password
user1:$6$mZM8gpmKdF9D$wqJo1HgGInLr1Tmk6kDrCCt1dY06Xr/luyQrlH0sXbXzSIVd63wglJqzX4nxHRTt/I6y9BjM5X4JJ.Tb7XY.d0
user2:$6$zE77VXo7CRLev9ly$F8kg.MC8eLz.DHR2IWREGrSwPyLaxObyfUgwpeJdQfasD8L/pBTgJhyGYtMjUR6IONL6E6lQN.2QLqZ5O5atO/
FDSNWS:*
.. _sec-conf-access-guest:
Guest user
~~~~~~~~~~
The CAPS server ships with a pre-configured anonymous user identified by
``guest``. It may be used during login at the
:ref:`web interface<sec-caps-web-interface>` in which case access is authorized
against the client IP.
The guest user may be assigned to a :ref:`user group <sec-conf-access-group>`
and its :ref:`access properties<sec-conf-access-passwd>` may be defined.
Anonymous access may be disabled through IP-based DENY rules in the
:ref:`access control<sec-conf-access-stream>` list file.
.. _sec-conf-access-user-serv:
Service-specific users
~~~~~~~~~~~~~~~~~~~~~~
For some services it might be desirable to disable the authentication entirely.
This can be archived by adding one of the special service specific users to the
:ref:`shadow file<sec-conf-access-auth>` followed by an asterisk indicating
an empty password. Optionally :ref:`stream specific access<sec-conf-access>`
can be granted or revoked to this user as well. The flowing users are available
for the individual services:
* HTTP - Access to the :ref:`web interface<sec-caps-web-interface>`
* FDSNWS - Access to :ref:`sec-caps-fdsnws` dataselect service served through
the HTTP protocol (``/fdsnws/dataselect/1/query``)
* WWS - Access to the :ref:`sec-caps-wws` Protocol
.. _sec-conf-access-group:
Groups
~~~~~~
A group file, defined by ``AS.auth.basic.users.group``, allows to assign users
to groups. Each line of the file consists of a group name followed by a user
list. The formal definition of one rule is:
``GROUP: USER[, USER[, ...]]``
where
* ``GROUP`` is the name of the new group definition
* ``USER`` is a user account defined in the :ref:`shadow<sec-conf-access-auth>`
file or the special id ``guest``
Example:
.. code-block:: properties
group1: user1, user2
A group may by referenced by the
:ref:`access control<sec-conf-access-stream>` or
:ref:`sec-conf-access-passwd` file. In both cases a ``%`` prefix is required to
distinguish it from a user name.
.. _sec-conf-access-passwd:
Passwd: user access properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In addition to :ref:`authentication by user name and password<sec-conf-access-stream>`,
user access control properties can be set in a
passwd file defined by ``AS.auth.basic.users.passwd``. The formal definition of
a line is
``USER|%GROUP:PROP[, PROP[, ...]]``
where
* ``USER`` is a user account defined in the :ref:`shadow<sec-conf-access-auth>`
file or one of the special ids ``all`` or ``guest``.
* ``GROUP`` is a user group definition from the :ref:`group<sec-conf-access-group>`
file. A ``%`` must be placed before the group name to distinguish it from
a user.
* ``PROP`` is a property granted to the user or group. The following properties
are currently supported:
* read - Grants permission to request data from the server
* write - Grants permission to store data into the server
* admin - Grants permission to request server statistics and the view server
statistics on the :ref:`server website <sec-caps-web-interface>`.
By default read and write permissions are granted to the
:ref:`guest user<sec-conf-access-guest>` and all authenticated users not
listed in this file.
The following example changes this and revokes read and write permissions per
default. Read access is provided to anonymous and users belonging to the
``group1`` while write access is only granted to ``user1``.
.. code-block:: properties
all:
guest: read
%group1: read
user1: read,write
.. _sec-conf-ssl:
Secure sockets layer (SSL)
--------------------------
The Secure Sockets Layer (SSL) is a standard for establishing a secured
communication between applications using insecure networks. Neither client
requests nor server responses are readable by communication hubs in between. SSL
is based on a public-key infrastructure (PKI) to establish trust about the
identity of the communication counterpart. The concept of a PKI is based on
public certificates and private keys.
The following example illustrates how to generate a self-signed certificate
using the OpenSSL library:
.. code-block:: sh
$ openssl req -new -x509 -sha512 -newkey rsa:4096 -out caps.crt -keyout caps.key -nodes
The last parameter ``-nodes`` disables the password protection of the private
key. If omitted, a password must be defined which will be requested when
accessing the private key. :term:`CAPS` will request the password on the command
line during startup.
To enable SSL in :term:`CAPS` the ``AS.SSL.port`` as well as the location of the
``AS.SSL.certificate`` and ``AS.SSL.key`` file must be specified.
Optionally the unencrypted ``AS.port`` may be deactivated by setting a value
of ``-1``.
.. include:: /apps/caps.rst
:start-line: 10