seiscomp

SeisComP system control utility

Description

The tool seiscomp allows controlling your SeisComP system on the command line. As other SeisComP modules it provides options and commands, e.g., the command help. Apply seiscomp to

• Install software dependencies,

• Print

  • environment variables of the installed SeisComP system,

  • internal SeisComP variables which can be used in configurations,

  • suggestions for timed automatic actions, i.e. “conjobs”,

• Make a basic setup including the SeisComP database,

• List daemon modules by categories,

• Enable or disable modules in order to start them by default,

• Start, stop, restart or reload single or multiple modules or all default modules,

• Check the status of module,

• Execute single or multiple modules or all default modules

• Print the run status of modules,

• Manage modules aliases,

• Update inventory or bindings configurations,

• Manage bindings by a specific shell.

Note

When executing seiscomp, all actions refer to the SeisComP installation from within which seiscomp is called. This allows to refer to a default but also to any other installed SeisComP system and to operate multiple SeisComP systems in parallel, e.g., for testing different versions or for running different projects. Then give the full path to the seiscomp tools. Example:

$HOME/seiscomp-test/bin/seiscomp

Many of these actions are used by scconfig.

Help

Use the command help for learning about the full set of options and other commands including examples:

seiscomp help

For basic help you may also use the option -h:

seiscomp -h

Applications

Software dependencies

Software dependencies should be installed after installation or updates of SeisComP. You may install dependencies on different levels, e.g., base, gui, fdswnws, [database]-server. Examples:

seiscomp install-deps base
seiscomp install-deps base gui mariadb-server

Alternatively run the shell scripts for your Linux flavor and version located in seiscomp/share/deps/.

Note

For making a full installation and setup follow the instructions starting with section SeisComP Installation.

Print

You may print the environment variables related to your considered SeisComP installation, internal SeisComP variables or suggestions for timed automatic procedures. Examples:

seiscomp print env
$HOME/seiscomp-test/bin/seiscomp print env
seiscomp print variables
seiscomp print crontab

Add the environment variables to your shell configuration for making them known user wide. Internal variables are resolved when applying them in user configurations. For adjusting, adding or removing crontab listings execute:

man crontab
crontab -e

Basic setup

Make a basic setup of your SeisComP system interactively after installation. This will also allow you to generate a database or to configure the connection to an existing one. Run, e.g.

seiscomp setup
$HOME/seiscomp-test/bin/seiscomp setup

List

List modules which can be started to run as background daemon modules by categories. Examples:

seiscomp list modules
seiscomp list enabled
seiscomp list started

Enable/disable [*]

Enabled modules will be started to run as a background daemon module. You may enable or disable one or multiple modules. Examples:

seiscomp enable scautopick
seiscomp enable scautopick scautoloc
seiscomp disable scautopick scautoloc

Start/stop/restart/reload [*]_

Start all enabled modules:

seiscomp start

Stop all modules and start all enabled modules:

seiscomp restart

Start/stop/restart specific modules

seiscomp start scautopick scautoloc
seiscomp stop scautopick scautoloc
seiscomp restart scautopick scautoloc

In order to apply configurations, a module must be (re)started since it reads any configuration only during startup. Restarts will create downtimes and should be avoided as much as possible. In order to minimize downtimes, some modules may apply changes in configuration by reloading during runtime without restarting. For reloading you may use the command seiscomp reload. The application of reloading is therefore restricted to a limited range of modules and parameters.

Note

Graphical modules such as scolv cannot be operated as background daemon modules. Therefore, they cannot be started but they can be executed.

Check [*]_

When modules stop unexpectedly, they are not stopped in a clean way. Such stopped modules may be detected and started again in order to minimize downtimes. Apply the check command to all or specific modules. Examples:

seiscomp check
seiscomp check scautopick

Execute

Instead of running daemon modules you may execute modules in a terminal and observe the output, e.g., for debugging or for applying command-line options. Examples:

seiscomp exec scolv --debug
seiscomp exec scautopick --debug

Note

When all relevant system environment variables point to the same SeisComP installation from where seiscomp is executed, then it is enough to execute modules by their names replacing the above:

scolv --debug
scautopick --debug

Status [*]_

List the status of all, enabled, disabled, started, or specific modules. Examples:

seiscomp status
seiscomp status enabled
seiscomp status disabled
seiscomp status started
seiscomp status scautopick

:command:status` will report modules which terminated due to errors.

Module Aliases

For some SeisComP modules aliases can be generated allowing the separate execution with specific configurations in parallel the original module and even in separate pipeline with specific message groups. Using the alias command aliases modules can be created or removed. Examples for creating or removing the alias l1autopick to scautopick:

seiscomp alias create l1autopick scautopick
seiscomp alias remove l1autopick

When creating aliases, soft links to the original module executable files, the default configuration and the init files are created. The alias itself is registered in SEISCOMP_ROOT/etc/descriptions/aliases. If a module does not allow creating aliases a notification is printed. Example:

seiscomp alias create scolv1 scolv
error: module 'scolv' not found

After creating aliases, they may be configured and operated in the same way as the original module.

Warning

The length of alias names for modules considering bindings is strictly limited to 20 characters.

When removing aliases, all links and the alias registration are removed but possibly existing module or binding configurations remained unchanged. The option --interactive allows removing these configurations interactively.

seiscomp --interactive alias remove l1autopick

Update configuration [*]_

The command update-config allows reading bindings configurations from the standard @KEYDIR@ directory as well as inventory from @SYSTEMCONFIGDIR@/inventory and sending them to the messaging for storing in the database or for generating the configuration of standalone modules:

seiscomp update-config

Executing seiscomp update-config involves:

• Merging inventory,

• Sending inventory updates to the messaging,

• Synchronisation of inventory, key files and bindings,

• Sending any updates of bindings to the messaging,

• Generation of configuration for standalone modules.

The command can therefore be rater time consuming. For speeding up you may be more specific:

• Only update global bindings and all trunk modules without inventory

  seiscomp update-config trunk
  

• Update only inventory

  seiscomp update-config inventory
  

• Update bindings of scautopick only

  seiscomp update-config scautopick
  

  The command may be similarly applied to any other module considering bindings.

Note

Instead of reading bindings configurations from the standard @KEYDIR@ directory, the module bindings2cfg can read bindings from any key directory and write the Config parameters to SCML or send them to the messaging.

seiscomp Shell

The seiscomp shell is a special environment, e.g., allowing to control bindings of modules to stations.

Applications are:

• Create or remove station bindings,

• Create or remove binding profiles,

• Remove binding profiles.

Invoke seiscomp along with the shell command to start the shell:

seiscomp shell


  ================================================================================
  SeisComP shell
  ================================================================================

  Welcome to the SeisComP interactive shell. You can get help about
  available commands with 'help'. 'exit' leaves the shell.

  $

The full list of shell control commands are printed along with the help of the seiscomp shell:

================================================================================
SeisComP shell
================================================================================

Welcome to the SeisComP interactive shell. You can get help about
available commands with 'help'. 'exit' leaves the shell.

$ help
Commands:
  list stations
    Lists all available stations keys.

  list profiles {mod}
    Lists all available profiles of a module.

...

Note

[*]

With this command, the flag --invert can be used in order to invert the application to the specific modules. You may provide one or more module names. A major application is to restart most SeisComP modules after a change in global bindings. However, seedlink and slarchive are not affected by global bindings and any downtime of these modules shall be avoided. Example:

seiscomp --invert restart seedlink slarchive

The same procedure could be achieved without --invert by explicitly stating all other modules which, however, may result in a long list of module names.

Command-Line Options

seiscomp [flags] command(s) [argument(s)]

Flags

--asroot

Allow running a command as root.

--csv

Print output as CSV in machine-readable format.

-h, --help

Produce this help message.

-i, --interactive

Interactive mode: Allow deleting configurations interactively when removing aliases.

--invert

Invert the selection of the specified module names when using any of the commands: start, stop, check, status, reload, or restart.

--wait arg

Define a timeout in seconds for acquiring the seiscomp lock file, e.g., seiscomp --wait 10 update-config.