.. _sec-caps-config: Execution and Automatic Startup =============================== |appname| uses the |scname| infrastructure for startup, configuration and logging. Please refer to the |scname| `documentation `_ 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 ``~/.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 ``--debug`` switch: .. code-block:: sh seiscomp stop caps seiscomp exec caps --debug File System Tuning ================== Depending on the number of streams :term:`CAPS` should handle there are some settings which can improve the IO 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 :file:`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` and :ref:`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`. In addition :ref:`read and write permission` 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`, configuration prefix: ``AS.plugin`` * Client - Default CAPS client protocol, e.g. used by the :ref:`CAPS recordstream` or by the :ref:`capstool`, configuration prefix: ``AS`` * HTTP - :ref:`Administrative web interface` and :ref:`FDSNWS dataselect service`, 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` file or the special id ``all``. * ``GROUP`` is a user group definition from the :ref:`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 ` 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` in which case access is authorized against the client IP. The guest user may be assigned to a :ref:`user group ` and its :ref:`access properties` may be defined. Anonymous access may be disabled through IP-based DENY rules in the :ref:`access control` 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` followed by an asterisk indicating an empty password. Optionally :ref:`stream specific 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` * 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` file or the special id ``guest`` Example: .. code-block:: properties group1: user1, user2 A group may by referenced by the :ref:`access control` 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`, 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` file or one of the special ids ``all`` or ``guest``. * ``GROUP`` is a user group definition from the :ref:`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 `. By default read and write permissions are granted to the :ref:`guest user` 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