Installazione

Prerequisiti

È richiesto un server di database PostgreSQL. Il foreign data wrapper deve essere installato sulla stessa istanza server su cui è in esecuzione il server di database.

Mantenere la directory predefinita PG_HOME in /var/lib/pgsql ed evitare di spostarla. Inoltre, non creare punti di mount aggiuntivi all'interno di questa directory (ad esempio, montando /var/lib/pgsql/17/data da un dispositivo diverso). La modifica del layout in questo modo può complicare notevolmente i futuri aggiornamenti di PostgreSQL. Montare invece /var/lib/pgsql direttamente da un altro dispositivo oppure utilizzare tablespace aggiuntivi come descritto di seguito.

Installazione standard

Installare l'RPM dal repository SKOOR

Se StableNet FDW deve essere installato per una versione Major specifica di SKOOR (ad es. 8), utilizzare

dnf install "eranger-stablenet-fdw-8.*"

Altrimenti utilizzare

dnf install "eranger-stablenet-fdw"

Per configurare l'applicazione SKOOR affinché utilizzi StableNet FDW, è possibile utilizzare lo script init-data-source.py.

python3 /opt/stablenet-fdw/init-data-source.py -h
usage: init-data-source.py [-h] -w WEBSERVICE [-t TABLESPACE_ROOT]
                           [-d DATABASE_CONNECTION]
                           [--database-name DATABASE_NAME]
                           [--database-owner DATABASE_OWNER]
                           [--database-password DATABASE_PASSWORD]

Initializes StableNet data source in Skoor

optional arguments:
  -h, --help            show this help message and exit
  -w WEBSERVICE, --webservice WEBSERVICE
                        StableNet webservice URL (usually something like
                        https://<host>:5443/api/1)
  -t TABLESPACE_ROOT, --tablespace-root TABLESPACE_ROOT
                        Root directory for PostgreSQL tablespace folders.
  --database-name DATABASE_NAME
                        PostgreSQL database name for StableNet FDW.
  --database-owner DATABASE_OWNER
                        PostgreSQL role/user owning the StableNet database.
  --database-password DATABASE_PASSWORD
                        Password for the PostgreSQL owner role.

Il nome del database, il proprietario e la password hanno come valore predefinito infosim; tablespace-root ha come valore predefinito /var/lib/pgsql.

Esempio di utilizzo:

sudo python3 /opt/stablenet-fdw/init-data-source.py -w https://<STABLENET_HOST>:5443/api/1

Questo script automatizza il processo di configurazione eseguendo le seguenti operazioni:

  1. Configura SKOOR Auth e StableNet FDW applicando l'argomento --webservice.

  2. Crea un tablespace nel percorso specificato da --tablespace-root.

  3. Crea un nuovo database PostgreSQL all'interno di tale tablespace.

  4. Inizializza le tabelle esterne.

  5. Connette SKOOR al nuovo database come origine dati.

  6. Importa gli script di sincronizzazione e le query dati standard.

Configurazione

Dopo una modifica della configurazione, è necessario riavviare il server PostgreSQL.

systemctl restart postgresql-17

File di configurazione

/etc/stablenet-fdw/stablenet-fdw.conf

Configurazione minima

Le seguenti impostazioni sono obbligatorie per ottenere un'installazione funzionante.

[global]
default_user =
                                        # Default user name for the StableNet® API.
                                        # This is used in case no authorization
                                        # is provided by the SQL client.
default_password =
                                        # Default password for the StableNet® API.
                                        # This is used in case no authorization
                                        # is provided by the SQL client.

Alcune versioni meno recenti di Oracle richiedono l'installazione della libreria client Oracle sul sistema. Installarla utilizzando il programma di installazione più recente di Oracle Instant Client e configurare il percorso

#oracle_client_lib_dir =
                                        # Path to the Oracle client library directory.
                                        # This is used to load the Oracle client library
                                        # for the Oracle database connection.
                                        # If omitted, the thin client is used which might have
                                        # problems connectiong to older Oracle databases.

Configurazione del tunnel autossh per l'accesso a StableNet MySQL

Prerequisito:

Il tunnel è necessario solo se la connessione al database MySQL in /opt/stablenet/snmw/wildfly/standalone/configuration/standalone.xml punta a localhost. In tal caso la connessione passa attraverso l'endpoint del tunnel locale, che viene inoltrato al server StableNet. Se invece vi è impostato direttamente l'IP di StableNet, il tunnel viene aggirato e non è necessario.

Se il DB StableNet è configurato sullo stesso server di SKOOR, saltare semplicemente questa configurazione.

  1. Generare la chiave SSH per l'utente skoor (NON impostare una passphrase):

    1. sudo -u eranger ssh-keygen -t ed25519

  2. Visualizzare e copiare la chiave pubblica:

    1. sudo -u eranger cat ~eranger/.ssh/id_ed25519.pub

  3. Accedere al server di destinazione (StableNet) e aggiungere la chiave

    1. mkdir -p ~/.ssh

    2. chmod 700 ~/.ssh

    3. echo "<public-key>" >> ~/.ssh/authorized_keys

    4. chmod 600 ~/.ssh/authorized_keys

    5. quindi disconnettersi dal server di destinazione

  4. Testare l'accesso (da SKOOR Server, senza richiesta di password)

    1. sudo -u eranger ssh <user>@<stablenet-ip>

  5. Installare autossh (su SKOOR Server)

    1. sudo dnf install autossh

  6. Creare il file di servizio systemd

    1. Percorso: /etc/systemd/system/stablenet-mysql-tunnel.service

    2. Nota: verificare prima il percorso di autossh con which autossh e inserire il risultato in ExecStart

[Unit]
Description=SSH tunnel to StableNet MySQL Database
After=sshd.service

[Service]
ExecStart=/bin/autossh -M 22023 -N -L 3306:localhost:3306 <user>@<stablenet-ip>
Restart=always
RestartSec=10
User=eranger

[Install]
WantedBy=multi-user.target
  1. Abilitare e avviare il servizio

    1. systemctl daemon-reload

    2. systemctl enable stablenet-mysql-tunnel

    3. systemctl start stablenet-mysql-tunnel

  2. Verificare lo stato

    1. systemctl status stablenet-mysql-tunnel

Risultato: la porta locale 3306 su SKOOR Server viene inoltrata tramite tunnel SSH alla porta MySQL (3306) del server StableNet. Sostituire di conseguenza i segnaposto <public-key> e <stablenet-ip>.

Connessione al database

[webservice]                            # use te form werbservice_<server_id>
                                        # to configure multiple StableNet® servers
                                        # (see below).
url =
                                        # URL of the StableNet® API
                                        # Usually something like https://<stablenet-host>:5443/api/1
database_connection =
                                        # Connection string to the StableNet® database.
                                        # This is used for the measurement data sync.
                                        # The connection string must be in the format:
                                        # MySQL: mysql+pymysql://<user>:<password>@<host>:3306/<database>
                                        # Oracle: oracle+oracledb://<user>:<password>@<host>:1521/?service_name=<service>
                                        # Connection info can be found on the StableNet server in
                                        # /opt/stablenet/snmw/wildfly/standalone/configuration/standalone.xml (<datasources>).
                                        # It's usually a good idea to use a different user and service than the one used by StableNet.

Filtro di misurazioni / metriche

Per limitare la quantità di dati che devono essere sincronizzati dal database StableNet, può essere opportuno configurare alcuni filtri o disattivare completamente alcuni tipi di misurazione.

#sync_ping_data = true
                                        # Sync ping measurement data from the StableNet® database.
                                        # Defaults to true.
#sync_snmp_data = true
                                        # Sync SNMP measurement data from the StableNet® database.
                                        # Defaults to true.
#sync_usrscript_data = true
                                        # Sync usrscript measurement data from the StableNet® database.
                                        # Defaults to true.
#sync_external_data = true
                                        # Sync external measurement data from the StableNet® database.
#sync_derived_data = false
                                        # Sync derived measurement data from the StableNet® database.
#ping_measurement_filter =
                                        # Filter for the ping measurement.
#snmp_measurement_filter =
                                        # Filter for the SNMP measurement.
#snmp_indexes =
                                        # List of SNMP indexes to be used for the SNMP measurement.
                                        # This is the number part of the metric key, e.g. #1234 -> 1234
#snmp_state_agg_measurements =
                                        # Comma separated list of template name / metric_key pairs of measurements
                                        # which should have state aggregation enabled.
                                        # Example: Interface Relative IPMPLS 64Bit#1234,template2#5678
#usrscript_measurement_filter =
                                        # Filter for the usrscript measurement.
#usrscript_indexes =
                                        # List of usrscript indexes to be used for the usrscript measurement.
                                        # This is the number part of the metric key, e.g. #1234 -> 1234
#usrscript_state_agg_measurements =
                                        # Comma separated list of template name / metric_key pairs of measurements
                                        # which should have state aggregation enabled.
                                        # Example: Interface Relative IPMPLS 64Bit#1234,template2#5678
#external_measurement_filter =
                                        # Filter for the external measurement.
#external_indexes =
                                        # List of external indexes to be used for the external measurement.
                                        # This is the number part of the metric key, e.g. #1234 -> 1234
#external_state_agg_measurements =
                                        # Comma separated list of template name / metric_key pairs of measurements
                                        # which should have state aggregation enabled.
                                        # Example: Y.1731#1234,template2#5678
#derived_measurement_filter =
                                        # Filter for the derived measurement.
#derived_indexes =
                                        # List of derived indexes to be used for the derived measurement.
                                        # This is the number part of the metric key, e.g. #1234 -> 1234
#derived_state_agg_measurements =
                                        # Comma separated list of template name / metric_key pairs of measurements
                                        # which should have state aggregation enabled.
                                        # Example: Y.1731#1234,template2#5678

Criteri di conservazione

È possibile configurare per quanto tempo vengono archiviati i dati per ciascun aggregato.

[retention_days]

#raw = 1
#minutely = 1
#5_minutely = 14
#15_minutely = 31
                                        # ~1 month
#hourly = 93
                                        # ~3 months
#daily = 365
                                        # ~1 years
#weekly = 365
                                        # ~1 years
#monthly = 1825
                                        # ~5 years
#quarterly = 1825
                                        # ~5 years
#yearly = 3650
                                        # ~10 years

Impostazioni avanzate

Esistono molte altre opzioni che possono essere utilizzate per ottimizzare StableNet FDW. Tali impostazioni sono descritte direttamente nel file di configurazione.

Utilizzo delle variabili d'ambiente

Le opzioni possono essere fornite anche tramite variabili d'ambiente utilizzando il prefisso STABLENET_FDW_WEBSERVICE_ e il nome dell'opzione in maiuscolo (ad es. STABLENET_FDW_WEBSERVICE_URL). Per le impostazioni global, GLOBAL deve essere omesso dalla chiave ENV (ad es. STABLENET_FDW_DEFAULT_USER ).

url è l'URL di base del servizio web API StableNet®. Solitamente ha il formato https://<host>:5443/api/1.

Più server StableNet

È possibile definire più istanze StableNet® utilizzando più sezioni webservice con suffissi server_id univoci. Il server_id viene utilizzato come identificatore interno, ad esempio per ottenere la stringa di autorizzazione corrispondente da SKOOR Auth. È necessario impostare un server_name appropriato, utilizzato per identificare il server nelle tabelle esterne e aggregate. Ciò può essere configurato anche utilizzando le variabili d'ambiente (ad es. STABLENET_FDW_WEBSERVICE_URL_TEST, STABLENET_FDW_WEBSERVICE_SERVER_NAME_TEST).

[webservice_production]
server_name = Production Server
url = https://stablenet.prod:5443/api/1
database_connection = ...

[webservice_staging]
server_name = Staging Server
url = https://stablenet.staging:5443/api/1
database_connection = ...

Voce corrispondente in SKOOR Auth (/etc/opt/eranger/eranger-auth.conf)

[provider.1]
type = stablenet
name = StableNet®
webservice_url_production = https://stablenet.prod:5443/api/1
webservice_url_staging = https://stablenet.staging:5443/api/1

Test della connessione

psql -h localhost -p 5432 -U infosim -d infosim -c "SELECT * from stablenet.stablenet_info;"

Questo comando dovrebbe restituire il numero di dispositivi nell'istanza StableNet® connessa.