.. highlight:: rst

.. _scmaster:

########
scmaster
########

**The messaging system**


Description
===========

scmaster is the implementation of the :ref:`messaging <concepts_messaging>`
mediator.


.. _section-scmaster-groups:

Message Groups
==============

scmaster provides the :ref:`message groups <messaging-groups>`. Configure

* :confval:`defaultGroups`: Add the groups which can be used by all queues.
* :confval:`queues.$name.groups`: Set all groups which are used by the given
  queue. You may inherit :confval:`defaultGroups`, e.g.: ::

     queues.production.groups = ${defaultGroups},L1PICK

  .. warning ::

     Setting any value without inheriting :confval:`defaultGroups` ignores all
     values of :confval:`defaultGroups`.


Queues
======

scmaster provides *queues* for separating the processing.
Typically, the default queue *production* is used. To add new queues

#. Define a new queue by adding a new profile with some name,
#. Configure the profile parameters :confval:`queues.$name.*`,
#. Register the queue in :confval:`queues`.


Scheme
======

scmaster provides unsecured and secured connection which is addressed by the
scheme values *scmp* and *scmps*, respectively, in :confval:`connection.server`
when connecting to the messaging.
Read the :ref:`concepts section <messaging-scheme>` for more details. *scmps*
is in use when configuring :confval:`interface.ssl.bind`.


Database Access
===============

scmaster reads from and writes to the database and reports the database connection
to the clients of the messaging system (compare with the :ref:`concepts section <messaging-db>`).

The database is configured per queue.


Single Machine
--------------

When running all |scname| modules on a single machine, the read and write
parameters are typically configured with *localhost* as a *host name*.

Example: ::

   queues.production.processors.messages.dbstore.read = sysop:sysop@localhost/seiscomp
   queues.production.processors.messages.dbstore.write = sysop:sysop@localhost/seiscomp


Multiple Machines
-----------------

If the clients are located on machines different from the messaging, the
*host name* of the read parameter
must be available on the client machine and the client machine must be able to
connect to the host with its name. If the database is on the same machine as the
messaging, the *host name* of the write connection typically remains *localhost*.

Example for connecting clients on computerB to the messaging on computerA (compare
with the :ref:`concepts section <messaging-distribution>`).

* Configuration of scmaster on computerA: ::

     queues.production.processors.messages.dbstore.read = sysop:sysop@computerA/seiscomp
     queues.production.processors.messages.dbstore.write = sysop:sysop@localhost/seiscomp

* Global configuration of client on computerB: ::

     connection.server = computerA/production

Database Proxy
--------------

scmaster can accept database requests and forward results to clients without
exposing the underlying database. That allows clients to connect to the database
of a particular queue via the Websocket HTTP protocol. No specific database
plugin is required at the client which reduces the complexity of configuration.

Be aware that due to the nature of a proxy which is another layer on top of the
actual database connection the performance is not as high as direct database
access.

To let scmaster return the proxy address of the database connection, set

.. code::

   queues.production.processors.messages.dbstore.proxy = true

in the configuration file.


Access Control
==============

scmaster does not provide any built-in access control to connecting clients.
The only exception is the possibility to verify client certificates against
the server certificate if SSL is enabled.

.. code::

   interface.ssl.verifyPeer = true

It is required that the client certificate is signed by the server certificate
otherwise the client connection will be rejected.


.. _scmaster_configuration:

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

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

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



.. confval:: defaultGroups

   Default: ``AMPLITUDE, PICK, LOCATION, MAGNITUDE, FOCMECH, EVENT, QC, PUBLICATION, GUI, INVENTORY, CONFIG, LOGGING, SERVICE_REQUEST, SERVICE_PROVIDE, STATUS_GROUP``

   Type: *list:string*

   The default set of message groups for each queue. Only used
   if a queues group list is unset \(note: empty is not unset\).


.. confval:: queues

   Default: ``production, playback``

   Type: *list:string*

   Enable messaging queues defined as profile in queues. The profile
   names are the final queue names.


.. note::
   **interface.\***
   *Control the messaging interface. The default protocol is*
   *"scmp" but "scmps" (secure protocol) is*
   *used when valid SSL certificate and key are configured.*



.. confval:: interface.bind

   Default: ``0.0.0.0:18180``

   Type: *ipbind*

   Local bind address and port of the messaging system.
   0.0.0.0:18180 accepts connections from all clients,
   127.0.0.1:18180 only from localhost.


.. confval:: interface.acl

   Type: *list:ipmask*

   The IP access control list for clients which are allowed
   to connect to the interface. Separate each IP with a space
   and put the entire list in double quotes, e.g.
   \"127.0.0.1 192.168.1.2 192.168.0.0\/16\".


.. confval:: interface.socketPortReuse

   Default: ``true``

   Type: *boolean*

   SO_REUSEADDR socket option for the TCP listening socket.


.. note::
   **interface.ssl.\***
   *SSL encryption is used if key and certificate are configured.*



.. confval:: interface.ssl.bind

   Default: ``0.0.0.0:-1``

   Type: *ipbind*

   Additional local bind address and port of the messaging
   system in case SSL encryption is active.


.. confval:: interface.ssl.acl

   Type: *list:ipmask*

   The IP access control list for clients which are allowed
   to connect to the interface. See interface.acl for
   further details.


.. confval:: interface.ssl.socketPortReuse

   Default: ``true``

   Type: *boolean*

   SO_REUSEADDR socket option for the TCP listening socket.


.. confval:: interface.ssl.key

   Type: *path*

   


.. confval:: interface.ssl.certificate

   Type: *path*

   


.. confval:: interface.ssl.verifyPeer

   Default: ``false``

   Type: *boolean*

   If enabled then the certificate of a connecting client
   is verified against the servers certificate. It is
   required that the client certificate is signed by the
   server certificate otherwise the connection is refused.


.. note::
   **queues.\***
   *Set the parameters for each messaging queue. The queues are used*
   *when listed in the "queues" parameter. Several queues*
   *can be used in parallel. For queues with without databases leave*
   *the processor parameters empty.*



.. note::

   **queues.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`queues` to become active.

   .. code-block:: sh

      queues = a,b
      queues.a.value1 = ...
      queues.b.value1 = ...
      # c is not active because it has not been added
      # to the list of queues
      queues.c.value1 = ...


.. confval:: queues.$name.groups

   Type: *list:string*

   Define the list of message groups added to the queue.
   If unset, then the defaultGroups will be used.
   A queue will always add the default group \"STATUS_GROUP\".
   This parameter overrides defaultGroups.


.. confval:: queues.$name.acl

   Default: ``0.0.0.0/0``

   Type: *list:ipmask*

   The IP access control list for clients which are allowed
   to join the queue. See interface.acl for further details.


.. confval:: queues.$name.maximumPayloadSize

   Default: ``1048576``

   Type: *int*

   Unit: *B*

   The maximum size in bytes of a message to be accepted.
   Clients which send larger messages will be disconnected.
   The default is 1MB.


.. confval:: queues.$name.plugins

   Type: *list:string*

   List of plugins required by this queue. This is just a
   convenience parameter to improve configurations
   readability. The plugins can also be added to the
   global list of module plugins.
   
   Example: dbstore


.. confval:: queues.$name.processors.messages

   Type: *string*

   Interface name. For now, use \"dbstore\"to
   use a database.
   
   Use empty for testing or playbacks without a database.


.. note::
   **queues.$name.processors.messages.dbstore.\***
   *Define the database connection parameters.*



.. confval:: queues.$name.processors.messages.dbstore.driver

   Type: *string*

   Selected the database driver to use.
   Database drivers are available through plugins.
   The default plugin is dbmysql which supports
   the MYSQL database server. It is activated
   with the core.plugins parameter.


.. confval:: queues.$name.processors.messages.dbstore.read

   Type: *string*

   Set the database read connection which is
   reported to clients that connect to this server.
   If a remote setup should be implemented,
   ensure that the hostname is reachable from
   the remote computer.


.. confval:: queues.$name.processors.messages.dbstore.write

   Type: *string*

   Set the database write connection which is
   private to scmaster.
   A separate write connection enables different
   permissions on the database level for scmaster
   and clients.


.. confval:: queues.$name.processors.messages.dbstore.proxy

   Default: ``false``

   Type: *boolean*

   If enabled then the database connection as configured
   in 'read' is not being returned to the client
   but the URL \"proxy:\/\/\". This URL
   tells the client to open the database via the
   websocket proxy at the messaging address,
   e.g. http:\/\/localhost\/production\/db. The same
   hostname and queue must be used as for the
   initial messaging connection.


.. confval:: queues.$name.processors.messages.dbstore.strictVersionMatch

   Default: ``true``

   Type: *boolean*

   If enabled, the plugin will check the database
   schema version and refuse to start if the
   version doesn't match the latest version.
   If disabled and the an object needs to be
   stored, which is incompatible with the
   database schema, this object is lost.
   Leave this option enabled unless you know
   exactly what are you doing and what the
   consequences are.


.. confval:: queues.$name.processors.messages.dbstore.deleteTree

   Default: ``true``

   Type: *boolean*

   Enables removing the entire object tree from
   the database if a parent object is being deleted.
   This will also decrease the numbers of notifiers
   sent to scmaster. Depending on the database
   backend, it can improve the performance.


.. confval:: http.filebase

   Default: ``@DATADIR@/scmaster/http/``

   Type: *path*

   The directory served by the http server at staticPath.


.. confval:: http.staticPath

   Default: ``/``

   Type: *string*

   The URL path at which html files and assets are available.
   All files under filebase will be served at this URL path.


.. confval:: http.brokerPath

   Default: ``/``

   Type: *string*

   The URL path at which the broker websocket is available.



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

.. program:: scmaster

:program:`scmaster [options]`


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

.. 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:: --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:: --log-file arg

   Use alternative log file.

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

   Execute in trace mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 \-\-print\-component\=1
   \-\-print\-context\=1 .


Wired
-----

.. option:: --bind arg

   The non\-encrypted bind address. Format [ip:]port

.. option:: --sbind arg

   The encrypted bind address. Format: [ip:]port

