.. _sec-inst: Installation ============ This page describes the installation procedure of the :term:`GSS` server. Directory/File structure ------------------------ The :term:`GSS` server is usually installed within a |scname| environment. The following table shows the location of the :term:`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: .. note:: :program:`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 |gsmdata|. Make sure you have write permission in the specified directories. Install |appname| ----------------- #. Login as sysop (this is the user assumed throughout these instructions) #. Update the package list and install :ref:`GSS`, and other required or desired packages: .. code-block:: sh sysop@host:~$ cd $HOME/install/gsm sysop@host:~$ ./gsm update sysop@host:~$ ./gsm install gss-server .. _sec-inst-req: Install dependencies -------------------- The :term:`GSS` is based on the SeisComP framework and requires SeisComP base dependencies. The library dependencies can be installed as follows: #. Login as root #. Install dependencies .. code-block:: sh root@host:~# /home/sysop/seiscomp/bin/seiscomp install-deps base gss .. _sec-inst-req-ubuntu: By default the :term:`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 :term:`GSS` database must be created and permissions have to be granted to a user. .. _sec-inst-web-db-mariadb: MariaDB/MySQL ~~~~~~~~~~~~~ Create the database and set permissions .. code-block:: sh mysql -h localhost -u root -p mysql> CREATE DATABASE gss CHARACTER SET utf8mb4 COLLATE utf8mb4_bin; 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/hostname of the server. Also the database name, user and password may need to be modified. To allow access from all hosts, ``localhost`` can be replaced by ``'%'``. Load :term:`GSS` database schema .. code-block:: sh mysql -h localhost -u sysop -p -D gss < @ROOTDIR@/share/db/gss/mysql.sql .. _sec-inst-web-db-pgsql: PostgreSQL ~~~~~~~~~~ Create the datase and set permissions .. code-block:: sh 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 :term:`GSS` database schema .. code-block:: sh psql -h localhost -U sysop -W gss < @ROOTDIR@/share/db/gss/postgres.sql .. _sec-inst-be: SQLite3 ~~~~~~~ No database initialization is required for SQLite3. The server creates the database file and loads the :term:`GSS` database schema automatically if the database file does not exist. Configuration ============= This section describes the configuration of the :term:`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 :term:`GSS` backend are configured in the gss configuration files which follow the :term:`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: .. code-block:: sh 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 :term:`GSS` simulation profiles come into play. Simulation profiles allow to define simulation parameters for a specific backend and region on :term:`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 :ref:`gsm ` to install a set of predefined example source region files: .. code-block:: sh sysop@host:~$ cd install/gsm sysop@host:~$ ./gsm install sourceregions Using :program:`scconfig`, in :term:`GSS` -> profiles add a *Simulation profile* and configure the parameters. * :confval:`profiles.$name.backend` - Simulation backend to be used for this profile * :confval:`profiles.$name.aoi` - (Area Of Interest) Path to BNA or GeoJSON file * :confval:`profiles.$name.parameters` - Comma separated key/value pairs of simulation parameters, e.g., :confval:`maxTime:120` or :confval:`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: :confval:`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). .. code-block:: sh 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 :ref:`black line `, and the outline of the default bathymetry associated with this sourceRegion is :ref:`shown in green `. .. _fig-source_regions: .. figure:: media/install/source_region.png :align: center :width: 18 cm Source region (black line) and default bathymetry outline (green) .. _note-show_bna: .. note:: To show source regions as black lines in |scname| 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 |scname| map applications, e.g., scmv or TOAST. This subsection describes how to create a new region file with |scname|. #. 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. #. Then right-mouse click -> Measurements -> Save as BNA/geoJSON File. To save in `GeoJSON `_ format use the filename extension *.geojson*. Database -------- The :term:`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 .. code-block:: sh GSS.database=mysql://sysop:sysop@localhost/gss PostgreSQL .. code-block:: sh GSS.database=postgresql://sysop:sysop@localhost/gss SQLite3 .. code-block:: sh GSS.database=@ROOTDIR@/var/lib/gss/archive/simulations.db Interfaces ---------- The :term:`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) ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: sh # 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 :term:`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. .. code-block:: sh # 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: .. code-block:: sh # 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: .. code-block:: sh # 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 :term:`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 .. code-block:: sh 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.