Upgrading SeisComP

You will …

  • Upgrade a SeisComP system

  • Migrate a SeisComP3 system to a newer SeisComP version

Pre-requisites for this tutorial:

  • Tutorial on installation and SeisComP previously installed


  • Upgraded SeisComP

Time range estimate:

  • 60 minutes


Installing a new SeisComP release version is typically simple and the step described in Normal Upgrade can be applied. More actions are required when

SeisComP versions

SeisComP has developed over time. The versions can be distinguished by the name of the release:

  • SeisComP since version 4.0.0 uses release version numbers such as 5.2.1 where

    • 5: major version with changes in API and database schema version, new features, bug fixed, optimizations,

    • 2: minor version with new features, bug fixed, optimizations,

    • 1: patch number with bug fixes, optimizations.


    When increasing the major version number, an upgrade of the database is required.

  • SeisComP3 uses release versions, names, numbers and patch numbers.

    Full example: SeisComP3-jakarta-2020.330.02

    • 3: release version

    • jakarta: release name

    • 2020.330: release number

    • 02: patch number

    Names are adjusted depending on changes in source code:

    • Release version: major changes in module groups, functionality, concepts, data model. Example: SeisComp3 is SeisComP in version 3.0 in comparison to version 2.5 the GUIs were introduced.

    • Release name: major changes in functionality, concepts, data model. Example: with SeisComP3-Seattle the new user friendly configuration GUI scconfig was introduced.

    • Release number: changes in data model version and/or major changes in applications and optimizations. The numbers include the year and the day of the year of the software release. Example: Jakarta-2018.327

    • Patch number: optimizations of applications without changes in the data model version.

Upgrade SeisComP on multiple machines

Applications can only connect to a messaging system that runs with a database in an equal or lower data base schema version. In distributed SeisComP systems one machine host the messaging system and the database and all other machines are connected to this messaging or are running independently, the SeisComP installation on the machine operating the messaging is always updated last.

Example: A distributed system includes a processing system with the messaging system and database and a GUI work station connected to the processing system:

  1. Upgrade the GUI work station

  2. Upgrade the processing system, take actions to upgrade the database version.


Always stop all SeisComP modules before upgrading:

seiscomp stop

Package Download

Get the SeisComP package in the latest version or older ones from gempa GmbH or from the download website of Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH [68].


gempa provides gsm - gempa software management tool [29] for convenient and consistent download and installation of SeisComP and other packages.

Documentation of Changes

The important novelties, optimizations and changes that are available after upgrading are documented in the change log which can be read online. It is recommend to read the change log before taking further actions.

The details can also be found locally in the file


which is integrated in the documentation or accessible from the Docs panel in scconfig.


New features are regularly advertised and described in detail on the News website of gempa GmbH and on the SeisComP forum [24].

Normal Upgrade

The normal upgrade including upgrading the major version of SeisComP takes only a few steps:

  1. Download the SeisComP package.

  2. Stop all SeisComP modules:

    seiscomp stop
  3. Install the new packages.


    Users of external, e.g., gempa modules must ensure that these external modules match the SeisComP release version if they depend on SeisComP libraries.

  4. Test the database schema version and update bindings

    seiscomp update-config

    Upgrade the database schema version if mismatches are reported.

  5. After a successful upgrade, start all modules again and observe the status:

    seiscomp start
    seiscomp status started

Upgrade database schema version

When installing a new SeisComP release with a higher major version number, upgrading the database may be required. The database version will be tested and the required actions will be shown when executing:

seiscomp update-config

or when pressing the Update Configuration button in scconfig. An upgrade from version SeisComP3 jakarta-2017.334 to SeisComP in version 5.1.0 will give, e.g.:

seiscomp update-config
* starting kernel modules
starting scmaster
* configure kernel
* configure scmaster
INFO: checking DB schema version of queue: production
  * check database write access ... OK
  * database schema version is 0.10
  * last migration version is 0.12
  * migration to the current version is required. apply the following
    scripts in exactly the given order:
    * mysql -u sysop -p -D seiscomp -h localhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_10_to_0_11.sql
    * mysql -u sysop -p -D seiscomp -h localhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_11_to_0_12.sql
error: updating configuration for scmaster failed

The shown migration scripts can be used directly as given and in the given order:

  • MySQL / MariaDB:

    mysql -u sysop -p -D seiscomp -h localhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_10_to_0_11.sql
    mysql -u sysop -p -D seiscomp -h localhost < /home/sysop/seiscomp/share/db/migrations/mysql/0_11_to_0_12.sql
  • PostgreSQL:

    psql -U sysop -d seiscomp -h localhost -W -f /home/sysop/seiscomp/share/db/migrations/postgresql/0_10_to_0_11.sql
    psql -U sysop -d seiscomp -h localhost -W -f /home/sysop/seiscomp/share/db/migrations/postgresql/0_11_to_0_12.sql

Using the migration scripts provides a more user friendly way than copying the lines of MySQL code from the changelog. In future versions we might add the option to automatically run the migrations.


Upgrading the database make take some time. Do no interrupt the process! During this time, the SeisComP messaging system is unavailable causing a downtime of the system.

After applying the migration scripts the database should be at the correct version. Test again with:

seiscomp update-config

After successfully upgrading the database continue your previous upgrade procedure.

SeisComP3 to version >=4

SeisComP in version 4 has some major differences to SeisComP3 which require adjustments. The main differences are in the directories of the SeisComP installation and the messaging system. The changes and the required actions are explained below. They must be considered in addition to the steps set out in section Normal Upgrade.

Files and directories

With SeisComP3 all the default installation typically required all modules and configurations in the directories

  • seiscomp3/ , typically $HOME/seiscomp3 or /opt/seiscomp3/

  • $HOME/.seiscomp3/

As of SeisComP in version 4 the directories are:

  • seiscomp/ , typically $HOME/seiscomp/ or /opt/seiscomp/

  • $HOME/.seiscomp/

All configuration files must be migrated to the new structures. This includes:

  • Configurations and inventory in seiscomp3/:

    • seiscomp3/etc/*.cfg

    • seiscomp3/etc/inventory/

    • seiscomp3/etc/keys/

  • Configurations in $HOME/.seiscomp3/

  • Logs in $HOME/.seiscomp3/log (optional)

  • All user-defined files and directories in seiscomp3/share/

  • All user-defined seedlink and other templates in seiscomp3/share/templates/

  • The waveform archive and other archives typically in seiscomp3/var/lib/

  • User-defined files and directories in other places.


    Some configuration default and description files have changed. Spread, arclink and arclinkproxy are not part of SeisComP anymore. Therefore, do not migrate:

    • any default configuration, description and init files. Better enable the desired daemon modules again:

      seiscomp/bin/seiscomp enable [module]
    • any file related to spread or the arclink and arclinkproxy servers.

Configurations containing absolute paths, e.g. /home/sysop/seiscomp3/share/scautoloc/grid_custom.conf, must be adjusted. Better use internal SeisComP variables such as @DATADIR@ instead of seiscomp3/share or seiscomp/share.

Software dependencies

The software dependencies may have changed. Install the missing ones.

System variables

The system environment variables must be updated, e.g. in $HOME/.bashrc. Remove or uncomment the lines $HOME/.bashrc referring to the depreciated SeisComP3 version. Then execute

seiscomp/bin/seiscomp print env >> $HOME/.bashrc
source $HOME/.bashrc


When using pipelines or alias modules, create and enable the alias module names again, e.g.

seiscomp alias create [alias] [module]
seiscomp enable [alias]

Migrate the module and bindings configurations of the alias modules including all related additional files which are referred to in the configurations.

Messaging system

One of the main changes SeisComP3 to SeisComP in version 4.0 is the messaging system. Spread does not exist anymore and only scmaster is started initially for the messaging system. scmaster allows to operate several queues in parallel with different databases. This flexibility comes with additional parameters which require configuration. Migrate the legacy database parameters and configure the new one:

  1. Remove or comment the obsolete dbplugin plugin manually from scmaster.cfg and global.cfg

    # plugins = dbplugin
  2. Set up the messaging queues in the configuration of scmaster in scmaster.cfg.

    • Add and configure a new queue or stay with the default ones.

      • production considers a database by default.

      • playback considers no database by default. Here, parameters can be exchanged through the messaging without storing in the database.

      In the following examples, the production queue shall be assumed.


      The production queue is used by default by all modules connected to the messaging system. When removing this queue and a database shall be used, another queue must exist and the queue name must be configured for all modules in the global connection.server parameter. See below for an example.

      • Add the required plugins per queue. Currently only dbstore is supported. Example for the production queue:

        queues.production.plugins = dbstore
      • Add non-default message groups, e.g. L1PICK and L1LOCATION to the list of groups in one of the ways:

        • Recommended: Add groups per queues to defaults in queues.$name.groups, e.g. for the production group. This convenient configuration per queue considers the default groups in defaultGroups and simply adds new groups in the configuration of queues

          queues.production.groups = ${defaultGroups}, L1PICK, L1LOCATION
        • Set groups per queue in queues.$name.groups, ignoring groups in defaultGroups

        • Set groups in defaultGroups



        When setting groups in the queues all groups configured in defaultGroups will be ignored unless ${defaultGroups} is used. Add all groups from defaultGroups to the queues to keep the default groups.

      • Add the interface name, currently only dbstore is supported. Example for a queue names production

        queues.production.processors.messages = dbstore
      • Add the database parameters which can be used from the legacy configuration

        queues.production.processors.messages.dbstore.driver = mysql
        queues.production.processors.messages.dbstore.read = sysop:sysop@localhost/seiscomp3
        queues.production.processors.messages.dbstore.write = sysop:sysop@localhost/seiscomp3


        The name of the database can be freely chosen. The example assumes that the database named seiscomp3 exists already and that it shall be continued to be used with the new SeisComP in version 4.x.x.

    • Add one or more of the queues to the queues parameter to register them by their names

      queues = production, playback
  3. Configure the connection parameters of all modules connecting to the messaging system in the global configuration, e.g. in global.cfg. As in SeisComP3 the connection server is localhost. The queue name is added to the host by “/”. The default queue is production, e.g.

    connection.server = localhost/production


    If production shall be used, then no additional configuration is required.


After adjusting the structure, variables and configuration parameters, check if the database requires an upgrade as well.

Automatic module check

If applied, adjust the settings for automatic module status check, e.g. crontab entries. For crontab use:

crontab -e

System daemon

If SeisComP is controlled by the system daemon, e.g. to start enabled SeisComP modules automatically during computer startup, then the startup script must be adjusted.

Upgrade From SeisComP3 Jakarta-2018.327 or Before