625 lines
14 KiB
Groff
625 lines
14 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "SCMASTER" "1" "Oct 14, 2025" "6.9.1" "SeisComP"
|
|
.SH NAME
|
|
scmaster \- SeisComP Documentation
|
|
.sp
|
|
\fBThe messaging system\fP
|
|
.SH DESCRIPTION
|
|
.sp
|
|
scmaster is the implementation of the \fI\%messaging\fP
|
|
mediator.
|
|
.SH MESSAGE GROUPS
|
|
.sp
|
|
scmaster provides the \fI\%message groups\fP\&. Configure
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fI\%defaultGroups\fP: Add the groups which can be used by all queues.
|
|
.IP \(bu 2
|
|
\fI\%queues.$name.groups\fP: Set all groups which are used by the given
|
|
queue. You may inherit \fI\%defaultGroups\fP, e.g.:
|
|
.INDENT 2.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
queues.production.groups = ${defaultGroups},L1PICK
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBWARNING:\fP
|
|
.INDENT 2.0
|
|
.INDENT 3.5
|
|
Setting any value without inheriting \fI\%defaultGroups\fP ignores all
|
|
values of \fI\%defaultGroups\fP\&.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH QUEUES
|
|
.sp
|
|
scmaster provides \fIqueues\fP for separating the processing.
|
|
Typically, the default queue \fIproduction\fP is used. To add new queues
|
|
.INDENT 0.0
|
|
.IP 1. 3
|
|
Define a new queue by adding a new profile with some name,
|
|
.IP 2. 3
|
|
Configure the profile parameters \fBqueues.$name.*\fP,
|
|
.IP 3. 3
|
|
Register the queue in \fI\%queues\fP\&.
|
|
.UNINDENT
|
|
.SH SCHEME
|
|
.sp
|
|
scmaster provides unsecured and secured connection which is addressed by the
|
|
scheme values \fIscmp\fP and \fIscmps\fP, respectively, in \fI\%connection.server\fP
|
|
when connecting to the messaging.
|
|
Read the \fI\%concepts section\fP for more details. \fIscmps\fP
|
|
is in use when configuring \fI\%interface.ssl.bind\fP\&.
|
|
.SH DATABASE ACCESS
|
|
.sp
|
|
scmaster reads from and writes to the database and reports the database connection
|
|
to the clients of the messaging system (compare with the \fI\%concepts section\fP).
|
|
.sp
|
|
The database is configured per queue.
|
|
.SS Single Machine
|
|
.sp
|
|
When running all \fISeisComP\fP modules on a single machine, the read and write
|
|
parameters are typically configured with \fIlocalhost\fP as a \fIhost name\fP\&.
|
|
.sp
|
|
Example:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
queues.production.processors.messages.dbstore.read = sysop:sysop@localhost/seiscomp
|
|
queues.production.processors.messages.dbstore.write = sysop:sysop@localhost/seiscomp
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Multiple Machines
|
|
.sp
|
|
If the clients are located on machines different from the messaging, the
|
|
\fIhost name\fP 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 \fIhost name\fP of the write connection typically remains \fIlocalhost\fP\&.
|
|
.sp
|
|
Example for connecting clients on computerB to the messaging on computerA (compare
|
|
with the \fI\%concepts section\fP).
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Configuration of scmaster on computerA:
|
|
.INDENT 2.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
queues.production.processors.messages.dbstore.read = sysop:sysop@computerA/seiscomp
|
|
queues.production.processors.messages.dbstore.write = sysop:sysop@localhost/seiscomp
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.IP \(bu 2
|
|
Global configuration of client on computerB:
|
|
.INDENT 2.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
connection.server = computerA/production
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Database Proxy
|
|
.sp
|
|
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.
|
|
.sp
|
|
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.
|
|
.sp
|
|
To let scmaster return the proxy address of the database connection, set
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
queues.production.processors.messages.dbstore.proxy = true
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
in the configuration file.
|
|
.SH ACCESS CONTROL
|
|
.sp
|
|
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.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
interface.ssl.verifyPeer = true
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
It is required that the client certificate is signed by the server certificate
|
|
otherwise the client connection will be rejected.
|
|
.SH MODULE CONFIGURATION
|
|
.nf
|
|
\fBetc/defaults/global.cfg\fP
|
|
\fBetc/defaults/scmaster.cfg\fP
|
|
\fBetc/global.cfg\fP
|
|
\fBetc/scmaster.cfg\fP
|
|
\fB~/.seiscomp/global.cfg\fP
|
|
\fB~/.seiscomp/scmaster.cfg\fP
|
|
.fi
|
|
.sp
|
|
.sp
|
|
scmaster inherits \fI\%global options\fP\&.
|
|
.INDENT 0.0
|
|
.TP
|
|
.B defaultGroups
|
|
Default: \fBAMPLITUDE, PICK, LOCATION, MAGNITUDE, FOCMECH, EVENT, QC, PUBLICATION, GUI, INVENTORY, CONFIG, LOGGING, SERVICE_REQUEST, SERVICE_PROVIDE, STATUS_GROUP\fP
|
|
.sp
|
|
Type: \fIlist:string\fP
|
|
.sp
|
|
The default set of message groups for each queue. Only used
|
|
if a queues group list is unset (note: empty is not unset).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues
|
|
Default: \fBproduction, playback\fP
|
|
.sp
|
|
Type: \fIlist:string\fP
|
|
.sp
|
|
Enable messaging queues defined as profile in queues. The profile
|
|
names are the final queue names.
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fBinterface.*\fP
|
|
\fIControl the messaging interface. The default protocol is\fP
|
|
\fI\(dqscmp\(dq but \(dqscmps\(dq (secure protocol) is\fP
|
|
\fIused when valid SSL certificate and key are configured.\fP
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.bind
|
|
Default: \fB0.0.0.0:18180\fP
|
|
.sp
|
|
Type: \fIipbind\fP
|
|
.sp
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.acl
|
|
Type: \fIlist:ipmask\fP
|
|
.sp
|
|
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.
|
|
\(dq127.0.0.1 192.168.1.2 192.168.0.0/16\(dq.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.socketPortReuse
|
|
Default: \fBtrue\fP
|
|
.sp
|
|
Type: \fIboolean\fP
|
|
.sp
|
|
SO_REUSEADDR socket option for the TCP listening socket.
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fBinterface.ssl.*\fP
|
|
\fISSL encryption is used if key and certificate are configured.\fP
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.ssl.bind
|
|
Default: \fB0.0.0.0:\-1\fP
|
|
.sp
|
|
Type: \fIipbind\fP
|
|
.sp
|
|
Additional local bind address and port of the messaging
|
|
system in case SSL encryption is active.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.ssl.acl
|
|
Type: \fIlist:ipmask\fP
|
|
.sp
|
|
The IP access control list for clients which are allowed
|
|
to connect to the interface. See interface.acl for
|
|
further details.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.ssl.socketPortReuse
|
|
Default: \fBtrue\fP
|
|
.sp
|
|
Type: \fIboolean\fP
|
|
.sp
|
|
SO_REUSEADDR socket option for the TCP listening socket.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.ssl.key
|
|
Type: \fIpath\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.ssl.certificate
|
|
Type: \fIpath\fP
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B interface.ssl.verifyPeer
|
|
Default: \fBfalse\fP
|
|
.sp
|
|
Type: \fIboolean\fP
|
|
.sp
|
|
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.
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fBqueues.*\fP
|
|
\fISet the parameters for each messaging queue. The queues are used\fP
|
|
\fIwhen listed in the \(dqqueues\(dq parameter. Several queues\fP
|
|
\fIcan be used in parallel. For queues with without databases leave\fP
|
|
\fIthe processor parameters empty.\fP
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fBqueues.$name.*\fP
|
|
$name is a placeholder for the name to be used and needs to be added to \fI\%queues\fP to become active.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
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 = ...
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.groups
|
|
Type: \fIlist:string\fP
|
|
.sp
|
|
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 \(dqSTATUS_GROUP\(dq.
|
|
This parameter overrides defaultGroups.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.acl
|
|
Default: \fB0.0.0.0/0\fP
|
|
.sp
|
|
Type: \fIlist:ipmask\fP
|
|
.sp
|
|
The IP access control list for clients which are allowed
|
|
to join the queue. See interface.acl for further details.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.maximumPayloadSize
|
|
Default: \fB1048576\fP
|
|
.sp
|
|
Type: \fIint\fP
|
|
.sp
|
|
Unit: \fIB\fP
|
|
.sp
|
|
The maximum size in bytes of a message to be accepted.
|
|
Clients which send larger messages will be disconnected.
|
|
The default is 1MB.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.plugins
|
|
Type: \fIlist:string\fP
|
|
.sp
|
|
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.
|
|
.sp
|
|
Example: dbstore
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.processors.messages
|
|
Type: \fIstring\fP
|
|
.sp
|
|
Interface name. For now, use \(dqdbstore\(dqto
|
|
use a database.
|
|
.sp
|
|
Use empty for testing or playbacks without a database.
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
\fBqueues.$name.processors.messages.dbstore.*\fP
|
|
\fIDefine the database connection parameters.\fP
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.processors.messages.dbstore.driver
|
|
Type: \fIstring\fP
|
|
.sp
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.processors.messages.dbstore.read
|
|
Type: \fIstring\fP
|
|
.sp
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.processors.messages.dbstore.write
|
|
Type: \fIstring\fP
|
|
.sp
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.processors.messages.dbstore.proxy
|
|
Default: \fBfalse\fP
|
|
.sp
|
|
Type: \fIboolean\fP
|
|
.sp
|
|
If enabled then the database connection as configured
|
|
in \(aqread\(aq is not being returned to the client
|
|
but the URL \(dqproxy://\(dq. 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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B queues.$name.processors.messages.dbstore.strictVersionMatch
|
|
Default: \fBtrue\fP
|
|
.sp
|
|
Type: \fIboolean\fP
|
|
.sp
|
|
If enabled, the plugin will check the database
|
|
schema version and refuse to start if the
|
|
version doesn\(aqt 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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B http.filebase
|
|
Default: \fB@DATADIR@/scmaster/http/\fP
|
|
.sp
|
|
Type: \fIpath\fP
|
|
.sp
|
|
The directory served by the http server at staticPath.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B http.staticPath
|
|
Default: \fB/\fP
|
|
.sp
|
|
Type: \fIstring\fP
|
|
.sp
|
|
The URL path at which html files and assets are available.
|
|
All files under filebase will be served at this URL path.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B http.brokerPath
|
|
Default: \fB/\fP
|
|
.sp
|
|
Type: \fIstring\fP
|
|
.sp
|
|
The URL path at which the broker websocket is available.
|
|
.UNINDENT
|
|
.SH COMMAND-LINE OPTIONS
|
|
.sp
|
|
\fBscmaster [options]\fP
|
|
.SS Generic
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-h, \-\-help
|
|
Show help message.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-V, \-\-version
|
|
Show version information.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-plugins arg
|
|
Load given plugins.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-D, \-\-daemon
|
|
Run as daemon. This means the application will fork itself
|
|
and doesn\(aqt need to be started with &.
|
|
.UNINDENT
|
|
.SS Verbosity
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-verbosity arg
|
|
Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
|
|
4:debug.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-v, \-\-v
|
|
Increase verbosity level (may be repeated, eg. \-vv).
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-q, \-\-quiet
|
|
Quiet mode: no logging output.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-component arg
|
|
Limit the logging to a certain component. This option can
|
|
be given more than once.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-s, \-\-syslog
|
|
Use syslog logging backend. The output usually goes to
|
|
/var/lib/messages.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-l, \-\-lockfile arg
|
|
Path to lock file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-console arg
|
|
Send log output to stdout.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-debug
|
|
Execute in debug mode.
|
|
Equivalent to \-\-verbosity=4 \-\-console=1 .
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-log\-file arg
|
|
Use alternative log file.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-trace
|
|
Execute in trace mode.
|
|
Equivalent to \-\-verbosity=4 \-\-console=1 \-\-print\-component=1
|
|
\-\-print\-context=1 .
|
|
.UNINDENT
|
|
.SS Wired
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-bind arg
|
|
The non\-encrypted bind address. Format [ip:]port
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-sbind arg
|
|
The encrypted bind address. Format: [ip:]port
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
gempa GmbH, GFZ Potsdam
|
|
.SH COPYRIGHT
|
|
gempa GmbH, GFZ Potsdam
|
|
.\" Generated by docutils manpage writer.
|
|
.
|