[seiscomp, scanloc] Install, add .gitignore
This commit is contained in:
555
share/doc/seiscomp/html/_sources/apps/scmaster.rst.txt
Normal file
555
share/doc/seiscomp/html/_sources/apps/scmaster.rst.txt
Normal file
@ -0,0 +1,555 @@
|
||||
.. 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:: 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
|
||||
|
||||
Reference in New Issue
Block a user