Documentation

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.

[webservice]  

url =
                                        # URL of StableNet® the web service

#[webservice_<server_id>]               # Optional, if multiple StableNet® servers 
                                        # are used. Replace <server_id> with a unique
                                        # identifier for the StableNet® server.
                                        # Only alphanumeric lower case characters are allowed.
                                        # Please note, that every webservice section 
                                        # must have a unique identifier if multiple 
                                        # StableNet® servers are used.

#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 des données

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 des 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-20240313-115126.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_name TEXT
name TEXT
version TEXT
technical_version TEXT

stablenet_taggable

server_name TEXT
domain TEXT
id BIGINT
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_name TEXT
id BIGINT
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_name TEXT
id BIGINT
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_name TEXT
id BIGINT
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_name TEXT
id BIGINT
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_name TEXT
id BIGINT
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_name TEXT
id BIGINT
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_name TEXT
domain TEXT
id BIGINT
name TEXT
description TEXT

domain TEXT (obligatoire)
id BIGINT

stablenet_measurement

server_name TEXT
id BIGINT
name TEXT
description TEXT
tags JSONB
dest_device_id BIGINT
dest_interface_id BIGINT
agent_id BIGINT
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_name TEXT
measurement_id BIGINT
data_id BIGINT
description TEXT
expected_interval INT
key TEXT
name TEXT
only_average BOOL
unit TEXT

measurement_id BIGINT

stablenet_measurement_data

server_name TEXT
measurement_id BIGINT
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, la table stablenet_measurement_data_aggregated doit être utilisée.

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.

Previous
L'interface utilisateur et les styles de StableNet
Next
Intégration de CashPilot