# scmaster — SeisComP Release documentation

6.9.0

# scmaster

The messaging system

## Description

scmaster is the implementation of the messaging mediator.

## Message Groups

scmaster provides the message groups. Configure

- `defaultGroups`: Add the groups which can be used by all queues.

- `queues.$name.groups`: Set all groups which are used by the given queue. You may inherit `defaultGroups`, e.g.:

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

  Warning

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

## Queues

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

1. Define a new queue by adding a new profile with some name,

2. Configure the profile parameters `queues.$name.*`,

3. Register the queue in `queues`.

## Scheme

scmaster provides unsecured and secured connection which is addressed by the scheme values scmp and scmps, respectively, in `connection.server` when connecting to the messaging. Read the concepts section for more details. scmps is in use when configuring `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 concepts section).

The database is configured per queue.

### Single Machine

When running all SeisComP 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 concepts section).

- 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

    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.

    interface.ssl.verifyPeer = true

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

## Module Configuration

`etc/defaults/global.cfg`
`etc/defaults/scmaster.cfg`
`etc/global.cfg`
`etc/scmaster.cfg`
`~/.seiscomp/global.cfg`
`~/.seiscomp/scmaster.cfg`

scmaster inherits global options.

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

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.

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.

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

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.

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.

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.

interface.ssl.socketPortReuse

  Default: `true`

  Type: boolean

  SO_REUSEADDR socket option for the TCP listening socket.

interface.ssl.key

  Type: path

interface.ssl.certificate

  Type: path

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 `queues` to become active.

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

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

http.filebase

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

  Type: path

  The directory served by the http server at staticPath.

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.

http.brokerPath

  Default: `/`

  Type: string

  The URL path at which the broker websocket is available.

## Command-Line Options

scmaster [options]

### Generic

-h, --help

  Show help message.

-V, --version

  Show version information.

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

--plugins arg

  Load given plugins.

-D, --daemon

  Run as daemon. This means the application will fork itself and doesn’t need to be started with &.

### Verbosity

--verbosity arg

  Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug.

-v, --v

  Increase verbosity level (may be repeated, eg. -vv).

-q, --quiet

  Quiet mode: no logging output.

--component arg

  Limit the logging to a certain component. This option can be given more than once.

-s, --syslog

  Use syslog logging backend. The output usually goes to /var/lib/messages.

-l, --lockfile arg

  Path to lock file.

--console arg

  Send log output to stdout.

--debug

  Execute in debug mode. Equivalent to --verbosity=4 --console=1 .

--log-file arg

  Use alternative log file.

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

--trace

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

### Wired

--bind arg

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

--sbind arg

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