Installation

This page describes the installation procedure of the GSS server.

Directory/File structure

The GSS server is usually installed within a SeisComP environment. The following table shows the location of the GSS bundle:

Location

Description

@ROOTDIR@/bin/gss

Binary of the back-end server

@DATADIR@/plugins

Location of the simulation plugins, e.g., EasyWave2

/home/data/forecastzones

Location of the forecast zones and points, e.g., RTSP

/home/data/sourceregions

Location of the source regions definitions

Note

gsm (gempa software manager) is a command line tool for handling software packages. Execute ./gsm -h to list options and consult the file README to get further information. After initial setup of gsm with ./gsm setup, the file gsm.conf contains the configured parameters. Re-run setup or edit gsm.conf with a text editor to make modifications. By default, bathymetry, forecast zones, source regions, etc. are installed at /home/data. Make sure you have write permission in the specified directories.

Install gss

  1. Login as sysop (this is the user assumed throughout these instructions)

  2. Update the package list and install GSS, and other required or desired packages:

    sysop@host:~$ cd $HOME/install/gsm
sysop@host:~$ ./gsm update
sysop@host:~$ ./gsm install gss-server

Install dependencies

The GSS is based on the SeisComP framework and requires SeisComP base dependencies. The library dependencies can be installed as follows:

  1. Login as root

  2. Install dependencies

    root@host:~# /home/sysop/seiscomp/bin/seiscomp install-deps base gss

By default the GSS uses SQLite3 as database backend. If a different database backend should be used it must be installed and configured separately. The installation and configuration of common used database backends like

  • MariaDB

  • MySQL

  • PostgreSQL

is described here.

Database Initialization

The GSS database must be created and permissions have to be granted to a user.

MariaDB/MySQL

Create the database and set permissions

mysql -h localhost -u root -p
mysql> CREATE DATABASE gss CHARACTER SET utf8mb4;
mysql> GRANT USAGE ON gss.* TO sysop@localhost IDENTIFIED BY 'sysop';
mysql> GRANT ALL PRIVILEGES ON gss.* TO sysop@localhost;

If the MySQL server resides on a different machine, localhost must be replaced by the IP of the server. Also the database name, user and password may need to be modified.

Load GSS database schema

mysql -h localhost -u sysop -p -D gss < @ROOTDIR@/share/db/gss/mysql.sql

PostgreSQL

Create the datase and set permissions

sudo -u postgres -i
createuser -P -d sysop
   Enter password for new role:
   Enter it again:
   Shall the new role be a superuser? (y/n) n
   Shall the new role be allowed to create more new roles? (y/n) n
createdb -O sysop gss
exit

Load GSS database schema

psql -h localhost -U sysop -W gss < @ROOTDIR@/share/db/gss/postgres.sql

SQLite3

No database initialization is required for SQLite3. The server creates the database file and loads the GSS database schema automatically if the database file does not exist.

Configuration

This section describes the configuration of the GSS. The first subsection describes necessary configuration steps for running the server. The following sections cover advanced configuration options, e.g., SSL encryption. The parameters controlling the GSS backend are configured in the gss configuration files which follow the SeisComP configuration schema.

Basic

Load simulation backend plugins that provide tsunami simulation results, e.g. SSH max grids or arrival times. The following example adds the EasyWave2 On-the-fly simulation backend to the plugin list that the server loads at start:

plugins = ${plugins},simeasywave2

More simulation backends can be added in the same way.

Simulation profiles: backend, parameters and source regions

Simulation backends may have specific parameters, e.g., the maximum simulation time or a bathymetry file. Some of them can be configured in the backend configuration but the values then apply to all automatic simulations.

There are use cases where this is not enough. This is where GSS simulation profiles come into play. Simulation profiles allow to define simulation parameters for a specific backend and region on GSS level. Regions can be defined in BNA or GeoJSON format. The regions must not overlap each other. With the simulation profiles it is possible, for example, to calculate a simulation for one region for 2 hours and to set a different simulation time for another region. Or to preselect bathymetry files for certain regions.

Use gsm to install a set of predefined example source region files:

sysop@host:~$ cd install/gsm
sysop@host:~$ ./gsm install sourceregions

Using scconfig, in GSS -> profiles add a Simulation profile and configure the parameters.

  • profiles.$name.backend - Simulation backend to be used for this profile

  • profiles.$name.aoi - (Area Of Interest) Path to BNA or GeoJSON file

  • profiles.$name.parameters - Comma separated key/value pairs of simulation parameters, e.g., maxTime:120 or preferredGrid:io_rtsp. The preferredGrid expects the name of the bathymetry without file name ending. In the TOAST Simulation Setup dialog in the Simulation backends tab, when availabe it is highlighted with a star.

Register the profile at: profiles.

The following example shows how to register simulation profile taking the example of a source region for the Indian Ocean. The entries are evaluated in FIFO order. If none of the entries matches, the algorithm tries to select a fallback grid (Simulation backend dependent).

GSS.profiles = IndianOcean

GSS.profiles.IndianOcean.backend = EasyWave2
GSS.profiles.IndianOcean.aoi = /home/data/sourceregions/IndianOcean.bna
GSS.profiles.IndianOcean.parameters = peferredGrid:io_rtsp, maxTime:240

In the following figure, the sourceRegion defined in the profile above is shown as black line, and the outline of the default bathymetry associated with this sourceRegion is shown in green.

../_images/source_region.png

Figure 35: Source region (black line) and default bathymetry outline (green)

Note

To show source regions as black lines in SeisComP map applications, register the source region files as described here.

Custom regions

Source region files can be created with a text editor, GIS tools or with SeisComP map applications, e.g., scmv or TOAST. This subsection describes how to create a new region file with SeisComP.

  1. Click and hold the CTRL-key and do a series of left-mouse clicks. On the lower left you can see total length and area covered by the polygon.

  2. Then right-mouse click -> Measurements -> Save as BNA/geoJSON File. To save in GeoJSON format use the filename extension .geojson.

Database

The GSS stores meta information about requests and computed simulations in a database. Simulation products like grids are managed by the simulation backends. By default the server uses a SQLite3 database for storing the data which is created automatically if it does not exist. This subsection describes how to change the database backend. Supported database backends are MysQL, PostgreSQL and SQLite3. The database connection string follows the :term:`SeisComP’ schema service://user:password@host/db. Below are example configurations for the different database backends:

MySQL

GSS.database=mysql://sysop:sysop@localhost/gss

PostgreSQL

GSS.database=postgresql://sysop:sysop@localhost/gss

SQLite3

GSS.database=@ROOTDIR@/var/lib/gss/archive/simulations.db

Interfaces

The GSS functionality can be accessed via Telnet and/or HTTP protocol. The following table shows a possible port mapping for the different interfaces.

Port

Description

19010

Data port

19011

Encrypted data port

19080

HTTP interface providing a REST API and browse capability

19443

Encrypted HTTP interface

The port configuration can be changed as follows. By default SSL is not enabled.

Non secure (Default setup)

# Defines the server port for client requests.
GSS.port = 19010

    # Port to listen for HTTP request. Recommended HTTP port is 19080.
GSS.http.port = 19080

Secure sockets layer (SSL)

The Secure Sockets Layer (SSL) is a standard for establishing a secured communication between applications using insecure networks. Neither client requests nor server responses are readable by communication hubs in between. SSL is based on a public-key infrastructure (PKI) to establish trust about the identity of the communication counterpart. The concept of a PKI is based on public certificates and private keys.

To enable SSL in GSS the GSS.SSL.port as well as the location of the GSS.SSL.certificate and GSS.SSL.key file must be specified. Optionally the unencrypted GSS.port may be deactivated by setting a value of -1.

# Defines the SSL server port for client requests. By default SSL requests are
# disabled. Recommended SSL port is 19011.
GSS.SSL.port = 19011

# Port to listen for HTTPS request. Recommended HTTPS port is 19443.
GSS.https.port = 19443

# Defines the path to the SSL certificate to use.
GSS.SSL.certificate = @CONFIGDIR@/ssl/gss-cert.pem

# Defines the path to the private SSL key to use. This key is not shared with
# clients.
GSS.SSL.key = @CONFIGDIR@/ssl/gss-key.pem

In addition, the minimum supported SSL protocol version and the available ciphers can be configured as follows:

# Sets the minimum supported protocol version, e.g., TLSv1.2 or TLSv1.3.
GSS.SSL.minVersion = TLSv1.2

# Sets the list of available ciphers for TLSv1.2 and below. The format of the
# cipherList and expamples are provided at detail at
# https://www.openssl.org/docs/man3.1/man1/openssl-ciphers.html , e.g. ,
# ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384:AES256-SHA. The tool sslscan
# can be used to check the configured ciphers, e.g., sslscan --tls12
# localhost:19443
GSS.SSL.cipherList = ECDHE-RSA-AES256-GCM-SHA384:AES256-GCM-SHA384:AES256-SHA

# Sets the list of available ciphers for TLSv1.3 and above. The format and
# examples are provided at
# https://www.openssl.org/docs/man3.1/man1/openssl-ciphers.html , e.g.
# ,TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256. The tool sslscan can be
# used to check the configured ciphers, e.g., sslscan --tls12 localhost:19443
GSS.SSL.cipherSuites = TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256

Note

Even the server has built-in SSL support it is recommended to let a proxy server like nginx do the SSL handling. This has the following advantages:

  • The SSL certificate is in one place if more than one service is proxied

  • More advanced SSL configuration are available

HTTP security policy headers

Modern web applications using HTTP response headers to transmit security policies to the browser. By passing these security policies back to the client, web applications can ensure a much safer experience for their visitors and reduce the risk of successful attacks. By default the GSS server adds no security policies to HTTP responses since the requirements can change. Instead, additional HTTP headers can be set in the configuration as follows:

# Comma separated list of additional HTTP headers added to HTTP responses,
# e.g., X-Frame-Options: DENY. This option can be used to implement custom HTTP
# security policies.
GSS.http.additionalHeaders = X-Frame-Options: DENY

Note

It is recommend to implement the HTTP security policies in a proxy server like nginx.

Authentication

The GSS supports client authentication via OpenSSL certificates for SSL enabled interfaces. By default no client certificate is required to access the server. Set the option GSS.verifyPeer as follows

GSS.verifyPeer = true

to force client authentication. If the client validation fails the the access is forbidden.

Note

The OpenSSL client certificate must been signed with the corresponding OpenSSL server certificate.