StableNet® Foreign Data Wrapper (Enveloppeur de données étrangères)

Conditions préalables

Une base de données PostgreSQL avec un utilisateur autorisé à modifier les objets de la base de données est nécessaire. Le wrapper de données étrangères doit être installé sur la même instance de serveur que le serveur de base de données.

Exemple : Créer une base de données infosim appartenant au rôle infosim:

export DB_NAME=infosim
mkdir -p /var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/tab_space/${DB_NAME} \
 /var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/idx_space/${DB_NAME} && \
 chown -R postgres:postgres /var/lib/pgsql/custom/user_tblspc
psql -Upostgres -c "CREATE ROLE $DB_NAME WITH LOGIN PASSWORD '$DB_NAME';"
psql -Upostgres -c "CREATE TABLESPACE ${DB_NAME}_tab OWNER $DB_NAME \
LOCATION '/var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/tab_space/$DB_NAME';"
psql -Upostgres -c "CREATE TABLESPACE ${DB_NAME}_idx OWNER $DB_NAME \
LOCATION '/var/lib/pgsql/custom/user_tblspc/${DB_NAME}_tblspc/idx_space/$DB_NAME';"
psql -Upostgres -c "CREATE DATABASE $DB_NAME WITH OWNER $DB_NAME TEMPLATE template0 \
TABLESPACE ${DB_NAME}_tab ENCODING 'UTF8' LC_COLLATE 'de_CH.UTF-8' LC_CTYPE 'de_CH.UTF-8';"

Installation standard

Installer le RPM à partir de SKOOR Repo

dnf install eranger-stablenet-fdw

Configuration

Fichier de configuration

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

[global]

#accept_insecure_certificate = false
                                        # Accept insecure certificates
                                        # (self-signed, expired, etc.)
                                        # when connecting to the web service
default_user =
                                        # Default user name for the web service.
                                        # This is used in case no authorization
                                        # is provided by the SQL client.
default_password =
                                        # Default password for the web service.
                                        # This is used in case no authorization
                                        # is provided by the SQL client.
#skoor_auth_url = http://localhost:8094
                                        # URL of the SKOOR web service
                                        # (default: http://localhost:8094)
                                        # This is used to get the StableNet®
                                        # auth tokens.

#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.

#history_days = 365
                                        # Number of days the history data is loaded
                                        # from the StableNet® database.
                                        # Defaults to 365 days.

[database]

#host = localhost
                                        # Hostname of the PostgreSQL database
#port = 5432
                                        # Port of the PostgreSQL database
#database = infosim
                                        # Name of the PostgreSQL database
#user = infosim
                                        # User name of the PostgreSQL database
#password = infosim
                                        # Password of the PostgreSQL database
#schema = stablenet
                                        # Schema of the PostgreSQL database
                                        # (default: stablenet)
#measurement_data_table = stablenet_measurement_data
                                        # Name of the measurement data table
                                        # (default: stablenet_measurement_data)

[retention_days]

#raw = 1
#minutely = 1
#five_minutely = 14
#fifteen_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

[webservice]                            # use te form werbservice_<server_id>
                                        # to configure multiple StableNet® servers
                                        # (see below).

url =
                                        # URL of StableNet® the web service
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.
#ping_measurement_filter =
                                        # Filter for the ping measurement (e.g. 'Device Domain' eq 'Test').
#snmp_measurement_filter =
                                        # Filter for the SNMP measurement (e.g. 'Device Domain' eq 'Test').
#snmp_indexes =
                                        # List of SNMP indexes to be used for the SNMP measurement.

#[webservice_<server_id>]               # Optional, if multiple StableNet® servers
                                        # are used. Replace <server_id> with a unique
                                        # identifier for the StableNet® server.
                                        # Only alphanumeric lowercase characters are allowed.
                                        # Please note, that every webservice section
                                        # must have a unique identifier if multiple
                                        # StableNet® servers are used. if the server_id
                                        # changes, a resync of the measurement data is needed
                                        # because the measurement ID change (<measurment_id>@<server_id>).
                                        # If you already have a webservice configured without server_id,
                                        # then it's recommended to leave the existing webservice without
                                        # server_id and add a new webservice with server_id. This avoids
                                        # a resync of the measurement data.

#server_name =
                                        # Unique name of the connected StableNet®
                                        # server. This should be a human readable
                                        # name, not a technical identifier.
                                        # Defaults to server_id if omitted.
#url =
                                        # URL of the StableNet® the web service

Les options peuvent également être fournies par des variables d'environnement utilisant le préfixe STABLENET_FDW_WEBSERVICE_ et le nom de l'option en majuscules (par exemple STABLENET_FDW_WEBSERVICE_URL). Pour les paramètres de global, GLOBAL doit être omis de la clé ENV (par exemple STABLENET_FDW_DEFAULT_USER ).

url est l'URl de base du service web StableNet® API. Il se présente généralement sous la forme https://<host>:5443/api/1.

Plusieurs instances StableNet® peuvent être définies en utilisant plusieurs sections webservice avec des suffixes server_id uniques. Le server_id est utilisé comme identifiant interne pour, par exemple, obtenir la chaîne d'autorisation correspondante de SKOOR Auth. Un server_name approprié doit être défini pour identifier le serveur dans les tables étrangères et agrégées. Ceci peut également être configuré à l'aide de variables d'environnement (par exemple STABLENET_FDW_WEBSERVICE_URL_TEST, STABLENET_FDW_WEBSERVICE_SERVER_NAME_TEST).

Après un changement de configuration, le serveur PostgreSQL doit être redémarré.

systemctl restart postgresql-13

Initialisation des tables étrangères

Initialisation des tables étrangères nécessaires au wrapper de données étrangères.

/opt/stablenet-fdw/init-foreign-tables.sh -h <host> -p <port> -d <database> -U <user> -o <owner>

e.g.

/opt/stablenet-fdw/init-foreign-tables.sh -U postgres -h localhost -p 5432 -d infosim -o infosim

Cette commande doit être exécutée après chaque mise à jour de eranger-stablenet-fdw pour obtenir de nouvelles définitions de tables.

Test de la connexion

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

Cette commande devrait retourner le nombre d'appareils dans l'instance StableNet® connectée.

Agrégation de données (Déclassé)

Initialisation des données agrégées

Initialise l'hypertable Timescale nécessaire pour les données métriques agrégées.

/opt/stablenet-fdw/init-aggregated-data.sh -h <host> -p <port> -d <database> -U <user> -o <owner> \
-i <interval> [-m <metric_keys>] [-f <tag_filter>] [-r <retention>]

-m Liste séparée par des virgules de clés métriques à pré-agréger. Peut être omis pour précharger les données pour toutes les métriques, mais cela peut prendre beaucoup de temps. Par exemple "SNMP_1,SNMP_2,SNMP_3"

-i Intervalle de préchargement des données, par exemple 6 months, 1 week, 5 days

-f Filtre d'étiquettes pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"

-r Politique de conservation des données, par ex. "1 year"

Initialisation du rafraîchissement des données agrégées

Crée une tâche TimescaleDB pour mettre à jour périodiquement les données agrégées pour des mesures données.

/opt/stablenet-fdw/init-aggregated-data-refresher.sh -h <host> -p <port> -d <database> -U <user> -o <owner> \
[-m <metric_keys>][-f <tag_filter>]

-m Liste séparée par des virgules de clés de mesures à agréger. Peut être omis pour rafraîchir les données pour toutes les métriques. Par exemple "SNMP_1,SNMP_2,SNMP_3"

-f Filtre d'étiquette pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"

Ajouter / supprimer des mesures

Installation de Docker Compose

Configuration

Ajoutez les variables d'environnement suivantes à la section environnement des services eranger-postgresql du fichier SKOOR docker-compose.yaml et définissez la variable STABLENET_FDW_WEBSERVICE_URL à une URL valide de l'hôte StableNet :

      - STABLENET_FDW_WEBSERVICE_URL=https://<StableNet host>:5443/api/1
      - STABLENET_FDW_ACCEPT_INSECURE_CERTIFICATE=false
      - STABLENET_FDW_DEFAULT_USER=myuser
      - STABLENET_FDW_DEFAULT_PASSWORD=mypass
      - STABLENET_FDW_SKOOR_AUTH_URL=http://eranger-auth-${INSTANCE_NAME}:8094

Configuration du conteneur de service web

Le webservice doit être capable de communiquer avec le composant eranger-auth pour authentifier les requêtes à StableNet. Dans la section du service eranger-webservice, ajoutez la variable d'environnement suivante :

      - SKOOR_WEBSERVICE_auth_service_url=http://eranger-auth-${INSTANCE_NAME}:8094

Initialisation des tables étrangères

Dans le conteneur en cours d'exécution, lancer le script init-database.sh pour supprimer et recréer le schéma stablenet (attention : tous les objets du schéma sont supprimés !).

Exemple avec une base de données client nommée infosim avec l'utilisateur infosim (mettre la variable PGSQL_CONTAINER au nom du conteneur eranger-postgresql) :

export PGSQL_CONTAINER=eranger-postgresql-<instance>
docker exec $PGSQL_CONTAINER /opt/stablenet-fdw/init-foreign-tables.sh -h localhost \
-p 5432 -d infosim -U postgres -o infosim

Exécutez une requête de données dans le tableau de bord pour vérifier le wrapper de données étrangères :

SELECT * from stablenet.stablenet_info

Agrégation de données

Initialisation des données agrégées

Initialise l'hypertable Timescale nécessaire pour les données métriques agrégées.

docker exec $PGSQL_CONTAINER /opt/stablenet-fdw/init-aggregated-data.sh -h localhost \
-p 5432 -d infosim -U postgres -o infosim -i <interval> [-m <metric_keys>] [-f <tag_filter>] [-r <retention>]

-m Liste de clés métriques séparées par des virgules à pré-agréger. Peut être omis pour précharger les données de toutes les métriques, mais cela risque de prendre beaucoup de temps.

-i Intervalle de préchargement des données, par exemple 6 months, 1 week, 5 days

-f Tag filter pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"

-r Politique de conservation des données, par ex. "1 year"

Initialisation du rafraîchissement des données agrégées

Crée une tâche TimescaleDB pour mettre à jour périodiquement les données agrégées pour des mesures données.

docker exec $PGSQL_CONTAINER /opt/stablenet-fdw/init-aggregated-data-refresher.sh -h localhost \
-p 5432 -d infosim -U postgres -o infosim [-m <metric_keys>] [-f <tag_filter>]

-m Liste séparée par des virgules de clés de mesures à agréger. Peut être omis pour rafraîchir les données pour toutes les métriques. Par exemple "SNMP_1,SNMP_2,SNMP_3"

-f Filtre d'étiquette pour filtrer les mesures, par exemple "'Device Domain' eq 'Test'"

Intégration dans SKOOR

Le FDW StabeleNet peut être intégré en créant une nouvelle source de données dans la section Data & Objects.

image-20250423-054101.png

Après avoir sauvegardé, l'ampoule dans la navigation devrait devenir verte.

image-20240313-120727.png

Les tables étrangères peuvent être inspectées dans l'onglet Data .

image-20240313-121026.png

Alors que certaines tables étrangères peuvent être inspectées immédiatement (par exemple stablenet_taggable_device), d'autres requièrent des qualificatifs obligatoires et ne peuvent pas être visualisées. Voir le tableau ci-dessous pour les qualificatifs obligatoires.

Tables étrangères

Nom

Champs

Qualificatifs

stablenet_info

server_id TEXT
name TEXT
version TEXT
technical_version TEXT

stablenet_taggable

server_id TEXT
domain TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

domain TEXT (obligatoire)
id BIGINT
tag_filter TEXT

stablenet_taggable_device

server_id TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_interface

server_id TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_job

server_id TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_link

server_id TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_service

server_id TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_taggable_agent

server_id TEXT
id TEXT
name TEXT
display_name TEXT
state TEXT
attribute_tags JSONB
custom_tags JSONB
tag_filter TEXT

id BIGINT
tag_filter TEXT

stablenet_tag_category

server_id TEXT
domain TEXT
id TEXT
name TEXT
description TEXT

domain TEXT (obligatoire)
id BIGINT

stablenet_measurement

server_id TEXT
id TEXT
name TEXT
description TEXT
tags JSONB
dest_device_id TEXT
dest_interface_id TEXT
agent_id TEXT
start_time TIMESTAMPTZ
end_time TIMESTAMPTZ
state TEXT
type TEXT
template_name TEXT
permanent BOOL
payload JSONB
active BOOL
tag_filter TEXT

tag_filter TEXT
dest_device_id BIGINT

stablenet_measurement_metric

server_id TEXT
measurement_id TEXT
data_id BIGINT
description TEXT
expected_interval INT
key TEXT
name TEXT
only_average BOOL
unit TEXT

measurement_id BIGINT

stablenet_measurement_data

server_id TEXT
measurement_id TEXT
metric_key TEXT
metric_name TEXT
"start" TIMESTAMPTZ
"end" TIMESTAMPTZ
bucket_size INT (secondes)
"timestamp" TIMESTAMPTZ
min double precision
max double precision
avg double precision
tag_filter TEXT

measurement_id BIGINT
metric_key TEXT
"start" TIMESTAMPTZ (obligatoire)
"end" TIMESTAMPTZ (obligatoire)
bucket_size INT (obligatoire)
tag_filter TEXT

Bien que measurement_id et metric_key soient optionnels, il n'est pas recommandé d'exécuter des requêtes sans eux. En effet, les données de toutes les mesures et de toutes les métriques sont lues, ce qui peut prendre beaucoup de temps et alourdit la charge du serveur StableNet. Cela n'est conseillé que pour des périodes très courtes < 1h. Si plusieurs mesures et métriques sont nécessaires, le tableau stablenet_measurement_data_aggregated doit être utilisé.

Données de mesure agrégées

Agrégées par heure, mises à jour automatiquement toutes les heures. Peuvent être utilisées pour effectuer des requêtes analytiques sur un large éventail de mesures et sur de grandes plages de temps.

Il s'agit essentiellement d'une échelle de temps hypertable(https://docs.timescale.com/ ). La taille des blocs est de 7 jours, les blocs sont compressés après 7 jours.

Nom

Champs

stablenet_measurement_data_aggregated

server_name TEXT
measurement_id BIGINT
metric_key TEXT
metric_name TEXT
"timestamp" TIMESTAMPTZ NOT NULL
min double precision
max double precision
avg double precision

stablenet_measurement_data_aggregated contient uniquement des données pour les clés métriques configurées.