436 lines
14 KiB
ReStructuredText
436 lines
14 KiB
ReStructuredText
.. _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
|