Documentazione

Installazione

Prerequisiti

È necessario un server di database PostgreSQL. Il wrapper per dati esterni deve essere installato sulla stessa istanza del server su cui è in esecuzione il server di database.

Si prega di mantenere la directory predefinita PG_HOME in /var/lib/pgsql ed evitare di spostarla. Inoltre, non creare punti di montaggio aggiuntivi all'interno di questa directory (ad esempio, montando /var/lib/pgsql/17/data da un dispositivo diverso). Modificare la struttura in questo modo può complicare significativamente 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 il pacchetto RPM dal repository SKOOR

Se è necessario installare StableNet FDW per una versione Major specifica di SKOOR (ad es. la 8), utilizzare

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

Altrimenti utilizzare

dnf install "eranger-stablenet-fdw"

Per configurare l’applicazione SKOOR in modo che 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 sono impostati di default su infosim, mentre tablespace-root è impostato di default su /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 dall'--tablespace-root.

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

  4. Inizializza le tabelle esterne.

  5. Collega SKOOR al nuovo database come origine dati.

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

Configurazione

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

systemctl restart postgresql-17

File di configurazione

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

Configurazione minima

Per garantire il corretto funzionamento dell’installazione, è obbligatorio impostare le seguenti opzioni.

[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 precedenti di Oracle richiedono che la libreria client Oracle sia installata 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.

Configurare il tunnel autossh per l'accesso a MySQL su StableNet

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 l'IP di StableNet è impostato direttamente in quel file, il tunnel viene bypassato e non è necessario.

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

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

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

  2. Stampa e copia 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. Verifica l'accesso (dal SKOOR Server, senza richiesta di password)

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

  5. Installare autossh (sul SKOOR Server)

    1. sudo dnf install autossh

  6. Crea il file di servizio systemd

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

    2. Nota: verificare prima il percorso di autossh con il comando `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. Verifica lo stato

    1. systemctl status stablenet-mysql-tunnel

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

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.

Filtraggio delle misurazioni / metriche

Per limitare la quantità di dati da sincronizzare dal database StableNet, potrebbe essere utile 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 i dati vengono conservati 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 numerose altre opzioni che possono essere utilizzate per ottimizzare il funzionamento del FDW di StableNet. Tali impostazioni sono descritte direttamente nel file di configurazione.

Utilizzo delle variabili d’ambiente

Le opzioni possono essere specificate 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 globali, è necessario omettere GLOBAL dalla chiave ENV (ad es. STABLENET_FDW_DEFAULT_USER).

url è l’URL di base del servizio web dell’API StableNet®. Di solito ha la forma https://<host>:5443/api/1.

Più server StableNet

È possibile definire più istanze di StableNet® utilizzando più sezioni «webservice» con suffissi «server_id» univoci. L’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, che verrà utilizzato per identificare il server nelle tabelle esterne e aggregate. Ciò può essere configurato anche tramite 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

Verifica della connessione

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

Questo dovrebbe restituire il numero di dispositivi presenti nell’istanza StableNet® connessa.

Precedente
Installazione
Successivo
Aggiornamento