scinv

Inventory database synchronisation.

Description

scinv merges inventory XML files to a single inventory, synchronises an inventory with another (most common use is with database), creates initial key files and much more …

scinv is used by etc/init/scinv.py to synchronise the inventory from etc/inventory with the database.

seiscomp update-config inventory

Commands

scinv works with different commands:

  • apply: Read and apply notifiers,

  • check: Check the consistency of inventories,

  • keys: Merge inventory files and generate key files,

  • ls: List the content of inventories,

  • merge: Merge inventory files,

  • sync: Synchronize inventories in files and writing sending to the messaging for saving to the database.

The command must be given as 1st parameter to the application. All others parameters must follow.

scinv $command [options] [files]

sync

Synchronises an applications inventory with a given source given as file(s). It checks the consistency of the inventory using check before synchronization. The applications inventory is either read from the database or given with –inventory-db. As a result all information in the source is written to target and target does not contain any additional information. The source must hold all information. This works different to merge. If an output file is specified with -o no notifiers are generated and sent via messaging.

This command is used by etc/init/scinv.py as follows:

scinv sync --console=1 -H localhost:$p --filebase "$fb" \
           --rc-dir "$rc" --key-dir "$kd"

where

$p = configured messaging port
$fb = $SEISCOMP_ROOT/etc/inventory
$rc = $SEISCOMP_ROOT/var/lib/rc
$kd = $SEISCOMP_ROOT/etc/key

merge

Merges two or more inventories into one inventory checking the consistency of the inventory using :ref:`scinv_check`before synchronization. This command is useful to merge existing subtrees into a final inventory before synchronization.

scinv merge net1.xml net2.xml -o inv.xml

Note

Merging inventory XML files is also supported by scxmlmerge but without the full consistency checks.

apply

Applies stored notifiers created with sync and option --create-notifier which is saved in a file (-o). Source is the applications inventory read from the database or given with --inventory-db. If -o is passed, no messages are sent but the result is stored in a file. Useful to test/debug or prepare an inventory for offline processing.

# Synchronise inventory and save the notifiers locally. No messages are sent.
scinv sync -d mysql://sysop:sysop@localhost/seiscomp \
      --create-notifier -o sync_patch.xml

# Sent the notifiers to the target system
scinv apply -H localhost sync_patch.xml

This operation can be useful to save differences in synchronization for validation or debugging problems.

keys

Synchronise station key files with current inventory pool. This command merges all XML files in the inventory pool (or the given files) and checks if a corresponding station key file in etc/key exists. If not an empty station key file is created. If a station key file without a corresponding station in the merged inventory is found, it is deleted.

ls

List contained items up to response level. This command is useful to inspect an XML file or the complete inventory pool.

$ scinv ls SK.KOLS.xml

  network SK       Slovak National Network of Seismic Stations
    epoch 1980-01-01
    station KOLS   Kolonicke sedlo, Slovakia
      epoch 2004-09-01
      location __
        epoch 2004-09-01
        channel BHE
          epoch 2006-04-25 12:00:00 - 2010-03-24
        channel BHN
          epoch 2006-04-25 12:00:00 - 2010-03-24
        channel BHZ
          epoch 2006-04-25 12:00:00 - 2010-03-24
        channel EHE
          epoch 2004-09-01 - 2006-04-25 10:00:00
        channel EHN
          epoch 2004-09-01 - 2006-04-25 10:00:00
        channel EHZ
          epoch 2004-09-01 - 2006-04-25 10:00:00
        channel HHE
          epoch 2006-04-25 12:00:00 - 2010-03-24
        channel HHE
          epoch 2010-03-25
        channel HHN
          epoch 2006-04-25 12:00:00 - 2010-03-24
        channel HHN
          epoch 2010-03-25
        channel HHZ
          epoch 2006-04-25 12:00:00 - 2010-03-24
        channel HHZ
          epoch 2010-03-25

The default level of information printed is chan. Available levels are net, sta, chan and resp. The output level is controlled by --level.

For checking the available networks and stations in the inventory pool, calling

scinv ls --level sta

is enough.

check

Checks consistency of passed inventory files or a complete filebase. In the first step the inventory is merged from all files. In the second step several consistency checks are applied such as:

  • Overlapping epochs on each level (network, station, …),

  • Valid epochs (start < end),

  • Defined gain in a stream,

  • Set gain unit,

  • Distance of the sensor location to the station location,

  • “Invalid” location 0/0.

When inconsistencies or other relevant information are found, alerts are printed:

  • !: Error, user must take an action,

  • C: Conflict, user should take an action,

  • W: Warning, user should check if an action is required,

  • I: Information,

  • D: Debug,

  • R: Unresolvable, user should check if an action is required,

  • ?: Question.

Note

The following table lists checks of objects for deficiencies and the test results.

  • This test matrix may be incomplete. Consider adding more tests and results.

  • Please report inventory issues not caught by tests to the SeisComP development team, e.g. on :cite:t:`seiscomp-github`.

Object

Check description

Alert

Comments

network

start time after end time

!

network without station

W

empty start time

handled by SeisComP inventory reader: network is ignored

empty station

W

empty code

W

station

start time after end time

!

empty or no start time

W

station is ignored

start time after end time

!

empty code

W

empty latitude

W

empty longitude

W

empty elevation

W

elevation > 8900

!

elevation < -12000

!

has no sensor location

W

sensorLocation

coordinates far away from station

W

--distance overrides default threshold (10 km)

elevation far away from station

W

--max-elevation-difference overrides default threshold (500 m)

epoch outside network epochs

C

epoch outside station epochs

C

empty or no start time

W

sensorLocation is ignored

empty latitude

W

empty longitude

W

elevation > 8900

!

elevation < -12000

!

empty or no elevation

W

has no channel/stream

W

stream

empty or no start time

handled by SeisComP inventory reader: stream is ignored

empty azimuth

C

epoch outside sensorLocation

C

epoch outside station

C

epoch outside network

C

start time after end time

C

missing gain value

W

empty value is handled by SeisComP inventory reader

missing gain unit

W

empty value is handled by SeisComP inventory reader

missing gain frequency

empty value is handled by SeisComP inventory reader

missing sampling rate

empty value is handled by SeisComP inventory reader

missing depth

W

empty value is handled by SeisComP inventory reader

missing azimuth

empty value is handled by SeisComP inventory reader

missing dip

empty value is handled by SeisComP inventory reader

empty sensor ID

I

large depth

W

--max-sensor-depth overrides default threshold (500 m)

sensor

referenced sensor not available

R

Module Configuration

etc/defaults/global.cfg
etc/defaults/scinv.cfg
etc/global.cfg
etc/scinv.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scinv.cfg

scinv inherits global options.

syncKeys

Type: boolean

Synchronise key files. Default is true.

purgeKeys

Type: boolean

Delete key files if a station does not exist in inventory. Default is true.

Note

check.* Quantities probed when using the check command.

check.maxDistance

Type: double

Unit: km

Maximum allowed distance between station and location coordinates. Default is 10.

check.maxElevationDifference

Type: double

Unit: m

Maximum allowed differences between elevation of station and sensor location. Default is 500.

check.maxSensorDepth

Type: double

Unit: m

Maximum allowed depth of channel (sensor). This is the depth of the sensor below the surface. Default is 500.

Command-Line Options

scinv command [options] [files]

Command is one of: sync, merge, apply, keys, ls and check.

Generic

-h, --help

Show help message.

-V, --version

Show version information.

--config-file arg

Use alternative configuration file. When this option is used the loading of all stages is disabled. Only the given configuration file is parsed and used. To use another name for the configuration create a symbolic link of the application or copy it. Example: scautopick -> scautopick2.

--plugins arg

Load given plugins.

-D, --daemon

Run as daemon. This means the application will fork itself and doesn’t need to be started with &.

--auto-shutdown arg

Enable/disable self-shutdown because a master module shutdown. This only works when messaging is enabled and the master module sends a shutdown message (enabled with --start-stop-msg for the master module).

--shutdown-master-module arg

Set the name of the master-module used for auto-shutdown. This is the application name of the module actually started. If symlinks are used, then it is the name of the symlinked application.

--shutdown-master-username arg

Set the name of the master-username of the messaging used for auto-shutdown. If "shutdown-master-module" is given as well, this parameter is ignored.

Verbosity

--verbosity arg

Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug.

-v, --v

Increase verbosity level (may be repeated, eg. -vv).

-q, --quiet

Quiet mode: no logging output.

--component arg

Limit the logging to a certain component. This option can be given more than once.

-s, --syslog

Use syslog logging backend. The output usually goes to /var/lib/messages.

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Execute in debug mode. Equivalent to --verbosity=4 --console=1 .

--log-file arg

Use alternative log file.

Messaging

-u, --user arg

Overrides configuration parameter connection.username.

-H, --host arg

Overrides configuration parameter connection.server.

-t, --timeout arg

Overrides configuration parameter connection.timeout.

-g, --primary-group arg

Overrides configuration parameter connection.primaryGroup.

-S, --subscribe-group arg

A group to subscribe to. This option can be given more than once.

--content-type arg

Overrides configuration parameter connection.contentType.

--start-stop-msg arg

Set sending of a start and a stop message.

Database

--db-driver-list

List all supported database drivers.

-d, --database arg

The database connection string, format: service://user:pwd@host/database. "service" is the name of the database driver which can be queried with "--db-driver-list".

--config-module arg

The config module to use.

--inventory-db arg

Load the inventory from the given database or file, format: [service://]location .

--db-disable

Do not use the database at all

Manager

--filebase dir

Filebase to check for XML files. If not given, all XML files passed are checked.

--rc-dir dir

If given, rc (resource) files will be created in this directory for each station. The station descriptions will be from the last available epoch.

--key-dir dir

If given this directory is used to synchronise key files.

-o, --output file

Output file.

--level int

Information level reported by ls. One of "net", "sta", "cha" or "resp". Default is "cha".

--compact

Enable compact output for ls: each object one line.

Merge

--strip

Remove unreferenced objects (data loggers, sensors, …).

Check

--distance

Maximum allowed distance between station and location coordinates when using the check command.

--max-elevation-difference

Maximum allowed difference in elevation between station and sensorlocation in m. Larger differences will be reported.

--max-sensor-depth

Maximum allowed depth of channel (sensor). This is the depth of the sensor below the surface in m. Larger depths will be reported.

Sync

--create-notifier

If an output file is given then all notifiers will be saved and not the result set itself.

--no-keys

Do not synchronise key files.

--no-rc

Do not synchronise rc files.

--purge-keys

(default) Delete key files if a station does not exist in inventory.

--no-purge-keys

Do not delete key files if a station does not exist in inventory.

--test

Do not send any notifiers and just output resulting operations and conflicts.