System management

The installation contains modules for data acquisition, data archiving, processing, distribution and much more. To control all these modules and to update their configuration the central program seiscomp is used with commands and options.

seiscomp is a Python script installed in seiscomp/bin/seiscomp. The graphical tool scconfig is a user-friendly wrapper tool for many commands in seiscomp.

The entire management framework is built upon Python which is portable to different platforms. To make seiscomp work, ensure that Python is installed on your system.

seiscomp of a particular installation can be called from anywhere in the file system with its full path. It will source the environment of the installation automatically. Thus, it is possible to control different installations on one computer.

Warning

seiscomp should never run with root privileges unless you know exactly what you are doing.

seiscomp refuses to work when run with root privileges and issues an error. To run it with root privileges the command-line option --asroot must be given as first parameter, e.g.:

seiscomp --asroot start seedlink

To get an overview of all available commands, issue

seiscomp/bin/seiscomp help

This will print all commands. To get help for a particular command, append it to the help command.

seiscomp/bin/seiscomp help [command]

seiscomp Commands

The seiscomp script can be executed with additional commands:

  • alias create|remove [new-name] [module name]

    Manages module aliases.

  • check [module list]

    Checks if all passed modules are still running if they have been started. If no modules are listed, all modules are checked.

  • disable [module list]

    The opposite of enable. Removes the file etc/init/[module].auto for each module passed.

  • enable [module list]

    Enables a module to be started and checked automatically when either start or check is called without arguments. This creates a file etc/init/[module].auto for each module passed.

  • exec [cmd]

    Executes a module.

  • help [command]

    Prints help on commands.

  • install-deps [packages]

    Installs 3rd party packages on which SeisComP depends such as MariaDB or MySQL. This is currently only supported for major Linux distributions. A list of packages needs to be given. Available packages are: base, GUI, mariadb-server, postgresql-server, fdsnws.

    1. Install only base system dependencies:

      seiscomp install-deps base

    2. Install base system dependencies and MariaDB/MySQL/PostgreSQL server:

      MariaDB

      seiscomp install-deps base mariadb-server

      MySQL. Install either MariaDB or MySQL, not both at the same time!

      seiscomp install-deps base mysql-server

      PostgreSQL:

      seiscomp install-deps base postgresql-server

    3. Install also gui and fdsnws dependencies:

      seiscomp install-deps gui fdsnws

  • list modules|aliases|enabled|disabled

    Lists items.

  • print crontab|env

    Prints pre-defined parameters.

  • restart [module list]

    Restarts all the given modules. If no module is passed, all running and enabled modules are first stopped and then restarted.

  • setup

    Initializes the configuration of all available modules. Each module implements its own setup handler which is called at this point. The initialization takes the installation directory into account and should be repeated when copying the system to another directory.

    Warning

    setup might overwrite previous settings with default values.

  • shell

    Starts the interactive SeisComP shell, an approach to make configuration and manipulation of bindings more easy on the command line.

  • start [module list]

    Starts all modules in [module list]. If no module is named, all enabled modules are started.

  • status [module list]

    Prints the status of some, started, enabled or all modules.

  • stop [module list]

    Stops all modules in [module list]. If no module name is given, all running modules are stopped.

  • update-config [module list]

    Updates the configuration. Modules should be able to read the configuration files in etc directly, but some modules such as Seedlink need an additional step to convert the configuration to their native format. Furthermore all trunk station bindings and the inventory need to be synchronized with the database. If no module list is given, update-config is called for all available modules. Otherwise only the modules passed are updated.

SeisComP Shell

The SeisComP shell can be started with

user@host:~$ seiscomp/bin/seiscomp shell

which will open a command prompt. The shell is a helper to manage module station bindings. Instead of manipulating hundreds of files using difficult commands such as sed in Bash scripts, shell can be used. It supports:

  • list available stations

  • list available profiles of a module

  • list modules to which a station is bound

  • bind stations to modules

  • delete bindings

  • track configuration of a station

================================================================================
seiscomp shell
================================================================================

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

$

Enter help to get a list of supported commands. The results of all commands issued are written to disk immediately and not buffered.

Examples

  1. Assigning the scautopick global profile to all GE stations

    $ set profile scautopick global GE.*

  2. Replace all profiles with station configuration for scautopick from GE network

    $ remove profile scautopick global GE.*

  3. Show bindings for station GE.MORC

    $ print station GE.MORC
[global]
/home/sysop/seiscomp/etc/key/global/profile_BH
--------------------------------------------------------------------------------
detecStream = BH
--------------------------------------------------------------------------------

[seedlink]
/home/sysop/seiscomp/etc/key/seedlink/profile_geofon
--------------------------------------------------------------------------------
sources = chain
sources.chain.address = geofon.gfz-potsdam.de
sources.chain.port = 18000
--------------------------------------------------------------------------------

[scautopick]
/home/sysop/seiscomp/etc/key/scautopick/profile_default
--------------------------------------------------------------------------------
detecEnable = true
detecFilter = "RMHP(10)>>ITAPER(30)>>BW(4,0.7,2)>>STALTA(2,80)"
trigOn = 3
trigOff = 1.5
timeCorr = -0.8
--------------------------------------------------------------------------------

[slarchive]
/home/sysop/seiscomp/etc/key/slarchive/profile_1day
--------------------------------------------------------------------------------
selectors = BHZ.D
keep = 1
--------------------------------------------------------------------------------

    This helps to see immediately in which file a certain parameter is defined and what module the station is bound to.

Module Init Scripts

All modules which can run in the background as daemon modules have init scripts. The init scripts are placed in etc/init. seiscomp loads all .py files and tries to find a class called Module. This class is then instantiated with the environment object passed as only parameter to the constructor. If no error occurred then the module is registered.

The name of the init script is ignored and not used furthermore. Only the name in the Module object is important. It is important to note that only one module can be placed in one init script.

The Module class must implement the interface used by seiscomp. See seiscomp.Kernel.Module for more details.

A simple default implementation looks like this which is available as a template and can be used directly by using the same name as the module’s name. The module’s name in this template is derived from the filename, but this isn’t a general rule as stated before.

import seiscomp.Kernel

class Module(seiscomp.Kernel.Module):
  def __init__(self, env):
    seiscomp.Kernel.Module.__init__(self, env, env.moduleName(__file__))

SeisComP provides a Python module (seiscomp.Kernel) that allows to write init scripts in an easy way.

Python kernel module

The SeisComP setup kernel module provides interfaces to write init handlers for modules used by seiscomp in Python.

class seiscomp.Kernel.Module(env, name)
Parameters

  • env – The passes environment from seiscomp which is stored in self.env.

  • name – The module name which must be passed by derived classes. It is stored in self.name.

The module interface which implements the basic default operations. Each script can define its own handlers to customize the behaviour.

isRunning()
Return type

Boolean

Checks if a module is running. The default implementation returns True if the lockfile if not locked.

start()
Return type

Integer

Starts a module and returns 0 if no error occured and 1 otherwise. This method is called from seiscomp start.

stop()
Return type

Integer

Stops a module and returns 0 if no error occured and 1 otherwise. This method is called from seiscomp stop.

check()
Return type

Integer

Check is the same as start. The decision whether to check a module or not is made seiscomp which check the existence of the corresponding run file. Returns 1 is case of error, 0 otherwise.

status(shouldRun)
Parameters

shouldRun – Boolean parameter that indicates if the module should run or not. This is evaluated by seiscomp.

Prints the status of the module to stdout. Either is CSV format or as free text. This depends on self.env._csv. The default implementations calls

self.env.logStatus(self.name, self, self.isRunning(), shouldRun,\
                   self.env.isModuleEnabled(self.name) or \
                   isinstance(self, CoreModule))
updateConfig()

Updates the configuration and bindings based on the module’s .cfg files and etc/key/[modname]. A trunk module does not need to do anything here. Stand-alone modules need to implement this method to convert the configuration to their native format.

This is called from seiscomp update-config.

printCrontab()

Prints crontab entries to stdout. The default implementation does not print anything.

This is called from seiscomp print crontab.

class seiscomp.Kernel.CoreModule(seiscomp.Kernel.Module)

The core module interface. A core module is a normal module but is started before all modules and stopped afterwards. Core modules are always enabled and will be started with seiscomp start unless a CoreModule implementation applies additional checks in Module.start().

scmaster is a core module which is a requirement for all trunk modules.

class seiscomp.Kernel.Environment

Access to the setup environment.