NOAA/seiscomp-training
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[installation] Init with inital config for global

Browse Source
This commit is contained in:
Dirk Rössler
2025-10-30 15:08:17 +01:00
commit 7640b452ed
3678 changed files with 2200095 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
share/doc/seiscomp/html/_sources/base/tutorials/addstation.rst.txt Normal file
View File

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

194
share/doc/seiscomp/html/_sources/base/tutorials/archiving.rst.txt Normal file
View File

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

344
share/doc/seiscomp/html/_sources/base/tutorials/geofon_waveforms.rst.txt Normal file
View File

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

314
share/doc/seiscomp/html/_sources/base/tutorials/help.rst.txt Normal file
View File

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

278
share/doc/seiscomp/html/_sources/base/tutorials/magnitude-regionalization.rst.txt Normal file
View File

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

352
share/doc/seiscomp/html/_sources/base/tutorials/postinstall.rst.txt Normal file
View File

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

131
share/doc/seiscomp/html/_sources/base/tutorials/processing.rst.txt Normal file
View File

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

155
share/doc/seiscomp/html/_sources/base/tutorials/servefdsnws.rst.txt Normal file
View File

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

85
share/doc/seiscomp/html/_sources/base/tutorials/template.rst.txt Normal file
View File

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

683
share/doc/seiscomp/html/_sources/base/tutorials/upgrading.rst.txt Normal file
View File

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

244
share/doc/seiscomp/html/_sources/base/tutorials/waveformplayback.rst.txt Normal file
View File

@ -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]

158
share/doc/seiscomp/html/_sources/base/tutorials/waveforms.rst.txt Normal file
View File

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