[seiscomp, scanloc] Install, add .gitignore

share/doc/seiscomp/html/_sources/base/addons.rst.txt

@@ -0,0 +1,20 @@
+.. _addons:
+
+*************
+Addon Modules
+*************
+
+Addon modules make use of the |scname| framework but do not ship with the
+|scname| package. Instead they are provided in separate packages. These packages
+can be downloaded and deployed or
+:ref:`compiled from source code <compiling_source>` separately. How these
+modules eventually integrate into the default |scname| installation depends on
+these addon modules themselves.
+
+The modules are:
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   /base/addons/sed

share/doc/seiscomp/html/_sources/base/addons/sed.rst.txt

@@ -0,0 +1,32 @@
+.. _addons-sed:
+
+scdetect
+========
+
+Real-time earthquake detection based on waveform cross-correlation by ETHZ/SED.
+
+* Source code :
+  `GitHub <https://github.com/swiss-seismological-service/scdetect>`_.
+* Documentation: Included within the software package or
+  `online <https://scdetect.readthedocs.io/en/stable/>`_.
+
+scrtdd
+======
+
+Real-time double difference event relocation by ETHZ/SED.
+
+* Source code :
+  `GitHub <https://github.com/swiss-seismological-service/scrtdd>`_.
+* Documentation: Included within the software package or
+  `online <https://docs.gempa.de/scrtdd/current/>`_.
+
+
+sed-eew
+=======
+
+Modules for earthquake early warning by ETHZ/SED.
+
+* Source code :
+  `GitHub <https://github.com/SED-EEW/SED-EEW-SeisComP-contributions>`_.
+* Documentation: Included within the software package or
+  `online <https://docs.gempa.de/sed-eew/current/>`_.

share/doc/seiscomp/html/_sources/base/api-python-client.rst.txt

@@ -0,0 +1,401 @@
+.. _api-client-python:
+
+seiscomp.client
+===============
+
+.. py:module:: seiscomp.client
+
+Modules are meant to be standalone programs doing a particular job. The
+seiscomp.client package focuses on three main aspects:
+
+* Communicate with other modules
+* Access station- and event metadata through a database
+* Fetch waveform data
+
+Therefore a client package has been developed combining these concepts in an
+easy way with only a couple of API calls. Since |scname| has been developed in
+C++ and uses the object oriented paradigm forcefully, modules build on the
+Application (C++: :class:`Seiscomp::Client::Application`, Python:
+:class:`seiscomp.client.Application`) class. It manages the messaging connection
+and waveform sources in a transparent way.
+
+The class :class:`Seiscomp::Client::Application` is the base class for
+all |scname| applications. It manages messaging and database
+connections, provides access to command line options and configuration
+parameters and also handles and interprets notifier messages.
+
+Blocking network operations like reading messages are moved into threads that
+are synchronized in a single blocking message queue. This queue allows pushing
+elements from different threads and unblocks when a new element is ready to be
+popped. If the queue is full (currently 10 elements are allowed) the pushing
+threads also block until an element can be pushed again.
+
+This way applications do not have to poll and thus do not burn CPU cycles.
+
+The application class is event driven. It runs the event loop which pops the
+message queue and dispatches events with their handlers. Handler methods are
+prefixed with *handle*, e.g. :func:`handleMessage`.
+
+.. note::
+
+   When overriding handlers it is always good practise to call the base
+   handlers before running custom code.
+
+
+Application class
+-----------------
+
+The application class is part of the seiscomp.client package. It needs to
+be imported first.
+
+.. code-block:: python
+
+   import seiscomp.client
+
+A common strategy to write a module with that class is to derive from it and
+run it in a Python main method.
+
+.. code-block:: python
+
+   import sys
+   import seiscomp.client
+
+   # Class definition
+   class MyApp(seiscomp.client.Application):
+       def __init__(self, argc, argv):
+           seiscomp.client.Application.__init__(self, argc, argv)
+
+   # Main method to call the app
+   def main(argc, argv):
+       app = MyApp(argc, argv)
+       return app()
+
+   # Call the main method if run as script
+   if __name__ == "__main__":
+       sys.exit(main(len(sys.argv), sys.argv))
+
+
+An application can be called with the parenthesis operator :func:`()` which
+returns the applications result code and serves as input to :func:`sys.exit`.
+Operator() is a wrapper for :func:`Application.exec`.
+
+
+The workflow of :func:`Application.exec` looks as follows:
+
+.. code-block:: python
+
+   def exec(self):
+       self.returnCode = 1
+
+       if self.init() and self.run():
+           self.returnCode = 0
+
+       self.done()
+
+       return self.returnCode
+
+:func:`init`, :func:`run` and :func:`done` are explained in more detail in
+the next sections.
+
+
+Constructor
+^^^^^^^^^^^
+
+To create an application, derive from the seiscomp.client.Application class
+and configure it in the constructor.
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 7,9,11
+
+   class MyApp(seiscomp.client.Application):
+       # MyApp constructor
+       def __init__(self, argc, argv):
+           # IMPORTANT: call the base class constructor
+           seiscomp.client.Application.__init__(self, argc, argv)
+           # Default is TRUE
+           self.setMessagingEnabled(False)
+           # Default is TRUE, TRUE
+           self.setDatabaseEnabled(False, False)
+           # Default is TRUE
+           self.setDaemonEnabled(False)
+
+As marked in line 4, the call of the constructor of the base class is very
+important. It takes the command line parameters and sets up internal
+application variables. Without this call the application will either not run
+at all or show undefined/unexpected behaviour.
+
+The constructor takes also the initial parameters of the application such as
+enabling a messaging connection and enabling database access.
+
+Messaging, database and daemon mode is enabled by default. The daemon mode is
+important if the application should be started as service and therefore should
+support the option ``-D, --daemon``. Utilities and non daemon applications
+should disable that mode.
+
+Example calls to this options are shown in the highlighted lines of the above
+code block.
+
+If messaging is enabled, the messaging username is derived from the binary
+called (*not the class name*). If the script is called test.py then the username
+selected is **test**. The username can be overridden either in the configuration
+file (:ref:`global`) or using the API.
+
+.. code-block:: python
+
+   self.setMessagingUsername("test")
+
+Setting the username to an empty string results in a random username selected
+by the messaging server.
+
+All application methods are defined in the C++ header file
+:file:`src/trunk/libs/seiscomp/client/application.h`.
+
+
+Init
+^^^^
+
+The workflow of the init function looks like this:
+
+.. code-block:: python
+
+   init (virtual)
+       initConfiguration (virtual)
+       initCommandLine (virtual)
+           createCommandLineDescription (virtual)
+       parseCommandLine (virtual)
+           printUsage (virtual)
+       validateParameters (virtual)
+       loadPlugins
+       forkDaemon
+       initMessaging
+       initDatabase
+       loadInventory or loadStations
+       loadDBConfigModule
+       loadCities
+
+Methods marked with virtual can be overridden. :func:`init` itself calls
+a lot of handlers that can be customized. Typical handlers are
+:func:`initConfiguration`, :func:`createCommandLineDescription`
+and :func:`validateParameters`.
+
+:func:`initConfiguration` is used to read parameters of the configuration files
+and to populate the internal state. If something fails or if configured values
+are out of bounds, False can be returned which causes :func:`init` to return
+False and to exit the application with a non-zero result code.
+
+An example is show below:
+
+.. code-block:: python
+
+   def initConfiguration(self):
+       if not seiscomp.client.Application.initConfiguration(self):
+           return False
+
+       try:
+           self._directory = self.configGetString("directory")
+       except:
+           pass
+
+       return True
+
+This method reads the directory parameter from the configuration file(s) and
+sets it internally. If the directory is not given in any of the modules
+configuration files, it logs an error and aborts the application by returning
+False.
+
+:func:`createCommandLineDescription` is used to add custom command line options.
+This is a void function and does not return any value. It is also not necessary
+to call the base class method although it does not hurt.
+
+.. code-block:: python
+
+   def createCommandLineDescription(self):
+       self.commandline().addGroup("Storage")
+       self.commandline().addStringOption("Storage", "directory,o", "Specify the storage directory")
+
+A new command line option group is added with :func:`addGroup` and then a new
+option is added to this group which is a string option.
+Four types can be added
+as options: string, int, double and bool: :func:`addStringOption`, :func:`addIntOption`,
+:func:`addDoubleOption` and :func:`addBoolOption`.
+
+:func:`validateParameters` can be used to fetch the values of previously added
+command line options and to validate each parameter. If False is returned, the
+application is aborted with a non-zero result code.
+
+.. code-block:: python
+
+   def validateParameters(self):
+       try:
+           self._directory = self.commandline().optionString("directory")
+       except:
+           pass
+
+       # The directory validity is checked to avoid duplicate checks in
+       # initConfiguration.
+       if not self._directory:
+           seiscomp.logging.error("directory not set")
+           return False
+
+       if not exists(self._directory):
+           seiscomp.logging.error(
+               "directory {} does not exist".format(self._directory))
+           return False
+
+       return True
+
+
+Custom initialization code after checking all parameters can be placed in the
+overridden method :func:`init`.
+
+.. code-block: python
+
+   def init(self):
+       if not seiscomp.client.Application.init(self):
+           return False
+
+       # Custom initialization code runs here.
+       setupCustomConnections()
+       readMyDataFiles()
+
+       return True
+
+But be aware that the process forked already if started as daemon. To run before
+the fork, it needs to be put into :func:`validateParameters`.
+
+
+Run
+^^^
+
+The workflow of the run method looks like this:
+
+.. code-block:: python
+
+   run (virtual)
+       startMessageThread
+       messageLoop
+           readMessage
+           dispatchMessage (virtual)
+               handleMessage (virtual)
+                   addObject (virtual)
+                   updateObject (virtual)
+                   removeObject (virtual)
+               handleReconnect (virtual)
+               handleDisconnect (virtual)
+               handleTimeout (virtual)
+               handleAutoShutdown (virtual)
+
+The run method starts the event loop and waits for new events in the queue.
+In case of messaging a thread is started that sits and waits for messages
+and feeds them to the queue and to the event loop in :func:`run`. Without
+messaging the run loop would do nothing but waiting for SIGTERM or
+a timer event enabled with :func:`enableTimer`. If the event loop is not needed
+because no timer and messages are needed, it should be overridden and the
+code should be placed there. This will disable the event loop.
+
+:func:`run` is expected to return True on success and False otherwise. If False
+is returned the application exists with a non-zero return code. Custom return
+codes can always be set with :func:`Application.exit`.
+
+If the scmaster sends a message to the client it is received in the applications
+message thread and pushed to the queue. The event loop pops the message from
+the queue and calls :func:`handleMessage`. The default implementation uses two
+settings when handling a messages that can be controlled with
+:func:`enableInterpretNotifier` and :func:`enableAutoApplyNotifier`.
+
+:func:`enableInterpretNotifier` controls whether the Application queries the
+message type and extracts notifier objects. For each notifier it parses the
+operation and dispatches the parentID and the object either to
+:func:`addObject`, :func:`updateObject` or :func:`removeObject` handler. This
+behaviour is enabled by default. If disabled, a clients needs to parse the
+messages by itself and implement this method.
+
+:func:`enableAutoApplyNotifier` controls whether incoming notifier objects are
+applied automatically to objects in local memory. If the client has already
+an object in memory and an update notifier for this object is received, the object
+in the notifier is copied to the local object. This behaviour is enabled by default.
+
+
+Done
+^^^^
+
+The workflow of the done method looks like this:
+
+.. code-block:: python
+
+   done (virtual)
+       closeTimer
+       closeMessaging
+       closeDatabase
+
+:func:`done` is usually not overridden. If custom code and clean up procedures
+need to be placed in :func:`done`, the base class **must** be called. :func:`done` is a
+void function.
+
+.. code-block:: python
+
+   def done(self):
+       seiscomp.client.Application.done()
+
+       # Custom clean ups
+       closeMyDataFiles()
+       closeCustomConnections()
+
+
+
+StreamApplication class
+-----------------------
+
+The application class has another occurrence: :class:`seiscomp.client.StreamApplication`.
+
+The class :class:`StreamApplication` extends the :class:`Application`
+in terms of record acquisition. It spawns another thread that reads the records
+from a configurable source and adds a new handler method
+:func:`StreamApplication.handleRecord` to handle these records.
+
+
+Its workflow looks like this:
+
+.. code-block:: python
+
+   init (virtual)
+       +initRecordStream
+   run (virtual)
+       +startAcquisitionThread
+           +storeRecord
+       Application.messageLoop
+           dispatchMessage (virtual)
+               +handleRecord (virtual)
+    done (virtual)
+        +closeRecordStream
+
+
+Received records can be handled with :func:`handleRecord`.
+
+.. code-block:: python
+
+   def handleRecord(self, rec):
+       print rec.streamID()
+
+The stream subscription should be done in :func:`init`. :func:`recordStream`
+returns the RecordStream instance which can be used to add stream requests.
+
+.. code-block:: python
+
+   def init(self):
+       if not seiscomp.client.StreamApplication.init(self):
+           return False
+
+       # Subscribe to some streams
+       self.recordStream().addStream("GE", "MORC", "", "BHZ")
+       return True
+
+
+The record stream service is configured either with configuration files
+(:confval:`recordstream`) or
+via command-line options ``-I`, ``--record-url``.
+
+The application finishes if the record stream read EOF. Running a :class:`StreamApplication`
+with :ref:`Seedlink<seedlink>` would probably never terminate since it is a
+real time connection and handles reconnects automatically.

share/doc/seiscomp/html/_sources/base/build.rst.txt

@@ -0,0 +1,135 @@
+.. _build:
+
+***********************
+Getting the Source Code
+***********************
+
+.. caution::
+
+   For production systems only
+   :ref:`install the officially released packages <installation-packages>`
+   from :cite:t:`seiscomp`, :cite:t:`gempa` or compile from the corresponding
+   release tags in this repository.
+
+The |scname| software collection is distributed among several repositories.
+For more information about compilation and build configuration head over to
+:cite:t:`seiscomp-github`.
+
+For building a complete |scname| distribution checkout all repositories using
+the following script:
+
+.. code-block:: sh
+
+   #!/bin/bash
+
+   if [ $# -eq 0 ]
+   then
+       echo "$0 <target-directory>"
+       exit 1
+   fi
+
+   target_dir=$1
+   repo_path=https://github.com/SeisComP
+
+   echo "Cloning base repository into $1"
+   git clone $repo_path/seiscomp.git $1
+
+   echo "Cloning base components"
+   cd $1/src/base
+   git clone $repo_path/seedlink.git
+   git clone $repo_path/common.git
+   git clone $repo_path/main.git
+   git clone $repo_path/extras.git
+
+   echo "Cloning external base components"
+   git clone $repo_path/contrib-gns.git
+   git clone $repo_path/contrib-ipgp.git
+   git clone https://github.com/swiss-seismological-service/sed-SeisComP-contributions.git contrib-sed
+
+   echo "Done"
+
+   cd ../../
+
+   echo "If you want to use 'mu', call 'mu register --recursive'"
+   echo "To initialize the build, run 'make'."
+
+
+.. _compiling_source:
+
+***********************************
+Compiling |scname| from Source Code
+***********************************
+
+To build from source you will need to clone from one or more repositories as
+described in :ref:`build`.
+
+Before building, **install all the dependencies**,
+as described below in :ref:`build_dependencies`.
+
+The easiest way to compile |scname| is to use the :file:`Makefile` file
+provided which creates a build directory inside the source tree.
+
+Perform the following steps:
+
+* Clone all required repositories (see above)
+* Run :file:`make`
+* Configure the build
+* Press 'c' as long as 'g' appears
+* Press 'g' to generate the Makefiles
+* Enter the build directory and run :file:`make install`
+
+By default all files are installed under :file:`$HOME/seiscomp`.
+This location can be changed with `cmake` or with its front end `ccmake`.
+
+Basically the build directory can live anywhere. The following steps create
+a build directory, configure the build and start it:
+
+.. code-block:: sh
+
+   $ mkdir sc-build
+   $ cd sc-build
+   $ ccmake /path/to/sc-src
+   # Configure with ccmake
+   $ make install
+
+
+.. _build_dependencies:
+
+Software dependencies
+=====================
+
+For compiling the |scname| sources the following development software packages
+are required (Debian/Ubuntu package names):
+
+* g++
+* git
+* cmakecmake-gui
+* libboost
+* libxml2-dev
+* flex
+* libfl-dev
+* libssl-dev
+* crypto-dev
+* python3-dev (optional)
+* python3-numpy (optional, required if Numpy support is enabled which is also the default configuration)
+* libqt5-dev (optional)
+* qtbase5-dev (optional)
+* libmysqlclient-dev (optional)
+* libpq-dev (optional)
+* libsqlite3-dev (optional)
+* ncurses-dev (optional)
+
+As of |scname| in version 5.0.0 support for Python 2 is dropped and Python 3 has
+become the default.
+The Python development libraries are required if Python wrappers should be
+compiled which is the default configuration. The development files must
+match the used Python interpreter of the system.
+
+
+Compiling |scname| for MacOS
+============================
+
+Although |scname| has been developed, compiled and tested on Linux systems,
+users have compiled |scname| on MacOS.
+The procedures are given online by external sources :cite:p:`macos-compile`.
+Please contact the managers of these sources for any requests.

share/doc/seiscomp/html/_sources/base/changelog.rst.txt

@@ -0,0 +1,3 @@
+.. _sc-changelog:
+
+.. mdinclude:: CHANGELOG.md

share/doc/seiscomp/html/_sources/base/citation.rst.txt

@@ -0,0 +1,22 @@
+.. _citation:
+
+********
+Citation
+********
+
+Please give appropriate reference to |scname| :cite:p:`seiscomp` when publishing your work.
+You may cite the |scname| software as:
+
+Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH (2008).
+The SeisComP seismological software package. GFZ Data Services.
+doi: `10.5880/GFZ.2.4.2020.003 <http://dx.doi.org/10.5880/GFZ.2.4.2020.003>`_.
+
+BibTex: ::
+
+   @Misc{seiscomp,
+     Title                    = {{The SeisComP seismological software package. GFZ Data Services.}},
+     Author                   = {{Helmholtz-Centre Potsdam - GFZ German Research Centre for Geosciences and gempa GmbH}},
+     Year                     = {2008},
+     Doi                      = {10.5880/GFZ.2.4.2020.003},
+     Url                      = {https://www.seiscomp.de}
+   }

share/doc/seiscomp/html/_sources/base/coding-conventions.rst.txt

@@ -0,0 +1,298 @@
+.. _coding_conventions:
+
+******************
+Coding Conventions
+******************
+
+Code Style
+**********
+
+Formatting
+==========
+
+For C++ always use tab indentation. In case of line break white spaces have to be
+used to fill the space. The recommended tab width is 4 characters.
+
+.. code-block:: c++
+
+   // Tabs are visualized with '>' and spaces with '.'
+   int myFunction() {
+   >   int a = 5;
+   >   if ( a > 5 ) {
+   >   >   SEISCOMP_DEBUG("A is greater than 5. Its current value is %d",
+   >   >   ...............a);
+   >   return a;
+   }
+
+C++ code is (or should be) written with the following code style:
+
+.. code-block:: c++
+
+   /***************************************************************************
+    * Copyright (C) ...                                                       *
+    *                                                                         *
+    * All rights reserved.                                                    *
+    * Contact: <contact>                                                      *
+    *                                                                         *
+    * Author: <name>                                                          *
+    * Email: <email>                                                          *
+    *                                                                         *
+    * GNU Affero General Public License Usage                                 *
+    * This file may be used under the terms of the GNU Affero                 *
+    * Public License version 3.0 as published by the Free Software Foundation *
+    * and appearing in the file LICENSE included in the packaging of this     *
+    * file. Please review the following information to ensure the GNU Affero  *
+    * Public License version 3.0 requirements will be met:                    *
+    * https://www.gnu.org/licenses/agpl-3.0.html.                             *
+    *                                                                         *
+    * Other Usage                                                             *
+    * Alternatively, this file may be used in accordance with the terms and   *
+    * conditions contained in a signed written agreement between you and      *
+    * gempa GmbH.                                                             *
+    ***************************************************************************/
+
+   #ifndef NAMESPACE_LIB_FILENAME_H
+   #define NAMESPACE_LIB_FILENAME_H
+
+
+   #include <math.h>
+
+   class Complex {
+      public:
+         Complex(double re, double im)
+         : _re(re), _im(im) {}
+
+         double modulus() const {
+             return sqrt(_re * _re + _im * _im);
+         }
+
+         <template typename T>
+         void set(T r, T i) {
+             _re = r;
+             _im = i;
+         }
+
+       private:
+           double _re;
+           double _im;
+   };
+
+
+   void bar(int i) {
+       static int counter = 0;
+       counter += i;
+   }
+
+
+   namespace Foo {
+   namespace Bar {
+
+
+   void foo(int a, int b) {
+       for ( int i = 0; i < a; ++i ) {
+           if (  i < b )
+               bar(i);
+           else {
+               bar(i);
+               bar(b);
+           }
+       }
+   }
+
+
+   } // namespace Bar
+   } // namespace Foo
+
+   #endif
+
+
+File layout
+===========
+
+* See above header example
+* **Trailing newline**: use a newline at the end of each source file.
+* **Include guards**: Use include guards in your header files instead of #pragma once:
+
+  .. code-block:: c++
+
+     #ifndef NAMESPACE_LIB_FILENAME_H
+     #define NAMESPACE_LIB_FILENAME_H
+     ...
+     #endif
+
+
+Name layout
+===========
+
+Use descriptive names and camel capping. That means the name of the element
+starts with the case given in the following table. Every concatenated word
+starts with an uppercase letter (e.g. myDescriptiveElementName).
+
+For straight enumerations where values start with 0 a quantity name should be
+defined that describes the upper bound for all valid enumeration values. Its
+name should be prepended by two letters describing the enumeration name and an
+underscore.
+
+Look at the class example above for guidance.
+
++-----------------------------+----------------------+--------------------------------------+
+| Type                        | Case of first letter | Comment                              |
++=============================+======================+======================================+
+| variable                    | lowercase            |                                      |
++-----------------------------+----------------------+--------------------------------------+
+| function                    | lowercase            |                                      |
++-----------------------------+----------------------+--------------------------------------+
+| structure                   | uppercase            |                                      |
++-----------------------------+----------------------+--------------------------------------+
+| class                       | uppercase            |                                      |
++-----------------------------+----------------------+--------------------------------------+
+| member variables:                                                                         |
++-----------------------------+----------------------+--------------------------------------+
+| \- public                   | lowercase            | starts without underscore            |
++-----------------------------+----------------------+--------------------------------------+
+| \- protected                | lowercase            | starts with underscore               |
++-----------------------------+----------------------+--------------------------------------+
+| \- private                  | lowercase            | starts with underscore               |
++-----------------------------+----------------------+--------------------------------------+
+| methods                     | lowercase            |    no                                |
++-----------------------------+----------------------+--------------------------------------+
+| static methods              | uppercase            |    no                                |
++-----------------------------+----------------------+--------------------------------------+
+| inline methods and          | lowercase            | sourced out into separate .ipp file  |
+| templates                   |                      | with same name as the header file    |
++-----------------------------+----------------------+--------------------------------------+
+| enumeration                 | uppercase            | elements are written all uppercase   |
++-----------------------------+----------------------+--------------------------------------+
+| documentation and           | -                    | use Doxygen                          |
+| comments                    |                      |                                      |
++-----------------------------+----------------------+--------------------------------------+
+
+File naming
+===========
+
+All source and header files are named with lowercase letters. The suffix of a
+source file is ".cpp" while for a header file it is ".h". The name of files
+that contain a class has to correspond with the class name. For other files,
+a descriptive name has to be provided (e.g. protocol.h instead of pro.h).
+
+
+Programming Guidelines
+**********************
+
+Return values
+=============
+
+While designing methods or functions these rules about return values should be kept in mind:
+
+- Functions returning an int or related types as status: 0 means success;
+  everything else is an error [1]_
+- Functions returning a pointer:
+  0 (or :code:`nullptr`) means an error and of course an
+  invalid pointer [1]_
+- Functions returning a class object can throw an exception in case of an error.
+  This is not obligatory and should be used with care.
+
+  **Example**: std::string myMethod();
+
+Exception specifications
+========================
+
+According to [2]_ dynamic exception specifications are considered or proposed
+as deprecated feature and not recommended [3]_. Don't use them in declaring a function prototype.
+
+.. code-block:: c++
+
+   // Don't use that
+   int foo() throw(ValueException);
+
+   // Just declare it without an exception specification
+   int foo();
+
+
+Null pointer
+============
+
+Use either 0 or the :code:`nullptr` keyword of C++11.
+Check a null pointer with implicit boolean conversion.
+
+.. code-block:: c++
+
+   if ( !ptr )
+       do_something();
+
+rather than
+
+.. code-block:: c++
+
+   if ( ptr == 0 )
+       do_something();
+
+or
+
+.. code-block:: c++
+
+   if ( ptr == NULL )
+       do_something();
+
+Virtual Functions
+=================
+
+Virtual functions are a fundamental concept of polymorphic classes. Virtual
+functions will be overwritten in derived classes to implement specific
+behaviour. It can happen that the signature of the virtual function in the
+base class changes but derived classes do not follow this change.
+
+This causes in erroneous behaviour as the derived virtual function will not
+be called as desired. What is even worse is that this mismatch of signatures
+is hard to find and to debug.
+
+Fortunately C++11 introduces the long awaited override keyword which declares
+that a virtual function of a derived class intends to override the virtual
+function with the same name of the base class. If both signatures do not match,
+the compiler will throw an error.
+
+.. code-block:: c++
+
+   class Base {
+       virtual void print() {
+           cout << "Base class" << endl;
+       }
+   }
+
+   class Derived : public Base {
+       virtual void print() {
+           cout << "Derived class" << endl;
+       }
+   }
+
+If we change the signature of print to take an additional parameter then
+the derived method will not be called anymore.
+
+.. code-block:: c++
+
+   class Base {
+       virtual void print(ostream &os) {
+           os << "Base class" << endl;
+       }
+   }
+
+Adding the override keyword will force the compiler to check both signatures
+for equality.
+
+.. code-block:: c++
+
+   class Derived : public Base {
+       void print() override {
+           os << "Derived class" << endl;
+       }
+   }
+
+This code above will throw an error during compilation and one has to adapt
+the signature of the function.
+
+Use the override keyword whenever you implement a virtual function in derived
+classes.
+
+.. [1] http://www.stroustrup.com/bs_faq2.html#null
+.. [2] http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3051.html
+.. [3] http://www.gotw.ca/publications/mill22.htm

share/doc/seiscomp/html/_sources/base/concepts.rst.txt

@@ -0,0 +1,23 @@
+.. _concepts:
+
+********
+Concepts
+********
+
+This chapter refers to concepts shared between any applications of
+the :term:`trunk` package.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   Messaging: Exchanging information in real-time processing </base/concepts/messaging>
+   Modules: Daemon programs and command-line tools </base/concepts/modules>
+   Plugins: Extensions to modules </base/concepts/plugins>
+   Database: Storing meta data, configurations and data products</base/concepts/database>
+   Waveform archive: Storing raw waveform data </base/concepts/waveformarchives>
+   RecordStream: Access to data from real-time servers or archives </base/concepts/recordstream>
+   Inventory: Station meta data </base/concepts/inventory>
+   Configuration: Inventory, module and binding configurations </base/concepts/configuration>
+   Processing: Magnitude computation </base/concepts/magnitudes>
+   Processing: Locator types </base/concepts/locators>

share/doc/seiscomp/html/_sources/base/concepts/configuration.rst.txt

@@ -0,0 +1,904 @@
+.. _concepts_configuration:
+
+#############
+Configuration
+#############
+
+
+Scope
+=====
+
+This chapter describes the configuration of a processing system and how all
+the pieces gear into each other. It will cover module specific
+configuration, inventory (station metadata) and module station bindings.
+
+
+Overview
+========
+
+The |scname| framework defines a common schema to read configuration parameters.
+This schema is used by all :ref:`SeisComP modules <concepts_modules>` with names
+starting with **sc**, e.g. `scautopick`. Other modules might be available
+as well such as third party modules which use other naming conventions.
+
+A way to discover a module that uses the |scname| configuration schema
+is to call it with ``--help``. The first lines of a typical output look like
+this:
+
+.. code-block:: sh
+
+   Generic:
+     -h [ --help ]                         Produce help message
+     -V [ --version ]                      Show version information
+     --config-file arg                     Use alternative configuration file
+
+The reason for that is that there are also other modules which do not
+use the |scname| core and client libraries such Seedlink plugins, Seedlink
+itself and some others which are not part of the trunk source package. Those
+modules need translators to generate their native configuration when
+the configuration is updated (``seiscomp update-config``).
+
+Again, the two indicators that a module uses the following configuration
+schema are:
+
+* The module name is prefixed with **sc**, e.g. *scautopick*
+* The output of ``--help`` looks like the text fragment above
+
+A typical configuration requires the following steps:
+
+#. Generation and import of an inventory (station meta data): Read the concept
+   section :ref:`concepts_inventory`,
+#. :ref:`Configuration of modules <global_modules_config>`,
+#. :ref:`Configuration of bindings <global_bindings_config>`.
+
+.. note::
+
+   :ref:`Standalone modules <concepts_modules>` can also run without inventory.
+
+
+.. _concepts_configuration-configs:
+
+Configuration of Modules
+========================
+
+|scname| modules provide 2 types of configurations:
+
+* :ref:`Module configurations <global_modules_config>` define module control
+  parameters which are equally applied to all operations on waveforms, event
+  parameters, graphical user interfaces, etc.
+
+  **All** :ref:`daemon modules <concepts_modules_daemon>` and **some**
+  :ref:`command-line tools <concepts_modules_commandline>` provide module
+  configurations. *Module configurations are overridden by bindings
+  configurations.*
+
+* :ref:`Binding configurations <global_bindings_config>` define control
+  parameters per station and even stream. They are used for station- and even
+  stream-specific definitions, e.g. the data acquisition from a particular
+  station or server using :ref:`seedlink` or the phase detection by
+  :ref:`scautopick`.
+
+  In contrast to module configuration, **only some**
+  :ref:`daemon modules <concepts_modules>` and a very few
+  :term:`GUI modules <GUI>` provide bindings. *Binding configurations override
+  module configurations.*
+
+Whether or not a module considers bindings configurations can be read in the
+module configuration panel of :ref:`scconfig`.
+
+.. raw:: html
+
+   <div class="two column layout">
+
+.. figure:: ../media/scconfig_no_bindings.png
+   :alt: scconfig: no bindings configurations
+
+   scconfig modules panel indicating that no bindings can be configured.
+
+.. figure:: ../media/scconfig_has_bindings.png
+   :alt: scconfig: no bindings configurations
+
+   scconfig modules panel indicating that bindings can be configured.
+
+.. raw:: html
+
+   </div>
+
+
+.. _global_modules_config:
+
+Module configuration
+--------------------
+
+Configurations for modules are saved as :file:`*.cfg` files. There are three
+directories involved where configuration files can be stored:
+
+#. :file:`$SEISCOMP_ROOT/etc/defaults/`: This directory ships with the distribution
+   of |scname| and should never be touched. All contained files might be
+   overwritten with the next software update.
+#. :file:`$SEISCOMP_ROOT/etc/`: This directory will never be populated by a software
+   update and it is save to store global module configuration files there.
+   Depending on the system setup this directory might be read-only to users.
+   It is called the system configuration directory.
+#. :file:`$HOME/.seiscomp/`: This directory is in the user's home directory and
+   it is meant to provide configurations which override default and system
+   configurations.
+   It is called the user configuration directory.
+
+Furthermore there are two file names involved in each directory:
+:file:`global.cfg` and :file:`[module].cfg`. The file :file:`global.cfg`
+will be loaded by all modules and it is a good place to store common
+parameters such as messaging connections or logging configurations.
+
+The three directories and two files result in 6 locations to read all of a
+module's configuration parameters:
+
+#. :file:`$SEISCOMP_ROOT/etc/defaults/global.cfg`
+#. :file:`$SEISCOMP_ROOT/etc/defaults/[module].cfg`
+#. :file:`$SEISCOMP_ROOT/etc/global.cfg`
+#. :file:`$SEISCOMP_ROOT/etc/[module].cfg`
+#. :file:`$HOME/.seiscomp/global.cfg`
+#. :file:`$HOME/.seiscomp/[module].cfg`
+
+The order of the configuration files above also represents the order of loading.
+Parameters can be available in any of these files. The last occurrence of a
+parameter takes priority such as  configurations in :file:`$HOME/.seiscomp/`.
+
+
+Adjusting
+~~~~~~~~~
+
+:ref:`scconfig` provides a user-friendly graphical interface to adjust the
+global and the module configuration parameters.
+
+.. figure:: ../media/scconfig_config_modules.png
+   :alt: scconfig: module configuration
+   :align: center
+   :width: 18cm
+
+   scconfig modules module configuration panel.
+
+Alternatively, you may adjust the module configuration files corresponding to
+a module. An easy way of getting started is to copy the default configuration
+file in :file:`$SEISCOMP_ROOT/etc/defaults/` to :file:`$SEISCOMP_ROOT/etc/` and
+adjust it there.
+
+.. warning::
+
+   Do not adjust any parameter in the default configuration files located in
+   :file:`$SEISCOMP_ROOT/etc/defaults/` as they will be overwritten by future
+   software updates.
+
+
+Application
+~~~~~~~~~~~
+
+Module configurations are usually read when starting a module and cannot be
+changed during runtime. For applying any change on module configuration
+
+#. Save the configuration,
+#. Restart or execute all affected modules.
+
+In addition to a permanent configuration you may temporally override any
+configuration parameter when executing a module. Provide the full structure of
+the configuration parameter on the command line along with "=" between parameter
+and value. This will identify the parameter as a configuration parameter
+overridden on the command line. E.g. refer to the codes parameter of
+:ref:`scrttv` in the streams section as `codes.streams`:
+
+.. code-block:: sh
+
+   $ scrttv --streams.codes="GR.*.*.HH?"
+
+
+.. _global_bindings_config:
+
+Bindings configuration
+----------------------
+
+Bindings configure parameters specific to stations and for a certain module.
+A station might require a custom set of parameters for e.g. data acquisition from
+a remote data logger or server, for processing or
+displaying. |scname| design is that bindings will be stored
+in the database. All modules requiring this information read them from the
+database. In this way consistent inventory and its bindings will be distributed
+to all modules running locally or on remote computers.
+
+.. hint::
+
+   Bindings can be conveniently configured in the Bindings panel of :ref:`scconfig`.
+   Read the section :ref:`scconfig-bindings` for instructions.
+
+.. _config-fig-binding:
+
+.. figure:: ../media/binding.*
+   :align: center
+
+   Binding
+
+   A binding holds the configuration how a station is used in a module.
+
+Parameters defined in bindings override parameters in module configurations.
+Bindings configurations are saved as stations bindings or as bindings profiles with
+given names:
+
+#. **Station binding parameters:** :file:`$SEISCOMP_ROOT/etc/key/[module]/station_NET_STA`
+   is used only be one station NET.STA.
+#. **Binding profile parameters:** :file:`$SEISCOMP_ROOT/etc/key/[module]/profile_[name]`
+   can be used by many stations. Then any update of this file applies to all stations
+   bound to this profile.
+
+Like in this list, the actual binding parameters for each module are
+expected in either :file:`etc/key/$MODULE/station_$NET_$STA` or
+:file:`etc/key/$MODULE/profile_$PROFILE`. That depends if a profile should
+be used or not. If the station key file registers a module with a colon
+following a name then this name is the profile name. If just a module is given
+then the station binding file will be read.
+
+The bindings themselves are links from the module to the station. They are written
+into key files, e.g.
+
+* :file:`$SEISCOMP_ROOT/etc/key/station_NET_STA`
+
+Example of bindings profiles:
+
+.. code-block:: properties
+
+   # Binding references
+   global:__HH
+   scautopick:default
+   seedlink:geofon
+
+Example of bindings profiles and a station binding for slarchive:
+
+.. code-block:: properties
+
+   # Binding references
+   global:__HH
+   scautopick:default
+   seedlink:geofon
+   slarchive
+
+The key files are named like :file:`station_$NET_$STA`, e.g. :file:`station_GE_MORC`.
+The names within the key files define for which modules the station registers. In the
+above example it is the **global**, **scautopick**, **seedlink** and slarchive.
+
+To list all modules a particular station is configured for is very simple by printing the content
+of the station key file:
+
+.. code-block:: sh
+
+   $ cat etc/key/station_GE_MORC
+   seedlink:geofon
+   global:BH
+   scautopick
+
+Another way is a bit more complicated but at least all information is
+there. To show all stations configured for SeedLink could be done this way:
+
+.. code-block:: sh
+
+   $ for i in `find etc/key -type f -maxdepth 1 -name "station_*_*"`; do
+   > egrep -q '^seedlink(:.*){0,1}$' $i && echo $i;
+   > done
+   etc/key/station_GE_MORC
+   etc/key/station_GE_UGM
+
+Modules usually read the bindings configuration from the database but not from files.
+Therefore,  the bindings are stored in the database when executing
+
+.. code-block:: sh
+
+   $ seiscomp update-config
+
+The database tables involved are ``ConfigModule``, ``ConfigStation``, ``Setup``,
+``ParameterSet`` and ``Parameter``.
+
+.. _config-fig-configdb-schema:
+
+.. figure:: ../media/configdb-schema.png
+   :align: center
+
+   Configuration database schema
+
+To illustrate the contents of the objects, the XML representation
+is used below.
+
+.. code-block:: xml
+
+   <Config>
+     <module publicID="Config/trunk" name="trunk" enabled="true">
+       ...
+     </module>
+   </Config>
+
+A ConfigModule with publicID *Config/trunk* is created with name *trunk*. This
+ConfigModule is managed by the global initialization script (:file:`etc/init/trunk.py`)
+and will be synchronized with configured bindings of all trunk modules. The
+ConfigModule trunk is the one that is actually used by all configurations unless
+configured otherwise with:
+
+.. code-block:: sh
+
+   $ scapp --config-module test
+
+Here :program:`scapp` would read ConfigModule *test*. Because a ConfigModule *test*
+is not managed by :program:`seiscomp update-config` it is up to the user to create
+it.
+
+
+For each station that has at least one binding, a ConfigStation object is
+attached to the ConfigModule:
+
+.. code-block:: xml
+
+   <Config>
+     <module publicID="Config/trunk" name="trunk" enabled="true">
+       <station publicID="Config/trunk/GE/UGM"
+                networkCode="GE" stationCode="UGM" enabled="true">
+         ...
+       </station>
+     </module>
+   </Config>
+
+and finally one Setup per module:
+
+.. code-block:: xml
+
+   <Config>
+     <module publicID="Config/trunk" name="trunk" enabled="true">
+       <station publicID="Config/trunk/GE/UGM"
+                networkCode="GE" stationCode="UGM" enabled="true">
+         <setup name="default" enabled="true">
+           <parameterSetID>
+             ParameterSet/trunk/Station/GE/UGM/default
+           </parameterSetID>
+         </setup>
+         <setup name="scautopick" enabled="true">
+           <parameterSetID>
+             ParameterSet/trunk/Station/GE/UGM/scautopick
+           </parameterSetID>
+         </setup>
+       </station>
+     </module>
+   </Config>
+
+
+Here two setups have been created: *default* (which is a special case for
+module *global* to be backwards compatible) and *scautopick* where each
+refers to a ParameterSet by its publicID. The next XML fragment shows
+the ParameterSet referred by the scautopick setup of station GE.UGM:
+
+.. code-block:: xml
+
+   <Config>
+     <parameterSet publicID="ParameterSet/trunk/Station/GE/UGM/scautopick"
+                   created="...">
+       <baseID>ParameterSet/trunk/Station/GE/UGM/default</baseID>
+       <moduleID>Config/trunk</moduleID>
+       <parameter publicID="...">
+         <name>timeCorr</name>
+         <value>-0.8</value>
+       </parameter>
+       <parameter publicID="...">
+         <name>detecFilter</name>
+         <value>
+           RMHP(10)&gt;&gt;ITAPER(30)&gt;&gt;BW(4,0.7,2)&gt;&gt;STALTA(2,80)
+         </value>
+       </parameter>
+       <parameter publicID="...">
+         <name>trigOff</name>
+         <value>1.5</value>
+       </parameter>
+       <parameter publicID="...">
+         <name>trigOn</name>
+         <value>3</value>
+       </parameter>
+     </parameterSet>
+   </Config>
+
+The mapping to the binding configuration files is 1:1. Each parameter in
+the configuration file is exactly one parameter in the database and their
+names are matching exactly.
+
+The concept of global bindings which are specialized for each module is
+reflected by the *baseID* of the ParameterSet which points to setup *default*
+of station GE.UGM:
+
+.. code-block:: xml
+
+   <Config>
+     <parameterSet publicID="ParameterSet/trunk/Station/GE/UGM/default"
+                   created="...">
+       <moduleID>Config/trunk</moduleID>
+       <parameter publicID="...">
+         <name>detecStream</name>
+         <value>BH</value>
+       </parameter>
+     </parameterSet>
+   </Config>
+
+This ends up with a final configuration for scautopick and station GE.UGM:
+
+===========   ==================
+Name          Value
+===========   ==================
+detecStream   BH
+timeCorr      -0.8
+detecFilter   RMHP(10)>>ITAPER(30)>>BW(4,0.7,2)>>STALTA(2,80)
+trigOff       1.5
+trigOn        3
+===========   ==================
+
+which is the concatenation of the two files :file:`etc/key/global/station_GE_UGM`
+and :file:`etc/key/scautopick/station_GE_UGM`. The filter grammar is explained in
+:ref:`filter grammar section <filter-grammar>`.
+
+
+The :file:`etc/key` directory is only used to ease the configuration of bindings.
+They are finally transferred to the database or converted to other
+representations a module might require to access them. The  directory :file:`etc/key` is meant
+for backup and used for copying bindings from one computer to another.
+
+
+Adjusting
+~~~~~~~~~
+
+:ref:`scconfig` provides a graphical interface to adjust the global and the module
+bindings parameters and to create the bindings. It populates the :file:`etc/key`
+directory and it takes care that they synchronize with the database when processing
+*Update configuration* in the *System* panel.
+
+.. figure:: ../media/scconfig_config_bindings.png
+   :alt: scconfig: bindings configuration
+   :align: center
+   :width: 18cm
+
+   scconfig modules bindings configuration panel.
+
+Alternatively, you may manually generate the binding parameter file
+:file:`etc/key/global/station_GE_UGM` and
+:file:`etc/key/scautopick/station_GE_UGM` and add the binding to the key file
+corresponding to the station, e.g.,
+:file:`$SEISCOMP_ROOT/etc/key/station_GE_UGM`.´
+
+
+SeisComP shell
+~~~~~~~~~~~~~~
+
+Instead of creating bindings in :ref:`scconfig` or by adjusting key files
+manually you may assign binding profiles to stations or networks or remove them
+using the |scname| shell which is a specific shell:
+
+#. Start the |scname| shell:
+
+   .. code-block:: sh
+
+      seiscomp shell
+
+#. Issue a shell command. Examples:
+
+   * Read the help of the new shell:
+
+     .. code-block:: sh
+
+        ================================================================================
+        SeisComP shell
+        ================================================================================
+
+        Welcome to the SeisComP interactive shell. You can get help about
+        available commands with 'help'. 'exit' leaves the shell.
+
+        $ help
+
+   * add the existing scautopick binding profile, *default*, to the station
+     *GE.UGM*:
+
+     .. code-block:: sh
+
+        $ set profile scautopick default GE.UGM
+
+     or to all stations of the network *GE*:
+
+     .. code-block:: sh
+
+        $ set profile scautopick default GE.UGM
+
+   * remove the scautopick binding profile, *default*, from the station *GE.UGM*:
+
+     .. code-block:: sh
+
+        $ remove profile scautopick default GE.UGM
+
+   * exit the shell and get back to the Linux shell:
+
+     .. code-block:: sh
+
+        $ exit
+
+
+Example: global bindings
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A binding is a set of name value pairs just like a configuration file but for
+a station. In the file system a binding looks like this:
+
+.. code-block:: properties
+
+   detecLocid = ""
+   detecStream = HH
+
+Simple. These are actually two parameters from the global binding and it solves
+a common issue elegantly: a station might provide a couple of channels, often
+data in various sampling rates, e.g. LH, BH, SH and HH. Co-located stations
+with velocity and acceleration sensors also provide at least two channel groups,
+e.g. HL and HH. Those groups are also provided with different location code,
+e.g. 00 and 10. To process a station a module needs to know which channel
+it should process. To display a representative data channel a viewer needs to
+know which channel to show. Global bindings solve that issue by defining the
+"preferred" location code and channel code with the two parameters `detecLocid`
+and `detecStream`. The TraceView, :ref:`scrttv` can read all available station
+bindings, compose a fully qualified channel name from network code (part of the
+binding), station code, detecLocid and detecStream. It will then lookup the
+inventory information for that channel and display it.
+
+The meta data of a binding are:
+
+* Network code,
+* Station code,
+* Module name.
+
+The actual binding data are the key value pairs.
+
+
+Reading bindings
+~~~~~~~~~~~~~~~~
+
+Binding configuration parameters are read during a module start after the module
+configuration parameters.
+They override the module configuration.
+Like module configurations, parameters defined in the global bindings can be
+overridden in module bindings. The order of loading is:
+
+#. :file:`$SEISCOMP_ROOT/etc/key/global/`: Global bindings configurations
+#. :file:`$SEISCOMP_ROOT/etc/key/[module]`:  Bindings configurations for a particular module.
+
+If the module connects to a messaging server then it will receive the database parameters,
+connect to it and read the bindings. Otherwise the user has to provide the
+database address. A module never reads the key directory. It only
+gets the bindings from the configuration tables.
+
+As with inventory information there might are cases when a module should
+not connect to a database and work offline, in particular when ``--ep`` is being
+used.
+
+In order to
+read the bindings configuration from XML files (again in SCML format),
+use :ref:`scxmldump` to dump the configuration XML file and let
+the module use this XML file, ``--config-db`` must be used:
+
+.. code-block:: sh
+
+   $ myapp --config-db config.xml
+
+That will completely bypass the database (even if used for event information or
+inventory) for reading station bindings.
+
+To extract a configuration XML file from the database, :ref:`scxmldump` can be used:
+
+.. code-block:: sh
+
+   $ scxmldump -fC -d localhost -o config.xml
+
+One can also create a config XML file straight from the ``etc/key`` directory
+with ``bindings2cfg``:
+
+.. code-block:: sh
+
+   $ bindings2cfg -o config.xml
+
+To create an XML file from a temporary key directory, an alternative directory
+can be specified with ``--key-dir``:
+
+.. code-block:: sh
+
+   $ bindings2cfg --key-dir /tmp/key -o config.xml
+
+
+Application
+~~~~~~~~~~~
+
+Binding configurations are read when starting a module and cannot be
+changed during runtime. For applying any change on binding configurations
+
+#. Save the configuration,
+#. Update the configuration
+
+   .. code-block:: sh
+
+      $ seiscomp update-config
+
+#. Restart or execute all affected modules.
+
+
+Summary
+~~~~~~~
+
+* Bindings are maintained as key files in :file:`etc/key`,
+* Key files are another human readable representation of bindings,
+* ``seiscomp update-config`` or ``seiscomp update-config trunk`` writes the
+  information from :file:`etc/key` to the database,
+* A module never reads :file:`etc/key`,
+* Bindings are being read from the database or an XML file.
+
+
+Validation
+----------
+
+After changing configuration the affected modules should be tested, e.g. by
+running with informative debug logging output. You may use :ref:`scdumpcfg` for
+dumping the module an binding parameters into a summary file.
+
+
+.. _concepts_configuration_parameters:
+
+Format of Parameters
+====================
+
+The :term:`trunk` configuration files are simple text files where each line
+is a name-value pair containing the parameter name and its value.
+
+Parameter values can be provided as
+
+* plain values or comma-separated lists on single or multiple lines
+  (read sections below) or as
+* :ref:`variables <concepts_configuration_variables>`, allowing to refer to
+  previously defined parameters, e.g., in :file:`global.cfg` or to define relative
+  directories related to the |scname| installation or the Linux system.
+
+.. warning::
+
+   In contrast to previous versions of |scname| the parameter names are now
+   case-sensitive. Use :ref`scchkcfg` to check configurations from previous
+   versions regarding case-sensitivity.
+
+
+Basic
+-----
+
+Module and binding configuration files are simple text file where each line is a
+name-value pair for one parameter. The parameter names are case-sensitive. The
+format is a simple as:
+
+.. code-block:: properties
+
+   agencyID = gempa
+   recordstream = slink://localhost:18000
+
+Spaces in string parameters must be protected by quotes:
+
+.. code-block:: properties
+
+   eventlist.filter.types.blacklist = "not existing"
+
+Parameter groups are indicated by a separating dot ("."). The dot separates the
+group from the parameter name or other groups. The item after the last dot is
+the parameter.
+
+Later assignments of parameters override previous ones so the order of lines in the
+configuration file is important. The file is parsed top-down.
+
+.. note::
+
+   Values are not type-checked. Type checking is part of the module
+   logic and will be handled there. The configuration file parser will not raise
+   an error if a string is assigned to a parameter that is expected to be an
+   integer.
+
+
+Comments
+--------
+
+Everything following an unescaped **#** (hash) is a comment and is going to
+be ignored. Blank lines and white spaces are ignored by the parser as well
+unless quoted or escaped. Escaping is done by prepending a backslash (**\\\\**)
+to the character that needs escaping. It backslash should be part of the
+string, two backslashes should be used (**\\\\\\\\**).
+
+.. code-block:: properties
+
+   agencyID = gempa  # This is a comment
+
+   # The preceding empty line is ignored. Now the value of skyColor is replaced
+   # with 'blue'.
+   # The final value of a parameter is the result of the last assignment parsed
+   # from top to bottom.
+   agencyID = gempa
+
+
+Lists
+-----
+
+Values can be either scalar values or lists. List items are separated by commas.
+
+.. code-block:: python
+
+   # This is a list definition
+   rainbowColors = red, orange, yellow, green, blue, indigo, violet
+
+If a value needs to include a comma, white space or any other special
+character it can either be escaped with backslash ('\\') or quoted with double
+quotes ("). Whitespaces are removed in unquoted and unescaped values.
+
+.. code-block:: properties
+
+   # This is a comment
+
+   # The following list definitions have 2 items: 1,2 and 3,4
+   # quoted values
+   tuples = "1,2", "3,4"
+   # escaped values
+   tuples = 1\,2, 3\,4
+
+The value of the parameter tuples is now `["1,2", "3,4"]`.
+
+
+Multi-line
+----------
+
+Values can extend over multiple lines if a backslash is appended to each line
+
+.. code-block:: properties
+
+   # Multi-line string
+   text = "Hello world. "\
+          "This text spawns 3 lines in the configuration file "\
+          "but only one line in the final value."
+
+   # Multiline list definition
+   rainbowColors = red,\
+                   orange,\
+                   yellow,\
+                   green, blue,\
+                   indigo, violet
+
+
+Control characters
+------------------
+
+A limited set of control characters is allowed within strings.
+
+.. csv-table::
+   :widths: 10 90
+   :align: left
+   :delim: ;
+
+   \\n; new line
+   \\t; tab
+
+Example of a string consisting of two lines:
+
+.. code-block:: properties
+
+   a = "123 456"\n"This is a new line with text"
+
+The control characters must be outside of double quotes. Everything **within**
+double quotes will **not** be decoded. Hence, "\n" will end up as the string
+"\n" and not a new line character.
+
+
+Namespaces
+----------
+
+A basic usage of variable names is to organize them in namespaces. A common
+habit is to separate namespaces and variable names with a period character:
+
+.. code-block:: properties
+
+   colors.sky = blue
+   colors.grass = green
+
+Here a namespace called ``colors`` is used. The configuration file parser does
+not care about namespaces at all. The final name (including the periods) is what
+counts. But to avoid repeating namespaces again and again, declarations can
+be wrapped in a namespace block. See the following example:
+
+.. code-block:: properties
+
+   colors {
+      sky = blue
+      grass = green
+   }
+
+Application code will still access ``colors.sky`` and ``colors.grass``.
+Namespaces can be arbitrarily nested and even survive includes.
+
+.. code-block:: properties
+
+   A {
+      B1 {
+         var1 = 123
+      }
+
+      B2 {
+         var1 = 456
+      }
+   }
+
+The final list of parameter names is:
+
+* A.B1.var1
+* A.B2.var1
+
+
+.. _concepts_configuration_variables:
+
+Variables
+=========
+
+Environment or preceding configuration variables (configuration parameters) can
+be used as values for :ref:`parameters <concepts_configuration_parameters>` in
+the configuration of SeisComP modules with `${var}`, e.g.
+
+.. code-block:: properties
+
+   plugins = ${plugins}, hypo71
+
+   homeDir = ${HOME}
+   myPath = ${homeDir}/test
+   myseiscomp = ${SEISCOMP_ROOT}
+
+|scname| knows internal variables defining the it environment. The can be used
+with `@var@`, e.g.
+
+.. code-block:: properties
+
+   autoloc.stationConfig = @DATAGDIR@/autoloc/station.conf
+
+Available internal |scname| variables are:
+
++------------------+-----------------------------+
+| Variable         | Value                       |
++==================+=============================+
+| ROOTDIR          | $SEISCOMP_ROOT              |
++------------------+-----------------------------+
+| DEFAUTLCONFIGDIR | $SEISCOMP_ROOT/etc/defaults |
++------------------+-----------------------------+
+| SYSTEMCONFIGDIR  | $SEISCOMP_ROOT/etc          |
++------------------+-----------------------------+
+| DATADIR          | $SEISCOMP_ROOT/share        |
++------------------+-----------------------------+
+| CONFIGDIR        | $HOME/.seiscomp             |
++------------------+-----------------------------+
+| LOGDIR           | $HOME/.seiscomp/log         |
++------------------+-----------------------------+
+
+The list of internal |scname| variables can also be read in the information
+panel of :ref:`scconfig`.
+
+.. figure:: ../media/scconfig_information.png
+   :alt: scconfig: information panel
+   :align: center
+   :width: 18cm
+
+   scconfig information panel indicating the internal |scname| variables.
+
+The internal |scname| variable CONFIGDIR can be re-defined by the SHELL
+environment variable SEISCOMP_LOCAL_CONFIG. Setting SEISCOMP_LOCAL_CONFIG will
+also effect LOGDIR which is automatically set to
+:file:`$SEISCOMP_LOCAL_CONFIG/log`.
+Example:
+
+.. code-block:: sh
+
+   export SEISCOMP_LOCAL_CONFIG=/var/log/seiscomp
+
+
+Related Tools
+=============
+
+* :ref:`bindings2cfg`
+* :ref:`scchkcfg`
+* :ref:`scconfig`
+* :ref:`scdumpcfg`
+* :ref:`scxmldump`

share/doc/seiscomp/html/_sources/base/concepts/database.rst.txt

@@ -0,0 +1,117 @@
+.. _concepts_database:
+
+********
+Database
+********
+
+
+Scope
+=====
+
+This chapter provides an overview over databases supported by |scname|.
+
+
+Overview
+========
+
+|scname| can store and read information from a relational database management
+system (RDBMS). Supported are basically all existing RDBMS for which a plugin
+can be written. Currently, :ref:`database plugins <concepts_plugins>` are
+provided for
+
+.. csv-table::
+   :widths: 1 1
+   :header: Database, Plugin Name
+   :align: left
+
+   MySQL / MariaDB, *dbmysql*
+   PostgreSQL, *dbpostgresql*
+   SQLite3, *dbsqlite3*
+
+
+Database access
+---------------
+
+Typically, the database is accessed by the messaging (:ref:`scmaster`) for
+reading and writing.
+Most other modules can only read from the database but do not write into it.
+Among the few exceptions which can also directly write to the database are
+:ref:`scdb` and :ref:`scardac`.
+
+The database connection provided by the messaging is configured by the
+:ref:`scmaster module configuration <scmaster>`. :ref:`Modules <concepts_modules>`
+connected to the messaging receive the read connection parameters through the
+messaging connection. However, the default read connection by these and all
+other modules may be set with :confval:`database` in
+:ref:`global configuration <global-configuration>` or set on the command line
+using :option:`--database` or simply :option:`-d`.
+Read the sections :ref:`installation` and :ref:`getting-started` on the
+installation and the configuration of the database backend and the initial setup
+of the database itself, respectively.
+
+The database connection may be used together with the *debug* option to print
+the database commands along with debug log output. Example for using
+:ref:`scolv` in offline mode with database debug output:
+
+.. code-block:: sh
+
+   scolv -d localhost?debug --offline --debug
+
+
+Database schema
+---------------
+
+The used database schema is well defined and respected by all modules which
+access the database. It is similar to the SeisComML schema (:term:`SCML`,
+a version of XML) and the C++ / Python class hierarchy of the datamodel
+namespace / package.
+
+Information of the following objects can be stored in the database as set out in
+the :ref:`documentation of the data model <api-datamodel-python>`.
+
+.. csv-table::
+   :widths: 25, 75
+   :header: Object, Description
+   :align: left
+   :delim: ;
+
+   :ref:`Config <concepts_configuration>`; station bindings
+   :ref:`DataAvailability <api-datamodel-python>`; information on continuous data records
+   :ref:`EventParameters <api-datamodel-python>`; derived objects like picks, amplitudes, magnitudes origins, events, etc.
+   :ref:`Inventory <concepts_inventory>`; station meta data
+   :ref:`Journaling <api-datamodel-python>`; information on commands and actions, e.g., by :ref:`scevent <scevent-journals>`
+   :ref:`QualityControl <api-datamodel-python>`; waveform quality control parameters
+
+.. note::
+
+   The Config parameters just cover station bindings. Application/module specific
+   configurations (all .cfg files) are not stored in the database and only kept
+   in files.
+
+The currently supported version of the database schema can be queried by any
+module connecting to the data base using the option :option:`-V`. Example:
+
+.. code-block:: sh
+
+   $ scm -V
+
+     scm
+     Framework: 6.0.0 Development
+     API version: 16.0.0
+     Data schema version: 0.12
+     GIT HEAD: 5e16580cc
+     Compiler: c++ (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
+     Build system: Linux 6.2.0-26-generic
+     OS: Ubuntu 22.04.3 LTS / Linux
+
+
+Related Modules
+===============
+
+* :ref:`scardac`
+* :ref:`scdb`
+* :ref:`scdbstrip`
+* :ref:`scdispatch`
+* :ref:`scquery`
+* :ref:`scqueryqc`
+* :ref:`scxmldump`

share/doc/seiscomp/html/_sources/base/concepts/inventory.rst.txt

@@ -0,0 +1,244 @@
+.. _concepts_inventory:
+
+*********
+Inventory
+*********
+
+
+Scope
+=====
+
+This chapter describes the concept of inventories.
+
+
+Overview
+========
+
+In |scname| the term :term:`inventory` refers to the meta data of data recording
+stations.
+Many |scname| :ref:`modules <concepts_modules>` require inventory information to
+operate correctly and a correct inventory is therefore fundamental to |scname|.
+
+The inventory will be read from the :ref:`database <concepts_database>`
+by default. To insert or update the inventory in the database, this information
+needs to be created or downloaded and converted. The following sections will
+describe the process of populating the database and how applications get access
+to it.
+
+The format used for inventory is known as :term:`SCML`. Correct inventory in
+:term:`SCML` format can be generated by :cite:t:`smp`. Some modules for
+**converting from other formats** are listed in section
+:ref:`concepts_inventory_format`. Tools for **processing inventory** are
+listed in section :ref:`concepts_inventory_tools`.
+
+The inventory shall contain all meta data describing the full recording system
+and the
+pre-processing of the raw data stream provided to the data processing modules
+using the :ref:`RecordStream <concepts_recordstream>`. Inventories should be
+always complete w.r.t the
+processed data streams, correct and up-to-date. Beside network, station, location
+and stream information they must include the full sensor and datalogger responses.
+
+Older version used key files to configure available networks and stations.
+Because the support of response meta-data was very limited, tools were build to
+add this functionality. Since the release of Seattle the concept of key files
+for station meta-data has been completely removed from the system. Now |scname|
+only handles station meta-data in its own XML format called :term:`SCML`.
+The task of supporting old key files, dataless SEED and other formats has been
+out-sourced to external applications. The inventory synchronization is a
+:ref:`two-stage process <config-fig-inventory-sync>`:
+
+#. Convert :ref:`external formats <concepts_inventory_format>` into :term:`SCML`
+#. Synchronize inventory pool with the database: merged all inventory files and
+   synchronize with the database using :program:`scinv snyc`.
+
+.. _config-fig-inventory-sync:
+
+.. figure:: ../media/inventory-sync.png
+   :align: center
+   :width: 12cm
+
+   Inventory synchronization as a two-stage process
+
+All station meta-data are stored in :file:`etc/inventory`
+and can be organized as needed. Either one file per network, a file containing the
+complete inventory or one file for all instruments and one file per station.
+The update script
+
+.. code-block:: xml
+
+   $ scinv sync
+
+loads the existing inventory from the database and merges each file in :file:`etc/inventory`.
+Finally it removes all unreferenced objects and sends all updates to the database.
+
+The |scname| :ref:`configuration <concepts_modules>` does not deal with station
+meta-data anymore.
+It only configures parameters for modules and module-station associations.
+The management of the inventory can and should be handled by external tools
+e.g. :cite:t:`smp`.
+
+The |scname| documentation describes the
+:ref:`data model including the inventory <api-datamodel-python>`.
+
+
+.. _concepts_inventory_format:
+
+Inventory Format
+================
+
+A typical inventory file in :term:`SCML` looks like this:
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp xmlns="http://geofon.gfz-potsdam.de/ns/seiscomp-schema/0.11" version="0.11">
+     <Inventory>
+       <sensor>...
+       <datalogger>...
+       <network>...
+     </Inventory>
+   </seiscomp>
+
+The version attribute of the ``seiscomp`` tag represents the schema version of
+the |scname| data model which is consistent with the database schema version
+and the version of all other representations.
+
+.. note::
+
+   All geographic coordinates (latitudes, longitudes, elevation) are assumed in the
+   World Geodetic System 1984 (WGS84) reference system (National Imagery and
+   Mapping Agency 2000). Latitudes, longitudes are provided in degrees but
+   elevations are given in meters.
+
+Inventories must be provided to |scname| in XML files in :term:`SCML` format. A
+convenient way to generate clean and correct inventory files in :term:`SCML`
+format is :cite:t:`smp`. Tools are provided to convert between other formats:
+
+
+.. csv-table::
+   :widths: 1 1
+   :header: Module namespace, Conversion
+   :align: left
+
+   arclink2inv, Arclink XML to SeisComPML
+   :ref:`dlsv2inv`, dataless SEED to SeisComPML
+   :ref:`inv2dlsv`, SeisComPML to dataless SEED
+   :ref:`fdsnxml2inv`, FDSN StationXML to SeisComPML and back
+
+
+Adding / Updating Inventory
+===========================
+
+To add inventory information to the |scname| database one either has to write directly
+to the database with custom script (not recommended) or place :term:`SCML` files
+in :file:`@SYSTEMCONFIGDIR@/inventory`. The service to import all data in that
+directory can be called with
+
+.. code-block:: sh
+
+   $ seiscomp update-config inventory
+
+This command runs :ref:`scinv` finally. :ref:`scinv` merges all XML files and
+synchronizes the merged local inventory tree with the database. That is a
+rather complex process and for more information it is recommended to study
+the source code of :ref:`scinv`. The bottom line is that inventory data is created
+from :term:`SCML` files.
+
+Because nobody will ever create such XML files by hand, tools are necessary.
+A quite popular tools is the online station management portal (SMP)
+:cite:p:`smp`. SMP will output XML in version of :term:`SCML` directly.
+
+Another source is the FDSN station webservice (FDSNWS). If the |scname|
+implementation of FDSNWS is used, the SeisComP XML format can be requested
+directly as an extension. Otherwise FDSN StationXML will be provided. Inventory
+in FDSN StationXML needs to be converted with either :ref:`fdsnxml2inv` or
+:ref:`import_inv`. The latter is a more versatile application that also supports
+several import formats.
+
+.. code-block:: sh
+
+   $ import_inv fdsnxml download-1234.xml
+
+This will automatically place the output XML file in
+:file:`@SYSTEMCONFIGDIR@/inventory`. Afterwards call
+
+.. code-block:: sh
+
+   $ seiscomp update-config inventory
+
+to synchronize the changes with the database. If :program:`scconfig` is used,
+then either the ``Sync`` button of the `Inventory` panel or the
+``Update configuration`` button of the ``System`` panel must pressed.
+
+**Summary**
+
+In order to populate the database with inventory information, the following
+steps have to be performed:
+
+#. Convert existing station meta data formats to :term:`SCML`
+#. Place all :term:`SCML` files at :file:`@SYSTEMCONFIGDIR@/inventory`
+#. Synchronize the inventory files and write the meta data to the database. Run
+
+   .. code-block:: sh
+
+      $ scinv sync
+
+   or
+
+   .. code-block:: sh
+
+      $ seiscomp update-config inventory
+
+
+Reading Inventory
+=================
+
+Applications usually connect to the database and read the necessary inventory
+information. An application can decide whether it requires full response
+information including sensor and data logger response functions or just channel
+information without instrument descriptions. The latter performs faster and
+some applications do not require full instrument information.
+
+An application usually does not require special configuration to read inventory
+information. A database connection is enough and it comes usually along with the
+handshake message of the messaging server.
+
+If the messaging is not involved, the database can be specified by the
+command-line option ``-d``:
+
+.. code-block:: sh
+
+   $ myapp -d [type]://[user]:[password]@[host]:[port]
+
+There are cases when an application should be run without a database connection
+but requires inventory information, particularly in combination with the
+``--ep`` command line argument. To direct an application to an inventory XML file
+(again in :term:`SCML` format), ``--inventory-db`` must be used:
+
+.. code-block:: sh
+
+   $ myapp --inventory-db inventory.xml
+
+The option ``--inventory-db`` will cause the module to completely bypass
+the database for reading inventory information even if used for event
+information. The file :file:`inventory.xml` can be created from the database
+using :ref:`scxmldump`.
+
+
+.. _concepts_inventory_tools:
+
+Related Tools
+=============
+
+* arclink2inv
+* :ref:`dlsv2inv`
+* :ref:`fdsnxml2inv`
+* :ref:`import_inv`
+* :ref:`invextr`
+* :ref:`inv2dlsv`
+* :ref:`sccnv`
+* :ref:`scinv`
+* :ref:`scxmldump`
+* :ref:`tab2inv`
+* :ref:`tabinvmodifier`

share/doc/seiscomp/html/_sources/base/concepts/locators.rst.txt

@@ -0,0 +1,82 @@
+.. _concepts_locators:
+
+Locators
+########
+
+Locators receive :term:`phase picks <pick>` from modules such as :ref:`scautoloc`,
+:ref:`screloc` or :ref:`scolv` for locating seismic or non-seismic sources. The
+solutions may include source time and location with or without uncertainties.
+They are used to form new :term:`origins <origin>` which can be treated
+further.
+
+|scname| ships with built-in locators:
+
+* :ref:`FixedHypocenter <global_fixedhypocenter>` (FH)
+* :ref:`Hypo71 <global_hypo71>`
+* :ref:`iLoc <global_iloc>`
+* :ref:`LOCSAT <global_locsat>`, the default locator in :ref:`scautoloc` and :ref:`scolv`
+* :ref:`NonLinLoc <global_nonlinloc>`
+* :ref:`StdLoc <global_stdloc>`
+
+and a none built-in locator:
+
+* :ref:`LocExt <global_locext>`.
+
+While the built-in locators are well defined and documented, any other external
+locator routine can be added to |scname| by configuration of the locator
+:ref:`LocExt <global_locext>` and custom scripts.
+LOCSAT and FixedHypocenter are native to |scname|. All other locators are
+implemented as :term:`plugins <plugin>`. A :term:`plugin`
+needs to be added to the list of loaded plugins by configuration of the global
+parameter :confval:`plugins` for making the corresponding locator available to
+|scname| applications.
+
+A comparison of the locators is given in the table below.
+
+.. note::
+
+   The specifications given below may depend on the configuration of the
+   respective locator. Please carefully read the documentation of the locators
+   for optimizing their performance.
+
+.. csv-table::
+   :widths: 30 10 10 10 10 10 10 10
+   :header: , FH, Hypo71, iLoc, LocExt, LOCSAT, NonLinLoc, StdLoc
+   :align: center
+
+   **Applications**, ,,,,,,
+   phases considered by default,                    seismic / infrasound, seismic, seismic / infrasound / hydroacoustic, [3], seismic / infrasound,  seismic, seismic
+   distance ranges of application,                  local / regional / teleseismic, local / regional, local / regional / teleseismic, [3], local / regional / teleseismic, local / regional / teleseismic, local / regional [4]
+   application with default configuration,          regional / teleseismic,  ❌, regional / global, [3], regional / teleseismic,  ❌,  local / regional [1]
+   **Algorithm**, ,,,,,,
+   inversion algorithm,                             linear,  iterative, configurable, [3], grid search, probabilistic, configurable
+   automatic phase renaming,                        ❌, ❌, ✅, [3], ❌, ❌, ❌
+   considers network code,                          ✅, ❌, ✅, [3], ✅, ✅ [1], ✅
+   positive station elevation,                      ✅ [2/4], ✅, ✅, [3], ✅ [2], ✅, ✅
+   negative station elevation,                      ❌, ✅, ✅, [3], ❌, ✅, ✅
+   considers pick time,                             ✅, ✅, ✅, [3], ✅, ✅, ✅
+   considers pick slowness,                         ❌, ❌, ✅, [3], ✅, ❌, ❌
+   considers pick backazimuth,                      ❌, ❌, ✅, [3], ✅, ❌, ❌
+   speed,                                           fast, fast, fast - intermediate, [3], fast, intermediate, fast - intermediate
+   **Velocity model**, ,,,,,,
+   velocity model,                                  1D [4], 1D, 1D, [3],1D, 1D / 3D, 1D / 3D [4]
+   independent Vp and Vs,                           ✅ [4], ❌, ✅, [3], ✅, ✅, ✅ [4]
+   default velocity model,                          iasp91 / tab, ❌, iasp91 / ak135, [3], iasp91 / tab, ❌, iasp91 / tab [1]
+   applies RSTT,                                    ❌ , ❌, ✅, [3], ❌, ❌, ❌
+   **Hypocenter solution**, ,,,,,,
+   inverts for hypocenter location,                 ❌, ✅, ✅, [3], ✅, ✅, ✅
+   inverts for hypocenter time,                     ✅, ✅, ✅, [3], ✅, ✅, ✅
+   supports negative source depth,                  ❌, ✅, ❌, [3], ❌, ✅, ✅
+   **Configuration**, ,,,,,,
+   native or plugin to load,                        ✅, *hypo71*, *lociloc*, *locext*, ✅, *locnll*, *stdloc*
+   |scname| provides locator,                       ✅, ✅, ✅, ❌, ✅, ✅, ✅
+   operates without external files,                 ✅, ❌, ❌, ❌, ✅, ❌, ✅
+   operates without custom scripts,                 ✅, ✅, ✅, ❌, ✅, ✅, ✅
+   **Others**, ,,,,,,
+   remarks,                                         intended for ground-truth tests / single-station location / any travel-time interface, ,operational at EMSC and ISC (earlier version), any external locator can be called by a custom script, currently the fastest locator in |scname| and the only one available to :ref:`scautoloc`, considers model uncertainties, uses travel-times from any travel-time interface
+   point of contact,                               :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, `ibondar2014 @gmail.com <ibondar2014@gmail.com>`_, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`, :cite:t:`seiscomp-forum`
+
+* [1]: requires initial or specific configuration
+* [2]: requires correction file
+* [3]: depends on selected locator
+* [4]: depends on selected travel-time interface

share/doc/seiscomp/html/_sources/base/concepts/magnitudes.rst.txt

@@ -0,0 +1,175 @@
+.. _concepts_magnitudes:
+
+Magnitudes
+##########
+
+Magnitudes are computed based on amplitudes measured from waveforms. Different
+types of amplitudes and magnitudes are available which are listed in
+:ref:`scamp` and :ref:`scmag`.
+
+
+Amplitudes
+==========
+
+Amplitudes can be measured automatically from waveforms
+
+* During phase picking by :ref:`scautopick` with generally fixed time windows
+  due to the absence of knowledge about source parameters or by,
+* :ref:`scamp` as soon as :term:`origins <origin>` are available. Depending
+  on the magnitude type, fixed or distance-dependent time windows apply.
+
+and interactively using :ref:`scolv`.
+
+
+Instrument simulation
+---------------------
+
+Amplitude measurements for some magnitude types require or allow the simulation
+of instruments such as :py:func:`Wood-Anderson torsion seismometers <WA>`
+(:cite:t:`richter-1935,uhrhammer-1990`), :py:func:`WWSSN_SP` or :py:func:`WWSSN_LP`.
+The calibration parameters describing the Wood-Anderson seismometer are
+configurable in global bindings or global module configuration:
+:confval:`amplitudes.WoodAnderson.gain`, :confval:`amplitudes.WoodAnderson.T0`,
+:confval:`amplitudes.WoodAnderson.h`. Specifically, the difference in magnitude
+due to configuration using original values listed in
+:cite:t:`richter-1935` and updated ones given in :cite:t:`uhrhammer-1990`
+result in a constant offset of 0.13 in those magnitudes which apply
+Wood-Anderson simulation, e.g. :term:`ML <magnitude, local (ML)>`,
+:term:`MLv <magnitude, local vertical (MLv)>`, :term:`MLc <magnitude, local custom (MLc)>`.
+
+
+Station Magnitudes
+==================
+
+Station magnitudes are computed automatically by :ref:`scmag` or interactively
+by :ref:`scolv` from measured amplitudes based on distance-dependent
+calibration curves which depend on magnitude type. When computing a set of
+magnitudes in :ref:`scolv` which is different from the set configured in
+:ref:`scmag`, then scmag may later add the missing magnitudes automatically.
+Magnitude types for which the evaluation status is set to "rejected", e.g., in
+scolv, will not be recomputed by scmag.
+
+
+.. _concepts-magnitudes-correction:
+
+Station corrections
+-------------------
+
+Linear station corrections applied to station magnitudes can be configured by
+global :ref:`binding parameters <global_bindings_config>`:
+
+#. Add a magnitude type profile where the name of the profile is the name of the
+   magnitude itself,
+#. Configure the correction parameters.
+
+When using binding profiles, all referencing stations will be affected equally
+which is typically not intended. In contrast, applying station bindings requires
+to set up many bindings which may not be intended either.
+
+Therefore, you may add lines to the global module configuration in
+:file:`global.cfg` where one line corresponds to one station with one magnitude
+and the corresponding correction parameter. The groups and the name of the
+parameters are identical to the global bindings parameters. All lines start with
+"*module.trunk*". Example for an offset correction of
+:term:`MLv <magnitude, local vertical (MLv)>` measured station GE.UGM:
+
+.. code-block:: properties
+
+   module.trunk.GE.UGM.magnitudes.MLv.offset = 0.1
+
+.. note::
+
+   The configuration of parameters starting with *module.trunk.* is not
+   supported by :ref:`scconfig`. All corresponding configurations must be done
+   by direclty editing the configuration file, e.g.,
+   :file:`seiscomp/etc/global.cfg`.
+
+
+Network Magnitudes
+==================
+
+Network magnitudes are computed automatically by :ref:`scmag` or interactively
+by :ref:`scolv` from station magnitudes based on averaging station magnitudes.
+The averaging methods applied by :ref:`scmag` are configurable by
+:confval:`magnitudes.average`. Available are (:cite:t:`rosenberger-1983`):
+
+* *mean*: the mean value from all station magnitudes.
+* *median*: the mean value from all station magnitudes.
+* *trimmedMean(X)*: gnores outlier station magnitudes by first removing the
+  largest and the smallest *X* % of the observed values (percentiles). The mean is
+  formed from the remaining station magnitudes.
+* *trimmedMedian(X)*: forms the median from all station magnitudes but returns
+  the uncertainty by ignoring the largest and the smallest *X* % station
+  magnitudes.
+* *medianTrimmedMean(X)*: returns the mean magnitude from all station magnitudes
+  differing less than *X* magnitudes from the median.
+
+
+Aliases
+=======
+
+New magnitude types (aliases) can be created based on existing magnitude and
+amplitude types but configured specifically.
+The setup procedure is outlined in the
+:ref:`tutorial on magnitude aliases <tutorials_magnitude-aliases>`.
+
+
+.. _concepts-magnitudes-regionalization:
+
+Regionalization
+===============
+
+The computation of station magnitudes can be regionalized. This means that for
+a specific region specific conditions apply when computing magnitudes. The
+conditions include any parameter available for configuring a magnitude
+including global binding parameters such as magnitude calibration, distance
+and depth ranges, etc. As an example you may wish to apply different
+attenuation curves for computing MLv magnitudes to earthquakes in Eastern and
+in Western Canada.
+
+Regionalization is achieved by adding magnitude-type profiles in the magnitudes
+section of global module configuration parameters. Regionalization assumes
+defaults from global bindings but overrides the values when configured. The
+setup procedure including
+:ref:`station corrections <concepts-magnitudes-correction>` is outlined in the
+:ref:`tutorial on regionalization <tutorials_magnitude-region-aliases>`.
+
+
+Moment Magnitudes
+=================
+
+Moment magnitudes can be derived from all other network magnitudes by mapping of
+the original network magnitude, e.g., *Mx*, to a new moment magnitude *Mw(Mx)*.
+
+The mapping function can be configured for all original magnitude types except
+:term:`mB <magnitude, derived mB (Mw(mB))>` and
+:term:`Mwp <magnitude, derived Mwp (Mw(Mwp))>` where the mapping is hardcoded.
+Read the :ref:`tutorial on moment magnitudes <tutorials_mags_moment>` for the
+configuration.
+
+
+.. _concepts-magnitudes-summary:
+
+Summary Magnitude
+=================
+
+In order to account for different phenomena related to magnitude computation
+including magnitude saturation and application of different magnitude types at
+specific distance and depth ranges of the sources a summary magnitude can be
+computed from network magnitudes by :ref:`scmag`. The summary magnitude is
+usually referred to as *M*. The name is configurable.
+
+.. note::
+
+   Station, network and summary magnitudes are contained uniquely in one
+   :term:`origin`.
+
+
+Preferred Magnitude
+===================
+
+From the list of computed network magnitudes and the summary magnitude,
+:ref:`scevent` can automatically determine the preferred magnitude of the
+:term:`event`. This may also be done interactively by operators in the
+:ref:`Event tab of scolv <scolv-sec-event-tab>` or by
+:ref:`custom commit buttons in scolv <sec-scolv-custom-commit>`.

share/doc/seiscomp/html/_sources/base/concepts/messaging.rst.txt

@@ -0,0 +1,242 @@
+.. _concepts_messaging:
+
+****************
+Messaging system
+****************
+
+
+Scope
+=====
+
+This chapter describes the messaging system used for exchanging parameter messages between
+different :ref:`SeisComP modules <concepts_modules>` during runtime.
+
+
+Overview
+========
+
+A typical real-time |scname| system consists of data processing and other
+modules (clients) and a messaging bus. The messaging bus connects all the
+clients letting them exchange information by messages through this bus.
+The messaging system is a fundamental concept of SeisComP following the
+publish-subscribe pattern :cite:p:`wppubsub`. It is provided by the |scname|
+module :ref:`scmaster`.
+
+Clients can be producers (sending messages) and/or consumers (receiving
+messages). The basic concept is really simple: A producer sends a message
+(some event parameter, arbitrary content) and a consumer read that message and tries to
+process it. That's it. That is a very generic approach which requires clients
+to understand the message content of each other.
+
+In |scname| this common messaging language consists of well defined message
+types and contents. The vast majority of messages sent around are so called
+**notifiers**.
+
+Notifiers inform about changes on the data model. They carry just three
+attributes:
+
+* The unique identifier of the parent object
+* The operation to apply (add, update or remove)
+* The subject
+
+Speaking XML, a notifier looks like this:
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp xmlns="http://geofon.gfz-potsdam.de/ns/seiscomp-schema/0.11" version="0.11">
+     <Notifier parentID="EventParameters" operation="add">
+       <Pick publicID="Pick/....">
+         <!-- All pick attributes will be placed here -->
+       </Pick>
+     </Notifier>
+   </seiscomp>
+
+Each client that receives such a notifier will take further actions if the
+information meets its interest. A simple example is :ref:`scautoloc`. It
+receives Pick objects in the form as written above. It stores the pick to its
+internal data structures and when there are enough picks to form an Origin,
+it does its processing and probably sends an Origin as a result (again as
+notifier).
+
+.. figure:: ../media/concepts/messaging/system.*
+   :alt: sketch of a distributed system
+   :align: center
+
+   Schematic view on a distributed SeisComP system.
+
+
+.. _messaging-queue :
+
+Queues
+======
+
+The messaging server (:ref:`scmaster`) manages a set of queues. Each queue is
+independent and clients can only connect to *one* queue at a time within one
+connection. Messages sent to a queue are sorted by their arrival time and
+forwarded to clients in exactly that order. That is called a FIFO (first in
+first out) queue.
+
+For each queue a set of processors can be added where each message is
+piped through. One example is the dbstore processor which applies notifiers to
+a configured relational database management system (RDBMS).
+
+One could configure scmaster with two queues, one for production which
+populates a database and one for playbacks which does not populate a database.
+
+A client can be directed to either the one or the other queue:
+
+.. code-block:: sh
+
+   connection.server = localhost/production
+
+or
+
+.. code-block:: sh
+
+   scautopick -H localhost/production
+
+
+.. _messaging-groups :
+
+Groups
+======
+
+Groups are like topic filters for a message. A message is always being sent to
+a specific group or a specific client (peer-to-peer). A client can subscribe
+to one or many groups and it will only receive messages tagged with a group it
+has subscribed to.
+
+For example :ref:`scautopick` processes waveforms sending detections or
+picks as pick notifiers to the PICK group. All clients subscribed to that group
+would also receive this information. If the queue is configured with the
+dbstore processor then it is guaranteed that the pick has been stored already
+in the database at the time of message arrival at the clients.
+
+A consumer of the PICK group messages is :ref:`scautoloc`. Whenever it receives
+a new pick it will try to associate it or to locate a seismic event. After it
+succeeded it will send an origin to the LOCATION group and so on.
+
+
+.. _messaging-scheme :
+
+Scheme
+======
+
+The messaging allows unencrypted or encrypted connections which are specified by
+the scheme parameter of the connection:
+
+* `scmp` (default): unencrypted,
+* `scmps`: encrypted.
+
+Scheme, host, port and :ref:`queue <messaging-scheme>` together form the
+connection URL of the messaging system which is configurable in
+:confval:`connection.server` or set by the command-line option ``-H``.
+
+Examples:
+
+* Connect to the production queue of the messaging on localhost with default port.
+  Not using encryption `scmp` can be assumed implicitly in global configuration ::
+
+     connection.server = localhost/production
+
+  On the command line use, e.g. ::
+
+     $ scolv -H localhost
+
+* Connect to the production queue of the messaging on localhost with default port.
+  Using non-default secure encryption and port the scheme and the port must be
+  provided explicitly  in global configuration ::
+
+     connection.server = scmps://localhost18181/production
+
+  On the command line use, e.g. ::
+
+     $ scolv -H scmps://localhost:18181/production
+
+
+.. _messaging-db :
+
+Database
+========
+
+The :ref:`database <concepts_database>` is populated by :ref:`scmaster` with all
+kind of information which might depend on
+each other. It is crucial for operations that write operations are well
+synchronized. Part of the messaging contract is that clients get read-only
+database access from :ref:`scmaster` and that they will never attempt to write
+into the database. In a fully-fledged |scname| system the only instance that is
+allowed to populate the database is the dbstore plugin of :ref:`scmaster`.
+
+When connecting from a client to the messaging, the database connection parameters
+are reported by :ref:`scmaster`. They can be overridden by the global configuration
+or command-line option ``-d``.
+
+Example: ::
+
+   scolv -H localhost -d mysql://sysop:sysop@localhost/seiscomp-test
+
+
+.. _messaging-distribution :
+
+Module distribution
+===================
+
+The messaging server accepts TCP/IP connections enabling a module actually
+running anywhere in the network. It happens that this concept is not understood
+and users run on each computer another :ref:`scmaster` instance to offload
+processing to more computers. Unfortunately each scmaster instance is
+configured with the same database connection which will most likely cause data
+inconsistencies because each group of modules which is connected to an scmaster
+instance does not know about the other scmaster clients and therefore ignore
+the sent updates.
+
+The correct approach is to run **one** scmaster on computer A which populates
+database X. Modules running on computer A, use
+
+.. code-block:: sh
+
+   connection.server = localhost/production
+
+while modules running on computer B use
+
+.. code-block:: sh
+
+   connection.server = computerA/production
+
+The database connection which is used by :ref:`scmaster` will be reported to the
+clients when they connect so no explicit database configuration is necessary.
+
+The messaging connection can be explicitly provided on the command line using
+the option ``-H`` considering the comments on the
+:ref:`scheme <messaging-scheme>` and :ref:`queue <messaging-queue>`, e.g.
+
+.. code-block:: sh
+
+   scolv -H computerA/production
+
+
+Web Frontend
+============
+
+When running :ref:`scmaster` a web frontend is available which can be adjusted to
+provide system information. The default port to access the web frontend is 18180:
+
+.. code-block:: sh
+
+   firefox localhost:18180
+
+.. figure:: ../media/concepts/messaging/scmaster_web.png
+   :alt: scmaster: web frontend
+   :align: center
+   :width: 10cm
+
+   scmaster: Web frontend
+
+
+Related Modules
+===============
+
+* :ref:`scmaster`
+* :ref:`scm`
+* :ref:`scmm`

share/doc/seiscomp/html/_sources/base/concepts/modules.rst.txt

@@ -0,0 +1,199 @@
+.. _concepts_modules:
+
+****************
+SeisComP modules
+****************
+
+
+Scope
+=====
+
+This document describes the difference between command-line and daemon modules.
+
+
+Overview
+========
+
+SeisComP is not a single executable but it provides a set of :term:`trunk` and
+:term:`standalone <standalone module>` :term:`modules <module>`. Trunk modules
+can be
+
+* :ref:`Command-line modules <concepts_modules_commandline>`,
+* :ref:`Daemon modules <concepts_modules_daemon>`.
+
+Modules are :ref:`configured by configuration files <concepts_modules_config>`
+either to be used directly or to generate its native configuration. Modules that
+need to convert the configuration or do not use the default configuration
+options (see below) are called :term:`standalone modules <standalone module>`.
+All other modules are called :term:`trunk` modules.
+
+Examples for standalone modules are :ref:`seedlink`, :ref:`slarchive` and :ref:`slmon`.
+
+.. note::
+
+   In order to start or execute modules without :command:`seiscomp exec`
+   (see below), the |scname| SHELL environment variables must be known to the
+   system. The variables and their values can be printed giving the full path to
+   the :ref:`seiscomp` tool. Example:
+
+   .. code-block:: sh
+
+      /home/sysop/seiscomp/bin/seiscomp print env
+
+
+.. _concepts_modules_daemon:
+
+Daemon Tools
+============
+
+Daemon tools are |scname| modules that can run automatically in the background
+without user interaction, e.g., for automatic data acquisition or data
+processing. The names of all daemon modules are listed when executing the
+:ref:`seiscomp` tool with :command:`list modules`:
+
+.. code-block:: sh
+
+   seiscomp list modules
+
+Daemon modules can be started to run in the background:
+
+.. code-block:: sh
+
+   seiscomp start scautopick
+
+When starting a daemon module, all verbosity output is logged to
+:ref:`log files <concepts_modules_logging>`. Daemon modules can also be executed
+as :ref:`command-line tools <concepts_modules_commandline>`.
+
+
+.. _concepts_modules_commandline:
+
+Command-Line Tools
+==================
+
+All non-daemon modules are command-line modules. These command-line modules
+and most :ref:`daemon modules <concepts_modules_daemon>` can be executed on
+demand from the SHELL command-line. These modules can also be
+utilities or :term:`graphical user interfaces (GUIs) <GUI>`.
+For executing use the full path to the :ref:`seiscomp` tool or, when the
+|scname| environment is known, just call the module name along with command-line
+options, e.g.
+
+.. code-block:: sh
+
+   seiscomp exec scolv [options]
+   scolv [options]
+
+Command-line modules are found in :file:`@ROOTDIR@/bin/` but they are **NOT**
+listed when executing
+
+.. code-block:: sh
+
+   seiscomp list modules
+
+Using options like :option:`-h` the list of available command-line options can
+be learned.
+
+.. code-block:: sh
+
+   scbulletin -h
+
+In addition, any module configuration parameter can be specified on
+the command line overriding the configured parameter. For indicating that a
+module configuration parameter is set on the command line separate the value
+from the parameter by '=' and provide the full set of sections separated by '.'.
+Example:
+
+.. code-block:: sh
+
+   scolv --picker.loadAllPicks=true
+
+When executing a module, all verbosity output is logged to
+:ref:`log files <concepts_modules_logging>`. The logging level can be controlled
+by configuration or by the command-line option :option:`-v`.
+
+.. code-block:: sh
+
+   scbulletin -vvvv
+
+Detailed debugging information can also be printed on the command line during
+runtime using the :option:`--debug` option:
+
+.. code-block:: sh
+
+   scbulletin --debug
+
+When starting a daemon module all verbosity output is stored in :file:`@LOGDIR@`
+or :file:`$SEISCOMP_ROOT/var/log`. Daemon modules can also be executed as
+:ref:`command-line tools <concepts_modules_commandline>`.
+
+
+.. _concepts_modules_config:
+
+Configuration
+=============
+
+Each :term:`standalone module` tries to read from three module configuration
+files whereas :term:`trunk` modules try to read the six files. Note that
+configuration parameters defined earlier are overwritten if defined in files
+read in later:
+
++-----------------------------------------+------------+----------------+
+| File                                    | Standalone | Trunk          |
++=========================================+============+================+
+| $SEISCOMP_ROOT/etc/defaults/global.cfg  |            |    X           |
++-----------------------------------------+------------+----------------+
+| $SEISCOMP_ROOT/etc/defaults/module.cfg  |  X         |    X           |
++-----------------------------------------+------------+----------------+
+| $SEISCOMP_ROOT/etc/global.cfg           |            |    X           |
++-----------------------------------------+------------+----------------+
+| $SEISCOMP_ROOT/etc/module.cfg           |  X         |    X           |
++-----------------------------------------+------------+----------------+
+|        ~/.seiscomp/global.cfg           |            |    X           |
++-----------------------------------------+------------+----------------+
+|        ~/.seiscomp/module.cfg           |  X         |    X           |
++-----------------------------------------+------------+----------------+
+
+In addition to the module configuration files some modules such as
+:ref:`seedlink` or :ref:`scautopick` consider :term:`bindings <binding>`.
+Bindings provide parameters specific to stations. They are configured as
+per-station bindings or profiles used for multiple stations.
+
+The :ref:`global configuration section <global-configuration>` describes all
+available global configuration parameters for a trunk module. Modules typically
+do not make use of all available global parameters because they may be disabled,
+e.g., the messaging component. So the configuration of the messaging server is
+disabled, too.
+
+The concept section :ref:`Configuration <concepts_configuration>` provides more
+details about configurations.
+
+
+.. _concepts_modules_logging:
+
+Logging
+=======
+
+Whenever operated, modules report the state of operation to log files. Trunk
+modules report the module and the start up log to :file:`@LOGDIR@/[module].log` and
+:file:`@ROOTDIR@/var/log/[module].log`, respectively. Standalone modules log to
+:file:`@ROOTDIR@/var/log/[module].log` only. The log files are rotated and the
+level of detail can be configured by :confval:`logging.level`. More parameters
+in :confval:`logging.*` provide more control over logging, e.g., the log file
+rotation.
+
+
+.. _concepts_modules_aliaes:
+
+Alias Modules
+=============
+
+Many :term:`trunk` and :term:`standalone modules <standalone module>` allow
+generating aliases as symbolic links to another module.
+These aliases are useful for running multiple instances of the same module with
+different configuration.
+
+Alias modules can be created or removed using the :ref:`seiscomp` tool by
+providing the commands :command:`alias create` or :command:`alias remove`,
+respectively. Read the documentation of :ref:`seiscomp <sec_seiscomp_aliases>`
+for the details.

share/doc/seiscomp/html/_sources/base/concepts/plugins.rst.txt

@@ -0,0 +1,91 @@
+.. _concepts_plugins:
+
+****************
+SeisComP plugins
+****************
+
+
+Scope
+=====
+
+This chapter describes the general use of plugins in SeisComP.
+
+
+Overview
+========
+
+Plugins expand the functionality of :ref:`applications <concepts_modules>`.
+They are C++ shared object libraries which are dynamically loaded at runtime
+into an application.
+
+Typical plugins provide access to:
+
+* :ref:`Databases <concepts_database>`
+* :ref:`Recordstream implementations <global_recordstream>`
+* :ref:`Locator routines <sec_index_extensions>`
+* :ref:`Amplitude and magnitude types <sec_index_extensions>`
+* :ref:`Waveform quality <scqc>`.
+
+The plugin files themselves are located in :file:`share/plugins`.
+
+By just loading a plugin an application does not change
+it's way to function magically. Common plugins just implement a certain
+interface (see e.g. messaging or RecordStream) and exhibit that functionality
+by adding a new entry to the internal interface factory. As an example an
+application makes use of interface ``DatabaseInterface``. Technically it
+creates a new object implementing a certain interface by calling the C++
+method:
+
+.. code-block:: sh
+
+   db = DatabaseInterface::Create("mysql");
+
+Without having a plugin loaded the returned object will be NULL or to put it
+in other words, there is not implementation for mysql available.
+
+Once the plugin ``dbmysql`` is loaded into the application, an implementation
+for type mysql is added and will be available to the application. It is
+still required for the application to explicitly ask for a particular
+interface. That is most likely left to the user by adding a corresponding
+configuration option to the configuration file.
+
+That means, if an application loads two plugins, e.g. ``dbmysql`` and
+``dbpostgresql`` that does not mean that it will not read from two database
+at a time. It means the user has now the option to either use a MySQL database
+or a PostgreSQL database. He still needs to make his choice in the
+configuration file.
+
+Trunk plugins are only supported as shared object libraries and therefore are
+required to be written in C++. Implementations for all available interfaces
+can be added. An incomplete list of SeisComP C++ interfaces:
+
+* :ref:`Messaging <concepts_messaging>`
+* :ref:`Database <concepts_database>`
+* :ref:`RecordStream <concepts_recordstream>`
+* Record formats
+* Map projections
+* :ref:`Time domain filters <filter-grammar>`
+* Importer
+* Exporter
+* **Amplitude processors**
+* **Magnitude processors**
+
+This is just a subset of available extensible interface factories. The
+emphasized entries refer to the factories which are most commonly extended.
+
+
+Location and Configuration
+==========================
+
+Plugins are located in :file:`$SEISCOMP_ROOT/share/pugins`. In order to make a
+plugins available for a module it must be added to the configuration of
+:confval:`plugins` of the global parameters of a module or in
+:ref:`global_configuration`.
+
+Configuring :confval:`plugins` with the name of a plugin will let the exclusively
+use this plugin and no other ones, e.g. default plugins. Example: ::
+
+   plugins = evrc
+
+In order to add a plugin to the default plugins or plugins loaded by before, e.g.
+by the global configuration, load these 

share/doc/seiscomp/html/_sources/base/concepts/recordstream.rst.txt

@@ -0,0 +1,68 @@
+.. _concepts_RecordStream:
+
+************
+RecordStream
+************
+
+Scope
+=====
+
+This document describes the RecordStream interface for accessing waveform data.
+
+Overview
+========
+
+A RecordStream refers to the interface which allows to retrieve records
+(time series) from arbitrary sources. An implementation can either be real-time
+and stream records continuously or time window based and just deliver what is
+available at the time of requesting data.
+A comprehensive list of RecordStream implementations is available in the
+:ref:`technical documentation <global_recordstream>`.
+
+RecordStream implementations have a name such as "slink", "fdsnws" or "file"
+which is used as scheme in the configuration URL. The location part of the URL
+is passed to the implementation. The scheme part is used to create the
+implementation. As one might have noticed, that RecordStream
+implementations can be added to existing applications with plugins.
+
+What do they do actually?
+
+Well, first of all they connect to or open the data source. If that fails, an
+error is logged. Then they are configured with time windows and channel
+identifieres. Once done, they are simply asked for new records in a loop. A
+RecordStream implementation can run forever or finish after a short time.
+The behavior depends on the implementation and configuration.
+
+The application uses RecordStreams like that:
+
+.. code-block:: python
+
+   # The RecordStream URL passed is slink://localhost:18000
+   scheme = URL.scheme()     # scheme = 'slink'
+   location = URL.location() # location = 'localhost:18000'
+   rs = RecordStream.Create(scheme)
+   if not rs:
+       throw Error()
+   if not rs.setSource(location):
+       throw Error()
+
+   rs.setStartTime(Time(2019,1,1))
+   rs.addStream('GE', 'UGM', '', 'BH?')
+   rs.addStream('GE', 'MORC', '', 'BH?')
+
+   while ( rec = rs.next() )
+       do_something_with(rec)
+
+In the example above the end time is not set, so actually an open time window
+should be read. That works pretty well for the Seedlink implemtation but the
+FDSNWS implementation would complain and issue an error because no end time
+was set. So configuring a RecordStream for an application requires some
+knowledge of the context and the supported features of the configured
+implementation.
+
+Although |scname| ships with the Seedlink server, the processing application
+are not aware of the fact that they connect to Seedlink. All time series
+retrieval is done with the RecordStream concept. There is no knowledge about
+the underlying implementation. This leads to a high flexibility and
+implementations can be added without the need to modify the base |scname|
+sources.

share/doc/seiscomp/html/_sources/base/concepts/waveformarchives.rst.txt

@@ -0,0 +1,67 @@
+.. _concepts_waveformarchives:
+
+*****************
+Waveform archives
+*****************
+
+Scope
+=====
+
+This chapter describes waveform archives for long-term storage of miniSEED data.
+
+Overview
+========
+
+While real-time data sources provide data for a rather short amount of time,
+long-term access to waveforms can be established through waveform archives.
+The :ref:`RecordStream interface <concepts_RecordStream>` allows a combined access
+to real-time data and data in :ref:`SDS <concepts_sds>` or other archives.
+
+.. note::
+
+   It is assumed that instrument corrections applied to the recorded
+   waveform data result in data in units of the real observations and their unmodified value.
+   Therefore, it is recommended to store only unprocessed raw data in units of digital counts
+   in the waveform archives and to provide the complete :ref:`inventory <concepts_inventory>`
+   referring to input data given in counts.
+
+.. _concepts_sds:
+
+SDS archives
+============
+
+SeisComP uses the SeisComP Data Structure (SDS) for archiving miniSEED waveform data.
+It has the structure:
+
+.. code-block:: sh
+
+   archive
+     + year
+       + network code
+         + station code
+           + channel code
+             + one file per day and location, e.g. NET.STA.LOC.CHAN.D.YEAR.DOY
+
+SeisComP ships with :ref:`slarchive` to create SDS archives from a miniSEED waveform
+buffer by :ref:`seedlink` in real time and with :ref:`scart` to intergrate miniSEED
+records from files into an SDS archive. :ref:`scart` can also be used to retrieve
+miniSEED records from an SDS archive.
+
+Access to waveform archives
+===========================
+
+Access from SeisComP processing and GUI modules to waveform archives is realized by
+:ref:`RecordStream implementations <concepts_RecordStream>`.
+The continuity of SDS archives can be monitored by :ref:`scardac` and exposed by
+the :ref:`fdsnws availability feature <fdsnws>`.
+miniSEED waveforms in SDS archives, can interactively retrieved using :ref:`scart`.
+Waveforms stored in SDS archives can be served to clients, e.g. using :ref:`fdsnws`.
+
+Related modules
+===============
+
+* :ref:`caps_plugin`
+* :ref:`fdsnws`
+* :ref:`scardac`
+* :ref:`scart`
+* :ref:`slarchive`

share/doc/seiscomp/html/_sources/base/contributing-docs.rst.txt

@@ -0,0 +1,581 @@
+.. _contributing_documentation:
+
+**************************
+Contributing Documentation
+**************************
+
+This is the documentation for the core processing elements and utilities that make up the |scname| system.
+It aims to document the configuration and command line options for
+|scname| in multiple formats (HTML, man, PDF, ePub etc) in a
+consistent way. The functionality of |scname| differs between
+versions so the documentation is versioned along with |scname|.
+For more general topics and tutorials please refer to the
+`SeisComP wiki`_.
+
+The documentation is written in `reStructuredText`_ (reST) a
+simple text mark up format. The documentation is generated using `Sphinx`_
+which is used to create the `Python documentation`_.
+The Sphinx website has a very good
+`introduction to reST`_ and also covers the Sphinx specific
+`directives`_.
+
+If you would like to add to this documentation or you find an error, then please
+submit a patch to `SeisComP on GitHub`_ or report to the
+SeisComP `discussion forum`_.
+
+.. note::
+
+   Please understand the :ref:`documentation style guide <documentation_style_guide>`
+   before contributing documentation.
+
+If you view the HTML version of the documentation in a browser,
+then you can use the *Show Source* link on each page to view the reST
+source. The source and the documentation files for executables (see below) are
+good starting points for a new patch.
+
+Documenting Executables
+=======================
+
+The documentation for executables is generated from two sources:
+
+'executable'.xml
+    An XML file that contains a brief description of the command,
+    markup describing the command line parameters, and any
+    configuration parameters for the executable. Each parameter should
+    have a brief description of the purpose of the parameter.
+
+    The description should be plain text and not contain reST markup. Where parameters are common across
+    a number of executables they should be placed in the appropriate common file and referred to using
+    their publicID.
+
+    All XML files live in the :file:`doc/apps` directory of the source
+    distribution or in :file:`etc/descriptions` of an installation.
+
+'executable'.rst
+    This is a text file in reST markup that gives any more-detailed description and examples for the executable.
+    It is combined with the corresponding .xml to create the full documentation.
+    The first entry in the file should be a paragraph giving a more
+    detailed description of the executable.
+
+These two files should be placed in a :file:`descriptions` sub-directory of the
+respective module, e.g. :file:`src/seedlink/apps/seedlink/descriptions/seedlink.rst`.
+The intention is that the documentation is close to the code to make it easier for developers to keep the
+documentation up to date with code changes.
+
+For a new executable an entry should also be made in the man section of :file:`conf.py`.
+The man page is a short form of the documentation that is generated from only the .xml file.
+
+
+Images
+======
+
+Any images should be placed in a suitable sub-directory of :file:`descriptions/media`.
+Read the :ref:`documentation on image styles <documentation_style_guide_image>` for more details.
+The images can then be referred to (in .rst) like::
+
+    .. figure::  media/scolv/scolv-overview.png
+       :width: 16cm
+       :align: center
+
+       Overview of the defrobnicator switches in :ref:`scolv`.
+
+The images will be moved to the correct location during the documentation build.
+
+
+Understanding the XML
+=====================
+
+As mentioned before XML is used to generate brief descriptions of the configuration and command line parameters.
+This section describes the XML format.
+
+Any description XML uses the root element *seiscomp*:
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp>
+     ...
+   </seiscomp>
+
+Three elements are used inside the root element: :ref:`module<xml-module>`, :ref:`plugin<xml-plugin>` and :ref:`binding<xml-binding>`.
+Modules, plugins and bindings can be described in one XML or split up into one file per description. It is better to
+have things as close as possible. A module and its binding should go into one module.XML whereas plugins should
+go into separate XML files.
+
+
+.. _xml-module:
+
+Module
+------
+
+A template for a description XML file can be found in :file:`doc/templates/app.xml`.
+
+The XML file describes the |scname| :term:`module` with the configuration and command-line parameters.
+
+Element: **module**
+
++-----------------------------+----------+-----------+-----------------------------------------------+
+| Name                        | XML type | Mandatory | Description                                   |
++=============================+==========+===========+===============================================+
+| **name**                    | attrib   |    yes    | The name of the module. This name must be     |
+|                             |          |           | unique among all available modules.           |
++-----------------------------+----------+-----------+-----------------------------------------------+
+| **category**                | attrib   |    no     | The category of the module. It is used by the |
+|                             |          |           | configurator to group modules and by the      |
+|                             |          |           | documentation generator to create the final   |
+|                             |          |           | document structure. The category can contain  |
+|                             |          |           | slashes to introduce hierarchies.             |
++-----------------------------+----------+-----------+-----------------------------------------------+
+| **standalone**              | attrib   |    no     | The standalone attribute is also optional and |
+|                             |          |           | by default false. Standalone means that the   |
+|                             |          |           | module does not take the global configuration |
+|                             |          |           | files (e.g. :file:`etc/global.cfg`) into      |
+|                             |          |           | account.                                      |
++-----------------------------+----------+-----------+-----------------------------------------------+
+| **inherit-global-bindings** | attrib   |    no     | If global bindings are inherited. The default |
+|                             |          |           | is 'false'. If 'yes', then all parameters of  |
+|                             |          |           | the global binding are also available in      |
+|                             |          |           | the module binding to allow overwriting them. |
+|                             |          |           | Standalone modules will never inherit global  |
+|                             |          |           | bindings regardless the value of this         |
+|                             |          |           | attribute.                                    |
++-----------------------------+----------+-----------+-----------------------------------------------+
+| **description**             | element  |    no     | A short description of the module.            |
++-----------------------------+----------+-----------+-----------------------------------------------+
+| **configuration**           | element  |    no     | The available configuration parameters. See   |
+|                             |          |           | element                                       |
+|                             |          |           | :ref:`configuration<xml-configuration>`.      |
++-----------------------------+----------+-----------+-----------------------------------------------+
+| **command-line**            | element  |    no     | The available command-line options. See       |
+|                             |          |           | element                                       |
+|                             |          |           | :ref:`command-line<xml-command-line>`.        |
++-----------------------------+----------+-----------+-----------------------------------------------+
+
+It follows a simple example of how a module definition looks like.
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp>
+     <module name="scevent" category="Modules/Processing">
+       <description>
+         Associates an Origin to an Event or forms a new Event if no match
+         is found. Selects the preferred magnitude.
+       </description>
+       <configuration/>
+       <command-line/>
+     </module>
+   </seiscomp>
+
+
+.. _xml-plugin:
+
+Plugin
+------
+
+A template for a description XML file can be found in :file:`doc/templates/plugin.xml`.
+
+The XML file describes the |scname| :term:`plugin` with the configuration and command-line parameters. This is most likely the
+case when an application loads dynamically shared libraries also called plugins.
+
+Element: **plugin**
+
++-------------------+----------+-----------+-----------------------------------------------+
+| Name              | XML type | Mandatory | Description                                   |
++===================+==========+===========+===============================================+
+| **name**          | attrib   |    yes    | The name of the plugin.                       |
++-------------------+----------+-----------+-----------------------------------------------+
+| **extends**       | element  |    yes    | The list of names of module names that        |
+|                   |          |           | the plugin extends, separated by commas.      |
++-------------------+----------+-----------+-----------------------------------------------+
+| **description**   | element  |    no     | A short description of the plugin.            |
++-------------------+----------+-----------+-----------------------------------------------+
+| **configuration** | element  |    no     | The available configuration parameters. See   |
+|                   |          |           | element                                       |
+|                   |          |           | :ref:`configuration<xml-configuration>`.      |
++-------------------+----------+-----------+-----------------------------------------------+
+
+Below is a simple example of how a plugin definition appears in XML.
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp>
+     <plugin name="NonLinLoc">
+       <extends>global</extends>
+       <description>
+         NonLinLoc locator wrapper plugin for SeisComP.
+         NonLinLoc was written by Anthony Lomax (http://alomax.free.fr/nlloc).
+       </description>
+       <configuration/>
+       <command-line/>
+     </plugin>
+   </seiscomp>
+
+
+.. _xml-binding:
+
+Binding
+-------
+
+A binding template can be found in :file:`doc/templates/binding.xml`.
+
+It describes the set of configuration parameters to configure a station for a module.
+
+Element: **binding**
+
++-------------------+----------+-----------+-----------------------------------------------+
+| Name              | XML type | Mandatory | Description                                   |
++===================+==========+===========+===============================================+
+| **module**        | attrib   |    yes    | The name of the module this binding belongs   |
+|                   |          |           | to.                                           |
++-------------------+----------+-----------+-----------------------------------------------+
+| **description**   | element  |    no     | A short description of the binding.           |
++-------------------+----------+-----------+-----------------------------------------------+
+| **configuration** | element  |    no     | The available configuration parameters. See   |
+|                   |          |           | element                                       |
+|                   |          |           | :ref:`configuration<xml-configuration>`.      |
++-------------------+----------+-----------+-----------------------------------------------+
+
+Below is an example of how a simple binding definition appears as XML.
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp>
+     <binding module="seedlink">
+       <description>
+         Configures sources and parameters of a SeedLink station.
+       </description>
+       <configuration/>
+     </binding>
+   </seiscomp>
+
+
+.. _xml-configuration:
+
+Configuration
+-------------
+
+This element is used to describe the configuration parameters (not command-line, just
+configuration file) of a module, binding and plugin.
+
+Element: **configuration**
+
++-------------------+----------+-----------+---------------------------------------------------+
+| Name              | XML type | Mandatory | Description                                       |
++===================+==========+===========+===================================================+
+| **parameter**     | element  |    no     | A top level parameter that does not contain       |
+|                   |          |           | dots in the configuration file.                   |
+|                   |          |           |                                                   |
+|                   |          |           | .. code-block:: sh                                |
+|                   |          |           |                                                   |
+|                   |          |           |    param = value                                  |
+|                   |          |           |    group.param = "another value"                  |
+|                   |          |           |                                                   |
+|                   |          |           | Here ``param`` is a top level parameter           |
+|                   |          |           | whereas ``group.param`` is not. See               |
+|                   |          |           | :ref:`parameter<xml-configuration-parameter>`.    |
++-------------------+----------+-----------+---------------------------------------------------+
+| **struct**        | element  |    no     | A top level structure definition. Structures      |
+|                   |          |           | are different from groups and parameters          |
+|                   |          |           | as they can be instantiated by an arbitrary       |
+|                   |          |           | name.                                             |
++-------------------+----------+-----------+---------------------------------------------------+
+| **group**         | element  |    no     | A parameter group that describes a logical        |
+|                   |          |           | grouping of parameters also called "scope" or     |
+|                   |          |           | "namespace". If a parameter in the                |
+|                   |          |           | configuration file contains dots, then only       |
+|                   |          |           | the last part is a parameter all others are       |
+|                   |          |           | groups.                                           |
+|                   |          |           |                                                   |
+|                   |          |           | .. code-block:: sh                                |
+|                   |          |           |                                                   |
+|                   |          |           |    group1.group2.param = value                    |
+|                   |          |           |                                                   |
++-------------------+----------+-----------+---------------------------------------------------+
+
+
+.. _xml-configuration-parameter:
+
+Element: **parameter**
+
++-------------------+----------+-----------+---------------------------------------------------+
+| Name              | XML type | Mandatory | Description                                       |
++===================+==========+===========+===================================================+
+| **name**          | attrib   |    yes    | The name of the parameter. This name must be      |
+|                   |          |           | unique among all parameters of the same           |
+|                   |          |           | level.                                            |
++-------------------+----------+-----------+---------------------------------------------------+
+| **type**          | attrib   |    no     | An optional description of the parameter          |
+|                   |          |           | type which can be interpreted by a                |
+|                   |          |           | configurator to provide specialized input         |
+|                   |          |           | widgets. It is also important for the user        |
+|                   |          |           | how the parameter is read by the module.          |
++-------------------+----------+-----------+---------------------------------------------------+
+| **unit**          | attrib   |    no     | An optional unit such as "s" or "km" or           |
+|                   |          |           | "deg".                                            |
++-------------------+----------+-----------+---------------------------------------------------+
+| **default**       | attrib   |    no     | The default value the module uses if this         |
+|                   |          |           | parameter is not configured.                      |
++-------------------+----------+-----------+---------------------------------------------------+
+| **description**   | element  |    no     | Gives a brief description of the parameter.       |
++-------------------+----------+-----------+---------------------------------------------------+
+
+.. _xml-configuration-struct:
+
+Element: **struct**
+
++-------------------+----------+-----------+---------------------------------------------------+
+| Name              | XML type | Mandatory | Description                                       |
++===================+==========+===========+===================================================+
+| **type**          | attrib   |    yes    | The name of the struct type. This name is         |
+|                   |          |           | used in a configurator to give a selection        |
+|                   |          |           | of available types to be instantiated.            |
++-------------------+----------+-----------+---------------------------------------------------+
+| **link**          | attrib   |    no     | The absolute reference parameter as it would      |
+|                   |          |           | appear in the configuration file which            |
+|                   |          |           | holds all instantiated structures.                |
+|                   |          |           |                                                   |
+|                   |          |           | .. code-block:: sh                                |
+|                   |          |           |                                                   |
+|                   |          |           |    # 'link' parameter holding all available       |
+|                   |          |           |    # structures. "local" and "teleseismic"        |
+|                   |          |           |    # are instances of a structure defined         |
+|                   |          |           |    # below.                                       |
+|                   |          |           |    locator.profiles = local, teleseismic          |
+|                   |          |           |                                                   |
+|                   |          |           |    # The structure defined in locator.profile     |
+|                   |          |           |    # would have "locator.profiles" as link        |
+|                   |          |           |    # attribute.                                   |
+|                   |          |           |    locator.profile.local.param = value            |
+|                   |          |           |    locator.profile.teleseismic.param = value      |
+|                   |          |           |                                                   |
++-------------------+----------+-----------+---------------------------------------------------+
+| **description**   | element  |    no     | Gives a brief description of the parameter.       |
++-------------------+----------+-----------+---------------------------------------------------+
+| **parameter**     | element  |    no     | Describes a parameter in the struct. See          |
+|                   |          |           | :ref:`parameter<xml-configuration-parameter>`.    |
++-------------------+----------+-----------+---------------------------------------------------+
+| **struct**        | element  |    no     | Describes a struct part of this struct.           |
++-------------------+----------+-----------+---------------------------------------------------+
+| **group**         | element  |    no     | Describes a group part of this struct. See        |
+|                   |          |           | :ref:`group<xml-configuration-group>`.            |
++-------------------+----------+-----------+---------------------------------------------------+
+
+
+
+.. _xml-configuration-group:
+
+Element: **group**
+
++-------------------+----------+-----------+---------------------------------------------------+
+| Name              | XML type | Mandatory | Description                                       |
++===================+==========+===========+===================================================+
+| **name**          | attrib   |    yes    | The name of the group. This name must be          |
+|                   |          |           | unique among all groups of the same level.        |
++-------------------+----------+-----------+---------------------------------------------------+
+| **description**   | element  |    no     | Gives a brief description of the parameter.       |
++-------------------+----------+-----------+---------------------------------------------------+
+| **parameter**     | element  |    no     | Describes a parameter in the group. See           |
+|                   |          |           | :ref:`parameter<xml-configuration-parameter>`.    |
++-------------------+----------+-----------+---------------------------------------------------+
+| **struct**        | element  |    no     | Describes a struct part of this group. See        |
+|                   |          |           | :ref:`struct<xml-configuration-struct>`.          |
++-------------------+----------+-----------+---------------------------------------------------+
+| **group**         | element  |    no     | Describes a group part of this group.             |
++-------------------+----------+-----------+---------------------------------------------------+
+
+
+Below is an example of the plugin definition for the NonLinLoc plugin. It contains
+groups, parameters and structures.
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp>
+     <plugin name="NonLinLoc">
+       <extends>global</extends>
+       <description>...</description>
+       <configuration>
+         <group name="NonLinLoc">
+           <parameter name="publicID" type="string"
+                      default="NLL.@time/%Y%m%d%H%M%S.%f@.@id@">
+             <description>
+               PublicID creation pattern for an origin created by NonLinLoc.
+             </description>
+           </parameter>
+
+           <parameter name="outputPath" type="path" default="/tmp/sc3.nll">
+             <description>
+               Defines the output path for all native NonLinLoc input and
+               output files.
+             </description>
+           </parameter>
+
+           <parameter name="profiles" type="list:string">
+             <description>
+               Defines a list of active profiles to be used by the plugin.
+             </description>
+           </parameter>
+
+           <group name="profile">
+             <struct type="NonLinLoc profile" link = "NonLinLoc.profiles">
+               <description>
+                 Defines a regional profile that is used if a prelocation falls
+                 inside the configured region.
+               </description>
+               <parameter name="earthModelID" type="string">
+                 <description>
+                   earthModelID that is stored in the created origin.
+                 </description>
+               </parameter>
+             </struct>
+           </group>
+         </group>
+       </configuration>
+     </plugin>
+   </seiscomp>
+
+
+
+.. _xml-command-line:
+
+Command-line
+------------
+
+This element is used to describe the command-line options of a module. The element structure is
+much simpler than the :ref:`configuration<xml-configuration>` element. The command-line only
+contains group elements which in turn have either option or optionReference elements. Through
+the optionReference element it is possible to refer to existing command-line options. This is
+important for all modules that are using the |scname| libraries because they share a set of
+basic command-line options inherited from the Application class.
+
+Element: **command-line**
+
++---------------------+----------+-----------+-----------------------------------------------+
+| Name                | XML type | Mandatory | Description                                   |
++=====================+==========+===========+===============================================+
+| **synopsis**        | element  |    no     | Optional description of how to start the      |
+|                     |          |           | module.                                       |
++---------------------+----------+-----------+-----------------------------------------------+
+| **description**     | element  |    no     | Optional description of the command-line      |
+|                     |          |           | and non option parameters.                    |
++---------------------+----------+-----------+-----------------------------------------------+
+| **group**           | element  |    no     | Describes an option group. See                |
+|                     |          |           | :ref:`group<xml-command-line-group>`.         |
++---------------------+----------+-----------+-----------------------------------------------+
+
+
+.. _xml-command-line-group:
+
+Element: **group**
+
++---------------------+----------+-----------+-----------------------------------------------+
+| Name                | XML type | Mandatory | Description                                   |
++=====================+==========+===========+===============================================+
+| **name**            | attrib   |    yes    | The name of the group. This name must be      |
+|                     |          |           | unique among all groups of the same level.    |
++---------------------+----------+-----------+-----------------------------------------------+
+| **option**          | element  |    no     | An option part of this group. See             |
+|                     |          |           | :ref:`option<xml-command-line-option>`.       |
++---------------------+----------+-----------+-----------------------------------------------+
+| **optionReference** | element  |    no     | A reference to an existing option using its   |
+|                     |          |           | publicID.                                     |
++---------------------+----------+-----------+-----------------------------------------------+
+
+
+.. _xml-command-line-option:
+
+Element: **option**
+
++---------------------+----------+-----------+-----------------------------------------------+
+| Name                | XML type | Mandatory | Description                                   |
++=====================+==========+===========+===============================================+
+| **flag**            | attrib   |    semi   | The short option flag. Either this attribute  |
+|                     |          |           | or long-flag must be set.                     |
++---------------------+----------+-----------+-----------------------------------------------+
+| **long-flag**       | attrib   |    semi   | The long option flag. Either this attribute   |
+|                     |          |           | or flag must be set.                          |
++---------------------+----------+-----------+-----------------------------------------------+
+| **param-ref**       | attrib   |    no     | Refers to a configuration parameter name that |
+|                     |          |           | this parameter overrides. Name is the full    |
+|                     |          |           | path, e.g. *connection.server* and not just   |
+|                     |          |           | *server*.                                     |
++---------------------+----------+-----------+-----------------------------------------------+
+| **argument**        | attrib   |    no     | The optional argument string. If argument is  |
+|                     |          |           | not set, the option is a switch.              |
++---------------------+----------+-----------+-----------------------------------------------+
+| **default**         | attrib   |    no     | The option's default value used if the option |
+|                     |          |           | is not given though it is hard in most cases  |
+|                     |          |           | because command-line options very often       |
+|                     |          |           | redefine configuration parameters which is    |
+|                     |          |           | then used as a default value for the option.  |
++---------------------+----------+-----------+-----------------------------------------------+
+| **publicID**        | attrib   |    no     | The optional publicID of the option to be     |
+|                     |          |           | able to reference it from an optionReference  |
+|                     |          |           | element. The publicID must be unique among    |
+|                     |          |           | all defined options.                          |
++---------------------+----------+-----------+-----------------------------------------------+
+| **description**     | element  |    no     | Gives a brief description of the option.      |
++---------------------+----------+-----------+-----------------------------------------------+
+
+
+Below is an example of the module definition for :program:`scautoloc` (extract).
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8"?>
+   <seiscomp>
+     <module name="scautoloc" category="Modules/Processing">
+       <description>Locates seismic events.</description>
+       <configuration>
+         ...
+       </configuration>
+       <command-line>
+         <group name="Generic">
+           <optionReference>generic#help</optionReference>
+           <optionReference>generic#version</optionReference>
+           <optionReference>generic#config-file</optionReference>
+           <optionReference>generic#plugins</optionReference>
+           <optionReference>generic#daemon</optionReference>
+           <optionReference>generic#auto-shutdown</optionReference>
+           <optionReference>generic#shutdown-master-module</optionReference>
+           <optionReference>generic#shutdown-master-username</optionReference>
+         </group>
+
+         <group name="Mode">
+           <option flag="" long-flag="test" argument="" default="">
+             <description>Do not send any object</description>
+           </option>
+
+           <option flag="" long-flag="offline" argument="" default="">
+             <description>
+               Do not connect to a messaging server. Instead a
+               station-locations.conf file can be provided. This implies
+               --test and --playback
+             </description>
+           </option>
+
+           <option flag="" long-flag="playback" argument="" default="">
+             <description>Flush origins immediately without delay</description>
+           </option>
+         </group>
+       </command-line>
+     </module>
+   </seiscomp>
+
+
+References
+==========
+
+.. target-notes::
+
+.. _`SeisComP wiki` : https://www.seiscomp.de/
+.. _`reStructuredText` : https://docutils.sourceforge.io/rst.html
+.. _`Sphinx` : https://www.sphinx-doc.org/
+.. _`Python documentation` : https://docs.python.org/
+.. _`introduction to reST` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _`directives` : https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
+.. _`SeisComP on GitHub` : https://github.com/SeisComP
+.. _`discussion forum` : https://forum.seiscomp.de

share/doc/seiscomp/html/_sources/base/filter-grammar.rst.txt

@@ -0,0 +1,406 @@
+.. _filter-grammar:
+
+**************
+Filter Grammar
+**************
+
+SeisComP supports string-based filter definitions. This section covers available
+filters and their parameters.
+
+The filter definitions support :ref:`SeisComP filters <sec-filters-list>` and
+building filter chains (operator >> or ->) as well as combining them with basic
+mathematical operators. Filter or the first filter in a filter chain
+is always applied to the raw, uncorrected data.
+Use brackets *()* to apply the operations within before the one outside.
+
+Mathematical operators are:
+
+* \+ : addition
+* \- : subtraction
+* \* : multiplication
+* \/ : division
+* \^ : power / exponentiation
+* \|. \| : absolute value.
+
+A special mathematical operator is a negative value replacing a positive
+frequency value, e.g., in Butterworth filters (see Section
+:ref:`sec-filters-list`). The modulus of the frequency value is multiplied by
+the sample rate of the waveforms to which it is applied. The resulting value
+defines the frequency the filter is configured with. Note, -0.5 defines the
+:term:`Nyquist frequency` of the data. Negative values can be applied for
+defining frequencies dynamically based on sample rate.
+
+Example:
+
+Data with a sample rate of 100 Hz shall be low-pass filtered at 80% of the
+Nyquist frequency by a :py:func:`Butterworth low-pass filter, BW_LP<BW_LP()>`. A
+value of -0.4 corresponds to 80% of the Nyquist frequency. The filter can be
+specified as :py:func:`BW_LP(3,-0.4)<BW_LP()>`.
+
+.. note::
+
+   Filters in |scname| are recursive allowing real-time application. Therefore,
+   filter artefacts, e.g. ringing, are always visible at the beginning of the
+   traces or after data gaps.
+
+
+Example
+=======
+
+.. code-block:: sh
+
+   A(1,2)>>(B(3,4)*2+C(5,6,7))>>D(8)
+
+where A, B, C and D are different filters configured with different parameters.
+In this example a sample *s* is filtered to get the final sample *sf* passing the following stages:
+
+#. filter sample *s* with A: *sa* = A(1,2)(*s*)
+#. filter *sa* with B: *sb* = B(3,4)(*sa*)
+#. *sb* = *sb* \* 2
+#. filter *sa* with C: *sc* = C(5,6,7)(*sa*)
+#. add *sb* and *sc*: *sbc* = *sb* + *sc*
+#. filter *sbc* with D: *sf* = D(8)(*sbc*)
+
+sf = final sample.
+
+The default filter applied by :ref:`scautopick` for making detections is
+
+:py:func:`RMHP(10)<RMHP()>` >> :py:func:`ITAPER(30)<ITAPER()>` >> :py:func:`BW(4,0.7,2)<BW()>` >> :py:func:`STALTA(2,80)<STALTA()>`
+
+It first removes the offset. Then an ITAPER of 30 seconds is applied before the data
+is filtered with a fourth order Butterworth bandpass with corner frequencies of 0.7 Hz and 2 Hz.
+Finally an STA/LTA filter with a short-time time window of 2 seconds and a long-term time window of
+80 seconds is applied.
+
+To apply mathematical operations on original waveforms use :py:func:`self()`, e.g.:
+
+.. code-block:: sh
+
+   self()^2>>A(1,2)
+
+
+Test filter strings
+===================
+
+Filters can be conveniently tested without much configuration. To perform such tests
+
+#. Open waveforms in :ref:`scrttv` or the picker window of :ref:`scolv`.
+#. Open a simple graphical text editor, e.g. gedit, pluma or kwrite and write down
+   the filter string.
+#. Mark / highlight the filter string and use the mouse to drag the filter string
+   onto the waveforms.
+#. Observe the differences between filtered and unfiltered waveforms.
+
+
+.. figure:: media/scrttv-filter.png
+   :align: center
+   :width: 10cm
+
+   scrttv with raw (blue) and filtered (black) data. The applied filter string
+   is shown in the lower left corner.
+
+
+.. _sec-filters-list:
+
+List of filters
+===============
+
+Multiple filter functions are available. Filters may take parameters as
+arguments. If a filter function has no parameter, it can be given either with
+parentheses, e.g. :py:func:`DIFF()<DIFF()>`, or without, e.g.
+:py:func:`DIFF<DIFF()>`.
+
+.. warning::
+
+   All frequencies passed by parameters to filters must be below the Nyquist
+   frequency of the original signal. Otherwise, filtering may result in undesired
+   behavior of modules, e.g., stopping or showing of empty traces.
+
+.. py:function:: AVG(timespan)
+
+   Calculates the average of preceding samples.
+
+   :param timespan: Time span to form the average in seconds
+
+.. _filter-bw:
+
+.. py:function:: BPENV(center-freq, bandwidth, order)
+
+   Butterworth bandpass filter combined with envelope computation.
+
+   This is a recursive approximation of the envelope. It depends on the bandpass center
+   frequency being also the dominant frequency of the signal. Hence it only makes sense for
+   bandpass filtered signals. Even though bandwidth and order may be changed it is
+   recommended to use the defaults.
+
+   :param center-freq: The center frequency of the passband in Hz. Negative values define the frequency as -value * sample rate.
+   :param bandwidth: The filter bandwidth in octaves (default is 1 octave)
+   :param order: The filter order of the bandpass (default is 4)
+
+.. py:function:: BW(order, lo-freq, hi-freq)
+
+   Alias for the :py:func:`Butterworth band-pass filter, BW_BP<BW_BP()>`.
+
+.. py:function:: BW_BP(order, lo-freq, hi-freq)
+
+   Butterworth bandpass filter (BW) realized as a causal recursive IIR (infinite impulse response)
+   filter. An arbitrary bandpass filter can be created for given order and corner frequencies.
+
+   :param order: The filter order
+   :param lo-freq: The lower corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+   :param hi-freq: The upper corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+
+
+.. py:function:: BW_BS(order, lo-freq, hi-freq)
+
+   Butterworth band stop filter realized as a causal recursive IIR (infinite impulse response) filter
+   suppressing amplitudes at frequencies between *lo-freq* and *hi-freq*.
+
+   :param order: The filter order
+   :param lo-freq: The lower corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+   :param hi-freq: The upper corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+
+
+.. py:function:: BW_HP(order, lo-freq)
+
+   Butterworth high-pass filter realized as a causal recursive IIR (infinite
+   impulse response) filter.
+
+   :param order: The filter order
+   :param lo-freq: The corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+
+
+.. py:function:: BW_HLP(order, lo-freq, hi-freq)
+
+   Butterworth high-low-pass filter realized as a combination of
+   :py:func:`BW_HP` and :py:func:`BW_LP`.
+
+   :param order: The filter order
+   :param lo-freq: The lower corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+   :param hi-freq: The upper corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+
+
+.. py:function:: BW_LP(order, hi-freq)
+
+   Butterworth low-pass filter realized as a causal recursive IIR (infinite
+   impulse response) filter.
+
+   :param order: The filter order
+   :param hi-freq: The corner frequency as 1/seconds. Negative values define the frequency as -value * sample rate.
+
+
+.. py:function:: CUTOFF(delta)
+
+   Sets the value of the current sample to the mean of the current and the
+   previous sample when the difference between the two exceeds *delta*.
+   Otherwise, the original value is retained.
+
+   :param delta: The threshold for forming the average.
+
+
+.. py:function:: DIFF
+
+   Differentiation filter realized as a recursive IIR (infinite impulse
+   response) differentiation filter.
+
+   The differentiation loop calculates for each input sample `s` the output sample `s\'`:
+
+   .. code-block:: py
+
+      s' = (s-v1) / dt
+      v1 = s;
+
+
+.. py:function:: DT
+
+   Replaces each input sample with the sampling time of the current sample. This
+   is a shortcut for :code:`1/SR` but more efficient as the division has to be
+   done only once and not once per input sample.
+
+
+.. py:function:: DURATION(trigger_on, trigger_off)
+
+   Replaces the input samples with the trigger duration. The duration is computed as the
+   time between `trigger_on` and `trigger_off`. Outside the trigger, the filter outputs
+   zero.
+
+.. py:function:: INT([a = 0])
+
+   Integration filter realized as a recursive IIR (infinite impulse response) integration
+   filter. The weights are calculated according to parameter `a` in the following way:
+
+   .. code-block:: py
+
+      a0 = ((3-a)/6) * dt
+      a1 = (2*(3+a)/6) * dt
+      a2 = ((3-a)/6) * dt
+
+      b0 = 1
+      b1 = 0
+      b2 = -1
+
+
+   The integration loop calculates for each input sample `s` the integrated output sample s\':
+
+   .. code-block:: py
+
+      v0 = b0*s - b1*v1 - b2*v2
+      s' = a0*v0 + a1*v1 + a2*v2
+      v2 = v1
+      v1 = v0
+
+   :param a: Coefficient `a`.
+
+
+.. py:function:: ITAPER(timespan)
+
+   A one-sided cosine taper applied when initializing the filter, e.g. at the
+   beginning of the data or after longer gaps.
+
+   :param timespan: The timespan to apply the taper in seconds.
+
+
+.. py:function:: MAX(timespan)
+
+   Computes the maximum within the timespan preceding the sample.
+
+   :param timespan: The timespan to measure the maximum in seconds
+
+
+.. py:function:: MEDIAN(timespan)
+
+   Computes the median within the timespan preceding the sample. Useful, e.g.
+   for despiking. The delay due to the filter may be up to its timespan.
+
+   :param timespan: The timespan to compute the median in seconds
+
+
+.. py:function:: MIN(timespan)
+
+   Computes the minimum within the timespan preceding the sample.
+
+   :param timespan: The timespan to measure the minimum in seconds
+
+
+.. py:function:: RM(timespan)
+
+   A running mean filter computing the mean value within *timespan*. For a given
+   time window in seconds the running mean is computed from the single amplitude
+   values and set as output. This computation is equal to :py:func:`RHMP<RMHP()>`
+   with the exception that the mean is not subtracted from single amplitudes but
+   replaces them.
+
+   .. code-block:: sh
+
+      RMHP = self-RM
+
+   :param timespan: The timespan to measure the mean in seconds
+
+
+.. py:function:: RMHP(timespan)
+
+   A high-pass filter realized as running mean high-pass filter. For a given time window in
+   seconds the running mean is subtracted from the single amplitude values. This is equivalent
+   to high-pass filtering the data.
+
+   Running mean high-pass of e.g. 10 seconds calculates the difference to the running mean of 10 seconds.
+
+   :param timespan: The timespan to measure the mean in seconds
+
+
+.. py:function:: RND(mean, stddev)
+
+   A random signal generator with Gaussian normal distribution. It replaces
+   input samples with the new signal. Use RND() with the operator '+' for adding
+   the random signal to some data. Example: (BW(3,0.7,2) + RND(0,10))>>STALTA(2,80)
+
+   :param mean: The mean value of the normal distribution
+   :param stddev: The standard deviation of the normal distribution
+
+
+.. py:function:: RUD(minimum, maximum)
+
+   A random signal generator with uniform distribution. It replaces input
+   samples with the new signal. Use RUD() with the operator '+' for adding the
+   random signal to some data. Example: (BW(3,0.7,2) + RUD(-10,10))>>STALTA(2,80)
+
+   :param minimum: The minimum value of the uniform distribution
+   :param maximum: The maximum value of the uniform distribution
+
+
+.. py:function:: self()
+
+   The original data itself.
+
+
+.. py:function:: SM5([type = 1])
+
+   A simulation of a 5-second seismometer.
+
+   :param type: The data type: either 0 (displacement), 1 (velocity) or 2 (acceleration)
+
+
+.. py:function:: SR
+
+   Replaces each input sample with the sampling rate of the current sample.
+
+
+.. py:function:: STALTA(sta, lta)
+
+   A STA/LTA filter is the ratio of a short-time amplitude average (STA) to a
+   long-time amplitude average (LTA) calculated continuously in two consecutive
+   time windows. This method is the basis for many trigger algorithm. The
+   short-time window is for detection of transient signal onsets whereas the
+   long-time window provides information about the actual seismic noise at the
+   station.
+
+   :param sta: Length of short-term time window in seconds
+   :param lta: Length of long-term time window in seconds. The time window ends
+       with the same sample as sta.
+
+
+.. py:function:: STALTA2(sta, lta, on, off)
+
+   The :py:func:`STALTA` implementation where LTA time window is kept fixed
+   between the time the STA/LTA ratio exceeds *on* and falls below *off*.
+
+   :param sta: Length of short-term time window in seconds
+   :param lta: Long-term time window ending with the same sample as sta
+   :param on: STA/LTA ratio defining the start of the time window for fixing LTA.
+   :param off: STA/LTA ratio defining the end of the time window for fixing LTA.
+
+
+.. py:function:: SUM(timespan)
+
+   :param timespan: The timespan to be summed up in seconds
+
+   Computes the amplitude sum of the timespan preceding the sample.
+
+
+.. py:function:: WA([type = 1[,gain=2080[,T0=0.8[,h=0.7]]]])
+
+   The simulation filter of a :term:`Wood-Anderson seismometer`. The data format
+   of the waveforms has to be given for applying the simulation filter
+   (displacement = 0, velocity = 1, acceleration = 2), e.g., WA(1) is the
+   simulation on velocity data.
+
+   :param type: The data type: 0 (displacement), 1 (velocity) or 2 (acceleration)
+   :param gain: The gain of the Wood-Anderson response
+   :param T0: The eigen period in seconds
+   :param h: The damping constant
+
+
+.. py:function:: WWSSN_LP([type = 1])
+
+   The instrument simulation filter of a
+   :term:`World-Wide Standard Seismograph Network (WWSSN) long-period seismometer <WWSSN_LP>`.
+
+   :param type: The data type: 0 (displacement), 1 (velocity) or 2 (acceleration)
+
+
+.. py:function:: WWSSN_SP([type = 1])
+
+   Analog to the :func:`WWSSN_LP`, the simulation filter of the
+   :term:`short-period seismometer of the WWSSN <WWSSN_SP>`.
+
+   :param type: The data type: 0 (displacement), 1 (velocity) or 2 (acceleration)

share/doc/seiscomp/html/_sources/base/getting-started.rst.txt

@@ -0,0 +1,466 @@
+.. _getting-started:
+
+*****************************
+Getting Started with |scname|
+*****************************
+
+Once the Linux system is installed the |scname| modules need to be configured including
+the :ref:`initial configuration and the connection to the database <getting-started-initial>`.
+The central tool to configure and control the system is :program:`seiscomp` which
+is explained more deeply in the :ref:`next chapter<system-management>`. A user-friendly
+graphical frontend to :program:`seiscomp` is :ref:`scconfig`.
+
+
+.. _getting-started-initial:
+
+Database Configuration
+======================
+
+Once the database server is defined and optimized as described in the section
+:ref:`database_configuration` you may configure |scname| with the database.
+Initially execute the steps listed in this section. You will need to consider
+differences in databases:
+
+* :ref:`MySQL <getting-started-mysql>` (not recommended),
+* :ref:`MariaDB <getting-started-mariadb>`,
+* :ref:`PostgreSQL <getting-started-postgresql>`.
+
+
+.. _getting-started-mysql:
+
+MySQL
+-----
+
+The initial configuration by the :program:`seiscomp` script or the
+wizard of :ref:`scconfig` allows to create and configure the MySQL database
+for |scname|. If you want to use MySQL continue with the
+:ref:`general setup <getting-started-setup>`.
+
+.. warning ::
+
+   * Using MySQL is currently not recommended. Preferably use MariaDB instead of MySQL
+     as MariaDB is the default SQL flavor of most supported Linux systems!
+   * As of MySQL 8.0 the password encryption and policy has changed resulting in
+     errors when connecting to a MySQL server. In 04/2021 this
+     does not seem to be fully supported in **Ubuntu 20.04**. Therefore, you need
+     to use a native password on the MySQL server.
+
+     .. code-block:: sh
+
+        $ sudo mysql -u root -p
+
+          ALTER USER 'sysop'@'%%' IDENTIFIED WITH mysql_native_password BY 'my_super_secret_password_matching_the_mysql_password_validation_policy';
+
+
+.. _getting-started-mariadb:
+
+MariaDB
+-------
+
+The initial configuration by the :program:`seiscomp` script or the
+wizard of :ref:`scconfig` allows to create and configure the MySQL database
+for |scname|.
+
+For setting up the database manually with MariaDB follow the instructions
+below.
+
+.. note::
+
+    With **Ubuntu 16.04** MariaDB has become the standard flavor of MySQL in
+    Ubuntu and either MariaDB or MySQL can be installed. The implementation
+    of MariaDB in Ubuntu requires additional steps. They must be taken
+    **before** the initial configuration in order to allow |scname| to make
+    use of MariaDB. Previously, the :ref:`scconfig` wizard and
+    :command:`seiscomp setup` could not be used to set up the MariaDB database.
+    **The option "Create database" had to be unchecked or answered with "no"**.
+    The issue is resolved in this release and both, :ref:`scconfig` wizard and
+    :command:`seiscomp setup` are now fully capable of the required actions.
+
+The full procedure to create the seiscomp database:
+
+.. code-block:: sh
+
+   user@host:~$ sudo mysql -u root -p
+        CREATE DATABASE seiscomp CHARACTER SET utf8mb4;
+        grant usage on seiscomp.* to sysop@localhost identified by 'sysop';
+        grant all privileges on seiscomp.* to sysop@localhost;
+        grant usage on seiscomp.* to sysop@'%' identified by 'sysop';
+        grant all privileges on seiscomp.* to sysop@'%';
+        flush privileges;
+        quit
+
+   user@host:~$ mysql -u sysop -p seiscomp < ~/seiscomp/share/db/mysql.sql
+
+.. note::
+
+   If character set 'utf8mb4' is not supported by your specific database server
+   version then use the old 'utf8' format. For historical reasons, SeisComP
+   would use then the 'utf8_bin' collation. The full statement looks as
+   follows: :code:`CREATE DATABASE seiscomp CHARACTER SET utf8 COLLATE utf8_bin`.
+
+.. _getting-started-postgresql:
+
+PostgreSQL
+----------
+
+The initial configuration allows configuring the PostgreSQL database parameters
+for |scname|.
+It also allows :ref:`creating the database <database_configuration_postgresql>`
+and the database tables.
+
+For a manual setup of the PostgreSQL database first :ref:`setup the database
+server<database_configuration_postgresql>`, then create the user, the database
+and the tables.
+
+
+#. Create the user and the database
+
+   :program:`CentOS`:
+
+   .. code-block:: sh
+
+      sudo@host:~$ sudo su
+      root@host:~$ sudo -i -u postgres
+      postgres@host:~$ psql
+
+         postgres=# create database seiscomp;
+         postgres=# create user sysop with encrypted password 'sysop';
+         postgres=# grant all privileges on database seiscomp to sysop;
+         postgres=# alter database seiscomp owner to sysop;
+         postgres=# exit
+
+      root@host:~$ exit
+
+#. Create the database tables
+
+   .. code-block:: sh
+
+      user@host:~$ psql -f ~/seiscomp/share/db/postgres.sql -t seiscomp -U sysop
+
+Continue with the :ref:`general setup <getting-started-setup>` considering the
+created database but **do not create the database again**.
+
+
+.. _getting-started-setup:
+
+General |scname| Setup
+======================
+
+Use :command:`seiscomp setup` or the wizard from within :ref:`scconfig` (:kbd:`Ctrl+N`) for the
+initial configuration including the database parameters. :command:`seiscomp setup` is the
+successor of the former :program:`./setup` script.
+
+In :command:`seiscomp setup` default values are given in brackets []: ::
+
+   user@host:~$ seiscomp/bin/seiscomp setup
+
+   ====================================================================
+   seiscomp setup
+   ====================================================================
+
+   This initializes the configuration of your installation.
+   If you already made adjustments to the configuration files
+   be warned that this setup will overwrite existing parameters
+   with default values. This is not a configurator for all
+   options of your setup but helps to setup initial standard values.
+
+   --------------------------------------------------------------------
+   Hint: Entered values starting with a dot (.) are handled
+         as commands. Available commands are:
+
+         quit: Quit setup without modification to your configuration.
+         back: Go back to the previous parameter.
+         help: Show help about the current parameter (if available).
+
+         If you need to enter a value with a leading dot, escape it
+         with backslash, e.g. "\.value".
+   --------------------------------------------------------------------
+
+This will ask for initial settings as database (if package trunk is installed)
+parameters and the logging backend.
+
+----
+
+.. code-block:: none
+
+   Organization name []:
+
+Sets the organisation name printed e.g. when you say *hello* to Seedlink
+or Arclink.
+
+----
+
+.. code-block:: none
+
+   Enable database storage [yes]:
+
+Enables or disables the database for the system. This option should be left
+enabled unless all modules should connect to remote processing machine which
+is already available. The database is required to store inventory information
+as well as processing results. The database is the central storage for all
+trunk modules and the default request handler of Arclink.
+
+----
+
+.. code-block:: none
+
+    0) mysql
+         MySQL server.
+    1) postgresql
+         PostgreSQL server. There is currently no support in setup to create the
+         database for you. You have to setup the database and user accounts on
+         your own. The database schema is installed under share/db/postgresql.sql.
+   Database backend [0]:
+
+If the database is enable the database backend can be selected. |scname|
+supports two main backends: MySQL and PostgreSQL. Select the backend to be used
+here but be prepared that only for the MySQL backend the setup can help to
+create the database and tables for you. If you are using PostgreSQL you have
+to provide a working database with the correct schema. The schema files are
+part of the distribution and can be found in :file:`seiscomp/share/db/postgresql.sql`.
+
+.. note::
+
+   As of PostgreSQL version 9 the default output encoding has changed to hex.
+   In order to fix issues with seiscomp log in to your database and run the
+   following command.
+
+   .. code-block:: sql
+
+      ALTER DATABASE seiscomp SET bytea_output TO 'escape';
+
+
+----
+
+.. code-block:: none
+
+   Create database [yes]:
+
+.. warning ::
+
+   If MySQL is selected it is possible to let :command:`seiscomp setup` to create
+   the database and all tables for you. Otherwise currently not and you need to set up the
+   database manually following the :ref:`given instructions <getting-started-mysql>`.
+   If the database has been created already, answer 'no' here.
+
+----
+
+.. code-block:: none
+
+   MYSQL root password (input not echoed) []:
+
+Give the MySQL root password for your database server to create the database
+tables. This is only required if the last question has been answered with 'yes'.
+
+----
+
+.. code-block:: none
+
+   Drop existing database [no]:
+
+If a database with the same name (to be selected later) exists already and the
+database should be created for you, an error is raised. To delete an existing
+database with the same name, say 'yes' here.
+
+----
+
+.. code-block:: none
+
+   Database name [seiscomp]:
+   Database hostname [localhost]:
+   Database read-write user [sysop]:
+   Database read-write password [sysop]:
+   Database public hostname [localhost]:
+   Database read-only user [sysop]:
+   Database read-only password [sysop]:
+
+Setup the various database options valid for all database backends. Give
+:command:`help` for more information.
+
+----
+
+If all question have been answered the final choice needs to be made to either
+create the initial configuration, go back to the last question or to quit
+without doing anything.
+
+.. code-block:: none
+
+   Finished setup
+   --------------
+
+   P) Proceed to apply configuration
+   B) Back to last parameter
+   Q) Quit without changes
+   Command? [P]:
+
+
+Environment variables
+=====================
+
+Commands can be used along with the :program:`seiscomp` script located in *seiscomp/bin/seiscomp*.
+Read the section :ref:`sec-management-commands` for more details on :program:`seiscomp`.
+E.g. |scname| modules can be executed like ::
+
+   user@host:~$ seiscomp/bin/seiscomp exec scrttv
+
+Calling :program:`seiscomp` with its full path, e.g.
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp [command]
+
+will load the full |scname| environment.
+Providing the full path allows starting other |scname| modules in a specific
+|scname| environment. Thus, multiple SeisComP installations can be maintained
+and referred to on the same machine.
+
+:program:`seiscomp` can also be used for printing the considered |scname| environment ::
+
+   user@host:~$ seiscomp/bin/seiscomp print env
+
+resulting in ::
+
+   export SEISCOMP_ROOT="/home/sysop/seiscomp"
+   export PATH="/home/sysop/seiscomp/bin:$PATH"
+   export LD_LIBRARY_PATH="/home/sysop/seiscomp/lib:$LD_LIBRARY_PATH"
+   export PYTHONPATH="/home/sysop/seiscomp/lib/python:$PYTHONPATH"
+   export MANPATH="/home/sysop/seiscomp/share/man:$MANPATH"
+   source "/home/sysop/seiscomp/share/shell-completion/seiscomp.bash"
+
+For convenience, the default |scname| installation can be referred to, when defining
+the required system variables, e.g. in :file:`~/.bashrc`. Then, the |scname| environment
+is known to the logged in user and |scname| modules can be
+executed without the :program:`seiscomp` script.
+
+For setting the environment
+
+#. Use the :program:`seiscomp` script itself to generate the parameters and write
+   the parameters to :file:`~/.bashrc` ::
+
+      user@host:~$ seiscomp/bin/seiscomp print env >> ~/.bashrc
+
+#. Load the environment or log out and in again ::
+
+      user@host:~$ source ~/.bashrc
+
+Thereafter, modules can be executed by their names without involving :program:`seiscomp`,
+e.g. ::
+
+   user@host:~$ scrttv
+
+
+Activate/Enable Modules
+=======================
+
+After the installation all module are disabled for auto start. If :command:`seiscomp start`
+is called, nothing will happen until modules are enabled. To enable a set of modules,
+:command:`seiscomp enable` needs to be called with a list of modules.
+For example, for a processing system with SeedLink for data acquisition,
+you may use:
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp enable seedlink slarchive scautopick scautoloc scamp scmag scevent
+   enabled seedlink
+   enabled slarchive
+   enabled scautopick
+   enabled scautoloc
+   enabled scamp
+   enabled scmag
+   enabled scevent
+
+A successive call of :command:`seiscomp start` will then start all enabled
+modules. This is also required to restart enabled modules with :command:`seiscomp check`.
+
+Alternatively, :ref:`scconfig<scconfig>` can be used to enable/disable
+and to start/stop/restart modules.
+
+However, before starting seiscomp, station information (metadata) need to
+be provided and the configuration needs to be updated.
+
+
+Supply Station Metadata
+=======================
+
+|scname| requires the metadata from seismic network and stations including full responses
+for data acquisition
+and processing. The metadata can be obtained from network operators or
+various other sources in different formats. The metadata include, e.g.:
+
+- Network association
+- Operation times
+- Location
+- Sensor and data logger specifications with full response information
+- Data stream specifications
+
+|scname| comes with various importers to add metadata
+for networks and stations including full response information.
+
+:ref:`import_inv` is the tool to import inventory data into |scname|.
+Alternatively can be used.
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp exec import_inv dlsv inventory.dataless
+
+This will import a dataless SEED volume into `etc/inventory/inventory.dataless.xml`.
+
+Repeat this step for all inventory data you want to import.
+
+
+Configure Station Bindings
+==========================
+
+The configuration of modules and bindings is explained in :ref:`global`. To
+add bindings in a more convenient way, start :ref:`scconfig`.
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp exec scconfig
+
+Typical binding profiles or station bindings involve bindings configurations for
+data acquisition and processing modules:
+
+* :ref:`seedlink`: Configure the plugin for the real-time data acquisition.
+* :ref:`slarchive`: Configure the data archiving.
+* :ref:`global <global>`: Configure :confval:`detecStream` and :confval:`detecLocid` to determine the
+  default streams for phase detection and for showing stations and streams in GUIs
+  like :ref:`scmv`, :ref:`scrttv` or :ref:`scolv`.
+* :ref:`scautopick`: Configure the automatic phase detection. You may overwrite global
+  binding parameters.
+
+
+Update Configuration, Start Everything
+======================================
+
+To update the configuration when new stations have been added or modified,
+:command:`seiscomp update-config` needs to be run. This creates configuration
+files of modules that do not use the configuration directly, writes the trunk
+bindings to the database and synchronizes the inventory with the database.
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp update-config
+   [output]
+
+After the configuration has been updated and the inventory has been synchronized,
+call :command:`seiscomp start` to start all enabled modules:
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp start
+   starting seedlink
+   starting slarchive
+   starting scautopick
+   starting scautoloc
+   starting scamp
+   starting scmag
+   starting scevent
+
+Now the system should run. To check everything again, :command:`seiscomp check`
+can be run which should print *is running* for all started modules.
+If everything is working, the analysis tools can be started, e.g. MapView.
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp exec scmv

share/doc/seiscomp/html/_sources/base/history.rst.txt

@@ -0,0 +1,71 @@
+.. _history:
+
+**********************
+Historical Information
+**********************
+
+The first version of SeisComP was developed for the
+:term:`GEOFON` program operated by :term:`GFZ`.
+
+Originally, |scname| was designed as a high-standard, fully automatic data
+acquisition and (near-)real-time data processing tool including quality control,
+event detection and location as well as dissemination of event alerts.
+
+SeisComP was further extended within the MEREDIAN project under the lead of
+GEOFON and :cite:t:`orfeus`.
+
+Following the devastating 2004 Indian Ocean earthquake and tsunami, the
+:cite:t:`gitews` (German Indian Ocean Tsunami Early Warning System) project led
+to additional functionality being implemented to fulfill the requirements of
+24/7 early warning control centers. Major changes in the architecture of SeisComP
+were necessary and many new features resulted in the upgrade of SeisComP to 
+version 3.
+
+Since 2008 SeisComP has been jointly developed by :term:`gempa GmbH`, a spin-off
+company of GFZ and GFZ. Nowadays, gempa GmbH is the main SeisComP developing and
+service company.
+
+Major SeisComP releases are shown below. The important changes as of version 4.0
+are documented in the :ref:`changelog <sc-changelog>`.
+
++---------+-----------+--------------------+-----------------------------------------------------+
+| Version | Name      |  Time              |                                                     |
++=========+===========+====================+=====================================================+
+| 1.0     |           | February 2001      | SeedLink 2.0 (plugin interface) Plugins for         |
+|         |           |                    | EarthData PS2400 and Lennartz M24                   |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 1.1     |           | August 2001        | SeedLink 2.1 (streams.xml, improved buffer          |
+|         |           |                    | structure); make conf/make key scripts LISS         |
+|         |           |                    | plugin, SeedLink-Antelope connectivity              |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 1.1.5   |           | January 2002       | SeedLink 2.5 (multi-station mode)                   |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 1.16    |           | March 2002         | GIF live seismograms                                |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 2.0     |           | October 2003       | SeedLink 3.0 (INFO request, time window extraction) |
+|         |           |                    | libslink, chain plugin, Comserv-independence        |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 2.1     |           | June 2004          | Python add-on package (SeisPy) incl. AutoLoc2 chain |
+|         |           |                    | plugin extension interface, triggered streams       |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 2.5     |           | March 2006         | Integration of add-on packages, modular config      |
+|         |           |                    | script                                              |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 3.0     | alpha     | May 2007           | new architecture, new magnitude types, GUI          |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 3.0     | Barcelona | May 2008           | Stability and performance improvements, improved    |
+|         |           |                    | GUI functionality                                   |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 3.0     | Erice     | May 2009           | New Earthquake Schema and performance improvements, |
+|         |           |                    | improved GUI functionality                          |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 3.0     | Potsdam   | September 2010     | New Inventory Schema and performance improvements,  |
+|         |           |                    | improved GUI functionality                          |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 3.0     | Seattle   | 2012               | New user friendly configuration GUI scconfig        |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 3.0     | Jakarta   | 2014               | Completely Open Source, including all GUIs          |
++---------+-----------+--------------------+-----------------------------------------------------+
+| 4.0.0   |           | May 2020           | Adopts the GNU Affero General Public License v. 3.0,|
+|         |           |                    | (AGPL), support for Python3 and QT5                 |
++---------+-----------+--------------------+-----------------------------------------------------+

share/doc/seiscomp/html/_sources/base/installation.rst.txt

@@ -0,0 +1,434 @@
+.. _installation:
+
+*********************
+|scname| Installation
+*********************
+
+|scname| requires a modern Linux operating system as it is developed and tested
+only under Linux. For production systems we recommend Linux distributions with
+long-term support (LTS). The Linux flavors under which |scname| has been tested
+are given along with the |scname| package names on the download sites of
+:cite:t:`seiscomp` and :cite:t:`gempa`.
+
+The software can be obtained and installed from
+
+* Officially released packages (TAR files) for different release versions,
+  Linux systems and architectures,
+* :ref:`Source code available on GitHub <build>`.
+
+Packages may include
+
+* Software for data acquisition, processing and :term:`GUIs <GUI>` for each
+  supported platform,
+* Maps. Maps from the |scname| releases Seattle and Zurich also work
+  in later releases
+* Documentation,
+* Station configuration files (optional).
+
+Download these packages from :cite:t:`seiscomp` or :cite:t:`gempa-download`.
+
+The next sections describe the installation of the binary packages of |scname|
+on
+
+* :program:`Ubuntu 18`, 64 bit system,
+* :program:`CentOS 7`, 64 bit system.
+
+
+Hardware Requirements
+=====================
+
+The hardware requirements for a seismic system depend on the size of the
+station network to be operated.
+
+Minimum requirements are:
+
+.. csv-table::
+   :widths: 10 90
+   :align: left
+   :delim: ;
+
+   CPU; 2
+   RAM; 4 GB
+   HDD; 20 GB
+   OS; Ubuntu last 3 major LTS versions, 64bit, Debian 8.0 64bit, RHEL 7, CentOS 7 64bit
+
+In case large networks (>100 stations) are operated, a distributed system is
+recommended. Normally a |scname| system is separated in several subsystems.
+A separation of data acquisition, processing and graphical user interfaces (GUI) is
+useful to permit stable performance.
+
+The minimum specifications of |scname| systems depend on the setup and the
+applications.
+
+Data acquisition systems:
+
++-----+----------------------------------------------------------------+
+| CPU | 2                                                              |
++-----+----------------------------------------------------------------+
+| RAM | 4 GB                                                           |
++-----+----------------------------------------------------------------+
+| HDD | Raid1/5/0+1 with >= 200GB                                      |
++-----+----------------------------------------------------------------+
+
+Processing systems:
+
++-----+----------------------------------------------------------------+
+| CPU | 4                                                              |
++-----+----------------------------------------------------------------+
+| RAM | 8 GB                                                           |
++-----+----------------------------------------------------------------+
+| HDD | Raid1/5/0+1 with >= 100GB                                      |
++-----+----------------------------------------------------------------+
+
+GUI system:
+
++-----+----------------------------------------------------------------+
+| CPU | 2                                                              |
++-----+----------------------------------------------------------------+
+| RAM | 4 GB                                                           |
++-----+----------------------------------------------------------------+
+| HDD | > 50 GB                                                        |
++-----+----------------------------------------------------------------+
+
+
+.. _installation-packages:
+
+Installation from Packages
+==========================
+
+This section describes the installation of |scname| from compiled |scname|
+packages which ship as :file:`*.tar.gz` files.
+
+
+Steps to take
+-------------
+
+Simply follow a few steps to complete your installation of |scname|:
+
+#. Log in to your Linux system as user, e.g. sysop, the standard user in this
+   documentation.
+#. Download the installation packages, e.g. from :cite:t:`seiscomp` or
+   :cite:t:`gempa-download`:
+
+   * :file:`seiscomp-[version]-[OS]-[arch].tar.gz`: main |scname| package with binaries, etc.
+     Ensure to download the right package matching your operating system (OS) and
+     hardware architecture (arch: 32 or 64-bit).
+   * :file:`seiscomp-[version]-doc.tar.gz`: |scname| documentation.
+
+     .. note::
+
+        When receiving the packages from :cite:t:`gempa-download`, the documentation is already
+        included in the main |scname| package to match the installed version. In this
+        case, the documentation does not need to be downloaded and installed separately.
+
+   * :file:`seiscomp-maps.tar.gz`: standard |scname| maps available on the
+     download site of :cite:t:`seiscomp`.
+
+#. Copy the downloaded files to your $HOME directory.
+
+#. Navigate to the $HOME directory or any other place where to install |scname|
+
+   .. code-block:: sh
+
+      user@host:$ cd
+
+#. Install the main |scname| package into :file:`seiscomp`
+
+   .. code-block:: sh
+
+      user@host:~$ tar xzf seiscomp-[version]-[OS]-[arch].tar.gz
+
+#. Install the |scname| map package into :file:`seiscomp/share/maps`
+
+   .. code-block:: sh
+
+      user@host:~$ tar xzf seiscomp-[release]-maps.tar.gz
+
+#. Optional: Install the documentation package into :file:`seiscomp/share/doc`
+
+   .. code-block:: sh
+
+      user@host:~$ tar xzf seiscomp-[version]-doc.tar.gz
+
+Unpacking these files creates the |scname| :ref:`directory structure<directory_structure>`.
+
+
+.. _directory_structure:
+
+Directory structure
+-------------------
+
+All installed files and directories are found below the *seiscomp* directory.
+The directory structure of the installed system is described the table below.
+
+.. csv-table::
+   :widths: 10 90
+   :header: Directory, Description
+   :align: left
+   :delim: ;
+
+   *bin*;              The user module binaries.
+   *lib*;              The base library directory used by all modules.
+   *lib/python*;       The Python library directory.
+   *man*;              The manual pages.
+   *sbin*;             The system/service/server binaries such as :ref:`seedlink`.
+   *var*;              Variable files whose content is expected to continually change.
+   *var/log*;          Log files of started modules. Usually modules log either to syslog or ~/.seiscomp/log. This directory contains the logs of the start of each module.
+   *var/lib*;          Default directory for files created by modules such as the waveform ringbuffer of :ref:`seedlink` or the waveform archive created by :ref:`slarchive`.
+   *var/run*;          Contains the .run and .pid files of modules started by :program:`seiscomp`.
+   *include*;          SDK header files for all libraries.
+   *share*;            Application data such as maps, cities.xml and others.
+   *share/templates*;  Template files used by e.g. :ref:`seedlink` to create its native configuration.
+   *etc*;              Configuration directory.
+   *etc/descriptions*; Contains all XML module descriptions.
+   *etc/defaults*;     The default configuration files. This directory is read as first when a module starts.
+   *etc/init*;         Module init scripts called by :program:`seiscomp`.
+   *etc/key*;          Station configurations and module bindings.
+
+
+.. _software_dependencies:
+
+Software dependencies
+---------------------
+
+|scname| depends on a number of additional software packages shipped with each
+Linux distribution.
+After installation of |scname| these packages can be installed using the
+:program:`seiscomp`.
+The :program:`seiscomp` tool comes with
+the command :command:`install-deps` which installs required packages.
+Read the section :ref:`System management<system-management>` for more detailed
+instructions. For example, to install the dependencies for using the MariaDB
+database, give 'mariadb-server' as parameter.
+
+.. code-block:: sh
+
+   user@host:~$ seiscomp/bin/seiscomp install-deps base mariadb-server
+   Distribution: Ubuntu 18.04
+   [sudo] password for sysop:
+   Reading package lists... Done
+   Building dependency tree
+   Reading state information... Done
+   ...
+
+More options for systems with GUIs and FDSNWS are: ::
+
+   user@host:~$ seiscomp/bin/seiscomp install-deps gui fdsnws
+
+
+If your distribution is not supported by :command:`install-deps`,
+install the above packages manually:
+
+:program:`Ubuntu` `version`
+
+.. code-block:: sh
+
+   user@host:~$ cd seiscomp/share/deps/ubuntu/[version]
+   ...
+
+:program:`CentOS` `version`
+
+.. code-block:: sh
+
+   user@host:~$ cd seiscomp/share/deps/centos/[version]
+   ...
+
+.. code-block:: sh
+
+   su root
+   bash install-mariadb-server.sh
+   bash install-postgresql-server.sh
+   bash install-base.sh
+   bash install-gui.sh
+   bash install-fdsnws.sh
+   ...
+
+or contact the |scname| developers to add support for your distribution.
+
+.. warning::
+
+   Either the MariaDB **or** the MySQL server can be installed; not both at the
+   same time. When replacing on by the other, ensure that all related files are
+   removed before installing the alternative server. For MySQL instead of MariaDB
+   use: ::
+
+      root@host:~$ sh install-mysql-server.sh
+
+   Preferably use MariaDB instead of MySQL as MariaDB is the default for the
+   supported Linux distributions!
+
+.. note ::
+
+   Linux systems develop dynamically and the installation of the dependencies
+   may be incomplete. |scname| modules will stop and indicate the missing software.
+   They can be installed manually.
+
+
+.. _database_configuration:
+
+*****************************
+Database Server Configuration
+*****************************
+
+|scname| is typically operated with a :ref:`database <concepts_database>` which
+should be optimized. This section describes how to setup and optimize the
+database server. For the setup of the database itself read the section
+:ref:`getting-started`.
+
+
+.. _database_configuration_mysql:
+
+MariaDB / MySQL
+===============
+
+* For better performance with a MariaDB/MySQL database, adjust the memory pool size. Test
+  the default of the **buffer\_pool_size** before making the change:
+
+  .. code-block:: sh
+
+    $ mysql -u root -p
+    show variables like 'innodb_buffer_pool_size';
+
+  The optimum **buffer\_pool_size** depends on your system (RAM size) and only needs
+  to be set if required. Choose your preferred value:
+
+  * Recommended value: 512M or more
+  * Minimum value: 64M
+
+  Additionally, reduce the database hard drive synchronization and make both adjustments
+  in the section [mysqld]:
+
+  .. code-block:: sh
+
+    [mysqld]
+    innodb_buffer_pool_size = <your value>
+    innodb_flush_log_at_trx_commit = 2
+
+  .. note ::
+
+     The location of the configuration file can differ between distributions.
+
+     :program:`Ubuntu`:
+
+     :file:`/etc/mysql/mariadb.conf.d/50-server.cnf`
+
+     :program:`CentOS`:
+
+     :file:`/etc/my.cnf`
+
+  Please read the documentation of your distribution. root privileges may
+  be required to make the changes.
+
+* To start MariaDB automatically during boot set
+
+  :program:`Ubuntu`
+
+  .. code-block:: sh
+
+     user@host:~$ sudo systemctl enable mariadb
+
+  :program:`CentOS`
+
+  .. code-block:: sh
+
+     user@host:~$ su root
+     root@host:~$ systemctl enable mariadb
+
+* If you make a fresh installation of MariaDB/MySQL, secure the database and set
+  a password for the root user
+
+  :program:`Ubuntu` ::
+
+     user@host:~$ sudo mysql_secure_installation
+
+  :program:`CentOS` ::
+
+     user@host:~$ su root
+     root@host:~$ mysql_secure_installation
+
+  .. warning ::
+
+     This step overrides database settings. Only execute the command
+
+     * After a fresh installation or
+     * If you are sure about the procedure.
+
+* After adjusting the parameters, MariaDB needs to be restarted. One can run
+
+  :program:`Ubuntu`:
+
+  .. code-block:: sh
+
+     user@host:~$ sudo systemctl restart mariadb
+
+  :program:`CentOS`:
+
+  .. code-block:: sh
+
+     user@host:~$ su root
+     root@host:~$ systemctl restart mariadb
+
+.. note ::
+
+   Replace mariadb by mysql when using MySQL instead of MariaDB.
+
+
+.. _database_configuration_postgresql:
+
+PostgreSQL
+==========
+
+* When using PostgreSQL, the database server must be initialized and secured.
+
+* By default PostgresSQL does not allow to login with username and password which
+  leads to the fact that :program:`scmaster` can not connect to the database
+  after |scname| database initialization. Here an example how to enable
+  user/password authentication for local and remote connections.
+
+
+.. code-block:: sh
+
+     # TYPE  DATABASE        USER            ADDRESS                 METHOD
+      # IPv4 local connections:
+      host    seiscomp        sysop           0.0.0.0/0               md5
+      host    all             all             127.0.0.1/32            ident
+
+.. note ::
+
+     The order of the rules matters and the location of the configuration file
+     can differ between distributions.
+
+     :program:`Ubuntu`:
+
+     :file:`/etc/postgresql/10/main/pg_hba.conf`
+
+     :program:`CentOS`:
+
+     :file:`/var/lib/pgsql/data/pg_hba.conf`
+
+* By default PostgresSQL accepts local connections only. If the database server
+  and clients are on different machines please change the listen address as
+  follows.
+
+  .. code-block:: sh
+
+     listen_addresses = 0.0.0.0/0
+
+  .. note ::
+
+     The location of the configuration file can differ between distributions.
+
+     :program:`Ubuntu`:
+
+     :file:`/etc/postgresql/10/main/postgresql.conf`
+
+     :program:`CentOS`:
+
+     :file:`/var/lib/pgsql/data/postgresql.conf`
+
+
+Next Steps
+==========
+
+Now everything is installed and the system can be configured. The
+:ref:`next chapter<getting-started>` chapter explains the first steps.

share/doc/seiscomp/html/_sources/base/introduction.rst.txt

@@ -0,0 +1,114 @@
+.. _introduction:
+
+**********************
+Introduction and Scope
+**********************
+
+SeisComP is likely the most widely distributed software package for real-time monitoring
+of earthquakes and other seismic events. It provides automatic and interactive
+seismological data acquisition, processing and data exchange over the internet. Its
+data transmission protocol SeedLink has become a de facto world standard.
+
+|scname| convinces many seismologists and earthquake specialists at data and
+research centers, companies and governmental agencies world-wide by:
+
+* Powerful and reliable automatic data processing in real time or during post-processing
+* User-friendly and comprehensive graphical interfaces
+* Modern and well-maintained OpenSource software on GitHub
+  :cite:p:`seiscomp-github` welcoming community contributions.
+
+The first work on what became |scname| today began nearly two decades ago
+with developments at :term:`GFZ` of plugins for digitizers.
+It is now continued by :term:`gempa GmbH` and GFZ.
+The :ref:`section on historical information <history>` provides details on the past
+and current releases.
+
+
+Features
+========
+
+Today |scname| includes the following features:
+
+* Data acquisition
+* Waveform archiving
+* Waveform data distribution
+* Data quality control
+* Data recording
+* Real-time data exchange
+* Network status monitoring
+* Real-time data processing
+* Automatic event detection and location
+* Interactive event detection and location
+* Automatic and interactive magnitude calculation
+* Interactive determination of focal mechanisms
+* Issuing event alerts
+* Event parameter archiving
+* Easy access to relevant information about stations, waveforms and recent
+  earthquakes through graphical user interface and command-line tools
+* Python interface for developing custom scripts and modules.
+
+
+Software Design
+===============
+
+The guidelines for the design of |scname| are:
+
+* Implementation of critical functions as standalone modules to guarantee the
+  independence from other functions (e.g. picker, magnitude calculation,
+  interactive analysis)
+* Easy implementation of custom modules
+* Independence of hard- and software
+* Ability of data exchange between different automatic real-time systems
+* Distribution of modules on several systems
+* Robust system for rapid and reliable earthquake solutions (especially during
+  seismic crises)
+
+These design principles have given |scname| much robustness and flexibility
+to respond to new developments. The |scname| community is encouraged to contribute
+their |scname| source code on GitHub :cite:p:`seiscomp-github`. Examples and
+guidelines for generating
+code are given in the :ref:`developer section <sec_index_developers>`.
+
+
+This Documentation
+==================
+
+This documentation begins with an :ref:`overview` and a :ref:`concepts` section
+necessary for understanding and using |scname| successfully.
+The :ref:`Glossary section <glossary>` introduces technical terms.
+All important code changes are listed in the :ref:`change log <sc-changelog>`.
+When using |scname| or contributing source code, you should understand the
+:ref:`license terms <license>`.
+If you actually make use of |scname| and publish the results, we ask you to give
+appropriate reference as set out on the :ref:`Citation section <citation>`.
+
+In the following section the documentation covers the :ref:`installation <installation>`
+and how to configure and operate a working |scname| system.
+A few :ref:`tutorials` will guide you through a first example set up and further
+operations.
+
+The tutorials are followed by :ref:`detailed technical descriptions <sec_index_modules>`
+of each individual |scname| module, grouped by their general functionality:
+
+* Interactive analysis
+* Data acquisition
+* Inventory management
+* Automatic processing
+* Utilities
+
+and many more :ref:`extensions <sec_index_extensions>` like descriptions of the
+:term:`RecordStream`, magnitude types, locators, GUI customizations, waveform
+filters or plugins.
+
+The final part of the documentation relates to
+:ref:`contributing your own source code <sec_index_developers>` to |scname|.
+This requires a deeper knowledge of the |scname| :ref:`data model<api-datamodel-python>`
+and other details.
+This part also includes guidelines for developers such as
+:ref:`coding conventions <coding_conventions>`, :ref:`unit tests <unittests>`
+and a :ref:`guide for contributing documentation <contributing_documentation>`.
+:ref:`Some Python examples <sdk-python-examples>` help you to get started
+quickly with programming for |scname|.
+
+|scname| is developed and distributed under the terms of the GNU
+:cite:t:`agpl`, as set out in the :ref:`license` section.

share/doc/seiscomp/html/_sources/base/license.rst.txt

@@ -0,0 +1,724 @@
+.. _license:
+
+*******
+License
+*******
+
+In a nutshell
+=============
+
+You can use the entire SeisComP software collection under
+the terms of the GNU AGPL, non-commercially or commercially. You can talk
+about the software, you can give training sessions with the software, you
+can install the software wherever you like regardless of whether
+you are doing it for profit or not.
+You can operate the software and do your business with it.
+
+If you want to modify the software then you must publish all the changes
+you made. Even if you only run it on your servers and expose it to the public.
+If you build software applications linking against SeisComP libraries you have
+to publish them under the GNU AGPL/GPL if they are for use by others.
+
+If you want to write closed-source software with SeisComP you can apply for
+a Commercial License. It is your decision whether you want to use the
+libraries under the GNU AGPL or the Commercial License. You can't do both!
+
+GNU AFFERO GENERAL PUBLIC LICENSE Usage
+=======================================
+
+This Software may be used under the terms of the GNU
+Affero General Public License version 3.0 as published by the Free Software
+Foundation. Please review the following information to ensure the
+GNU Affero General Public License version 3.0 requirements will be met.
+
+The SeisComP application package is licensed exclusively under the GNU AGPL.
+
+Commercial License Usage
+========================
+
+Licensees holding valid commercial SeisComP licenses may use the Software in
+accordance with the commercial license agreement between you and gempa GmbH.
+For further information use the contact form at https://www.gempa.de/contact.
+
+GNU AFFERO GENERAL PUBLIC LICENSE
+=================================
+
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc.
+`<https://fsf.org/>`_
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Preamble
+--------
+
+The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains
+free software for all its users.
+
+When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate. Many developers of free software are heartened and
+encouraged by the resulting cooperation. However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community. It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server. Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals. This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing
+under this license.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+TERMS AND CONDITIONS
+--------------------
+
+0. Definitions.
+~~~~~~~~~~~~~~~
+
+"This License" refers to version 3 of the GNU Affero General Public
+License.
+
+"Copyright" also means copyright-like laws that apply to other kinds
+of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of
+an exact copy. The resulting work is called a "modified version" of
+the earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user
+through a computer network, with no transfer of a copy, is not
+conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to
+the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+~~~~~~~~~~~~~~~
+
+The "source code" for a work means the preferred form of the work for
+making modifications to it. "Object code" means any non-source form of
+a work.
+
+A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+2. Basic Permissions.
+~~~~~~~~~~~~~~~~~~~~~
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright. Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below. Sublicensing is not allowed; section 10 makes
+it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such
+circumvention is effected by exercising rights under this License with
+respect to the covered work, and you disclaim any intention to limit
+operation or modification of the work as a means of enforcing, against
+the work's users, your or third parties' legal rights to forbid
+circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these
+conditions:
+
+-   a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+-   b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under
+    section 7. This requirement modifies the requirement in section 4
+    to "keep intact all notices".
+-   c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy. This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged. This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+-   d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+-   a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+-   b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the Corresponding
+    Source from a network server at no charge.
+-   c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source. This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+-   d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge. You need not require recipients to copy the
+    Corresponding Source along with the object code. If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source. Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+-   e) Convey the object code using peer-to-peer transmission,
+    provided you inform other peers where the object code and
+    Corresponding Source of the work are being offered to the general
+    public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal,
+family, or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling. In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of
+coverage. For a particular product received by a particular user,
+"normally used" refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected
+to use, the product. A product is a consumer product regardless of
+whether the product has substantial commercial, industrial or
+non-consumer uses, unless such uses represent the only significant
+mode of use of the product.
+
+"Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to
+install and execute modified versions of a covered work in that User
+Product from a modified version of its Corresponding Source. The
+information must suffice to ensure that the continued functioning of
+the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or
+updates for a work that has been modified or installed by the
+recipient, or for the User Product in which it has been modified or
+installed. Access to a network may be denied when the modification
+itself materially and adversely affects the operation of the network
+or violates the rules and protocols for communication across the
+network.
+
+Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+7. Additional Terms.
+~~~~~~~~~~~~~~~~~~~~
+
+"Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders
+of that material) supplement the terms of this License with terms:
+
+-   a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+-   b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+-   c) Prohibiting misrepresentation of the origin of that material,
+    or requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+-   d) Limiting the use for publicity purposes of names of licensors
+    or authors of the material; or
+-   e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+-   f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions
+    of it) with contractual assumptions of liability to the recipient,
+    for any liability that these contractual assumptions directly
+    impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the
+above requirements apply either way.
+
+8. Termination.
+~~~~~~~~~~~~~~~
+
+You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You are not required to accept this License in order to receive or run
+a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+11. Patents.
+~~~~~~~~~~~~
+
+A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned
+or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+A patent license is "discriminatory" if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License. You may not convey a covered work if you
+are a party to an arrangement with a third party that is in the
+business of distributing software, under which you make payment to the
+third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by
+you (or copies made from those copies), or (b) primarily for and in
+connection with specific products or compilations that contain the
+covered work, unless you entered into that arrangement, or that patent
+license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under
+this License and any other pertinent obligations, then as a
+consequence you may not convey it at all. For example, if you agree to
+terms that obligate you to collect a royalty for further conveying
+from those to whom you convey the Program, the only way you could
+satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+13. Remote Network Interaction; Use with the GNU General Public License.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your
+version supports such interaction) an opportunity to receive the
+Corresponding Source of your version by providing access to the
+Corresponding Source from a network server at no charge, through some
+standard or customary means of facilitating copying of software. This
+Corresponding Source shall include the Corresponding Source for any
+work covered by version 3 of the GNU General Public License that is
+incorporated pursuant to the following paragraph.
+
+Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+14. Revised Versions of this License.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Affero General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever
+published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+15. Disclaimer of Warranty.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+16. Limitation of Liability.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
+LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+---------------------------------------------
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program. It is safest to
+attach them to the start of each source file to most effectively state
+the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+        <one line to give the program's name and a brief idea of what it does.>
+        Copyright (C) <year>  <name of author>
+
+        This program is free software: you can redistribute it and/or modify
+        it under the terms of the GNU Affero General Public License as
+        published by the Free Software Foundation, either version 3 of the
+        License, or (at your option) any later version.
+
+        This program is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        GNU Affero General Public License for more details.
+
+        You should have received a copy of the GNU Affero General Public License
+        along with this program.  If not, see `<https://www.gnu.org/licenses/>`_.
+
+Also add information on how to contact you by electronic and paper
+mail.
+
+If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source. For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code. There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for
+the specific requirements.
+
+You should also get your employer (if you work as a programmer) or
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. For more information on this, and how to apply and follow
+the GNU AGPL, see `<https://www.gnu.org/licenses/>`_.

share/doc/seiscomp/html/_sources/base/management.rst.txt

@@ -0,0 +1,403 @@
+.. _system-management:
+
+*****************
+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 :program:`seiscomp`
+is used with commands and options.
+
+:program:`seiscomp` is a Python script installed in
+:file:`seiscomp/bin/seiscomp`.
+The graphical tool :ref:`scconfig<scconfig>` is a user-friendly wrapper
+tool for many commands in :program:`seiscomp`.
+
+The entire management framework is built upon Python which is portable to different
+platforms. To make :program:`seiscomp` work, ensure that Python is installed on
+your system.
+
+:program:`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.
+
+   :program:`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
+
+.. code-block:: sh
+
+   seiscomp/bin/seiscomp help
+
+This will print all commands. To get help for a particular command, append
+it to the ``help`` command.
+
+.. code-block:: sh
+
+   seiscomp/bin/seiscomp help [command]
+
+
+.. _sec-management-commands:
+
+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 :file:`etc/init/[module].auto` for
+  each module passed.
+
+* **enable** [module list]
+
+  Enables a module to be started and checked automatically when either :command:`start`
+  or :command:`check` is called without arguments. This creates a file :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 |scname| 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**.
+
+  #. Install only base system dependencies:
+
+     .. code-block:: sh
+
+        seiscomp install-deps base
+
+  #. 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
+
+  #. Install also gui and fdsnws dependencies:
+
+     .. code-block:: sh
+
+        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 |scname| :ref:`shell <system-management-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 :file:`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.
+
+.. _system-management-shell:
+
+SeisComP Shell
+==============
+
+The |scname| shell can be started with
+
+.. code-block:: sh
+
+   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 :command:`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
+
+.. code-block:: sh
+
+   ================================================================================
+   seiscomp shell
+   ================================================================================
+
+   Welcome to the SeisComP interactive shell. You can get help about
+   available commands with 'help'. 'exit' leaves the shell.
+
+   $
+
+Enter :command:`help` to get a list of supported commands. The results of all
+commands issued are written to disk immediately and **not buffered**.
+
+Examples
+--------
+
+#. Assigning the scautopick global profile to all GE stations
+
+   .. code-block:: sh
+
+      $ set profile scautopick global GE.*
+
+#. Replace all profiles with station configuration for scautopick from GE
+   network
+
+   .. code-block:: sh
+
+      $ remove profile scautopick global GE.*
+
+#. Show bindings for station GE.MORC
+
+   .. code-block:: sh
+
+      $ 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.
+
+
+.. _system-management-init:
+
+Module Init Scripts
+===================
+
+All modules which can run in the background as daemon modules have init scripts.
+The init scripts are placed in :file:`etc/init`. :program:`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 :program:`seiscomp`.
+See :py:class:`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.
+
+.. code-block:: py
+
+   import seiscomp.Kernel
+
+   class Module(seiscomp.Kernel.Module):
+     def __init__(self, env):
+       seiscomp.Kernel.Module.__init__(self, env, env.moduleName(__file__))
+
+
+|scname| provides a Python module (:py:mod:`seiscomp.Kernel`) that allows to
+write init scripts in an easy way.
+
+
+Python kernel module
+--------------------
+
+The |scname| setup kernel module provides interfaces to write init handlers
+for modules used by :program:`seiscomp` in Python.
+
+.. py:module:: seiscomp.Kernel
+
+.. py:class:: Module(env, name)
+
+   :param env: The passes environment from :program:`seiscomp` which is
+               stored in self.env.
+   :param 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.
+
+   .. py:attribute: env
+
+      The kernel environment.
+
+   .. py:attribute: name
+
+      The module's unique name. This name is used for run/pid and log files.
+
+   .. py:attribute: order
+
+      The module's start order. The default value is 100 and modules with
+      the same value are ordered alphabetically.
+
+   .. py:method:: isRunning()
+
+      :rtype: Boolean
+
+      Checks if a module is running. The default implementation returns True
+      if the lockfile if not locked.
+
+   .. py:method:: start()
+
+      :rtype: Integer
+
+      Starts a module and returns 0 if no error occured and 1 otherwise. This
+      method is called from :program:`seiscomp start`.
+
+   .. py:method:: stop()
+
+      :rtype: Integer
+
+      Stops a module and returns 0 if no error occured and 1 otherwise. This
+      method is called from :program:`seiscomp stop`.
+
+   .. py:method:: check()
+
+      :rtype: Integer
+
+      Check is the same as start. The decision whether to check a module
+      or not is made :program:`seiscomp` which check the existence
+      of the corresponding run file. Returns 1 is case of error, 0 otherwise.
+
+   .. py:method:: status(shouldRun)
+
+      :param shouldRun: Boolean parameter that indicates if the module should
+                        run or not. This is evaluated by :program:`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
+
+      .. code-block:: py
+
+         self.env.logStatus(self.name, self, self.isRunning(), shouldRun,\
+                            self.env.isModuleEnabled(self.name) or \
+                            isinstance(self, CoreModule))
+
+   .. py:method:: updateConfig()
+
+      Updates the configuration and bindings based on the module's .cfg files
+      and :file:`etc/key/[modname]`. A :term:`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 :program:`seiscomp update-config`.
+
+   .. py:method:: printCrontab()
+
+      Prints crontab entries to stdout. The default implementation does not
+      print anything.
+
+      This is called from :program:`seiscomp print crontab`.
+
+.. py:class:: 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 :program:`seiscomp start` unless a CoreModule
+   implementation applies additional checks in :py:meth:`Module.start`.
+
+   :ref:`scmaster` is a core module which is a requirement for all :term:`trunk`
+   modules.
+
+.. py:class:: Environment
+
+   Access to the setup environment.

share/doc/seiscomp/html/_sources/base/overview.rst.txt

@@ -0,0 +1,270 @@
+.. _overview:
+
+********
+Overview
+********
+
+This overview section is intended to quickly introduce the reader into
+key aspect of |scname| and to provide the access points for further reading.
+
+
+Modular structure
+=================
+
+A |scname| system is not a single piece of software but it involves automatic and
+interactive modules working
+separately to process data and to analyze seismicity.
+Read the :ref:`concepts section on modules <concepts_modules>` for more conceptional details.
+
+Each module has a particular task, such as:
+
+* Acquisition of waveform data from one or more providers
+* Waveform archiving
+* Waveform processing to identify phase arrivals
+* Processing of phase picks to detect events and compute locations
+* Providing a user interface for manually reviewing events
+
+and many more. Key features are summarized in the :ref:`introduction <introduction>`.
+
+.. figure::  media/sc-interaction.png
+   :width: 16cm
+   :align: center
+
+   Real-time data acquisition, archiving and automatic processing combined with manual analysis.
+
+
+Data acquisition modules
+------------------------
+
+Data acquisition modules allow to provide and store waveform data in real-time.
+They are described in the acquisition section of the modules documentation.
+
+
+Automatic processing modules
+----------------------------
+
+Automatic processing modules allow real-time or offline processing of waveforms and event parameters.
+They are described in the processing section of the modules documentation.
+
+
+Interactive modules
+-------------------
+
+Interactive :term:`GUI` modules show waveforms and processing results and allow user interactions:
+
+* :ref:`scolv`: processing waveforms, locating events and determining magnitudes and focal mechnisms
+* :ref:`scrttv`: view waveforms and phase picks, select events for processing in scolv, enable or disable stations
+   for automatic processing
+* :ref:`scmv`: view station locations on a map with status information and waveforms, select events for processing in scolv
+* :ref:`scesv`: view the latest events on a map and relevant event parameters
+* :ref:`scheli`: view the seismogram of a station in a helicorder plot, save images automatically
+* :ref:`scqcv`: view waveform quality control (QC) parameters, enable or disable stations
+   for automatic processing
+* :ref:`scmm`: the messaging system monitor
+
+The GUI modules are described in the Interactive analysis section of this documentation.
+
+
+Inventory modules
+-----------------
+
+Inventory modules allow to manipulate inventories, e.g. to convert different formats
+or to write information to the database.
+They are described in the inventory section of the modules documentation.
+
+
+Utility modules
+---------------
+
+Utility modules provide access to waveforms, the data base and much more.
+They are described in the utilities section of the modules documentation.
+
+
+Communication and database access
+=================================
+
+As modules run, they produce objects corresponding to geophysical concepts
+such as :term:`picks <pick>` and :term:`origins <origin>`.
+These objects are exchanged with, and stored for later use by, other modules.
+Communication between these modules happens in two ways:
+
+#. Via objects stored in, and retrieved from, a shared database.
+#. Via messages exchanged between modules.
+
+Managing the communication between the modules in |scname| is the job of the :ref:`messaging
+system <concepts_messaging>`.
+The messaging system is controlled by :ref:`scmaster`. It acts as gatekeeper to the database,
+and only the module :ref:`scmaster` is allowed
+write access to the database.
+Additional details are found under :ref:`concepts_messaging` in the :ref:`concepts` chapter.
+
+.. figure::  media/sc_system_standard.jpg
+   :width: 10cm
+   :align: center
+
+   Modular organization of |scname| with messaging system, RecordStream interface and database.
+
+
+Waveform data
+=============
+
+Internally in |scname|. most waveform data is currently handled as :term:`miniSEED` data (Data Only
+:term:`SEED` records).
+A time series of records is identified by its stream identifier,
+following the SEED naming convention, ::
+
+  NET.STA.LOC.CHA
+
+where::
+
+  NET - two or three letter alphanumeric network code
+  STA - 1-5 letter alphanumeric station code
+  LOC - 0 or 2-letter alphanumeric location code
+  CHA - 3-letter channel or stream code
+
+Here *alphanumeric* means the digits 0 to 9, and uppercase letters A-Z.
+
+For publicly-available seismic stations these are typically supplied
+by external servers such as :ref:`seedlink` or :cite:t:`caps` servers.
+For example, the :cite:t:`geofon` seismic network makes data available at port 18000
+at geofon.gfz-potsdam.de which you may query and test using :ref:`slinktool`.
+
+If you operate your own seismic network, you may collect data directly
+from your station's digitizer using one of the many plugins included with
+the :ref:`seedlink` module.
+You can configure |scname| to obtain data for each station via :term:`bindings <binding>`.
+This configuration is described in the :ref:`tutorial on seedlink <tutorials_geofon_waveforms>`.
+
+Waveform data can be saved locally, using |scname|'s :ref:`slarchive` module.
+The waveform archive is organized in a structured way on your local file system,
+with one file for each channel and day, known as the :term:`SDS` archive.
+Thanks to |scname|'s :ref:`concepts_recordstream` concept, its modules
+can be reconfigured to use the local data from an archive, a server or from files, allowing *playbacks*.
+This ability to replay old waveforms and re-analyze them, is very
+important for exploring your system configuration, and developing
+|scname|.
+
+Finally, being both a collector and a server of waveform data,
+:ref:`seedlink` allows you to chain |scname| installations together to
+obtain waveform data from upstream sources and relay it to other data users.
+
+.. figure::  media/sc-acquisition-server.png
+   :width: 10cm
+   :align: center
+
+   Data flow from data centers and stations via plugins to seedlink and the waveform archive
+   both providing the data to local or remote |scname| modules or other clients.
+
+   
+Access to Waveform Data
+=======================
+
+|scname| modules can access waveform data from many difference sources,
+such as a Seedlink server or an FDSN web service.
+
+In |scname| terminology, the data from these sources are *record streams*.
+Access to the waveform data can be configured by setting an appropriate :term:`RecordStream`.
+Read the :ref:`concept description of the RecordStream<concepts_recordstream>`
+and :ref:`technical documentation of the various implementations <global_recordstream>` for many more details.
+
+.. figure::  media/recordstream.png
+   :width: 10cm
+   :align: center
+
+   The RecordStream interface provides flexible access to waveform data.
+
+Taken together, this design gives |scname| operators much flexibility.
+Since messages can be exchanged between different computers, and
+waveform data can be obtained from many sources, the different modules
+do not all have to be on a single computer.
+Multiple operators can connect to a single |scname| installation from their own computers.
+
+
+Station metadata
+================
+
+By :term:`inventory` we mean all information about seismic streams and stations
+that is needed for processing the raw data obtained from sensors.
+They are therefore also referred to as *station metadata*.
+Read the :ref:`concepts section on inventory <concepts_inventory>` for more details
+on formats and configuration in |scname|.
+
+Inventories include
+
+* Names and time periods of networks, stations, locations and streams (epochs)
+* Sample rates
+* Instrument responses (sensor and data logger)
+* Station and sensor coordinates
+
+and other essential information.
+Today there are some common formats to store metadata:
+
+* FDSN StationXML
+* |scname| inventory
+* Dataless SEED - the old *de facto* standard
+* ArcLink XML.
+
+Dataless SEED can be imported to, and exported from, |scname| if needed.
+
+You can get inventory information from various public sources including
+:cite:t:`eida` or :cite:t:`iris` and many more. :cite:t:`smp` allows you to
+create and share meta data from your own
+station network and to export an inventory in :term:`SCML` format.
+
+Inventories for all considered recording stations need to be imported
+into |scname|. and loaded into its database, before data can be processed.
+There are various tools to do this.
+The tools are described in the inventory section of this documentation.
+
+.. note ::
+
+   In order to process data streams, the inventory must provide complete response information
+   for all the streams AND must match the :term:`bindings <binding>` configuration.
+
+
+Configuration
+=============
+
+The basics of configuring a |scname| system are described in the
+:ref:`concepts section <concepts_configuration>`. The :ref:`tutorials` of this
+documentation provide step-by-step recipes. The modules documentation explains
+the modules functioning, their configuration and command-line parameters and
+give additional examples and links to related topics.
+
+
+What next?
+==========
+
+The following :ref:`installation` section of this manual will help you install |scname|.
+You will then need to obtain some inventory and a source of waveform data.
+Configure bindings, enable the processing modules, and restart |scname|.
+If all has gone well, you should see some stations as colorful triangles in
+:ref:`scmv`,
+and their traces in
+:ref:`scrttv`.
+
+Eventually, your new |scname| system will pick and create origins,
+should a locatable :term:`seismic event <event>` take place while it
+is running.
+
+
+Where to Go for More Help
+=========================
+
+The :ref:`tutorial on help<tutorials_help>` provides comprehensive list of options
+to get help on |scname|.
+Most |scname| modules have built-in help messages and descriptive HTML
+documentation. Read the :ref:`tutorial on help <tutorials_help>` for a neat
+introduction.
+
+There are other sources of information beyond this documentation. The
+:cite:t:`seiscomp-forum` has many useful contributions from the community.
+You are encouraged to register and post your own questions and comments there.
+
+Professional support including installation, training courses, maintenance,
+module development and modification is provided world-wide by
+`gempa GmbH <https://www.gempa.de/>`_ :cite:p:`gempa`, a
+software company out-sourced from GFZ and founded by the main |scname|
+developers.
+
+Enjoy |scname|!

share/doc/seiscomp/html/_sources/base/references.rst.txt

@@ -0,0 +1,54 @@
+.. _sec-references:
+
+References
+==========
+
+.. bibliography::
+
+Potentially uncited but relevant sources of information include:
+
+:ref:`iLoc <global_iLoc>`
+-------------------------
+
+#. Bondár, I., K. McLaughlin and H. Israelsson, Improved event location uncertainty
+   estimates, Science Applications International Corp., Final Report,
+   AFRL-RV-HA-TR-2008-1074, 2008.
+#. Bondár, I. and K. McLaughlin, Seismic location bias and uncertainty in the presence
+   of correlated and non-Gaussian travel-time errors, Bull. Seism. Soc. Am., 99,
+   172-193, doi:10.1785/0120080922, 2009.
+#. Bondár, I., E.R. Engdahl, A. Villasenor, J.Harris and D. Storchak, ISC-GEM:
+   Global instrumental earthquake catalogue (1900-2009), II. Location and seismicity
+   patterns, Phys. Earth. Planet. Int., doi: 10.1016/j.pepi.2014.06.002, 239, 2-13, 2015.
+#. Buland, R. and C.H. Chapman, 1983. The computation of seismic travel times,
+   Bull. Seism. Soc. Am., 73, 1271-1302.
+#. Dziewonski, A.M. and F. Gilbert, 1976, The effect of small, aspherical perturbations
+   on travel times and a re-examination of the correction for ellipticity,
+   Geophys., J. R. Astr. Soc., 44, 7-17.
+#. Engdahl, E.R., R. van der Hilst, and R. Buland, 1998. Global teleseismic earthquake
+   relocation with improved travel times and procedures for depth determination,
+   Bull. Seism. Soc. Am., 88, 722-743.
+#. Kennett, B. and Engdahl, E.R., 1991. Travel times for global earthquake location
+   and phase identification, Geophys. J. Int., 105, 429–465.
+#. Kennett, B.L.N., E.R. Engdahl, and R. Buland,  1995. Constraints on seismic velocities
+   in the Earth from traveltimes, Geophys. J. Int., 122, 108-124.
+#. Kennett, B.L.N. and O. Gudmundsson, 1996, Ellipticity corrections for seismic
+   phases, Geophys. J. Int., 127, 40-48.
+#. Myers, S.C, M.L. Begnaud, S. Ballard, M.E. Pasyanos, W.S. Phillips, A.L. Ramirez,
+   M.S. Antolik, K.D. Hutchenson, J. Dwyer, C. A. Rowe, and G. S. Wagner, 2010,
+   A crust and upper mantle model of Eurasia and North Africa for Pn travel time
+   calculation, Bull. Seism. Soc. Am., 100, 640-656.
+#. Weber, B., Bondár, I., Roessler, D., Becker, J., SeisComP3 iLoc Integration
+   Applied to Array Processing, SnT conference, Abstract: T3.5-P54, Vienna/Austria,
+   2019,
+   `abstract: T3.5-P54 <https://events.ctbto.org/sites/default/files/2020-05/20190614-2019%20Book%20Of%20Abstracts%20Web%20Version%20with%20front%20cover%20-%20edited.pdf>`_
+
+:ref:`FixedHypocenter <global_fixedhypocenter>`
+-----------------------------------------------
+
+#. R. Le Bras, J. Wuster (2002). IDC Processing of Seismic, Hydroacoustic,
+   and Infrasonic Data [IDC5.2.1Rev1]. Angewandte Wissenschaft, Software und
+   Technologie GmbH.
+#. J.F. Evernden (1969). Precision of epicenters obtained by small numbers of
+   world-wide stations. Bull. Seism. Soc. Am., 59(3), 1365-1398.
+#. E.A. Flinn (1965). Confidence regions and error determinations for seismic
+   event location. Rev. Geophys., 3(1), 157-185.

share/doc/seiscomp/html/_sources/base/sdk-python-examples.rst.txt

@@ -0,0 +1,156 @@
+.. _sdk-python-examples:
+
+********
+Examples
+********
+
+Simple messaging client
+=======================
+
+Summary
+-------
+
+Example client that connects to the messaging, listens for event
+objects and dumps the event IDs.
+
+Goal
+----
+
+Illustrate the basic messaging concepts.
+
+Script
+------
+
+This script was demonstrated at the |scname| workshop in Erice. It should be
+relatively self-explanatory, but full understanding does require certain knowlege
+of Python.
+
+The script does nothing but
+
+* connect to a |scname| messaging server
+* subscribe to messages sent to messaging group "EVENT"
+* listen to these messages
+* dump the event IDs to the screen
+
+event-listener.py
+^^^^^^^^^^^^^^^^^^^^^^
+
+No actual real-world use case but a truly minimum example for a |scname| application.
+
+.. literalinclude:: sdk-examples/event-listener.py
+
+Note that the EventListener class is derived from the application class
+seiscomp.client.Application from which it inherits most of the functionality.
+For instance the ability to connect to the messaging and to the database are
+both provided by seiscomp.client.Application; the EventListener only has to
+enable messaging and database usage in the __init__ routine. The real action
+takes place in the doSomethingWithEvent routine, which is called by both
+updateObject and addObject, depending on whether the event object received is a
+newly added or just and updated event.
+
+
+Inventory examples
+==================
+
+Summary
+-------
+
+Various Python example scripts that retrieve inventory information from the
+database.
+
+Goal
+----
+
+Illustrate the usefulness of simple Python scripts to retrieve inventory
+information.
+
+Scripts
+-------
+
+The scripts in this section all deal with inventory access. All need to be
+invoked with the command-line ``-d`` option to specify the |scname| database
+from which the information is to be read. For example:
+
+.. code-block:: sh
+
+   python configured-streams.py -d localhost
+
+configured-streams.py
+^^^^^^^^^^^^^^^^^^^^^
+
+Print a list of all streams configured on a |scname| system.
+
+.. literalinclude:: sdk-examples/configured-streams.py
+
+station-coordinates.py
+^^^^^^^^^^^^^^^^^^^^^^
+
+Print the coordinates of all stations configured on a |scname| system.
+
+.. literalinclude:: sdk-examples/station-coordinates.py
+
+channel-gains.py
+^^^^^^^^^^^^^^^^
+
+Print channel gains for all streams configured on a |scname| system.
+
+.. literalinclude:: sdk-examples/channel-gains.py
+
+
+Simple waveform client
+======================
+
+Summary
+-------
+
+Example client that connects to a RecordStream service and dumps the content
+to stdout.
+
+Goal
+----
+
+Illustrate the basic RecordStream concepts.
+
+Script
+------
+
+waveform-client.py
+^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: sdk-examples/waveform-client.py
+
+The command-line option ``-I`` can be used to configure the record
+stream backend when running the test application.
+
+.. code-block:: sh
+
+   python testrec.py -I slink://localhost:18000
+
+or to ask Arclink for data
+
+.. code-block:: sh
+
+   python testrec.py -I arclink://localhost:18001
+
+
+Waveform client and record filtering
+====================================
+
+Summary
+-------
+
+Example client that connects to a RecordStream service, filters the records
+with a given |scname| filter and dumps the content to stdout.
+
+Goal
+----
+
+Illustrate the recordfilter concepts.
+
+Script
+------
+
+waveform-filter.py
+^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: sdk-examples/waveform-filter.py

share/doc/seiscomp/html/_sources/base/sdk-python-packages.rst.txt

@@ -0,0 +1,9 @@
+.. _sdk-python-packages:
+
+********
+Packages
+********
+
+.. toctree::
+  /base/api-python
+  /base/api-python-client

share/doc/seiscomp/html/_sources/base/sdk-python.rst.txt

@@ -0,0 +1,9 @@
+.. _sdk-python:
+
+******
+Python
+******
+
+.. toctree::
+  /base/sdk-python-packages
+  /base/sdk-python-examples

share/doc/seiscomp/html/_sources/base/sdk.rst.txt

@@ -0,0 +1,8 @@
+.. _sdk:
+
+************************
+Software Development Kit
+************************
+
+.. toctree::
+  /base/sdk-python

share/doc/seiscomp/html/_sources/base/style-guide.rst.txt

@@ -0,0 +1,459 @@
+.. _documentation_style_guide:
+
+*****************************
+Style Guide for Documentation
+*****************************
+
+
+File Layout
+===========
+
+The documentation of an executable module comes as a pair of source files:
+
+* A description XML file (.xml) giving command details, command-line and configuration parameters,
+* A documentation reST text file (.rst) gives a more-detailed module description and examples.
+
+Any other documentation, e.g. this style guide, tutorials, etc. only require the
+documentation reST text file.
+
+The reST text file should follow the guidelines in this style guide.
+
+The :ref:`contributing_documentation` section details
+the documentation requirements for executables including the structure of description XML files.
+
+
+Documentation Syntax
+====================
+
+A template for a typical application or module in reST is in :file:`doc/templates/app.rst`.
+An introductory paragraph should describe the purpose of the executable.
+The introduction is followed be any additional information needed to understand
+the command, introduced with one or more headings.
+Add information about testing and examples into their own sections.
+
+
+General principles
+------------------
+
+- If possible, keep line lengths under 80 characters.
+- It eases later editing if sentences in the raw RST start on a new
+  line, even though they will flow together in the finished document.
+- It is helpful if long text objects such as HTML link text each
+  appear on their own line.
+
+
+  .. _documentation_style_guide_headings:
+
+Section and headings
+--------------------
+
+Module description files do *not* require top-level headings, as the
+build script will take this text and assemble it with other
+description information in the appropriate part of the documentation.
+
+While RST doesn't care too much about what syntax is used for
+headings, it is best to stick to one style consistently.
+Thus, you will generally need only two levels of headings but you can add more.
+
++-------+------------------------------+
+| Level | Mark up beneath heading text |
++=======+==============================+
+| 1     |  ' ==== '                    |
++-------+------------------------------+
+| 2     |  " ---- "                    |
++-------+------------------------------+
+| 3     |  ' ~~~~ '                    |
++-------+------------------------------+
+| 4     |  ' ^^^^ '                    |
++-------+------------------------------+
+
+Use Title Case for headings within a section, and make only the first letter uppercase for subheadings.
+Higher levels, marked up with asterisks, are used for sections of the documentation.
+
+**Example:**
+
+.. code-block:: sh
+
+   Level 1 Title
+   =============
+
+   Some text.
+
+
+   Level 2 title
+   -------------
+
+   Some text
+
+Parts such as Examples are marked in **bold**.
+
+However notes and figures should use the appropriate RST directive, and don't require their own headings.
+
+- One blank line below headings is enough.
+- Two lines above are often used, and this looks better than one.
+
+Lists
+-----
+
+Use numbered or unnumbered lists at several levels.
+
+- Start list items at the first level with a capital letter. End them with a full stop.
+- Use lower-case letters for all other levels. End them with a full stop.
+
+.. code-block:: rst
+
+   #. Item 1.
+   #. Item 2.
+      * subitem 1.
+        #. subsubitem 1.
+        #. subsubitem 1.
+      * subitem 2.
+
+**Result:**
+
+#. Item 1.
+#. Item 2.
+
+   * subitem 1.
+
+     a. subsubitem 1.
+     #. subsubitem 2.
+
+   * subitem 2.
+
+
+Other markup tools and conventions
+----------------------------------
+
+- **Code fragments:** Use the reST code-block syntax for code fragments, with
+  flavors like "c", "python", "sh", "bash", "properties´" or "xml" as appropriate:
+
+  .. code-block:: rst
+
+     .. code-block:: sh
+
+        #!/bin/bash
+        echo $SEISCOMP_ROOT
+
+  Result:
+
+  .. code-block:: sh
+
+     #!/bin/bash
+     echo $SEISCOMP_ROOT
+
+- **Configuration parameters:** Configuration values have a special
+  syntax. Use the ':confval:' indicator for referencing a module configuration
+  parameter:
+
+  .. code-block:: rst
+
+     :confval:`logging.level`
+
+  Using this tag allows a link to be made within the documentation of that module
+  to the given configuration of the same module. The parameter must be defined
+  in the description XML file of the module.
+
+- **Command-line options:** Command-line options have a special
+  syntax. Use the ':option:' indicator for referencing an option:
+
+  .. code-block:: rst
+
+     :option:`--help`
+
+  The option must be defined in the description XML file of the module.
+
+- **Configuration files:** Use the reST ':file:' indicator to refer to files such
+  as configuration files:
+
+  .. code-block:: rst
+
+     :file:`$SEISCOMP_ROOT/etc/scautopick.cfg`
+
+  Result: :file:`$SEISCOMP_ROOT/etc/scautopick.cfg`
+
+- **Programs:** Use the reST ':program:' indicator for |scname| programs:
+
+  .. code-block:: rst
+
+     :program:`scautopick`
+
+  Result: :program:`scautopick`
+
+- **References:** Use the reST ':ref:' indicator for cross referencing |scname|
+  module documentation pages:
+
+  .. code-block:: rst
+
+     :ref:`scautopick`
+
+  Result: :ref:`scautopick`
+
+- **Glossary:** Use the reST ':term:' indicator for referencing terms in the
+  |scname| :ref:`glossary`:
+
+  .. code-block:: rst
+
+     :term:`magnitude`
+
+  Result: :term:`magnitude`
+
+
+.. _documentation_style_guide_links:
+
+Internal links
+--------------
+
+Create links to sections and subsections within and to figures  the text which can be referenced.
+Use unique link names, e.g. including the upper-level section name or the module name.
+Use appropriate short names to fit within the texts.
+
+Link within this documentation to the section on headings:
+
+.. code-block:: rst
+
+   .. _documentation_style_guide_headings:
+
+Reference:
+
+.. code-block:: rst
+
+   :ref:`short name <documentation_style_guide_headings>`
+
+Result: :ref:`short name <documentation_style_guide_headings>`
+
+
+External links and references
+-----------------------------
+
+Preferably you do not show full citations or URLs for literature or
+external web sites within the text but make references which
+are listed in the section :ref:`sec-references`. Procedure:
+
+#. Add publications, external URLs, etc. as complete citation
+   entries to the reference list :file:`doc/base/references.bib`
+   in the base |scname| :ref:`repository on Github <build>`.
+#. Cite documents within the RST file using the *cite*
+   directive
+
+   .. code-block:: rst
+
+      :cite:p:`seiscomp`
+      :cite:t:`seiscomp`
+
+   which results in :cite:p:`seiscomp` and
+   :cite:t:`seiscomp` within the documentation HTML text.
+
+If you really cannot avoid URLs in RST files, then you may link them to some
+text like
+
+.. code-block:: rst
+
+   `SeisComP forum <https://forum.seiscomp.de/>`_
+
+resulting in `SeisComP forum <https://forum.seiscomp.de/>`_.
+
+Alternatively you may generate reference in a *Reference* sections as
+
+.. code-block:: rst
+
+   References
+   ==========
+
+   .. target-notes::
+
+   .. _`discussion` : https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised
+
+and then cite it within the text as
+
+.. code-block:: rst
+
+   `discussion`_
+
+which results in `discussion`_.
+
+
+Text boxes
+----------
+
+You may emphasize information within the text as text boxes to stand out at different levels.
+Make sensible use of it!
+
+* Hints
+
+  .. code-block:: rst
+
+     .. hint::
+
+        This adds a useful hint.
+
+  Result:
+
+  .. hint::
+
+     This adds a useful hint.
+
+* Notes
+
+  .. code-block:: rst
+
+     .. note::
+
+        This adds an extra note.
+
+  Result:
+
+  .. note::
+
+     This adds an extra note.
+
+* Alerts
+
+  .. code-block:: rst
+
+     .. caution::
+
+        This adds a heads-up alert.
+
+  Result:
+
+  .. caution::
+
+     This adds a heads-up alert.
+
+* Warnings
+
+  .. code-block:: rst
+
+     .. warning::
+
+        This adds an important warning.
+
+  Result:
+
+  .. warning::
+
+     This adds an important warning.
+
+
+English Language
+================
+
+- SeisComP (capital P), not SeisComP 3 or SC3.
+- |scname| module names are proper nouns, even though written with lower case.
+  Thus they do not need an article.
+
+  * Correct: "Although :program:`scmaster` receives a message"
+  * Incorrect: "Although the scmaster receives a message..."
+
+A sentence may begin with a lower case module name e.g. "scmaster has five modes..."
+avoiding this: "The :program:`scmaster` module has..."
+
+- Word separation:
+
+  - Separate words:
+    base class, wave number, time span
+  - One word:
+    aftershock, foreshock, *and mainshock too*,
+    bandpass, eigenperiod etc., metadata, standalone, username, workflow, waveform
+  - Difficult:
+    high-pass filter; command line; command-line parameter
+
+- Hyphenation for compound adjectives: yes, before a noun; after verb to be is harder.
+  See the `discussion`_, e.g.:
+
+  - Use command-line parameters
+  - Type on the command line
+
+- Spelling:
+
+  Use American English:
+
+  - With 'z': digitizer, realize, visualize, synchronize, behavior, color.
+  - With 's': license.
+  - Center, data center.
+
+- Case:
+
+  - SEED, miniSEED (miniSEED in :cite:t:`libmseed-github`, or MiniSEED,
+    but Mini-SEED appears in Appendix G of the :cite:t:`seed-2012`.)
+  - Ctrl+S for 'control' key plus 's'.
+  - MySQL, PostgreSQL, MariaDB
+
+- Abbreviations:
+
+  - e.g., i.e.
+  - STA, LTA, STA/LTA detector
+  - TAR file
+
+
+.. _documentation_style_guide_images:
+
+Adding Images
+=============
+
+Code implementation
+-------------------
+
+* Add images with fixed width.
+* Add image captions.
+* Store images in a separate directory of below the directory where the
+  documentation is kept.
+
+Example for an image which can be enlarge by mouse click:
+
+.. code-block:: rst
+
+   .. figure::  media/image.png
+      :alt: image one
+      :width: 10cm
+      :align: center
+
+      Image one.
+
+Example for images in two columns which cannot be enlarged. Up to 4 columns are possible.
+Compare with the :ref:`concept section on configuration<concepts_configuration-configs>`:
+
+.. code-block:: rst
+
+   .. raw:: html
+
+   <div class="two column layout">
+
+   .. figure:: ../media/scconfig_no_bindings.png
+      :alt: scconfig: bindings configurations
+
+      scconfig modules panel indicating that no bindings can be configured.
+
+    .. figure:: ../media/scconfig_has_bindings.png
+       :alt: scconfig: no bindings configurations
+
+       scconfig modules panel indicating that bindings can be configured.
+
+    .. raw:: html
+
+    </div>
+
+
+Image style and format
+----------------------
+
+* Images shall be informative.
+* Images must not have any offensive or inappropriate content.
+* Use PNG format.
+* Make the important image details readable at the normal image size without enlargement.
+* Images shall be optimized for file size.
+* Images should have a frame, e.g. a window frame.
+* Avoid private information on images.
+* Do not show desktop background unless required.
+* Images from |scname| GUIs can be screenshots.
+* Do not create screenshots from applications started remotely with X-forwarding.
+  X-forwarding may distort the application features.
+
+
+References
+==========
+
+.. target-notes::
+
+.. _`discussion` : https://english.stackexchange.com/questions/65630/you-should-be-well-organised-or-you-should-be-well-organised

share/doc/seiscomp/html/_sources/base/tests.rst.txt

@@ -0,0 +1,202 @@
+.. _unittests:
+
+************
+Unit Testing
+************
+
+Introduction
+============
+
+From Wikipedia:
+
+  In computer programming, unit testing is a software testing method by which
+  individual units of source code, sets of one or more computer program modules
+  together with associated control data, usage procedures, and operating
+  procedures, are tested to determine whether they are fit for use. [#WPUT]_
+
+This chapter targets programmers, either ones contributing to |scname| or
+adding their extended set of modules / libraries.
+
+Since most of the |scname| code is written in C++, this chapter focuses on
+C++ unit tests. For C++, we have evaluated three unit test frameworks:
+
+* CppUnit
+* Google Test
+* Boost Test
+
+We found that Boost Test is the most appropriate, flexible and easy to
+understand unit test framework. Another important fact was the availability of
+Boost Test on all major Linux distributions via their package managers. That
+|scname| makes already use of other Boost libraries was the icing on the cake.
+
+So this chapter is about integrating unit tests into |scname| with the Boost Test
+library.
+
+Apart from the availability of the Boost test libraries, cmake with version
+2.8.0 or greater is also required.
+
+Preparations
+============
+
+With CMake it is easy to setup arbitrary tests. To make it even easier, we
+added a shortcut to the CMake macro :code:`SC_ADD_LIBRARY`. It collects all .cpp
+files in the directory :code:`${CMAKE_CURRENT_SOURCE_DIR}/test/{libraryname}`
+and creates tests from them.
+
+An example is the |scname| core library. It is located at
+:code:`src/base/common/libs/seiscomp`. Following the above rule, the test files
+shall be located in :code:`src/base/common/libs/seiscomp/test/core/*.cpp`. For each
+found source file, the macro will create a test with the same name and link
+its executable against the library the tests are built for.
+
+.. note::
+
+   The recommend test file naming is :code:`{class}_{function}.cpp`.
+
+Execution
+=========
+
+Compiling and running tests is as easy as running
+
+.. code-block:: sh
+
+   make test
+
+in the build directory. Thats it.
+
+Test implementation
+===================
+
+The following section shows an example of a simple but in many cases sufficient
+test module. This example can be used as a template for an |scname| unit test.
+
+.. code-block:: cpp
+
+   #define SEISCOMP_TEST_MODULE [TestModuleName]
+   #include <seiscomp/unittest/unittests.h>
+   #include <seiscomp/core/datetime.h>
+
+   BOOST_AUTO_TEST_SUITE([domain]_[namespace]_[module])
+
+   BOOST_AUTO_TEST_CASE(addition) {
+       Seiscomp::Core::TimeSpan k = 5, l = 7;
+       BOOST_CHECK(k + l  == Seiscomp::Core::TimeSpan(12));
+   }
+
+   BOOST_AUTO_TEST_CASE(dummy_warning) {
+       Seiscomp::Core::Time tNegativeUsec(3000, -789);
+       BOOST_WARN_EQUAL(tNegativeUsec.seconds(), 3000);
+       BOOST_WARN_EQUAL(tNegativeUsec.microseconds(), -789);
+   }
+
+   BOOST_AUTO_TEXT_SUITE_END()
+
+That was simple, wasn't it? For more complex examples and usages, visit the
+Boost Unit Test Framework documentation [#b1]_. Furthermore you have to link
+your test executable against :code:`${Boost_unit_test_framework_LIBRARY}` and
+:code:`seiscomp_unittest`. A simple CMakeLists.txt file looks as follows:
+
+.. code-block:: cmake
+
+   ADD_EXECUTABLE(test_mylib_myfeature feature.cpp)
+   SC_LINK_LIBRARIES_INTERNAL(test_mylib_myfeature unittest)
+   SC_LINK_LIBRARIES(test_mylib_myfeature ${Boost_unit_test_framework_LIBRARY})
+
+   ADD_TEST(
+       NAME test_mylib_myfeature
+       WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+       COMMAND test_mylib_myfeature
+   )
+
+Warning levels
+--------------
+
+In Boost Test there are **3 different levels** to handle the results.
+
+- Warning: WARN [#b2]_
+  The error is printed and the error counter **is not** increased.
+  The test execution will not be interrupted and will continue to execute other
+  test cases.
+
+- Error: CHECK
+  The error is printed and the error counter **is** increased.
+  The test execution will not be interrupted and will continue to execute other
+  test cases.
+
+- Fatal error: REQUIRE
+  The error is printed and the error counter **is** increased.
+  The test execution will be aborted.
+
+
+Tools
+-----
+
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+|                           Tool                            | what it do (short info)                   | example                                                   | return value                |
++===========================================================+===========================================+===========================================================+=============================+
+| BOOST_<LEVEL>_EQUAL(left, right)                          | left == right                             | BOOST_<LEVEL>_EQUAL(4,5)                                  |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>(predicate)                                  | predicate is true                         | BOOST_<LEVEL>(4+5 == 3+3+3)                               | if false, both results show |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_EXCEPTION(expression, exception, predicate) | is exception equal to throw               | BOOST_<LEVEL>_EXCEPTION(myVector(-5), out_of_range, true) | if false, show the exactly  |
+|                                                           | exception of expression                   |                                                           |          exception          |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_CLOSE(left, right, tolerance)               | (left - right) <= tolerance               | BOOST_<LEVEL>_CLOSE(5.3, 5.29,0.1)                        |    if false, the exactly    |
+|                                                           | tolerance in percentage                   |                                                           |      tolerance is show      |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_LT(left, right)                             | left < right                              | BOOST_<LEVEL>_LT(6,8)                                     |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_GT(left, right)                             | left > right                              | BOOST_<LEVEL>_GT(78,90)                                   |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_GE(left, right)                             | left >= right                             | BOOST_<LEVEL>_GE(54,10)                                   |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_LE(left, right)                             | left <= right                             | BOOST_<LEVEL>_LE(10,2)                                    |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_NE(left, right)                             | left != right                             | BOOST_<LEVEL>_NE(1,0)                                     |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_ERROR("message")                                    | increasing error counter and show message | BOOST_ERROR("There was a problem")                        |            message          |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_TEST_MESSAGE("message") [#b3]_                      | show message                              | BOOST_TEST_MESSAGE("Your ad can be placed here")          |            message          |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+| BOOST_<LEVEL>_THROW(expression,exception)                 | perform an exception perception check     | BOOST_<LEVEL>_THROW(myVector(-2),out_of_range)            |         true or false       |
++-----------------------------------------------------------+-------------------------------------------+-----------------------------------------------------------+-----------------------------+
+
+For more tools and information about the Boost unit test tools see [#b4]_.
+
+Test output
+===========
+
+The test binary will exit with an error code of 0 if no errors were detected
+and the tests finished successfully. Any other result code represents failed
+tests.
+
+An example output looks like this:
+
+.. code::
+
+   Running tests...
+   Test project /home/sysop/seiscomp/build
+       Start 1: stringtoxml
+   1/4 Test #1: stringtoxml ......................***Failed    0.03 sec
+       Start 2: datetime_time
+   2/4 Test #2: datetime_time ....................   Passed    0.03 sec
+       Start 3: xml_test
+   3/4 Test #3: xml_test .........................   Passed    0.03 sec
+       Start 4: datetime_timespan
+   4/4 Test #4: datetime_timespan ................   Passed    0.03 sec
+
+   75% tests passed, 1 tests failed out of 4
+
+   Total Test time (real) =   0.17 sec
+
+   The following tests FAILED:
+             1 - stringtoxml (Failed)
+   Errors while running CTest
+   Makefile:61: recipe for target 'test' failed
+   make: *** [test] Error 8
+
+.. [#WPUT] https://en.wikipedia.org/wiki/Unit_testing
+.. [#b1] As of Boost version 1.46, it is located at http://www.boost.org/doc/libs/1_46_0/libs/test/doc/html/index.html
+.. [#b2] *to see the warnings use the instruction:* **boost::unit_test::unit_test_log.set_threshold_level(boost::unit_test::log_warnings);**
+.. [#b3] *to see the messages use the instruction:* **boost::unit_test::unit_test_log.set_threshold_level(boost::unit_test::log_messages);**
+.. [#b4] As of Boost version 1.46, it is located at http://www.boost.org/doc/libs/1_46_0/libs/test/doc/html/utf.html

share/doc/seiscomp/html/_sources/base/time-grammar.rst.txt

@@ -0,0 +1,350 @@
+.. _time-formats:
+
+************
+Time Formats
+************
+
+In |scname| all absolute times of raw :term:`miniSEED` waveforms and
+:ref:`SeisComP objects <api-datamodel-python>` like event parameters, inventory,
+etc. are natively given and assumed in UTC. For reading and writing absolute
+times a range of formats are supported.
+
+Historically, the only time format native to |scname| would be
+
+.. code-block:: properties
+
+   YYYY-MM-DD hh:mm:ss.ssssss
+
+As a consequence of the space between *DD* and *hh* this time string needs
+to be enclosed by quotes or double quotes. Otherwise, the time string meant to
+be a single string only would be interpreted as two strings. Example:
+
+.. code-block:: sh
+
+   scevtls -d localhost --begin '2024-01-01 12:00:00'
+
+Depending on the module, trailing parameters could be omitted or not for
+shortening the arguments but the general rules were initially unclear.
+
+More flexibility has been introduced with SeisComP in version 6.4.0 with the
+new C++ and Python function:
+
+C++:
+
+.. code-block:: c
+
+   Seiscomp::Core::Time::fromString()
+
+Python:
+
+.. code-block:: python
+
+   seiscomp.core().time().fromString()
+
+In adaptation to the norm :cite:t:`iso_8601` a subset of strings is now
+available. Supported formats are
+
+* Calender dates,
+* Ordinal dates,
+* Times (24-hour clock system) in combination with calender or ordinal dates.
+
+Currently unsupported are:
+
+* Week dates,
+* Times without dates,
+* Time zone offset designators,
+* Local times.
+
+.. csv-table:: List and examples of supported time string formats
+   :widths: 30 30 40
+   :header: Implementation, Time string format, Examples: all actual times are identical
+   :align: left
+   :delim: ;
+
+   %FT%T.%fZ    ; YYYY-MM-DDThh:mm:ss.ssssssZ ; 2025-01-01T00:00:00.000000Z
+   %FT%T.%f     ; YYYY-MM-DDThh:mm:ss.ssssss  ; 2025-01-01T00:00:00.000000
+   %FT%TZ       ; YYYY-MM-DDThh:mm:ssZ        ; 2025-01-01T00:00:00Z
+   %FT%T        ; YYYY-MM-DDThh:mm:ss         ; 2025-01-01T00:00:00
+   %FT%R        ; YYYY-MM-DDThh:mm            ; 2025-01-01T00:00
+   %FT%H        ; YYYY-MM-DDThh               ; 2025-01-01T00
+   %Y-%jT%T.%f  ; YYYY-DDDThh:mm:ss.ssssss    ; 2025-001T00:00:00.000000
+   %Y-%jT%T     ; YYYY-DDDThh:mm:ss           ; 2025-001T00:00:00
+   %Y-%jT%R     ; YYYY-DDDThh:mm              ; 2025-001T00:00
+   %Y-%jT%H     ; YYYY-DDDThh                 ; 2025-001T00
+   %F %T.%f (*) ; YYYY-MM-DD hh:mm:ss.ssssss  ; '2025-01-01 00:00:00.000000'
+   %F %T    (*) ; YYYY-MM-DD hh:mm:ss         ; '2025-01-01 00:00:00'
+   %F %R    (*) ; YYYY-MM-DD hh:mm            ; '2025-01-01 00:00'
+   %F %H    (*) ; YYYY-MM-DD hh               ; '2025-01-01 00'
+   %F           ; YYYY-MM-DD                  ; 2025-01-01
+   %Y-%j        ; YYYY-DDD                    ; 2025-001
+   %Y           ; YYYY                        ; 2025
+
+(*): Time strings with spaces must be enclosed by quotes or double quotes for
+protecting the space.
+
+.. csv-table:: List of format symbols used in table of time string formats
+   :widths: 10 90
+   :header: Symbol, Description
+   :align: left
+   :delim: ;
+
+   YYYY;   4-digit year
+   MM;     2-digit month starting with 01
+   DD;     1- or 2-digit day of the month starting with 01
+   DDD;    1-, 2- or 3-digit day of year starting with 001
+   hh;     1- or 2-digit hour of the day starting with 00
+   mm;     1- or 2-digit minute of the hour starting with 00
+   ss;     1- or 2-digit second of the minute starting with 00
+   ssssss; 1-6 digits decimal fraction of a second with 0
+   Z;      Zone designator for the zero UTC offset
+
+Durations can be formed from start and end dates and times combined by tilde(~).
+Example:
+
+.. code-block:: sh
+
+   scart -dsEv -t 2024-01-01T12~2024-01-01T12:15:30.2Z
+
+
+.. _time-grammar:
+
+************
+Time Grammar
+************
+
+Amplitudes are measured on waveforms by modules such as :ref:`scautopick`,
+:ref:`scamp` or :ref:`scolv` for computing magnitudes, e.g., by :ref:`scmag` or
+:ref:`scolv`. The principles are outlined in the concepts section
+:ref:`concepts_magnitudes`.
+
+The time windows for measuring noise and signal amplitudes are given by their
+respective begin and end values. These window parameters are configured as
+global binding parameters specifically for a particular amplitude type, let's
+say :ref:`ML <global_ml>`:
+
+.. code-block:: properties
+
+   amplitudes.ML.noiseBegin
+   amplitudes.ML.noiseEnd
+   amplitudes.ML.signalBegin
+   amplitudes.ML.signalEnd
+
+**The configured values are added to trigger time**, *triggerTime*, which
+corresponds to the arrival of P waves for most applications. *triggerTime* is
+hence the sum of *originTime* and *relativeTriggerTime*.
+
+Example:
+
+.. math::
+
+   absoluteSignalEnd =\ &originTime + relativeTriggerTime + amplitudes.ML.signalEnd \\
+                     =\ &originTime - relativeOriginTime + amplitudes.ML.signalEnd \\
+                     =\ &triggerTime + amplitudes.ML.signalEnd
+
+.. important::
+
+   Where values of time-window parameter values shall be estimated from distance
+   measures such as :envvar:`D` or :envvar:`h`, the relative origin time,
+   :envvar:`OT`, must be added to get the actual difference to *triggerTime*. In
+   contrast, :py:func:`tt()` returns the time difference to :envvar:`OT`.
+   Therefore, :py:func:`tt()` does not need to be corrected for origin time.
+
+In |scname| the configuration of the begin and end values is supported in the
+Bindings Panel of :ref:`scconfig`: For global bindings parameters you may create
+an amplitude-type profile with the name of the amplitude type, e.g., ML. The
+profile allows you to configure the parameters.
+You may set the values as a combination of :ref:`functions <sec-time-functions>`,
+:ref:`operators <sec-time-operators>`, :ref:`variables <sec-time-variables>` and
+constant values. The combination of them allows setting up a flexible time
+grammar for time windows. You may further use parentheses *()* to apply
+operations within the parentheses before operations outside of parentheses.
+
+If the result of the final evaluation of the parameter value is *unset*, e.g.,
+because required information are not available, then the processing receives an
+error and the amplitude will not be computed.
+
+
+Examples
+========
+
+The details of the grammar elements used in the following examples are
+described :ref:`below <sec-time-details>`.
+
+* Return the signal end time to measure :term:`mB amplitudes <magnitude,
+  broadband body-wave (mB_BB)>`:
+
+  .. code-block:: properties
+
+     min(D * 11.5, 60)
+
+  where function :py:func:`min()` returns the minium from two parameters to,
+  epicentral distance, :envvar:`D`, is a variable and '\*' and '\+' are
+  operators.
+
+  In this example, the minimum time from either epicentral distance in degree
+  times 11.5 s/deg or 60 s is returned if epicentral distance is available. If
+  epicentral distance is not available, 60 s is returned hence being the default.
+
+* Return the signal end time to measure amplitudes ending before the arrival of
+  surface waves or 150 s:
+
+  .. code-block:: properties
+
+     min(OT + D * 35, 150)
+
+  where the epicentral distance, :py:envvar:`D`, is multiplied by 35 s/deg. The
+  relative origin time, :py:envvar:`OT`, is either added in order to obtain the
+  time relative to trigger time.
+  The minimum of this value and 150 s is returned by :py:func:`min()`. This
+  means that 150 s it the default in case epicentral distance is not available.
+
+* Return the time difference as the minimum of predicted arrivals of S-waves
+  adding 10 s or 150 s:
+
+  .. code-block:: properties
+
+     min(tt(S) + 10, 150)
+
+  where the function :py:func:`tt()` returns the relative travel time of the
+  argument, here the S phase, and '\+' is an operator.
+
+  In this example the minimum time from either the relative arrival time of S
+  phase plus 10 s or 150 s is returned.
+
+Similar to the statements above, the time windows for measuring amplitudes can
+be configured, e.g., for overriding default time for :term:`MLv amplitudes
+<magnitude, local vertical (MLv)>`:
+
+.. code-block:: properties
+
+   amplitudes.MLv.noiseBegin=-10
+   amplitudes.MLv.noiseEnd=-1
+   amplitudes.MLv.signalBegin=-1
+   amplitudes.MLv.signalEnd=tt(S)+10
+
+
+.. _sec-time-details:
+
+Functions, Operators, Variables
+===============================
+
+Variables, operators and functions are available. Variables define standard
+values and function provide values based on a parameter given within
+parentheses like :py:func:`tt()`. Find below their individual descriptions.
+
+
+.. _sec-time-functions:
+
+Functions
+---------
+
+.. py:function:: max(arg1, arg2)
+
+   Calculates the maximum of two values. If one value is unset then the other
+   value is returned. If both values are unset then the result is unset, too.
+
+   :param arg1: First value to consider
+   :param arg2: Second value to consider
+
+.. py:function:: min(arg1, arg2)
+
+   Calculates the minimum of two values. If one value is unset then the other
+   value is returned. If both values are unset then the result is unset, too.
+
+   :param arg1: First value to consider
+   :param arg2: Second value to consider
+
+
+.. py:function:: tt(phase)
+
+   Calculates the travel-time of the given phase **w.r.t. relative origin
+   time, :py:envvar:`OT`**. The result is unset if the travel time cannot be
+   computed. The travel times are computed based on the travel-time interface
+   and model defined in :confval:`amplitudes.ttt.interface` and
+   :confval:`amplitudes.ttt.model`, respectively.
+
+   :param phase: Phase name available with the defined travel-time interface
+                 and model.
+
+
+.. py:function:: arr(phase, acceptAll)
+
+   Extracts the travel times of actually used arrivals **relative to the trigger
+   time**. The arrivals with the given phase code must exist.
+
+   :param phase: Phase code of the arrival. The arrival must exist and the
+                 sensor location of the associated pick must match the sensor
+                 location of the target object.
+   :param acceptAll: Whether to accept all arrivals or only manually
+                     revised arrivals. The default is 'true' if not
+                     given. Allowed is either 'true' or 'false'. If
+                     'true' is given, then either the evaluation mode
+                     of the origin or the evaluation mode of the pick
+                     must be 'manual'.
+
+
+.. _sec-time-operators:
+
+Operators
+---------
+
+If either of the operands is unset then the result will be also unset.
+
+* \+ : addition
+* \- : subtraction
+* \* : multiplication
+* \/ : division
+* \^ : power / exponentiation
+* \|\| : logical OR which returns the first set value if any
+* \|. \| : absolute value
+* \% : modulo
+
+
+.. _sec-time-variables:
+
+Variables
+---------
+
+Variables can take the value *unset* when required information is not available.
+The behaviour of :ref:`operators <sec-time-operators>` and
+:ref:`functions <sec-time-functions>` with variables of value *unset* depends
+on the operator and function itself.
+
+.. envvar:: OT
+
+   Relative origin time as difference from origin to trigger
+   (originTime - triggerTime). For most amplitude types, the
+   trigger is the measured or the predicted arrival time of the P phase.
+
+   Unit: ``s``
+
+.. envvar:: D
+
+   :term:`Epicentral distance <distance, epicentral>`
+
+   Unit: ``deg``
+
+.. envvar:: d, R
+
+   :term:`Epicentral distance <distance, epicentral>`
+
+   Unit: ``km``
+
+.. envvar:: H
+
+   :term:`Hypocentral distance <distance, hypocentral>`
+
+   Unit: ``deg``
+
+.. envvar:: h
+
+   :term:`Hypocentral distance <distance, hypocentral>`
+
+   Unit: ``km``
+
+.. envvar:: Z
+
+   :term:`origin` depth
+
+   Unit: ``km``
+

share/doc/seiscomp/html/_sources/base/tutorials.rst.txt

@@ -0,0 +1,29 @@
+.. _tutorials:
+
+*********
+Tutorials
+*********
+
+This chapter provides some tutorials to help you get started with |scname|.
+
+The material here is not the primary documentation.
+Rather, it attempts to explain what is to be done in a step-by-step way.
+For details, see the other chapters of this manual.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   /base/tutorials/postinstall
+   /base/tutorials/upgrading
+   /base/tutorials/addstation
+   /base/tutorials/waveforms
+   /base/tutorials/archiving
+   /base/tutorials/processing
+   /base/tutorials/geofon_waveforms
+   /base/tutorials/servefdsnws
+   /base/tutorials/magnitude-regionalization
+   /base/tutorials/waveformplayback
+   /base/tutorials/help
+
+   /base/tutorials/template

share/doc/seiscomp/html/_sources/base/tutorials/addstation.rst.txt

@@ -0,0 +1,164 @@
+.. _tutorials_addstation:
+
+*****************
+Add a new station
+*****************
+
+This tutorial guides you through the most common activities
+involved in configuring a single new station in your existing SeisComP system.
+Depending on your needs, you will use parts of other tutorials to do this.
+
+Pre-requisites for this tutorial:
+
+* :ref:`tutorials_postinstall`
+* An understanding of :ref:`concepts_inventory`.
+
+You may also need to consult
+
+* :ref:`tutorials_waveforms`
+* :ref:`tutorials_processing`
+* :ref:`tutorials_archiving`
+
+Afterwards/Results/Outcomes:
+
+* Optionally, data for the new station are acquired and archived in real time.
+* Optionally, the new station is used for automatic real-time data processing.
+
+Time range estimate:
+
+* Variable
+
+----------
+
+Before you start
+================
+
+Try to answer the questions:
+
+* where will you get data?
+* if you want to process data locally, where will you get inventory?
+* which data will you share?
+* how long will you archive, and what streams?
+
+For this example, we'll add the GRSN Station Collm (CLL)
+from the GR network.
+
+* If you want to process data on this system, you will need
+  inventory (metadata).
+  Metadata can be obtained from many different sources or created from scratch.
+* If you don't want to process on this system, you won't need inventory,
+  but you will have to create key file by hand for acquisition and archiving.
+
+
+Obtaining inventory for your station
+====================================
+
+For processing, you will need inventory for the new station.
+How to obtain this will vary.
+You can fetch inventory from:
+
+* Other SeisComP systems. Use :ref:`scxmldump` to fetch inventories.
+* EIDA nodes :cite:p:`eida`. Use web interfaces such as web browsers or `wget`
+  to fetch an inventory.
+* Data centers providing :cite:t:`fdsn`. Use web interfaces such as web browsers
+  or `wget` to fetch an inventory.
+* Your own or shared user repositories on :cite:t:`smp`.
+
+
+.. note:: Create and share inventories
+
+   gempa's :cite:t:`smp` is a tool for creating inventory from scratch and
+   community sharing. Create inventories for new or old networks and stations
+   from permanent or temporary deployments.
+   SMP provides inventories in :term:`SCML` format in multiple versions
+   which can be used without modification.
+
+
+Configuring inventory
+=====================
+
+Suppose that, by one of the methods above,
+we have it in a single file, :file:`inventory_CLL.xml`.
+This must be converted from StationXML to SeisComP XML.
+The resulting file goes into
+:file:`~/seiscomp/etc/inventory`.
+See the chapter on :ref:`concepts_inventory`.
+
+.. code:: bash
+
+   ~/seiscomp/bin/seiscomp exec import_inv  fdsnxml ~/inventory_CLL.xml
+   Generating output to /home/user/seiscomp/etc/inventory/inventory_CLL.xml
+   No inventory read from inventory db
+   Create empty one
+   Processing /home/user/inventory_CLL.xml
+    - parsing StationXML
+    - converting into SeisComP-XML
+   Finished processing
+   Writing inventory to /home/user/seiscomp/etc/inventory/inventory_CLL.xml
+
+When inventory is loaded, you will see your station in the results
+of :ref:`scinv` with the `ls` option:
+
+.. code-block:: sh
+
+    $ ~/seiscomp/bin/seiscomp exec scinv ls
+    WARNING: /home/user/seiscomp/etc/inventory/README ignored: wrong extension
+    [..]
+    Parsing /home/user/seiscomp/etc/inventory/MY.xml ... done
+    Parsing /home/user/seiscomp/etc/inventory/GE.xml ... done
+    [..]
+    Merging inventory ... done
+      network GR       German Regional Seismic Network, BGR Hannover
+        epoch 1976-02-17
+        station CLL    GRSN Station Collm
+          epoch 1993-04-01
+          location __
+            epoch 2007-02-07
+            channel BHE
+              epoch 2007-02-07
+            channel BHN
+              epoch 2007-02-07
+            channel BHZ
+              epoch 2007-02-07
+            channel HHE
+              epoch 2007-02-07
+
+This shows the networks, stations, and channels, and the time spans for
+which they are known.
+For active stations, there must be an epoch (time span) with a start date
+but no end date shown for the desired channel.
+
+The inventory is not yet synchronized with the database. To finalize
+inventory configuration, run::
+
+  $ seiscomp update-config
+
+.. warning::
+
+  If you get an error, make sure that MySQL/MariaDB is running and the
+  database has been created correctly (see :ref:`tutorials_postinstall`).
+
+
+Configuring for acquisition
+===========================
+
+If you've configured inventory above, you'll already have a top-level
+key file for the station in the :file:`~/seiscomp/etc/key` directory.
+
+- You will need to know the waveform source, channels to be acquired,
+  location code used, if any.
+  See :ref:`tutorials_waveforms` for the remaining details.
+
+
+Configuring processing
+======================
+
+Now you can enable the station for processing.
+Follow the :ref:`tutorials_processing` tutorial.
+
+
+Configuring for archiving
+=========================
+
+If you want to archive waveforms, consider how long they should be retained.
+See :ref:`tutorials_archiving` for how to do this.

share/doc/seiscomp/html/_sources/base/tutorials/archiving.rst.txt

@@ -0,0 +1,194 @@
+.. _tutorials_archiving:
+
+*******************************
+Set up local waveform archiving
+*******************************
+
+You will ...
+
+* Set up :ref:`slarchive` with its necessary bindings
+* Set up `purge_datafiles` in crontab
+
+Pre-requisites for this tutorial:
+
+* Have SeisComP installed
+* Tutorial on :ref:`adding a new station<tutorials_addstation>`
+* Tutorial on :ref:`real-time data acquisition<tutorials_geofon_waveforms>`
+  so that you have local data for GE stations.
+  Alternatively you may already obtain real-time waveform data from
+  somewhere else (see :ref:`tutorials_waveforms`).
+
+Afterwards/Results/Outcomes:
+
+* Save real-time data in a local archive for later processing.
+* See :term:`miniSEED` day files for GE stations in your local :ref:`waveform archive <concepts_waveformarchives>`.
+
+Time range estimate:
+
+* 5 minutes
+
+Related tutorial(s):
+
+* Tutorial on :ref:`tutorials_servefdsnws`
+* Tutorial on :ref:`tutorials_waveformplayback`
+
+----------
+
+**Motivation**:
+Without activating archiving, your local Seedlink server
+will only keep waveforms for a short time.
+This makes it hard to review old events, for example.
+
+In this example, we'll arrange for keeping waveforms for one week.
+Before starting, you'll need bindings for your stations;
+see the tutorials :ref:`tutorials_geofon_waveforms`
+or :ref:`tutorials_waveforms`.
+
+The :program:`slarchive` collects data and archives it
+locally using a :term:`SDS` file system structure of
+nested subdirectories and systematically named files.
+
+
+In scconfig
+===========
+
+#. Under the Modules tab, go to Acquisition, and select :program:`slarchive`.
+   Here you can see the default parameters used.
+   By default, :program:`slarchive` connects to your local Seedlink server,
+   and archives to your local disk.
+
+#. Under the System tab, select the line for :program:`slarchive`, and click
+   "Enable module(s)" button at the top.
+
+#. Under Bindings:
+   On RHS right-click "slarchive" to add an slarchive profile.
+   Name it 'week', to keep waveforms for 7 days, and click 'Ok'.
+   The new profile appears in the (bottom right corner of :program:`scconfig`.
+   Double click on the profile to open its settings.
+   Unlock the box labeled "keep", and change the default from 30 to 7.
+
+   Once you have a binding profile, drag it over all the stations it
+   should apply to, under "Networks" on the left-hand side of the
+   bindings tool.
+
+.. warning:: The name 'week' is just a label.
+   Its functionality comes from changing the value of the `keep` parameter.
+   Changing the *name* of a binding profile does not change its function.
+
+.. note:: You can also choose which channels should be archived,
+   using the ":confval:`selectors`" box.
+   For instance, you may collect data at several sample rates,
+   and only wish to archive the highest rate.
+   If you collect LH, BH, HH streams at 0.1, 20, and 100 samples
+   per second, respectively, you might retain only the HH streams,
+   by setting ":confval:`selectors`" to "HH".
+
+#. Then return to System, and click 'Update configuration'.
+   Make sure the :program:`slarchive` module, or no module, is selected.
+
+#. Restart :program:`slarchive`.
+
+#. Adjust the :ref:`concepts_RecordStream` for making use of the archived waveforms
+   from within a :term:`GUI` or automatic data processing modules.
+
+
+Command line
+============
+
+You will need to edit each of your top-level key files to refer to
+a new binding profile.
+e.g.::
+
+  $ cd ~/seiscomp/etc/key
+  $ vi station_GR_CLL
+
+Add the line `slarchive:week` to whatever lines are already there.
+Afterwards it will look something like this::
+
+  # Binding references
+  global:BH
+  scautopick:default
+  seedlink:geofon
+  slarchive:week
+
+Repeat this for the top-level key file of each station
+you wish this binding to apply to.
+Now create the binding profile in the key directory.
+This is a file with a name corresponding to the binding profile name; here: 'week' ::
+
+  $ cd ~/seiscomp/etc/key
+  $ mkdir slarchive
+  $ vi slarchive/profile_week
+  # Number of days the data is kept in the archive. This requires purge_datafile
+  # to be run as cronjob.
+  keep = 7
+
+  $ seiscomp enable slarchive
+  $ seiscomp update-config slarchive
+  $ seiscomp restart slarchive
+  slarchive is not running
+  starting slarchive
+
+.. note::
+
+   Left unattended, your disk will eventually fill up with archived data.
+   To prevent this you will need a script like `purge_database`,
+   which is provided with SeisComP.
+   This can be run once per day using the `cron` feature of your system.
+   The command::
+
+      $ seiscomp print crontab
+
+   will print a number of lines to the terminal.
+   Type `crontab -e` and insert these lines into the crontab file for your
+   user (typically `sysop`).
+   Exit your crontab editor.
+   Displaying your crontab should now show a line for `purge_database`.::
+
+     $ crontab -l
+     20 3 * * * /home/sysop/seiscomp/var/lib/slarchive/purge_datafiles >/dev/null 2>&1
+     [There may be other lines too.]
+
+   This shows you that the `purge_datafiles` script
+   will run every day at 3:20 a.m.
+
+.. note::
+
+  If you examine the `purge_datafiles` script, you will see that all it does
+  is look for files with a last modified time older than a certain number
+  of days ago.
+  The number of days to keep can be set station-by-station using the
+  ARCH_KEEP feature.
+  A convenient way to do this for many stations is with
+  multiple binding profiles, one for each length of time desired.
+
+
+Checking archiving is functioning
+=================================
+
+* If :program:`seedlink` is configured correctly, a new station's streams
+  appears in output from :program:`slinktool`::
+
+    $ slinktool -Q : | grep CLL
+    GR CLL      HHZ D 2020/04/01 01:11:57.6649  -  2020/04/01 07:28:49.0299
+    GR CLL      HHE D 2020/04/01 01:11:57.6649  -  2020/04/01 07:28:45.0299
+    GR CLL      HHN D 2020/04/01 01:11:57.6649  -  2020/04/01 07:28:39.2299
+
+  This shows three streams being acquired from station 'CLL'.
+  The second time shown is the time of the most recent data for each stream.
+
+* If :program:`slarchive` is configured correctly, waveform data for the
+  station appears in :program:`slarchive`'s SDS archive directory:
+
+   .. code-block:: sh
+
+      $ ls -l seiscomp/var/lib/archive/2020/GR/CLL
+      total 12
+      drwxr-xr-x 2 user user 4096 Apr  1 06:30 HHE.D
+      drwxr-xr-x 2 user user 4096 Apr  1 06:30 HHN.D
+      drwxr-xr-x 2 user user 4096 Apr  1 06:30 HHZ.D
+
+      $ ls -l seiscomp/var/lib/archive/2020/GR/CLL/HHZ.D/
+      total 12728
+      -rw-r--r-- 1 user user 5492224 Mar 31 00:04 GR.CLL..BHZ.D.2020.090
+      -rw-r--r-- 1 user user 7531008 Apr  1 00:03 GR.CLL..BHZ.D.2020.091

share/doc/seiscomp/html/_sources/base/tutorials/geofon_waveforms.rst.txt

@@ -0,0 +1,344 @@
+.. _tutorials_geofon_waveforms:
+
+**********************************
+Add real-time stations from GEOFON
+**********************************
+
+You will use :ref:`scconfig` to:
+
+* Add stations of the GEOFON seismic network, obtained from GEOFON,
+  as a source of data.
+* Configure bindings to see these in your local system.
+
+Pre-requisites for this tutorial:
+
+* :ref:`Installation<tutorials_postinstall>`
+
+Afterwards/Results/Outcomes:
+
+* :program:`slinktool -Q` locally shows GE streams are available
+* :ref:`scrttv` locally shows the GE station traces
+
+Time range estimate:
+
+* 10-15 minutes
+
+Related tutorial(s):
+
+* Tutorial on :ref:`tutorials_archiving`
+* Tutorial on :ref:`tutorials_servefdsnws`
+
+----------
+
+GEOFON operates a global broadband seismic network jointly with many
+partner institutions with focus on EuroMed and Indian Ocean regions.
+As of 2020, the network consists presently of 78 high-quality active stations,
+for which data is acquired in real-time.
+This network has been assigned the network code *GE* by the
+International Federation of Digital Seismograph Networks (FDSN).
+
+The GEOFON data centre in Potsdam provides real-time data feeds for these
+stations.
+This tutorial demonstrates how to use this data in your own SeisComP system.
+
+The steps involved are:
+
+* Download metadata for the stations of interest.
+* Import them into your SeisComP system, and create bindings.
+* View the stations and their traces in the SeisComP GUIs.
+
+
+Check data are available
+========================
+
+First, we'll query the upstream Seedlink server, which runs on
+host `geofon.gfz-potsdam.de` at port 18000.
+We do this with SeisComP's :ref:`slinktool` command, giving the ``-L`` option
+to :ref:`slinktool`
+
+.. code-block:: sh
+
+   $ slinktool -L geofon.gfz-potsdam.de
+   6C GF01  GF01
+   6C GF02  GF02
+   6C GF03  GF03
+   [..]
+   ZB URD20 URD20
+   ZB VAL41 VAL41
+   ZB VOS   VOS
+
+This is a long list.
+It shows the network code and station code of each
+of the stations for which data is available from this Seedlink server.
+We'll just be interested in a few stations, namely those corresponding
+to broadband 20 sps vertical channels - with channel code BHZ, and with network
+code GE
+
+.. code-block:: sh
+  
+   $ slinktool -Q geofon.gfz-potsdam.de | grep ^GE.*BHZ
+   GE ACRG     BHZ D 2019/11/28 06:51:48.7500  -  2019/11/28 09:18:32.1000
+   GE APE      BHZ D 2019/11/28 07:40:52.0400  -  2019/11/28 12:22:00.3950
+   GE ARPR     BHZ D 2019/11/27 23:23:27.4400  -  2019/11/28 09:41:22.1500
+   GE ARPR     BHZ E 2019/11/27 23:23:27.4400  -  2019/11/28 09:16:25.0400
+   [..]
+   GE KBS   00 BHZ D 2019/11/24 13:22:12.9695  -  2019/11/24 22:46:17.4195
+   GE KBS   10 BHZ D 2019/11/24 13:22:12.9695  -  2019/11/24 22:46:19.5945
+   GE KBU      BHZ D 2019/11/28 06:53:21.8450  -  2019/11/28 12:22:18.2450
+   [..]
+
+The '-Q' option provides a formatted stream list,
+with one line for each stream available from the server.
+The columns are described in :ref:`tutorials_waveforms`;
+the `grep` command here limits output to just those GE stations;
+without it, this server provides over 16000 lines of output.)
+
+For an active station, with low latency, the last data time (on the
+right) will typically be just a few seconds in the past.
+If a station or its network connection to the GEOFON server is down,
+then it will be a longer time ago.
+
+
+Download station metadata
+=========================
+
+There are several possible ways to obtain inventory.
+
+- Use WebDC3 [#WebDC]_ or network pages [#NETPAGES]_
+  to obtain metadata for existing seismic networks.
+
+- Other sources of inventory, like a dataless SEED file, can also be used.
+
+- The Gempa Station Management Portal, :cite:t:`smp`,
+  is another important source of station metadata.
+  If you would like to create your own inventory you may use this online tool.
+  Before doing so, you will need to create an account on SMP.
+
+
+Option 1: Using FDSN web services
+---------------------------------
+
+The FDSN web services :cite:p:`fdsn` are the standard adopted by the FDSN and have been
+deployed at almost every data centre.
+One of them is called  *fdsnws-station* and
+is the service to contact to get all information related to stations, sensors,
+responses, etc.
+
+To get data from the *fdsnws-station* web service you can use any web client (browser or command
+line). For instance, the *wget* command. The file you will receive will be in
+StationXML format.
+
+.. code-block:: sh
+
+   $ wget "http://geofon.gfz-potsdam.de/fdsnws/station/1/query?net=GE&level=response" -O ge.xml
+
+
+Option 2: Using WebDC3
+----------------------
+
+WebDC3 is a graphical interface which allows you not only to send requests to
+FDSN webservice servers, but also to explore available stations
+and query event catalogs
+from different data centres among other possibilities.
+
+You can find detailed information about WebDC3 in the on-line documentation at
+:cite:t:`webdc3-documentation`.
+
+* Go to http://eida.gfz-potsdam.de/webdc3 with a browser.
+
+* Click on "Explore stations" and move the slider to select only the current year
+  and only "Public permanent nets" on the Network type list.
+  Select the GE network, "All Stations", BH channels, and click "Search".
+
+* About 80 stations should appear on the map, and on the list below it.
+
+  .. figure:: media/geofon_webdc_stations.png
+     :width: 16cm
+     :align: center
+
+     Stations of the GE network shown in WebDC, ready for a metadata request.
+
+* Go to the third tab, named "Submit request".
+
+* Click on "Absolute Mode" for the "Time Window Selection" and select time
+  window from some time ago to the present.
+
+* In the "Request type" section, click on "Metadata (StationXML)".
+  Set "Metadata level" to "Response".
+  **Response-level inventory is essential for SeisComP configuration**.
+
+* For metadata requests, no token should be required.
+  (This is only used for requests for restricted waveform data.)
+
+* If everything looks correctly click on "Submit".
+
+* Go to the fourth tab, called "Download Data".
+
+* In the "FDSNWS Requests" block, click on "Save" to mkae your request
+  to the GEOFON fdsnws-station web service.
+
+* When it's ready, you will be prompted to save an XML file to your local computer.
+
+Now find where your web browser has saved the file.
+
+
+Import the inventory
+====================
+
+It is easiest to use the import function of the :ref:`scconfig` GUI.
+Alternatively, you can import from the command line:
+
+* From FDSN StationXML:
+
+  .. code-block:: sh
+
+     $ fdsnxml2inv -f station.xml > etc/inventory/mynetwork.xml
+
+* From SeisComP XML with filtering:
+
+  .. code-block:: sh
+
+     $ invextr -f --chans 'NE.STA.*' mynetwork.xml > etc/inventory/mynetwork.xml
+
+Either way, afterwards, inventory is in :file:`~/seiscomp/etc/inventory`.
+It now needs to be loaded in to the SeisComP database.
+
+Import the metadata for your stations
+-------------------------------------
+
+* Open :ref:`scconfig` from the terminal.
+  Click on the "Inventory" tab on the left side bar.
+
+* Select "Import" and at "Source:", browse to the file with the inventory
+  (e.g. ~/Downloads/inventory.xml).
+  For "format", select "fdsnxml".
+
+  .. figure:: media/geofon_waveforms_old_fig5.png
+     :width: 16cm
+     :align: center
+
+     The Inventory tab of :ref:`scconfig`, during import of FDSN Station XML.
+     *TODO* Update this figure.
+
+* Click on OK, wait a couple of seconds, check that the process was successful -
+  it should display
+  "Writing inventory to /home/sysop/seiscomp/etc/inventory/{PACKAGE NAME}.xml"
+  and "Program exited normally" at the bottom.
+  Close the modal window.
+
+* Sync or Sync keys.
+  Make sure :ref:`scmaster` and Spread are running.
+  SeisComP reads the inventory files in :file:`~/seiscomp/etc/inventory`
+  and loads them into the database.
+  You will see messages like "Sending notifiers: 2%" as this occurs.
+  Eventually you should see "Program exited normally" again.
+
+Alternatively, go to "System" (second icon in the left column),
+click on "Update configuration" and restart SeisComP (Stop and Start buttons).
+
+
+Configure bindings
+==================
+
+As for individual stations (see the :ref:`processing tutoriual <tutorials_processing>`),
+we will need to create bindings for every GE station to the
+"global", "scautopick" and "seedlink" applications, as follows:
+
+
+* Create a global profile named "BH" by clicking with the right button on "global"
+  in the top right panel. Double click on it and set BH as *detectStream* and
+  empty location code as *detecLocID* information.
+
+  .. figure:: media/geofon_waveforms_old_fig6.png
+     :width: 16cm
+     :align: center
+
+     The "Bindings" tab in :ref:`scconfig`.
+     A profile for global, called "BH" is being created.
+
+     *TODO* CX stations are visible too.
+
+* Create a *scautopick* profile named "default" (no changes necessary).
+
+* Create a *seedlink* profile named "geofon". Double click on the profile.
+  Add a chain source with the green plus button on the left
+  (no other changes are necessary for data from GEOFON's server,
+  as it is the default).
+
+* Drag and drop all profiles from the right side to the network icon on the
+  left side (you may do that also at the station level).
+
+* Press Ctrl+S to save the configuration.
+  This writes configuration files in :file:`~/seiscomp/etc/key`.
+
+.. note::
+
+   A few GEOFON stations (including KBS, LVC, SUMG) are distributed
+   with a non-blank location code, typically either "00" or "10".
+   Configuring these requires additional work.
+   You can create a profile setting :confval:`detecLocID` to "10",
+   called "10BHZ", and apply this to the appropriate stations.
+   Repeat this for stations where location code "00" is desired (e.g. SFJD).
+
+
+Update the configuration
+========================
+
+The SeisComP database must be updated with the inventory and bindings.
+SeisComP's modules then require restarting to load the updated information.
+
+* Go to the System tab and press ESC (the Escape key, to de-select all modules).
+
+  #. Click on "Update configuration", at the right of the window.
+     (**Not** "Update", - that just refreshes :ref:`scconfig`'s
+     display of what is running!)
+  #. Press *Start* to start acquiring data from the already configured stations.
+
+* Alternatively, on the command line
+
+  .. code-block:: sh
+
+     $ seiscomp update-config
+     $ seiscomp restart
+
+
+Check it works
+==============
+
+* To confirm that you have waveform data for the station locally,
+  run :ref:`slinktool`.
+
+  .. code-block:: sh
+   
+     $ slinktool -Q
+
+* Open :ref:`scmv` to see a map view of the configured stations.
+* Open :ref:`scrttv` to see the incoming real-time streams.
+
+If you see colored triangles and traces incoming it means that
+you have configured your system properly.
+With this last step the configuration of these stations is considered to be finished.
+
+
+Further steps
+=============
+
+At this point,
+you can follow the same procedure for other networks/stations, provided you
+
+#. Have metadata available.
+#. Know the location of a Seedlink server for, and have access to, the waveforms.
+
+
+References
+==========
+
+.. target-notes::
+
+.. [#WebDC] The WebDC3 service is available at http://eida.gfz-potsdam.de.
+            See also
+            M. Bianchi, *et al.* (2015): WebDC3 Web Interface. GFZ Data Services.
+            doi:`10.5880/GFZ.2.4/2016.001 <http://dx.doi.org/10.5880/GFZ.2.4/2016.001>`_
+
+.. [#NETPAGES] For instance that of the GEOFON Program, at
+               https://geofon.gfz-potsdam.de/waveform/archive/network.php?ncode=GE.

share/doc/seiscomp/html/_sources/base/tutorials/help.rst.txt

@@ -0,0 +1,314 @@
+.. _tutorials_help:
+
+**************************
+Help! I'm stuck! Now what?
+**************************
+
+You will ...
+
+* Troubleshoot and resolve problems with SeisComP
+
+Pre-requisites for this tutorial:
+
+* Have your SeisComP installation and configuration available
+
+Afterwards/Results/Outcomes:
+
+* Improved understanding of ways to solve issues when operating SeisComP
+
+Time range estimate:
+
+* 30 minutes
+
+----------
+
+
+Outline
+=======
+
+Inevitably you will encounter difficulties using SeisComP.
+This tutorial reviews a few ways to diagnose your problems and
+get help to resolve them:
+
+* Detailed :ref:`HTML documentation <sec_tutorial_help_documentation>`
+* :ref:`Commandline help <sec_tutorial_help_commandline>`
+* The :ref:`SeisComP Forum <sec_tutorial_help_forum>`
+* Reviewing :ref:`logging options <sec_tutorial_help_logging>`
+* The :ref:`debugging options <sec_tutorial_help_debugging>`
+* :ref:`Commercial support <sec_tutorial_help_commercial>`
+
+
+Ways to diagnose and to get help
+================================
+
+
+.. _sec_tutorial_help_documentation:
+
+HTML documentation
+------------------
+
+Most modules have HTML documentation. When installed, it can be found in :ref:`scconfig`
+under *Docs*. The HTML documentation can also be reached from the *Help*  menu of all GUIs.
+It contains the description of configuration and command-line parameters along with
+an overview with many detailed information.
+
+.. figure:: media/gui_help.png
+   :width: 16cm
+   :align: center
+
+   :ref:`scmv` with access to the HTML documentation.
+
+The description of most configuration parameters is also available from
+within :ref:`scconfig`.
+Look under *Modules*, and choose the relevant module.
+For each parameter, the first few lines of description are shown;
+hovering over these reveals the full text.
+
+The HTML documentation is built regularly and available online, e.g.
+`gempa's documentation <https://docs.gempa.de>`_.
+
+
+.. _sec_tutorial_help_commandline:
+
+Commandline help
+----------------
+
+In addition to the HTML documentation, many SeisComP commands have manual
+pages which can be read on the command line:
+
+.. code-block:: sh
+
+   $ man [module name]
+
+and help on command-line options:
+
+.. code-block:: sh
+
+   $ [module name] -h
+
+.. note::
+
+   The command-line option *-h* can be used with almost all modules. No matter how many
+   other command-line parameters were given, *-h* will stop the module and print
+   the help on the command-line.
+
+
+.. _sec_tutorial_help_config-params:
+
+Configuration parameters
+------------------------
+
+The :ref:`scconfig` GUI tool can be conveniently used to adjust the :term:`module`
+and :term:`bindings <binding>` configuration. It also displays help on each individual
+configuration parameter for every module. Read the :ref:`concepts
+section on configuration <concepts_configuration>` for a comprehensive overview.
+
+
+.. raw:: html
+
+  <div class="two column layout">
+
+.. figure:: media/scconfig-tooltips.png
+  :alt: scconfig: tool tips
+
+  Tool tips provide information on parameters.
+
+.. figure:: media/scconfig-evaluation.png
+  :alt: scconfig: parameter evaluation
+
+  scconfig evaluates the syntax of input values.
+
+.. raw:: html
+
+  </div>
+
+
+.. _sec_tutorial_help_cmdline-params:
+
+Command-line parameters
+-----------------------
+
+Command-line parameters provide additional flexibility when executing modules.
+To learn about them read the :ref:`sec_tutorial_help_documentation` or execute
+
+.. code-block:: sh
+
+   $ [module name] -h
+
+
+.. _sec_tutorial_help_forum:
+
+The SeisComP Forum
+------------------
+
+.. figure:: media/help_forum.png
+   :width: 16cm
+   :align: center
+
+   The :cite:t:`seiscomp-forum`.
+
+The :cite:t:`seiscomp-forum` is the place to discuss |scname|.
+Announcements about updates, training courses and more are posted
+here by the developers, and users can post questions or discuss
+new developments.
+Anyone can browse the forum, while registration is required to post there.
+
+If you have specific technical problems, it helps to have tried
+some of the ideas below.
+Please include version information (the '-V' option described below)
+if you report a problem.
+
+
+.. _sec_tutorial_help_logging:
+
+Logging
+-------
+
+Most SeisComP applications use a standard logging approach.
+By default, they log to files in your :file:`~/.seiscomp/log` directory,
+such as :file:`scamp.log`.
+Further options for logging are described in
+:ref:`concepts_configuration`.
+
+You can control how often these are rotated
+(old log files are closed, and moved to a new file name, such as scamp.log.1, e.g. daily).
+Alternatively you can use the system-wide logging facility `syslog`
+and send logs to /var/log or another "standard" place.
+
+There are four levels of severity of SeisComP log messages,
+and applications can be configured to show only those which
+are more severe than a given threshold.
+
+* 1 = ERROR
+* 2 = WARNING
+* 3 = INFO
+* 4 = DEBUG.
+
+Default is 2.
+Setting `logging.level = 4` results in the most messages.
+
+For other modules such as :ref:`seedlink`, the log files are written to
+:file:`seiscomp/var/log/`
+
+
+.. _sec_tutorial_help_debugging:
+
+Debugging options
+-----------------
+
+Most SeisComP applications support two important command line options:
+
+* Use `--console` to send output to the terminal instead of the usual
+  log location.
+
+* `-v` for increased verbosity, or use `--verbosity=` *n* where *n*
+  is one of the four severity levels above.
+
+In addition:
+
+* `--debug` sets logging.level (see above) to 4 (DEBUG),
+  and sends logging output to the console (terminal) instead of the usual
+  log location.
+  (This is just an easier way of specifying `--verbosity=4 --console=1`.)
+  For example:
+
+  .. code-block:: sh
+
+     $ ~/seiscomp/bin/seiscomp exec scmag --debug
+     11:47:50 [debug] Adding plugin path: .
+     11:47:50 [debug] Adding plugin path: /home/user/.seiscomp/plugins
+     11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib/plugins
+     11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib
+     11:47:50 [debug] Adding plugin path: /home/user/seiscomp/share/plugins
+     11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib
+     11:47:50 [debug] Adding plugin path: /home/user/seiscomp/lib
+     11:47:50 [debug] Adding plugin path: /home/user/seiscomp/share/plugins/scmag
+     11:47:50 [debug] Trying to open plugin at /home/user/seiscomp/share/plugins/dbmysql.so
+     11:47:50 [info] Plugin dbmysql registered
+     11:47:50 [info]
+     Plugins:
+     --------
+      [1]
+       description: MySQL database driver
+            author: GFZ Potsdam <seiscomp-devel@gfz-potsdam.de>
+           version: 0.9.2
+               API: 12.1.0
+
+     11:47:50 [info] Connect to messaging
+     11:47:50 [debug] Trying to connect to scmag@localhost with primary group = MAGNITUDE
+     11:47:50 [info] Connecting to server: localhost
+     11:47:50 [info] Connected to message server: localhost
+     11:47:50 [info] Joining MASTER_GROUP group
+     11:47:50 [info] Sending connect message to server: localhost
+     11:47:51 [info] Server version is 'Jakarta 2018.327.p15'
+     11:47:51 [info] Outgoing messages are encoded to match schema version 0.11
+     11:47:51 [info] user "scmag" connected successfully to localhost
+
+  The above reveals that :program:`scmag` was able to load, and connect to the
+  messaging system.
+  Note that the *verbosity* of each message ("info", "debug", etc) is also
+  shown.
+  However a moment later we see:
+
+  .. code-block:: sh
+
+     11:47:51 [info] Connect to database
+     11:47:51 [debug] skipping unknown network message
+     11:47:51 [debug] skipping unknown network message
+     11:47:51 [debug] skipping unknown network message
+     11:47:56 [error] Timeout while waiting for database provide message
+     11:47:56 [debug] Leaving ::done
+     11:47:56 [info] Shutting down MagTool
+     - database accesses while runtime: 0
+
+  This suggests that :ref:`scmaster` was not running to provide a
+  connection to the database.
+  To resolve this, you could next check that :ref:`scmaster` is
+  running as expected.
+
+.. note::
+
+   Instead of `--debug` in the example above, you could run
+
+   .. code-block:: sh
+
+      $ ~/seiscomp/bin/seiscomp exec scmag -vvvv
+
+   The output is the same, but it is sent to your normal logging file,
+   typically `~/.seiscomp/log/scmag.log`.
+
+In :ref:`scconfig`, logging can be set globally.
+Go to the Modules tab, then System > global (see "logging")
+or per module.
+
+e.g. set "logging.level = 3" in $SEISCOMP_ROOT/etc/scamp.log
+to set level to *INFO* only for :ref:`scamp`.
+
+You should also be aware of the version of SeisComP that you are running.
+The '-V' or '--version' option provides this for many SeisComP modules.
+
+.. code-block:: sh
+
+   $ ~/seiscomp3/bin/seiscomp exec scmag -V
+   scmag: Jakarta 2018.327.p15
+   API version: 12.1.0
+   GIT HEAD:
+   Compiler: c++ (Ubuntu 7.3.0-16ubuntu3) 7.3.0
+   Build system: Linux 4.15.0-20-generic
+   OS: Ubuntu 18.04 LTS / Linux
+
+
+.. _sec_tutorial_help_commercial:
+
+Commercial support
+------------------
+
+Professional commercial support to SeisComP users is available from
+:cite:t:`gempa`.
+
+
+Next time you have a problem
+============================
+
+* Try some of the above techniques.
+* If you find a solution, don't forget to share it at the :cite:t:`seiscomp-forum`.

share/doc/seiscomp/html/_sources/base/tutorials/magnitude-regionalization.rst.txt

@@ -0,0 +1,278 @@
+.. _tutorials_magnitude-region-aliases:
+
+****************************************
+Magnitudes: Regionalization, Aliases, Mw
+****************************************
+
+You will ...
+
+* Regionalize magnitude
+* Create new magnitude types as aliases from other magnitudes and amplitudes.
+* Map magnitudes to the moment magnitude, Mw
+
+
+:Pre-requisites for this tutorial:
+
+  * Read the :ref:`concepts section on magnitudes <concepts_magnitudes>`.
+  * Real-time data for the station must be available locally.
+    See :ref:`tutorials_waveforms` or :ref:`tutorials_geofon_waveforms`.
+  * Inventory must be loaded locally.
+
+
+:Afterwards/Results/Outcomes:
+
+  * Regionalized magnitudes,
+  * New magnitude types as aliases.
+  * Moment magnitudes
+
+
+:Time range estimate:
+
+  * 30 minutes
+
+
+-----------
+
+
+.. _tutorials_magnitude-region:
+
+Regionalize Magnitudes
+======================
+
+By regionalization, magnitudes can be computed with region-dependent properties.
+The procedure to set up magnitude regionalization is:
+
+#. Create one file which contains the polygons surrounding the regions within
+   which magnitude parameters shall apply. The polygon files are provided in
+   :ref:`BNA <sec-gui_layers-vector-format-bna>` or
+   :ref:`GeoJSON format <sec-gui_layers-vector-format-geojson>` and located as
+   set out in the :ref:`documentation of map layers <sec-gui_layers>`. The file
+   can be created from any |scname| GUI application providing maps, e.g.,
+   :ref:`scmv`.
+#. For the desired magnitude type create a magnitude-type profile in global
+   module configuration. The name of the profile matches the name of the
+   magnitude, e.g., *MLc* for the :ref:`MLc magnitude <global_mlc>`.
+#. Configure the :confval:`magnitudes.MLc.regionFile` parameter with the full
+   path and name of the polygon file created above.
+#. Within the magnitude-type profile create one or more magnitude-region
+   profile(s) for defining the regionalized parameters applied to the region(s).
+   The name of a profile corresponds to the name of the polygon contained in the
+   polygon file to which the parameters shall apply. Use *world* for all regions
+   not covered by any polygon.
+#. Configure the regionalized magnitude parameters of the magnitude-region
+   profile. Activate the *enable* parameter if you wish to apply this profile.
+#. Restart the data processing:
+
+   .. code-block:: sh
+
+      seiscomp restart
+
+   or execute a GUI module.
+
+.. important::
+
+   * Parameters which can be configured along with regionalization assume
+     defaults from global binding parameters but override global bindings
+     parameters when configured.
+   * Once regionalization is active, magnitudes for events outside the
+     defined region(s) will not be computed. For considering such events add
+     another magnitude-region profile with the name "*world*".
+     Magnitudes for events outside any other magnitude-region profile will then
+     be computed according to this profile.
+
+
+Station corrections
+-------------------
+
+:ref:`Magnitude station corrections <concepts-magnitudes-correction>` can also
+be applied in case of regionalization. Simply add the names of the
+magnitude-region profile along with the correction parameter to the original
+parameter in global module configuration, :file:`global.cfg`, for the respective
+magnitude type and station. Use comma separation for multiple regions and colon
+for separating the region name from the value.
+
+Example for correcting MLv computed at station GE.UGM:
+
+.. code-block:: properties
+
+   module.trunk.GE.UGM.magnitudes.MLv.offset = 0.1, europe:0.2, asia:-0.1
+
+.. note::
+
+   The configuration of parameters starting with *module.trunk.* is not
+   supported by :ref:`scconfig`. All corresponding configurations must be done
+   by directly editing the configuration file, e.g.,
+   :file:`seiscomp/etc/global.cfg`.
+
+
+.. _tutorials_magnitude-aliases:
+
+Magnitude Aliases
+=================
+
+New magnitude types (aliases) can be created based on existing magnitude and
+amplitude types but configured specifically.
+
+The procedure to set up magnitude aliases is:
+
+#. Create a magnitude alias in :file:`global.cfg` by configuring
+   :confval:`magnitudes.aliases`. Example:
+
+   .. code-block:: properties
+
+      magnitudes.aliases = MLc1:MLc:MLc
+
+#. Configure the alias magnitudes in either way:
+
+   * Write bindings parameters to global module configuration or
+   * Set up :ref:`regionalization <tutorials_magnitude-region>`:
+
+   **Binding parameters in global module configuration:**
+
+   #. Read the relevant parameter names of the original magnitude from global
+      binding, e.g., in :ref:`scconfig`. The names must include the full
+      hierarchy including all sections. Example:
+
+      .. code-block:: properties
+
+         magnitudes.MLc01.parametric.c1
+
+   #. Open the module configuration file, e.g.,
+      :file:`seiscomp/etc/global.cfg` in a text editor.
+
+   #. Prepend *module.trunk.global.* to the parameter name and add it along with
+      its value to the configuration file. Example:
+
+      .. code-block:: properties
+
+         module.trunk.global.magnitudes.MLc01.parametric.c1 = 0.7
+
+   #. Add the new magnitude name to the configuration of all relevant modules,
+      e.g., :ref:`scamp`, :ref:`scmag`, :ref:`scevent`, :ref:`scolv`.
+
+   .. note::
+
+      The parameters starting with *module.trunk.* are not available for
+      configuration in :ref:`scconfig`.
+
+   .. warning::
+
+      Binding parameters configured in global module configuration should only
+      be considered exceptionally. These parameters will
+
+      * Override the corresponding parameters configured by regionalization
+        using the region *world*.
+      * Not be written to the database and cannot be accessed by SeisComP
+        modules running on other computers.
+
+   **Regionalization:**
+
+   * Consider the tutorial on
+     :ref:`magnitude regionalization <tutorials_magnitude-region>` above.
+   * For the name of the new magnitude-type profile now use the alias name.
+
+     .. hint::
+
+        When adding the magnitude-region profile in
+        :ref:`scconfig`, scconfig does not know about the referenced original
+        magnitude. Therefore, not all possible configuration parameters may be
+        listed depending on the magnitude, e.g. for MLc. For getting the full
+        list, first create and configure a magnitude-region profile for the
+        referenced magnitude.
+
+        #. Close scconfig
+        #. Open the configuration file :file:`global.cfg`
+        #. Rename the name of the referenced magnitude in the parameters to the
+           name of the alias.
+
+
+.. _tutorials_mags_moment:
+
+Moment Magnitudes
+=================
+
+All magnitudes, Mx, can be mapped to a moment magnitude, Mw(Mx).
+The configuration procedure is:
+
+#. Set up a magnitude-type profile for the original magnitude type in global
+   module configuration. Use :ref:`scconfig` for creating the profile.
+#. Configure the parameter *MwMapping*, which will become available along with
+   the new profile, e.g., :confval:`magnitudes.MLc.MwMapping`. Alternatively,
+   add the parameter to :file:`seiscomp/etc/global.cfg`. The parameter is
+   configured as a list of sample points of a piecewise linear function mapping
+   from the original magnitude, Mx, to Mw(Mx).
+   Example for Mw(MLc) based on MLc:
+
+
+   .. code-block:: properties
+
+      magnitudes.MLc.MwMapping = MLc_0:Mw(MLc)_0,MLc_1:Mw(MLc)_1,...,MLc_N:Mw(MLc)_N
+
+   Any magnitude value outside the configured range is ignored.
+
+   .. warning::
+
+      Do not map the magnitudes :term:`mB <magnitude, broadband body-wave (mB)>`
+      and :term:`Mwp <magnitude, broadband P-wave moment (Mwp)>` to Mw since
+      this is hardcoded already and done automatically by :ref:`scmag`.
+
+The new moment magnitudes will be available along with the original magnitudes
+and can be viewed in :ref:`scolv`or :ref:`scesv` and considered by :ref:`scmag`
+or :ref:`scevent`.
+
+In order to avoid that :ref:`summary magnitudes <concepts-magnitudes-summary>`
+are computed from original magnitudes and mapped Mw together and biased to both,
+the original magnitudes can be blocklisted in :ref:`scmag`
+(:confval:`summaryMagnitude.blacklist`).
+
+
+.. _tutorials_mags_regionalize_testing:
+
+Final Tests
+===========
+
+* Regionalization:
+
+  #. Start :ref:`scolv` with the option :option:`--debug` and load an event of
+     interest
+
+     .. code-block:: sh
+
+        scolv --debug
+
+  #. Relocate the event for generating a new origin.
+  #. Compute magnitudes selecting the magnitude of interest.
+  #. Inspect the computed magnitudes in the
+     :ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
+     debug output listing the considered magnitudes and stations along with
+     the regionalized parameters.
+
+* Magnitude aliases:
+
+  #. Start :ref:`scolv` with the option :option:`--debug` and load an event of
+     interest
+
+     .. code-block:: sh
+
+        scolv --debug
+
+  #. Relocate the event for generating a new origin.
+  #. Compute magnitudes selecting the magnitude of interest including the new
+     alias.
+  #. Inspect the computed magnitudes in the
+     :ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
+     debug output listing the considered magnitude names and aliases along with
+     the considered parameters and their values. Example where MLc1 is derived
+     from MLc with a modified maximum depth:
+
+     .. code-block:: sh
+
+        ...
+        13:30:46 [debug] GE.UGM: MLc1: effective correction (no locale) = 1.00:0.00
+        13:30:46 [debug] Parameters for magnitude MLc1
+        13:30:46 [debug]   + maximum depth: 50.000 km
+        13:30:46 [debug]   + distance mode: hypocentral
+        13:30:46 [debug]   + minimum distance: -1.000 km
+        13:30:46 [debug]   + maximum distance: 889.561 km
+        ...
+

share/doc/seiscomp/html/_sources/base/tutorials/postinstall.rst.txt

@@ -0,0 +1,352 @@
+.. _tutorials_postinstall:
+
+**********************
+Installation on Ubuntu
+**********************
+
+You will ...
+
+* Make a basic |scname| installation
+
+Pre-requisites for this tutorial:
+
+* Internet access
+
+Afterwards/Results/Outcomes:
+
+* Run a |scname| executable
+* Run a |scname| GUI program
+
+Time range estimate:
+
+* 10-15 minutes
+
+Related tutorial(s):
+
+* :ref:`tutorials_upgrade`
+* :ref:`tutorials_addstation`
+* :ref:`tutorials_geofon_waveforms`
+
+------------
+
+You may install |scname| by:
+
+#. :ref:`Compiling the source code <tutorials_postinstall_compile>`,
+#. :ref:`Installing pre-compiled release packages <tutorials_postinstall_package>`
+   including binaries, maps and documentation.
+
+
+Get your Linux System ready
+===========================
+
+First you need to get your Linux system ready.
+The following documentation refers to Ubuntu 20.04,
+but the steps for other Ubuntu versions are similar.
+
+#. Add a new user. Throughout our documentation, this user is called `sysop`.
+
+   .. code-block:: sh
+
+      $ sudo adduser sysop
+      $ sudo addgroup admin
+      $ sudo usermod -a -G admin,adm,audio sysop
+
+   .. note:
+
+      Adding a new user is not mandatory. You can install under an existing user
+      directory. Creating a new user is recommended as it allows an easy cleanup
+      of the system later simply by removing the new user if needed.
+
+#. Check the size and the architecture. This is espcially required when installing
+   :ref:`pre-compiled packages<tutorials_postinstall_package>`: ::
+
+     $ df -h
+     $ cat /etc/issue
+     $ uname -m
+
+   Compare the available disk space with the requirements given in
+   the :ref:`installation` section.
+   If 'uname' shows 'i686', you have a 32-bit system;
+   if you see 'x86_64', you have 64-bit.
+
+
+.. _tutorials_postinstall_compile:
+
+Install from source code
+========================
+
+To compile SeisComP from the source code follow the
+:ref:`instructions in the development section <build>`. You may later download and add
+maps as described below in the :ref:`package section <tutorials_postinstall_package>`.
+
+
+.. _tutorials_postinstall_package:
+
+Install pre-compiled release packages
+=====================================
+
+You may download and installed pre-compile SeisComP binary package, maps and documentation.
+
+#. Download the appropriate |scname| binary package taking into
+   account your Linux distribution and the architecture.
+   Get the package from the download site of |scname| :cite:p:`seiscomp` or from
+   :cite:t:`gempa-download`. Packages are available for Ubuntu and other Linux
+   flavors such as RHEL/CentOS and Debian.
+
+#. When downloading the |scname| binary packages you should also download
+
+   * maps for |scname|
+     
+     .. code-block:: sh
+   
+        wget "https://www.seiscomp.de/downloader/seiscomp-maps.tar.gz"
+
+   * the documentation package. Make sure, the documentation matches your
+     SeisComP version.
+
+     .. note::
+
+        The |scname| packages received from gempa GmbH contain the documentation
+        for the respective version and no separate download is required.
+
+#. Untar the :file:`seiscomp*` files (binary package, maps and documentation)
+   you will find in your home or downloads directory. For SeisComP in version
+   4.0.0 this is:
+
+   .. code-block:: sh
+
+      $ cd
+      $ tar xzf seiscomp-4.0.0-ubuntu20.04-x86_64.tar.gz
+      $ tar xzf seiscomp-maps.tar.gz
+      $ tar xzf seiscomp-4.0.0-doc.tar.gz
+      $ ls seiscomp
+      bin  etc  include  lib  man  sbin  share
+
+#. Install all dependencies needed and prepare the environment.
+
+   * This should be automatic for most distributions.
+     Simply run the install script
+     
+     .. code-block:: sh
+
+        $ ~/seiscomp/bin/seiscomp install-deps base
+        Distribution: Ubuntu 20.04
+
+     This will generally prompt for your user's password to allow `sudo` to
+     install packages on your system.
+
+   * On Ubuntu 18, Python 3 is installed, but not Python.
+     Get it first
+     
+     .. code-block:: sh
+
+        $ sudo apt-get install python libqtgui4
+
+   * On Ubuntu 20 and newer, you may need libpython3-dev before you can use
+     "install-deps"
+
+     
+     .. code-block:: sh
+
+        $ sudo apt-get install libpython3-dev
+
+   * Alternatively, for Mint 18 (Ubuntu 16.04):
+
+     .. code-block:: bash
+
+        $ sudo apt-get update
+        $ sudo apt-get install libxml2 libboost-filesystem1.58.0
+        libboost-iostreams1.58.0 libboost-thread1.58.0 libboost-program-options1.58.0
+        libboost-regex1.58.0 libboost-signals1.58.0 libboost-system1.58.0 libssl1.0.0
+        libncurses5 libmysqlclient20 libpq5 libpython2.7 python-numpy mysql-server
+        mysql-client libqtgui4 libqt4-xml libqt4-opengl libqt4-sql-sqlite
+
+
+#. Database. For a MariaDB installation:
+
+   .. code-block:: sh
+
+      $ seiscomp install-deps mariadb-server
+
+   or a MySQL installation:
+
+   .. code-block:: sh
+
+      $ seiscomp install-deps mysql-server
+
+   Also, for better performance with a MariaDB/MySQL database,
+   adjust the memory pool size and the restart MariaDB/MySQL server, as described
+   in the :ref:`database_configuration` section.
+
+   For PostgreSQL, also see the detailed :ref:`installation` instructions.
+
+   .. warning ::
+
+      For Ubuntu 18.04 and newer, take care with MariaDB/MySQL installation.
+      Before the next step, you must set a root password *for MariaDB/MySQL*
+      (not the Linux root password!).
+
+      MariaDB:
+
+      .. code-block:: sh
+
+         $ sudo mysql -e "SET old_passwords=0; ALTER USER root@localhost IDENTIFIED BY 'MyNewPassword'; FLUSH PRIVILEGES;"
+
+      MySQL:
+
+      .. code-block:: sh
+
+         $ sudo mysql -e "ALTER USER root@localhost IDENTIFIED WITH mysql_native_password BY 'MyNewPassword'; FLUSH PRIVILEGES;"
+
+      Substitute *MyNewPassword* by your own password and remember it --
+      you will need it in the next step.
+      In case of problems, search the Internet, or the
+      `SeisComP forum thread <https://forum.seiscomp.de/t/upgraded-to-ubuntu-18-04-and-i-broke-my-seiscomp3/1139>`_
+      (for logged-in forum members).
+
+
+Configuration
+=============
+
+Find a detailed description in section :ref:`getting-started` and short guide below.
+
+#. You may set some system environment variables.
+   For bash users, print the environment variables and copy them to your
+   :file:`.bashrc`
+
+   .. code-block:: sh
+
+      $ ~/seiscomp/bin/seiscomp print env
+      export SEISCOMP_ROOT=/home/sysop/seiscomp
+      export PATH=/home/sysop/seiscomp/bin:$PATH
+      export LD_LIBRARY_PATH=/home/sysop/seiscomp/lib:$LD_LIBRARY_PATH
+      export PYTHONPATH=/home/sysop/seiscomp/lib/python:$PYTHONPATH
+      export MANPATH=/home/sysop/seiscomp/share/man:$MANPATH
+      export LC_ALL=C
+      source /home/sysop/seiscomp/share/shell-completion/seiscomp.bash
+
+   The path to your home directory will likely differ from `/home/sysop` as shown above.
+   Therefore, do not copy and paste what you see here but use for your own
+   system the output from the command
+
+   .. code-block:: sh
+   
+      ~/seiscomp/bin/seiscomp print env
+   
+   Add the output from the command to your file :file:`~/.bashrc`
+
+   .. code-block:: sh
+
+      $ vi ~/.bashrc
+
+   Then reload the content of :file:`~/.bashrc` in your current environment
+
+   .. code-block:: sh
+
+      $ source ~/.bashrc
+
+   After this, you won't have to type `~/seiscomp/bin/seiscomp` as
+   the :ref:`seiscomp` command will be added to your shell's path.
+
+   .. hint::
+
+      If, when you attempt to run a SeisComP command such as :ref:`scconfig` or
+      :ref:`scolv`, you receive an error message like 
+
+      .. code-block:: sh
+
+         scconfig: command not found
+
+      then the most likely explanation is that you have not set your SeisComP
+      environment variables correctly.
+
+      Run the `seiscomp` command with the full path to
+      where you installed.
+      The seven lines of output are not actually run by the 'seiscomp print env'
+      command; you need to cut and paste them into your shell to run them.
+      You can also add these to your :file:`~/.bashrc`, :file:`~/.profile`,
+      or equivalent file with commands to be run every time you log in.
+
+#. Run `seiscomp setup` and enter your preferred IDs and password. For the other
+   fields, you can always accept the default values.
+
+   .. code-block:: sh
+
+      $ seiscomp setup
+
+   You should enter an appropriate short name (without spaces) for Agency ID and
+   Datacenter ID. These are used for Arclink and Seedlink, and in the information
+   describing data model objects such as origins and events.
+
+#. The `seiscomp` command is a wrapper, which controls the SeisComP modules.
+   See :ref:`system-management`.
+   Run something by typing seiscomp followed by a command
+
+   .. code-block:: sh
+
+      $ seiscomp help
+      Available commands:
+       install-deps
+       setup
+       shell
+       enable
+       disable
+       print
+       help
+
+     Use 'help [command]' to get more help about a command
+
+#. Start :ref:`scmaster`.
+   As described in the :ref:`overview`, these are needed for
+   communication between the SeisComP database and the individual
+   SeisComP modules.
+
+   .. code-block:: sh
+
+      $ seiscomp start scmaster
+      starting scmaster
+
+#. Install all dependencies needed for the GUI
+
+   .. code-block:: sh
+
+      $ seiscomp install-deps gui
+
+#. Start the :ref:`scconfig` GUI
+
+   .. code-block:: sh
+
+      $ seiscomp exec scconfig
+
+   Learn more about :ref:`scconfig` in this documentation.
+   You should see a screen/window like this.
+
+   .. figure:: media/postinstall_scconfig.png
+      :width: 16cm
+      :align: center
+
+      First view of :ref:`scconfig` configurator.
+
+#. Run :ref:`scrttv`
+
+   .. code-block:: sh
+
+      $ seiscomp exec scrttv
+
+   After seeing the SeisComP splash screen,
+   you'll likely get an error message "Could not read inventory (NULL)".
+   After a new installation, that's okay.
+   Click that box away, and you'll see a screen with
+   "Enabled", and "Disabled" tabs, and time along bottom axis as in the figure below.
+   To see stations and data you will later need to
+   :ref:`add inventory <tutorials_addstation>` and
+   :ref:`waveforms <tutorials_geofon_waveforms>` to your system.
+
+   .. figure:: media/postinstall_scrttv.png
+      :width: 14.6cm
+      :align: center
+
+      First view of the :ref:`scconfig` configuration tool.
+
+
+Congratulations, you're done with this tutorial.

share/doc/seiscomp/html/_sources/base/tutorials/processing.rst.txt

@@ -0,0 +1,131 @@
+.. _tutorials_processing:
+
+******************************
+Configure real-time processing
+******************************
+
+You will enable processing by your existing local SeisComP system.
+
+
+:Pre-requisites for this tutorial:
+
+  * Real-time data for the station must be available locally.
+    See :ref:`tutorials_waveforms` or :ref:`tutorials_geofon_waveforms`.
+  * Inventory must be loaded locally.
+
+:Afterwards/Results/Outcomes:
+
+  * The new station is available for visualization and general data processing.
+  * The new station is used for automatic real-time phase picking.
+
+:Time range estimate:
+
+  * 10 minutes.
+
+:Related tutorial(s):
+
+  * :ref:`tutorials_addstation`
+
+-----------
+
+
+Create bindings
+===============
+
+In SeisComP terminology, *bindings* are the connection between modules
+and individual stations.
+See the "Bindings" section of :ref:`concepts_configuration` for full details.
+
+You can create the necessary bindings for your new station
+using :ref:`scconfig`.
+Go to the "Bindings" tab on the left side bar of :ref:`scconfig`.
+
+* You will need to add  "global" and "scautopick" bindings.
+
+  * Create a global profile named "BH" by clicking with the right button on "global"
+    in the top right panel. Double click on it and set BH as *detectStream* and
+    empty location code as *detecLocID* information.
+    Adjust these as appropriate for your station.
+
+  * Create a *scautopick* profile named "default" (no changes necessary).
+
+  * Drag and drop all profiles from the right side to the network icon on the
+    left side (you may do that also at the station level).
+
+  * Press :kbd:`Ctrl`+:kbd:`S` to save the configuration.
+    This writes configuration files in :file:`~/seiscomp/etc/key`.
+
+* Alternatively, you can add the scautopick and global bindings
+  by editing the relevant top-level key file.
+  (For station CLL of the GR network, this would be :file:`etc/key/station_GR_CLL`.)
+  It would contain:
+
+  .. code::
+
+      # Binding references
+      global
+      scautopick:default
+
+  in addition to any other bindings that might be defined for this station.
+
+Then execute:
+
+.. code-block:: sh
+
+   $ seiscomp update-config
+   $ seiscomp restart scautopick
+
+or use :ref:`scconfig` for these actions.
+
+.. note::
+
+   * Station inventory must be available at least on channel level and the global
+     bindings must match the inventory and the available waveforms.
+   * Global bindings are required for data visualization and general data
+     processing.
+   * Enable :ref:`scautopick` for running it by default.
+   * Generated picks may be used by other modules, such as :ref:`scautoloc`
+     which must be set up independently.
+   * The default parameters for :ref:`scautopick` have been optimized for
+     monitoring earthquakes at teleseismic distances and the must be adjusted
+     for other types.
+
+
+Check the station is used for processing
+========================================
+
+If you have correctly configured the station for processing, then:
+
+* On restarting :program:`scautopick`, the station appears in the
+  :file:`scautopick.log` log
+  file in :file:`~/.seiscomp/log`::
+
+    2020/03/01 18:01:00 [info/Autopick] Adding detection channel GR.CLL..BHZ
+
+  After some time, a nearby event will occur and phases recorded on this station
+  should be picked. If :ref:`scautoloc` was running at the time and
+  :confval:`autoloc.pickLogEnable` was activated, the pick should appear in the
+  latest :file:`autoloc-picklog` file in :file:`~/.seiscomp/log`:
+
+  .. code-block:: sh
+
+     $ grep "CLL" .seiscomp/log/autoloc-picklog.2020-03-01
+     2020-03-01 18:31:47.1 GR CLL    BHZ __   40.9    177.433  1.1 A 20200301.183147.13-AIC-GR.CLL..BHZ
+
+* The station should now also appear in the GUIs.
+  After reopening them,
+
+  * The station should now show up in :program:`scmv`
+    (as a new triangle at the expected location on the map,
+    which is not black if the station is active).
+
+  * In :program:`scrttv` a trace or at least the line for the configured stream
+    should be visible.
+
+  * In :program:`scolv`, the new station is either already included
+    in automatic locations, or can be added manually.
+
+In case of problems, check that :confval:`detecStream` and
+:confval:`detecLocid` are set correctly.
+They must match both what is in inventory and the waveforms provided
+from the upstream server.

share/doc/seiscomp/html/_sources/base/tutorials/servefdsnws.rst.txt

@@ -0,0 +1,155 @@
+.. _tutorials_servefdsnws:
+
+**************************
+Enable local FDSNWS server
+**************************
+
+You will ...
+
+* Enable FDSN web service by :ref:`fdsnws` to serve waveforms and inventory for
+  a configured station
+
+Pre-requisites for this tutorial:
+
+* Tutorial on :ref:`tutorials_archiving`
+
+Afterwards/Results/Outcomes:
+
+* The station meta data and waveforms are available from a local web server
+
+Time range estimate:
+
+* 10 minutes
+
+----------
+
+By default, :ref:`fdsnws` will serve the three FDSN web services
+
+* fdsnws-dataselect
+* fdsnws-event
+* fdsnws-station
+
+on a server running locally on port 8080.
+
+The additional *availability* feature allows users to obtain information
+on continuous data segments in the waveform archive.
+This information is written to the
+:ref:`database <concepts_database>` by :ref:`scardac`.
+To active the availability feature set :confval:`serveAvailability` and
+:confval:`dataAvailability.enable` to true.
+The availability information can be retrieved using :ref:`scxmldump` or :ref:`fdsnws`.
+
+Set-up
+======
+
+#. Configure :ref:`fdsnws`:
+
+   * set the :ref:`RecordStream <concepts_RecordStream>` to point to archived data.
+   * configured and enable the desired services.
+
+#. Enable and start fdsnws locally:
+
+   * in :ref:`scconfig`, go to the System tab.
+     Click on the line for the "fdsnws" module, and press "Enable module(s)".
+     Then restart SeisComP.
+
+   * or from the command line
+   
+     .. code-block:: sh
+
+        $ seiscomp enable fdsnws
+        $ seiscomp start fdsnws
+
+#. Test by :ref:`visiting the locally started fdsnws <tutorials_servefdsnws-visit>`.
+
+Logging information goes to :file:`~/.seiscomp/log/fdsnws.log` by default.
+Information about requests handled goes to the file named in `accessLog`,
+if you set this.
+
+To see the available configuration options, go to the Modules tab in
+:ref:`scconfig`.
+Under Utilities open "fdsnws" to reveal the options.
+To disable fdsnws-event, for instance, unlock the "serveEvent" area
+and uncheck this parameter.
+
+You can limit the choice of stations shared to be less than what is in your
+SeisComP :ref:`inventory <concepts_inventory>` using the `allowRestricted`,
+`dataSelectFilter` and `stationFilter` options.
+
+
+.. _tutorials_servefdsnws-visit:
+
+Visiting the Service
+====================
+
+Once :ref:`fdsnws` is running, you can visit the local web server
+that it runs.
+In your browser, visit http://localhost:8080/fdsnws/dataselect/1/
+
+.. figure:: media/servefdsnws_dataselect.png
+   :width: 16cm
+   :align: center
+
+   Information screen shown by fdsnws-dataselect at
+   http://localhost:8080/fdsnws/dataselect/1/
+
+
+Check it Works
+==============
+
+* If you visit the URL http://localhost:8080/fdsnws/dataselect/1/version
+  you should receive a version number string - currently `1.1.0`.
+
+* To view all activated services visit http://localhost:8080/fdsnws/
+
+* The fdsnws-station service should give a list of networks configured
+  and served by the service, e.g. visiting
+  http://localhost:8080/fdsnws/station/1/query?level=network&format=text
+  produces
+  
+  .. code-block:: bash
+
+     #Network|Description|StartTime|EndTime|TotalStations
+     GE|GEOFON Program, GFZ Potsdam, Germany|1993-01-01T00:00:00||84
+
+  Omitting the `format=text` argument in the query string of the above URL
+  results in the service returning a StationXML file.
+
+.. figure:: media/servefdsnws_stationxml.png
+   :width: 16cm
+   :align: center
+
+   Example of StationXML returned by the fdsnws-station service at
+
+   http://localhost:8080/fdsnws/station/1/query?level=network
+
+
+Further Information
+===================
+
+* The `URL Builder at GEOFON <https://geofon.gfz-potsdam.de/waveform/builder.php>`_
+  lets you fill out a form to tailor your request.
+  The URL to use to make your request is displayed at the bottom of that page.
+
+* More example requests are at the
+  `FDSNWS description at GEOFON <https://geofon.gfz-potsdam.de/waveform/webservices.php>`_
+
+* The FDSN Web Services specification document :cite:p:`fdsn-specs` provides the
+  technical documentation and examples.
+
+
+Final Tests
+===========
+
+* The station should now be visible when you query your local fdsnws instance.
+  In your browser, visit
+  http://localhost:8080/fdsnws/station/1/query?format=text
+  to see a list of all channels available from your fdsnws server.
+
+* Request waveform data like this:
+
+  http://localhost:8080/fdsnws/dataselect/1/query?start=2020-01-01T01:01:01&end=2020-01-01T02:00:00
+
+  Don't forget to adjust your start and end times to match the data
+  actually present in your archive.
+  The above example is just for the first hour of 2020.

share/doc/seiscomp/html/_sources/base/tutorials/template.rst.txt

@@ -0,0 +1,85 @@
+.. _tutorials_template:
+
+*********************
+Create a new tutorial
+*********************
+
+You will ...
+
+* Add something
+* Configure something else
+
+Pre-requisites for this tutorial:
+
+* Have the source code of SeisComP available
+
+Afterwards/Results/Outcomes:
+
+* A new tutorial
+
+Time range estimate:
+
+* 30 minutes
+
+
+-----------
+
+
+Set-up
+======
+
+To use this template, you'll need to:
+
+#. Get the source code of the SeisComP documentation, e.g. from
+   :cite:t:`seiscomp-github`
+
+#. Copy this tutorial file (:file:`doc/base/tutorials/template.rst`) to the tutorials directory
+   with a new name, :file:`doc/base/tutorials/{nn}_{something}.rst`.
+
+#. Change the reference at the top (first line); it must be
+   *.. _tutorials_{something}*.
+
+#. Change the title: start with a verb, describe what the student is
+   trying to do.
+
+#. Set the tutorial task and a final confirmation action for the student
+   to verify check that it worked correctly.
+
+#. Add the file name without the ending *.rst* to the table of contents in :file:`doc/base/tutorials.rst`
+   assigning a position for your new tutorial within the sequence of
+   existing tutorials.
+
+#. Build the HTML documentation for viewing and :ref:`testing <tutorials_template_testing>`.
+
+#. Optionally, provide your new tutorial to the public repository:
+
+   * Create a new git branch
+   * Push the new branch to GitHub
+   * Create a merge request to get your branch merged into the master branch
+
+
+.. _tutorials_template_testing:
+
+Final Tests
+===========
+
+* If you've applied this template,
+
+  .. code-block:: sh
+
+     ls doc/base/tutorials
+
+  will show your new tutorial.
+
+* Rebuild the documentation
+
+  .. code-block:: sh
+
+     $ cd doc
+     $ python3 build-doc.py
+
+* View the new files in `build-doc/base/html/tutorials` using a web browser, e.g. firefox:
+
+  .. code-block:: sh
+
+     $ firefox build-doc/html/basetutorials.html

share/doc/seiscomp/html/_sources/base/tutorials/upgrading.rst.txt

@@ -0,0 +1,683 @@
+.. _tutorials_upgrade:
+
+******************
+Upgrading SeisComP
+******************
+
+You will ...
+
+* Upgrade a SeisComP system
+* Migrate a SeisComP3 system to a newer SeisComP version
+
+Pre-requisites for this tutorial:
+
+* Tutorial on :ref:`installation <tutorials_postinstall>` and SeisComP previously installed
+
+Afterwards/Results/Outcomes:
+
+* Upgraded SeisComP
+
+Time range estimate:
+
+* 60 minutes
+
+------------
+
+
+Background
+==========
+
+
+Installing a new SeisComP :ref:`release version <tutorials_upgrade_versions>`
+is typically simple and the step described in :ref:`tutorials_upgrade-normal`
+can be applied. **More actions** are required when
+
+* Upgrading the major version of SeisComP as described in :ref:`tutorials_upgrade-normal`.
+* Upgrading :ref:`from SeisComP3 to SeisComP in version 4.0.0. or higher <tutorials_upgrade_v4>`.
+* Upgrading :ref:`from SeisComP3 Jakarta-2018.327 or older to Jakarta-2020.330 or
+  SeisComP in version 4 or higher <tutorials_upgrade_seedlink>`.
+
+
+.. _tutorials_upgrade_versions:
+
+SeisComP versions
+-----------------
+
+SeisComP has :ref:`developed over time <history>`. 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.
+
+  .. note ::
+
+     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 :ref:`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 |scname| systems
+one machine host the messaging system and the database and all other machines
+are connected to this messaging or are running independently, the |scname|
+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:
+
+#. Upgrade the GUI work station
+#. Upgrade the processing system, take actions to
+   :ref:`upgrade the database version <tutorials_upgrade-db>`.
+
+.. note::
+
+   Always stop all SeisComP modules before upgrading:
+
+   .. code-block:: sh
+
+      seiscomp stop
+
+
+.. _tutorials_upgrade_download:
+
+Package Download
+================
+
+Get the SeisComP package in the latest version or older ones from gempa GmbH or
+from the download website of :cite:t:`seiscomp`.
+
+.. note ::
+
+   gempa provides :cite:t:`gsm` for convenient and consistent download and
+   installation of SeisComP and other packages.
+
+
+.. _tutorials_upgrade_changelog:
+
+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 <https://www.seiscomp.de/doc/base/changelog.html>`_.
+It is recommend to read the change log before taking further actions.
+
+The details can also be found locally in the file
+
+.. code-block:: sh
+
+   $SEISCOMP_ROOT/share/doc/seiscomp/CHANGELOG
+
+which is integrated in the :ref:`documentation <sc-changelog>` or accessible
+from the *Docs* panel in :ref:`scconfig`.
+
+.. note::
+
+   New features are regularly advertised and described in detail on the
+   `News website of gempa GmbH <https://www.gempa.de/news/>`_ and on the
+   :cite:t:`seiscomp-forum`.
+
+
+.. _tutorials_upgrade-normal:
+
+Normal Upgrade
+==============
+
+The normal upgrade including upgrading the major version of SeisComP takes only
+a few steps:
+
+#. :ref:`Download <tutorials_upgrade_download>` the SeisComP package.
+#. Stop all SeisComP modules:
+
+   .. code-block:: sh
+
+      seiscomp stop
+
+#. Install the new packages.
+
+   .. note::
+
+      Users of external, e.g., |gempa| modules must ensure that these external
+      modules match the SeisComP release version if they depend on SeisComP
+      libraries.
+
+#. Test the database schema version and update bindings
+
+   .. code-block:: sh
+
+      seiscomp update-config
+
+   :ref:`Upgrade the database schema version <tutorials_upgrade-db>` if
+   mismatches are reported.
+
+#. After a successful upgrade, start all modules again and observe the status:
+
+   .. code-block:: sh
+
+      seiscomp start
+      seiscomp status started
+
+
+.. _tutorials_upgrade-db:
+
+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:
+
+.. code-block:: sh
+
+   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.:
+
+.. code-block:: sh
+
+   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:
+
+  .. code-block:: sh
+
+     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:
+
+  .. code-block:: sh
+
+     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.
+
+.. warning::
+
+   Upgrading the database make take some time. Do no interrupt the process!
+   During this time, the |scname| 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:
+
+.. code-block:: sh
+
+   seiscomp update-config
+
+After successfully upgrading the database continue your previous upgrade procedure.
+
+
+.. _tutorials_upgrade_v4:
+
+SeisComP3 to version >=4
+========================
+
+SeisComP in version 4 has some major differences to SeisComP3 which require adjustments.
+The main differences are in the :ref:`directories of the SeisComP installation <sec-tutorials_upgrading_path>`
+and the :ref:`messaging system <sec-tutorials_upgrading_messaging>`.
+The changes and the required actions are explained below. They must be considered
+in addition to the steps set out in section :ref:`tutorials_upgrade-normal`.
+
+
+.. _sec-tutorials_upgrading_path:
+
+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 :ref:`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.
+
+  .. warning::
+
+     Some configuration default and description files have changed. Spread, arclink
+     and arclinkproxy are not part of |scname| anymore. **Therefore, do not migrate:**
+
+     * any default configuration, description and init files. Better enable the desired
+       daemon modules again:
+
+       .. code-block:: sh
+
+          seiscomp/bin/seiscomp enable [module]
+
+     *   any file related to spread or the arclink and arclinkproxy servers.
+
+Configurations containing absolute paths, e.g. :file:`/home/sysop/seiscomp3/share/scautoloc/grid_custom.conf`,
+must be adjusted. Better use :ref:`internal SeisComP variables <concepts_configuration_variables>`
+such as *@DATADIR@* instead of *seiscomp3/share* or *seiscomp/share*.
+
+
+Software dependencies
+---------------------
+
+The software dependencies may have changed.
+:ref:`Install the missing ones <software_dependencies>`.
+
+
+System variables
+----------------
+
+The system environment variables must be updated, e.g. in :file:`$HOME/.bashrc`.
+Remove or uncomment the lines  :file:`$HOME/.bashrc` referring to the depreciated SeisComP3
+version. Then execute
+
+.. code-block:: sh
+
+   seiscomp/bin/seiscomp print env >> $HOME/.bashrc
+   source $HOME/.bashrc
+
+
+Pipelines
+---------
+
+When using pipelines or alias modules, create and enable the alias module names again, e.g.
+
+.. code-block:: sh
+
+   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.
+
+
+.. _sec-tutorials_upgrading_messaging:
+
+Messaging system
+----------------
+
+One of the main changes SeisComP3 to SeisComP in version 4.0 is the :ref:`messaging system <concepts_messaging>`.
+Spread does not exist anymore and only :ref:`scmaster` is started initially for
+the messaging system. :ref:`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:
+
+
+#. Remove or comment the obsolete *dbplugin* plugin manually from
+   :file:`scmaster.cfg` and :file:`global.cfg` ::
+
+   # plugins = dbplugin
+
+#. Set up the messaging queues in the configuration of :ref:`scmaster` in
+   :file:`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.
+
+     .. note::
+
+        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
+        :confval:`connection.server` parameter. See below for an example.
+
+     * Add the required plugins per queue. Currently only *dbstore* is supported.
+       Example for the *production* queue:
+
+       .. code-block:: properties
+
+          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
+         :confval:`queues.$name.groups`, e.g. for the *production* group.
+         This convenient configuration per queue
+         considers the default groups in :confval:`defaultGroups` and simply adds
+         new groups in the configuration of queues
+
+         .. code-block:: properties
+
+            queues.production.groups = ${defaultGroups}, L1PICK, L1LOCATION
+
+       * Set groups per queue in :confval:`queues.$name.groups`,
+         ignoring groups in :confval:`defaultGroups`
+
+         .. code-block:: properties
+
+            queues.production.groups = L1PICK, L1LOCATION, AMPLITUDE, PICK, LOCATION, MAGNITUDE, FOCMECH, EVENT, QC, PUBLICATION, GUI, INVENTORY, ROUTING, CONFIG, LOGGING, IMPORT_GROUP, SERVICE_REQUEST, SERVICE_PROVIDE
+
+       * Set groups in :confval:`defaultGroups`
+
+         .. code-block:: properties
+
+            defaultGroups = L1PICK, L1LOCATION, AMPLITUDE, PICK, LOCATION, MAGNITUDE, FOCMECH, EVENT, QC, PUBLICATION, GUI, INVENTORY, ROUTING, CONFIG, LOGGING, IMPORT_GROUP, SERVICE_REQUEST, SERVICE_PROVIDE
+
+       .. warning::
+
+          When setting groups in the queues all groups configured in
+          :confval:`defaultGroups` will be ignored unless `${defaultGroups}` is used.
+          Add all groups from :confval:`defaultGroups` to the queues to keep the
+          default groups.
+
+     * Add the interface name, currently only *dbstore* is supported. Example for
+       a queue names *production*
+
+       .. code-block:: properties
+
+          queues.production.processors.messages = dbstore
+
+     * Add the database parameters which can be used from the legacy configuration
+
+       .. code-block:: properties
+
+          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
+
+       .. note::
+
+          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 :confval:`queues` parameter to register
+     them by their names
+
+     .. code-block:: properties
+
+        queues = production, playback
+
+
+#. Configure the connection parameters of all modules connecting to the messaging
+   system in the global configuration, e.g. in :file:`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.
+
+   .. code-block:: properties
+
+      connection.server = localhost/production
+
+   .. note::
+
+      If *production* shall be used, then no additional configuration is required.
+
+
+Database
+--------
+
+After adjusting the structure, variables and configuration parameters, check if the
+:ref:`database requires an upgrade <tutorials_upgrade-db>` as well.
+
+
+Seedlink
+--------
+
+When upgrading from SeisComp3 Jakrata-2018.327 or older and using :ref:`seedlink`,
+consider the sections :ref:`tutorials_upgrade_seedlink` and
+:ref:`tutorials_proc_seedlink`.
+
+
+Automatic module check
+----------------------
+
+If applied, adjust the settings for automatic module status check, e.g. crontab entries.
+For crontab use:
+
+.. code-block:: sh
+
+   crontab -e
+
+
+System daemon
+-------------
+
+If |scname| is controlled by the system daemon, e.g. to start enabled |scname|
+modules automatically during computer startup, then the startup script must be
+adjusted.
+
+
+Upgrade From SeisComP3 Jakarta-2018.327 or Before
+=================================================
+
+
+.. _tutorials_upgrade_seedlink:
+
+SeedLink buffer
+---------------
+
+In SeisComP3 prior to Jakarta-2020.330 two stations with the same
+station but different network code were mixed in one buffer directory.
+As of  Jakarta-2020.330 and SeisComP in version 4 the buffer directories are now
+unique!
+Before upgrading :ref:`seedlink`, you should therefore rename the buffer directories
+accordingly.
+
+.. warning::
+
+   You may discover data gaps if you do not rename the buffer directories.
+
+**Example:**
+
+#. Check the current situation:
+
+   .. code-block:: bash
+
+      sysop@host:~/seiscomp3/var/lib/seedlink/buffer$ ls
+        PB02
+
+#. Rename the directories properly:
+
+   #. Stop seedlink:
+
+      .. code-block:: sh
+
+         sysop@host:seiscomp stop seedlink
+
+   #. Upgrade to SeisComP3-jakarta-2020.330 or SeisComP in version 4 or higher.
+   #. Rename all seedlink buffer directories to NET.STA, e.g.
+
+      .. code-block:: bash
+
+         sysop@host:~/seiscomp3/var/lib/seedlink/buffer$ mv PB02 CX.PB02
+         sysop@host:~/seiscomp3/var/lib/seedlink/buffer$ ls
+           CX.PB02
+
+      .. note:
+
+         The :ref:`script below <seedlink-buffer-script>` can be used for renaming the seedlink buffer directories.
+   #. Update configuration:
+
+      .. code-block:: bash
+
+         sysop@host:seiscomp update-config
+
+   #. Start SeedLink
+
+      .. code-block:: bash
+
+         sysop@host:seiscomp start seedlink
+
+.. _seedlink-buffer-script:
+
+Script for renaming the seedlink buffer directories:
+
+.. code-block:: bash
+
+   #!/bin/bash
+
+   if [ -z ${SEISCOMP_ROOT+x} ]; then
+           echo "Environment variable SEISCOMP_ROOT is not set."
+           echo "Either use 'seiscomp exec [script]' or set SEISCOMP_ROOT to the installation "
+        exit 1
+        echo "path of your SeisComP installation."
+   fi
+
+   grep -A 2 ^station $SEISCOMP_ROOT/var/lib/seedlink/seedlink.ini | while read a b c; do
+       if [ "$a" = station -a "$b" != .dummy ]; then
+                id=$b
+                sta=""
+                net=""
+                while read a b c; do
+                        case $a in
+                                --) break;;
+                                name) eval sta=$c;;
+                                network) eval net=$c;;
+                        esac
+                done
+                if [ -z "$id" -o -z "$sta" -o -z "$net" ]; then
+                        echo "Error parsing seedlink.ini"
+                        break
+                fi
+
+                if [ "$id" != "$net.$sta" ]; then
+                        mv -v "$SEISCOMP_ROOT/var/lib/seedlink/buffer/$id" "$SEISCOMP_ROOT/var/lib/seedlink/buffer/$net.$sta"
+                else
+                        echo "$id: No renaming required"
+                fi
+        fi
+   done
+
+
+.. _tutorials_proc_seedlink:
+
+SeedLink stream processor
+-------------------------
+
+Since SeisComP3 in version Jakarta-2020.030 and SeisComP in version 4.0.0,
+SeedLink stream processors (``proc`` parameter) can be attached to both, stations
+and plugin instances. In order to distinguish between the two cases, either
+``proc`` (attach to station) or ``sources.*.proc`` (attach to plugin instance)
+parameter (or both) can be used in SeedLink bindings.
+
+
+chain plugin
+~~~~~~~~~~~~
+
+In case of the :ref:`chain plugin <seedlink-sources-chain-label>` for
+:ref:`seedlink`, there is
+normally just one instance, so stream processors attached to this instance apply
+to all stations. **This is normally not what we want.** Therefore the
+chain plugin does not support the ``sources.*.proc`` option.
+
+Before SeisComP3 in version Jakarta-2020.030 and SeisComP in version 4.0.0,
+stream processors were always attached to stations, even when ``sources.*.proc``
+was used. This means when upgrading:
+
+#. ``sources.chain.proc`` must be renamed to ``proc``
+#. streams\_\*.tpl templates must be moved one level up, from
+   :file:`$SEISCOMP_ROOT/seiscomp/share/templates/seedlink/chain/` to
+   :file:`$SEISCOMP_ROOT/seiscomp/share/templates/seedlink/`.
+
+.. note::
+
+   Using a stream processor with chain_plugin makes only sense when raw
+   data is generated (:confval:`sources.chain.channels.unpack`).
+
+
+Background
+~~~~~~~~~~
+
+A stream processor is an object defined in XML, which is used to create MiniSEED
+from raw data and optionally downsample the data. What is the difference between
+attaching a stream processor to station and plugin instance?
+
+Let's take a look at the following stream processor definition in
+:file:`$SEISCOMP_ROOT/share/templates/seedlink/streams_stream100.tpl`:
+
+.. code-block:: XML
+
+   <proc name="stream100">
+     <tree>
+       <input name="Z" channel="Z" location="" rate="100"/>
+       <input name="N" channel="N" location="" rate="100"/>
+       <input name="E" channel="E" location="" rate="100"/>
+       <node filter="FS2D5" stream="BH">
+         <node filter="F96C">
+           <node filter="ULP" stream="LH">
+             <node filter="VLP" stream="VH"/>
+           </node>
+         </node>
+       </node>
+     </tree>
+   </proc>
+
+This creates 20Hz BH\*, 1Hz LH\* and 0.1Hz VH\* streams from 100Hz Z, N, E raw
+data. If one plugin instance is used for the station, it does not make a
+difference whether this is attached to station or plugin instance. But suppose
+the station is using two plugin instances—one for broad-band and the other for
+strong-motion data—, both sending Z, N and E channels. Now if the stream processor
+is attached to station, data from both plugin instances would mixed up. We must
+attach a different stream processor to each plugin instance—one producing BH\*,
+LH\* and VH\* and the other one producing BN\* and so on.

share/doc/seiscomp/html/_sources/base/tutorials/waveformplayback.rst.txt

@@ -0,0 +1,244 @@
+.. _tutorials_waveformplayback:
+
+****************************
+Play back archived waveforms
+****************************
+
+Aims:
+
+* Use previously recorded waveform files to re-run the analysis
+  of an old event using SeisComP. This is known as a *waveform playback*.
+* Insert results into your current SeisComP database for later processing.
+* Review the results from playbacks.
+
+Pre-requisites for this tutorial:
+
+* Have SeisComP installed and configured
+* Have access to :term:`miniSEED` waveforms
+
+Afterwards/Results/Outcomes:
+
+* The results from the playback are in your SeisComP system, e.g. :term:`picks <pick>`,
+  :term:`origins <origin>`, :term:`amplitudes <amplitude>`, :term:`events <event>`
+
+Time range estimate:
+
+* 60 minutes
+
+Related tutorial(s):
+
+* Tutorial on :ref:`getting help <tutorials_help>`
+
+----------
+
+Playbacks are an important way of testing module and whole-system configurations,
+operator trainings, system demonstrations and validations and tuning of the SeisComP modules
+used for detecting and locating events, e.g. involving
+
+* :ref:`seedlink`
+* :ref:`slarchive`
+* :ref:`scautopick`
+* :ref:`scautoloc`
+* :ref:`scamp`
+* :ref:`scmag`
+* :ref:`scevent`
+* others.
+
+Playbacks rely on miniSEED data which are obtained from the :term:`SDS` archive or
+other sources. The miniSEED data records in the data files must be sorted by end time!
+
+There are two types of playbacks:
+
+* :ref:`Real-time playbacks <tutorials_rtplayback>`.
+* :ref:`Non-real-time playbacks <tutorials_nonrtplayback>`.
+
+
+Data preparation
+================
+
+First extract the data. Make sure the miniSEED records are sorted by end time.
+The data extraction depends on the data source.
+
+Examples:
+
+* **SDS archive:** Extract the data from your own SDS archive using :ref:`scart`
+  and save it in a new miniSEED file :file:`[your miniSEED file]`, sorted by
+  end time of the records.
+
+  Examples:
+
+  .. code-block:: sh
+
+     scart -dsE -l [list file] $SEISCOMP_ROOT/var/lib/archive > [your miniSEED file]
+
+* **FDSNWS:** Get the miniSEED data from an external FDSNWS server. The obtained
+  data are initially sorted by station and must therefore be sorted by end time
+  using :ref:`scmssort`. Use the resulting file :file:`[your miniSEED file]`
+  for your playback.
+
+  Example for one hour of data from the GE network from
+  `FDSNWS at GEOFON <https://geofon.gfz-potsdam.de/waveform/webservices/fdsnws.php>`_:
+
+  .. code-block:: sh
+
+     wget -O data.mseed "http://geofon.gfz-potsdam.de/fdsnws/dataselect/1/query?net=GE&cha=BH*&starttime=2021-04-01T06:00:00Z&endtime=2021-04-01T07:00:00Z"
+     scmssort -u -E data.mseed > [your miniSEED file]
+
+* **CAPS server:** Extract the data from gempa's CAPS server :cite:p:`caps`
+  using :cite:t:`capstool`:
+
+  .. code-block:: sh
+
+     capstool -H [host]:[port] [request file] > data.mseed
+
+  or :ref:`scart` with the *caps* :term:`recordstream`:
+
+  .. code-block:: sh
+
+     scart -I caps://[host]:[port] -l [list file] --stdout > data.mseed
+
+  Eventually, sort the downloaded data by end time with :ref:`scmssort` creating
+  a new file, :file:`[your miniSEED file]`:
+
+  .. code-block:: sh
+
+     scmssort -u -E data.mseed > [your miniSEED file]
+
+Use the resulting file :file:`[your miniSEED file]` for your playback.
+
+
+Playbacks
+=========
+
+
+.. _tutorials_rtplayback:
+
+Real-time playbacks
+-------------------
+
+In a real-time playback data are injected into the seedlink buffer from a file
+using the command-line tool :ref:`msrtsimul`. Therefore, seedlink requires a configuration.
+
+#. Prepare :ref:`seedlink` to except data from msrtsimul:
+
+   * In the :ref:`module configuration <concepts_configuration>`
+     of seedlink set
+
+     .. code-block:: sh
+
+        msrtsimul = true
+
+   * Save the configuration, update the configuration and restart seedlink:
+
+     .. code-block:: sh
+
+        seiscomp update-config
+        seiscomp restart seedlink
+
+     Open :scrttv: to verify the success of this re-configuration. No new data must arrive.
+
+#. Restart all automatic data processing modules you wish to involve. Additionally start
+   :ref:`slarchive` to archive the miniSEED data in the SDS archive for post-processing.
+
+   .. code-block:: sh
+
+      seiscomp restart scmaster scautopick scautoloc scamp scmag scevent slarchive
+
+#. Start all desired :term:`GUI` modules to observe the data acquisition and processing
+   and the event results, e.g.:
+
+   .. code-block:: sh
+
+      scrttv & scmv & scesv & scolv
+
+#. Start the playback using msrtsimul:
+
+   .. code-block:: sh
+
+      msrtsimul -v [your miniSEED file]
+
+   This will play back the data as if they where perfectly recorded and received now.
+   To preserve the time of the records use :program:`msrtsimul` with the historic
+   mode:
+
+   .. code-block:: sh
+
+      msrtsimul -v -m historic [your miniSEED file]
+
+   .. note::
+
+      Using :program:`msrtsimul` with the historic mode requires to reset the
+      seedlink buffer and the buffer of other processing modules by removing
+      the buffer files and restarting the modules. This mode may
+      therefore be exclusively used by experienced users.
+
+Revert the seedlink configuration after the playback to return to the original real-time
+data acquisition.
+
+.. warning::
+
+   Be careful with executing real-time playbacks on production SeisComP systems:
+
+   * You potentially disrupt the real-time data acquisition
+   * You potentially add data at wrong times to seedlink and your SDS waveform archive
+   * You modify the history of the created events
+   * You potentially add events at wrong origin times to your database.
+
+   Better use separate test systems for real-time playbacks.
+
+
+.. _tutorials_nonrtplayback:
+
+Non-real-time playbacks
+-----------------------
+
+In non-real-time playbacks, also referred to as offline playbacks, data are processed
+by each module as fast as possible. The results can be communicated by
+
+* Messages: message-based playback
+* XML files in :term:`SCML` format: XML playback. They require the processing
+  modules to provide the *- -ep* option.
+
+.. warning::
+
+   In non-real-time playbacks scheduling and the creation history are not representative of
+   real-time situations.
+
+
+Reviewing results
+=================
+
+Use :ref:`scolv` or other :term:`GUIs <GUI>` to review the results:
+
+*  Event parameters are in the default database. Configure :ref:`concepts_RecordStream`
+   if the waveforms are in the seedlink or in the :term:`SDS` archive:
+
+   .. code-block:: sh
+
+      scolv -d mysql://sysop:sysop@localhost/seiscomp
+
+*  Event parameters are in the default database but the waveforms are read from the miniSEED file:
+
+   .. code-block:: sh
+
+      scolv -d mysql://sysop:sysop@localhost/seiscomp -I file://[your file]
+
+   .. note::
+
+      Reading from the original file will only work if the actual times of the data
+      are preserved during the playback. This is **not** the case when starting
+      :program:`msrtsimul` without the historic mode.
+
+*  Event parameters are available in one XML file and the waveforms are read from the miniSEED file:
+
+   .. code-block:: sh
+
+      scolv --offline -d mysql://sysop:sysop@localhost/seiscomp -I file://[your miniSEED file]
+
+   To open the XML file click on the *File* menu of scolv. When results are available in several
+   XML files, the files can be merged beforehand using :ref:`scxmlmerge`.
+
+.. note::
+
+   Adjust the arguments to match your configuration. Use your own values for arguments enclosed by
+   brackets, e.g. [your file]

share/doc/seiscomp/html/_sources/base/tutorials/waveforms.rst.txt

@@ -0,0 +1,158 @@
+.. _tutorials_waveforms:
+
+*****************************************************************
+Get real-time data from a remote Seedlink server (single station)
+*****************************************************************
+
+You will use :program:`scconfig` to add waveforms for a single station
+which is already in inventory.
+
+Pre-requisites for this tutorial:
+
+* :ref:`Installation<tutorials_postinstall>`
+* Inventory for the station already loaded.
+
+Afterwards/Results/Outcomes:
+
+* :program:`slinktool -Q` locally shows the station's streams are available.
+
+Time range estimate:
+
+* 10 minutes
+
+Related tutorial(s):
+
+* :ref:`tutorials_archiving`
+* :ref:`tutorials_servefdsnws`
+* :ref:`tutorials_addstation`
+
+----------
+
+We suppose there is an upstream Seedlink server, such as that
+from GEOFON, IRIS, or some other public source.
+
+
+Check data are available
+========================
+
+First, we'll query the upstream Seedlink server,
+to confirm that it has current data.
+We do this with SeisComP's :program:`slinktool` command,
+giving it the '-L' option to list the available stations.
+For this example, we'll use the server at host `geofon.gfz-potsdam.de`
+on port 18000 (the default) ::
+
+  $ slinktool -L geofon.gfz-potsdam.de
+  AW VNA1  VNA1
+  AW VNA2  VNA2
+  [..]
+  GR BSEG  BSEG
+  GR BUG   BUG
+  GR CLL   CLL
+  GR CLZ   CLZ
+  [..]
+
+This can be a long list. It shows the network code and station code of each
+of the stations for which data is available from this Seedlink server.
+We can restrict the output to our station of interest using `grep`. ::
+
+  $ slinktool -Q geofon.gfz-potsdam.de | grep GR.CLL
+  GR CLL      LHN D 2020/05/06 15:13:41.2249  -  2020/05/06 21:15:28.0299
+  GR CLL      BHZ D 2020/05/06 15:13:41.2249  -  2020/05/06 21:22:13.1300
+  GR CLL      BHN D 2020/05/06 15:13:41.2249  -  2020/05/06 21:22:15.4300
+  GR CLL      HHE D 2020/05/06 15:13:41.2249  -  2020/05/06 21:22:50.3450
+  GR CLL      HHN D 2020/05/06 15:13:41.2249  -  2020/05/06 21:22:52.4650
+  GR CLL      HHZ D 2020/05/06 15:13:41.2249  -  2020/05/06 21:22:53.6850
+  GR CLL      LOG L 2020/05/06 15:13:41.2249  -  2020/05/06 19:59:53.3850
+  GR CLL      BHE D 2020/05/06 15:13:41.2249  -  2020/05/06 21:22:08.9300
+  [..]
+
+The '-Q' option provides a formatted stream list,
+with one line for each stream available from the server.
+The columns are: network code, station code, location code (which may
+be empty) and channel code, a flag, and then the (UTC) time of the
+first and last data available at the server.
+(The `grep` command here is used to limit output to just those CLL streams;
+without it, this server provides thousands of lines of output.)
+
+For an active station the last data time (shown on the
+right) will be very recent.
+
+
+.. note::
+
+   **(Advanced)**
+   You can restrict who has access to a station's data (from your server)
+   in your Seedlink bindings.
+   This sets the :confval:`access` variable in your :file:`seedlink.ini` file.
+   This can be done for all stations, or per station.
+   The documentation for :program:`seedlink` gives details.
+
+
+Configure bindings
+==================
+
+In :program:`scconfig`, under the Bindings tab:
+
+1. Create a *seedlink* profile named "geofon", named after the upstream server.
+
+   * Double click on the profile.
+   * Select the 'chain' plugin for the souce from the drop-down menu
+   * To add the plugin click on the green "plus" button on the left. Name it anything or even leave the name blank.
+   * Open this and set the name of the server (:confval:`address`)
+     and its TCP port, :confval:`port`. Normally you leave the port at 18000 which is the default.
+   * If you wish to limit the data requested to particular channels,
+     based on channel or location code,
+     set Seedlink's :confval:`selectors <sources.chain.selectors>` to "BH?.D" say
+     for fetch all BH stream and no auxiliary streams. Add the location code without
+     a space to limit by location as well, e.g. 00BH?.D. You may add a comma-separated
+     list of streams, e.g. "00BH?.D, 10BH?.D".
+     Otherwise you will be requesting all streams available for this
+     station, potentially wasting bandwidth and slowing your system.
+     No other changes are normally necessary.
+
+#. Drag and drop this profile from the right side to the network icon on the
+   left side (you may do that also at the station level)
+   to apply it to your station.
+
+#. Press Ctrl+S to save the configuration.
+   This writes configuration files in :file:`~/seiscomp/etc/key`.
+
+
+Update the configuration
+========================
+
+The SeisComP database must already be updated with the inventory
+(see Tutorial :ref:`tutorials_addstation`).
+SeisComP's modules then require restarting to load the updated information.
+
+* Go to the System tab and press ESC (the Escape key, to de-select all modules).
+
+  #. Click on "Update configuration", at the right of the window.
+     (**Not** "Refresh", - that just refreshes :program:`scconfig`'s
+     display of what is running!)
+  #. Press *Start* to start acquiring data from the already configured stations.
+
+* Alternatively, at the command line::
+
+    $ seiscomp update-config seedlink
+    $ seiscomp restart seedlink
+
+
+Check it works
+==============
+
+* To confirm that you have waveform data for the station locally,
+  run ::
+
+     slinktool -Q localhost
+
+
+Further steps
+=============
+
+At this point,
+you can follow the same procedure for other networks/stations, provided you
+
+1. Have metadata available. You may follow the tutorial :ref:`tutorials_addstation`.
+2. Know the location of a Seedlink server for, and have access to, the waveforms.