You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
490 lines
11 KiB
ReStructuredText
490 lines
11 KiB
ReStructuredText
.. 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
|
|
|
|
|
|
.. _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.
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
.. 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*
|
|
|
|
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
.. 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.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:: 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
|
|
|