489 lines
12 KiB
ReStructuredText
489 lines
12 KiB
ReStructuredText
.. highlight:: rst
|
|
|
|
.. _seiscomp:
|
|
|
|
########
|
|
seiscomp
|
|
########
|
|
|
|
**SeisComP system control utility**
|
|
|
|
|
|
Description
|
|
===========
|
|
|
|
The tool :program:`seiscomp` allows controlling your |scname| system on the
|
|
command line. As other |scname| modules it provides
|
|
options and commands, e.g., the command :command:`help`. Apply
|
|
:program:`seiscomp` to
|
|
|
|
* Install software dependencies,
|
|
* Print
|
|
|
|
* environment variables of the installed |scname| system,
|
|
* internal |scname| variables which can be used in configurations,
|
|
* suggestions for timed automatic actions, i.e. "*conjobs*",
|
|
|
|
* Make a basic setup including the |scname| database,
|
|
* List daemon modules by categories,
|
|
* Enable or disable modules in order to start them by default,
|
|
* Start, stop, restart or reload single or multiple modules or all default
|
|
modules,
|
|
* Check the status of module,
|
|
* Execute single or multiple modules or all default modules
|
|
* Print the run status of modules,
|
|
* Manage modules aliases,
|
|
* Update inventory or bindings configurations,
|
|
* Manage :ref:`bindings <binding>` by a specific shell.
|
|
|
|
.. note::
|
|
|
|
When executing :program:`seiscomp`, all actions refer to the |scname|
|
|
installation from within which :program:`seiscomp` is called. This allows
|
|
to refer to a default but also to any other installed |scname| system and to
|
|
operate multiple |scname| systems in parallel, e.g., for testing different
|
|
versions or for running different projects. Then give the full path to the
|
|
:program:`seiscomp` tools. Example:
|
|
|
|
.. code-block:: sh
|
|
|
|
$HOME/seiscomp-test/bin/seiscomp
|
|
|
|
Many of these actions are used by :ref:`scconfig`.
|
|
|
|
|
|
.. _sec_seiscomp_help:
|
|
|
|
Help
|
|
====
|
|
|
|
Use the command :command:`help` for learning about the full set of options and
|
|
other commands including examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp help
|
|
|
|
For basic help you may also use the option :option:`-h`:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp -h
|
|
|
|
|
|
.. _sec_seiscomp_applications:
|
|
|
|
Applications
|
|
============
|
|
|
|
|
|
.. _sec_seiscomp_sw_deps:
|
|
|
|
Software dependencies
|
|
---------------------
|
|
|
|
Software dependencies should be installed after installation or updates of
|
|
|scname|. You may install dependencies on different levels, e.g., *base*,
|
|
*gui*, *fdswnws*, *[database]-server*. Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp install-deps base
|
|
seiscomp install-deps base gui mariadb-server
|
|
|
|
Alternatively run the shell scripts for your Linux flavor and version located in
|
|
:file:`seiscomp/share/deps/`.
|
|
|
|
.. note::
|
|
|
|
For making a full installation and setup follow the instructions starting
|
|
with section :ref:`installation`.
|
|
|
|
|
|
.. _sec_seiscomp_print:
|
|
|
|
Print
|
|
-----
|
|
|
|
You may print the environment variables related to your considered |scname|
|
|
installation, internal |scname| variables or suggestions for timed automatic
|
|
procedures. Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp print env
|
|
$HOME/seiscomp-test/bin/seiscomp print env
|
|
seiscomp print variables
|
|
seiscomp print crontab
|
|
|
|
Add the environment variables to your shell configuration for making them known
|
|
user wide. Internal variables are resolved when applying them in user
|
|
configurations. For adjusting, adding or removing :program:`crontab` listings
|
|
execute:
|
|
|
|
.. code-block:: sh
|
|
|
|
man crontab
|
|
crontab -e
|
|
|
|
|
|
.. _sec_seiscomp_setup:
|
|
|
|
Basic setup
|
|
-----------
|
|
|
|
Make a basic setup of your |scname| system interactively after installation.
|
|
This will also allow you to generate a database or to configure the connection
|
|
to an existing one. Run, e.g.
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp setup
|
|
$HOME/seiscomp-test/bin/seiscomp setup
|
|
|
|
|
|
.. _sec_seiscomp_list:
|
|
|
|
List
|
|
----
|
|
|
|
List modules which can be started to run as background daemon modules by
|
|
categories. Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp list modules
|
|
seiscomp list enabled
|
|
seiscomp list started
|
|
|
|
|
|
.. _sec_seiscomp_enable:
|
|
|
|
Enable/disable [*]_
|
|
-------------------
|
|
|
|
Enabled modules will be started to run as a background daemon module.
|
|
You may enable or disable one or multiple modules. Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp enable scautopick
|
|
seiscomp enable scautopick scautoloc
|
|
seiscomp disable scautopick scautoloc
|
|
|
|
|
|
.. _sec_seiscomp_start:
|
|
|
|
Start/stop/restart/reload [*]_
|
|
------------------------------
|
|
|
|
Start all enabled modules:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp start
|
|
|
|
Stop all modules and start all enabled modules:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp restart
|
|
|
|
Start/stop/restart specific modules
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp start scautopick scautoloc
|
|
seiscomp stop scautopick scautoloc
|
|
seiscomp restart scautopick scautoloc
|
|
|
|
In order to apply configurations, a module must be (re)started since it reads
|
|
any configuration only during startup. Restarts will create downtimes and should
|
|
be avoided as much as possible. In order to minimize downtimes, some modules
|
|
may apply changes in configuration by reloading during runtime without
|
|
restarting. For reloading you may use the command :command:`seiscomp reload`.
|
|
The application of reloading is therefore restricted to a limited range of
|
|
modules and parameters.
|
|
|
|
.. note::
|
|
|
|
Graphical modules such as :ref:`scolv` cannot be operated as background
|
|
daemon modules. Therefore, they cannot be started but they can
|
|
be :ref:`executed <sec_seiscomp_execute>`.
|
|
|
|
|
|
.. _sec_seiscomp_check:
|
|
|
|
Check [*]_
|
|
----------
|
|
|
|
When modules stop unexpectedly, they are not stopped in a clean way. Such
|
|
stopped modules may be detected and started again in order to minimize
|
|
downtimes. Apply the :command:`check` command to all or specific modules.
|
|
Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp check
|
|
seiscomp check scautopick
|
|
|
|
|
|
.. _sec_seiscomp_execute:
|
|
|
|
Execute
|
|
-------
|
|
|
|
Instead of running daemon modules you may execute modules in a terminal and
|
|
observe the output, e.g., for debugging or for applying command-line options.
|
|
Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp exec scolv --debug
|
|
seiscomp exec scautopick --debug
|
|
|
|
.. note::
|
|
|
|
When all relevant system environment variables point to the same |scname|
|
|
installation from where seiscomp is executed, then it is enough to execute
|
|
modules by their names replacing the above:
|
|
|
|
.. code-block:: sh
|
|
|
|
scolv --debug
|
|
scautopick --debug
|
|
|
|
|
|
.. _sec_seiscomp_status:
|
|
|
|
Status [*]_
|
|
-----------
|
|
|
|
List the status of all, enabled, disabled, started, or specific modules.
|
|
Examples:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp status
|
|
seiscomp status enabled
|
|
seiscomp status disabled
|
|
seiscomp status started
|
|
seiscomp status scautopick
|
|
|
|
:command:status` will report modules which terminated due to errors.
|
|
|
|
|
|
.. _sec_seiscomp_aliases:
|
|
|
|
Module Aliases
|
|
--------------
|
|
|
|
For some |scname| modules aliases can be generated allowing the separate
|
|
execution with specific configurations in parallel the original module
|
|
and even in separate pipeline with specific message groups.
|
|
Using the :command:`alias` command aliases modules can be created or removed.
|
|
Examples for creating or removing the alias :program:`l1autopick` to
|
|
:ref:`scautopick`:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp alias create l1autopick scautopick
|
|
seiscomp alias remove l1autopick
|
|
|
|
When creating aliases, soft links to the original module executable files, the
|
|
default configuration and the init files are created. The alias itself is
|
|
registered in :file:`SEISCOMP_ROOT/etc/descriptions/aliases`. If a module does
|
|
not allow creating aliases a notification is printed. Example:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp alias create scolv1 scolv
|
|
error: module 'scolv' not found
|
|
|
|
After creating aliases, they may be configured and operated in the same way as
|
|
the original module.
|
|
|
|
.. warning::
|
|
|
|
The length of alias names for modules considering
|
|
:ref:`bindings<global_bindings_config>` is strictly limited to 20 characters.
|
|
|
|
When removing aliases, all links and the alias registration are removed but
|
|
possibly existing module or binding configurations remained unchanged. The
|
|
option :option:`--interactive` allows removing these configurations
|
|
interactively.
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp --interactive alias remove l1autopick
|
|
|
|
|
|
.. _sec_seiscomp_update:
|
|
|
|
Update configuration [*]_
|
|
-------------------------
|
|
|
|
The command :command:`update-config` allows reading bindings configurations from
|
|
the standard :file:`@KEYDIR@` directory as well as inventory from
|
|
:file:`@SYSTEMCONFIGDIR@/inventory` and sending them to the messaging for
|
|
storing in the database or for generating the configuration of
|
|
:term:`standalone modules <standalone module>`:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp update-config
|
|
|
|
Executing :command:`seiscomp update-config` involves:
|
|
|
|
* Merging inventory,
|
|
* Sending inventory updates to the messaging,
|
|
* Synchronisation of inventory, key files and bindings,
|
|
* Sending any updates of bindings to the messaging,
|
|
* Generation of configuration for :term:`standalone modules <standalone
|
|
module>`.
|
|
|
|
The command can therefore be rater time consuming. For speeding up you may be
|
|
more specific:
|
|
|
|
* Only update global bindings and all :term:`trunk` modules without inventory
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp update-config trunk
|
|
|
|
* Update only inventory
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp update-config inventory
|
|
|
|
* Update bindings of :ref:`scautopick` only
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp update-config scautopick
|
|
|
|
The command may be similarly applied to any other module considering
|
|
bindings.
|
|
|
|
.. note::
|
|
|
|
Instead of reading bindings configurations from the standard @KEYDIR@
|
|
directory, the module :ref:`bindings2cfg` can read bindings from any key
|
|
directory and write the Config parameters to :term:`SCML` or send them to
|
|
the messaging.
|
|
|
|
|
|
.. _sec_seiscomp_shell:
|
|
|
|
seiscomp Shell
|
|
==============
|
|
|
|
The seiscomp shell is a special environment, e.g., allowing to control
|
|
:term:`bindings <binding>` of :term:`modules <module>` to stations.
|
|
|
|
Applications are:
|
|
|
|
* Create or remove station bindings,
|
|
* Create or remove binding profiles,
|
|
* Remove binding profiles.
|
|
|
|
Invoke :program:`seiscomp` along with the :command:`shell` command to start the
|
|
shell:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp shell
|
|
|
|
|
|
================================================================================
|
|
SeisComP shell
|
|
================================================================================
|
|
|
|
Welcome to the SeisComP interactive shell. You can get help about
|
|
available commands with 'help'. 'exit' leaves the shell.
|
|
|
|
$
|
|
|
|
|
|
The full list of shell control commands are printed along with the help of the
|
|
seiscomp shell:
|
|
|
|
.. code-block:: sh
|
|
|
|
================================================================================
|
|
SeisComP shell
|
|
================================================================================
|
|
|
|
Welcome to the SeisComP interactive shell. You can get help about
|
|
available commands with 'help'. 'exit' leaves the shell.
|
|
|
|
$ help
|
|
Commands:
|
|
list stations
|
|
Lists all available stations keys.
|
|
|
|
list profiles {mod}
|
|
Lists all available profiles of a module.
|
|
|
|
...
|
|
|
|
|
|
.. note::
|
|
|
|
.. [*] With this command, the flag :option:`--invert` can be used
|
|
in order to invert the application to the specific modules. You may provide
|
|
one or more module names. A major application is to
|
|
restart most |scname| modules after a change in global bindings. However,
|
|
:ref:`seedlink` and :ref:`slarchive` are not affected by global
|
|
bindings and any downtime of these modules shall be avoided. Example:
|
|
|
|
.. code-block:: sh
|
|
|
|
seiscomp --invert restart seedlink slarchive
|
|
|
|
The same procedure could be achieved without :option:`--invert` by
|
|
explicitly stating all other modules which, however, may result in a
|
|
long list of module names.
|
|
|
|
|
|
|
|
Command-Line Options
|
|
====================
|
|
|
|
.. program:: seiscomp
|
|
|
|
:program:`seiscomp [flags] command(s) [argument(s)]`
|
|
|
|
|
|
Flags
|
|
-----
|
|
|
|
.. option:: --asroot
|
|
|
|
Allow running a command as root.
|
|
|
|
.. option:: --csv
|
|
|
|
Print output as CSV in machine\-readable format.
|
|
|
|
.. option:: -h, --help
|
|
|
|
Produce this help message.
|
|
|
|
.. option:: -i, --interactive
|
|
|
|
Interactive mode: Allow deleting configurations interactively when
|
|
removing aliases.
|
|
|
|
.. option:: --invert
|
|
|
|
Invert the selection of the specified module names when using any of the
|
|
commands: start, stop, check, status, reload, or restart.
|
|
|
|
.. option:: --wait arg
|
|
|
|
Define a timeout in seconds for acquiring the seiscomp lock
|
|
file, e.g., `seiscomp \-\-wait 10 update\-config`.
|
|
|