Dokumentation

Einrichtung

Voraussetzungen

Ein PostgreSQL-Datenbankserver ist erforderlich. Der Foreign Data Wrapper muss auf demselben Server installiert sein, auf dem der Server läuft, auf dem der Datenbankserver läuft.

Bitte behalten Sie das Standardverzeichnis PG_HOME unter /var/lib/pgsql bei und vermeiden Sie eine Verlagerung. Erstellen Sie außerdem keine zusätzlichen Einhängepunkte innerhalb dieses Verzeichnisses (z. B. das Einhängen von /var/lib/pgsql/17/data von einem anderen Gerät). Eine solche Änderung der Verzeichnisstruktur kann zukünftige PostgreSQL-Upgrades erheblich erschweren. Hängen Sie stattdessen /var/lib/pgsql direkt von einem anderen Gerät ein oder verwenden Sie zusätzliche Tablespaces, wie unten beschrieben.

Standardinstallation

RPM aus dem SKOOR-Repo installieren

Sollte StableNet FDW für eine bestimmte SKOOR-Major-Version (z. B. 8) installiert werden, verwenden Sie

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

Andernfalls verwenden Sie

dnf install "eranger-stablenet-fdw"

Um die SKOOR-Anwendung für die Verwendung des StableNet-FDW einzurichten, kann das Skript „init-data-source.py“ verwendet werden.

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.

Datenbankname, Eigentümer und Passwort sind standardmäßig „infosim“, der tablespace-root ist standardmäßig /var/lib/pgsql.

Anwendungsbeispiel:

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

Dieses Skript automatisiert den Einrichtungsprozess, indem es die folgenden Schritte ausführt:

  1. Konfiguriert SKOOR Auth und StableNet FDW durch Anwendung des Arguments „--webservice“.

  2. Richtet einen Tablespace unter dem durch „--tablespace-root“ angegebenen Pfad ein.

  3. Erstellt eine neue PostgreSQL-Datenbank innerhalb dieses Tablespace.

  4. Initialisiert die Fremdtabellen.

  5. Verbindet SKOOR als Datenquelle mit der neuen Datenbank.

  6. Importiert Synchronisationsskripte und Standarddatenabfragen.

Konfiguration

Nach einer Konfigurationsänderung muss der PostgreSQL-Server neu gestartet werden.

systemctl restart postgresql-17

Konfigurationsdatei

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

Mindestkonfiguration

Die folgenden Einstellungen müssen zwingend vorgenommen werden, um eine funktionsfähige Installation zu erhalten.

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

Bei einigen älteren Oracle-Versionen muss die Oracle-Client-Bibliothek auf dem System installiert sein. Installieren Sie diese mit dem neuesten Oracle Instant Client-Installationsprogramm und konfigurieren Sie den Pfad

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

Richten Sie einen Autossh-Tunnel für den Zugriff auf StableNet MySQL ein

Voraussetzung:

Der Tunnel wird nur benötigt, wenn die MySQL-Datenbankverbindung in der Datei „/opt/stablenet/snmw/wildfly/standalone/configuration/standalone.xml“ auf „localhost“ verweist. In diesem Fall läuft die Verbindung über den lokalen Tunnel-Endpunkt, der an den StableNet-Server weitergeleitet wird. Ist die StableNet-IP-Adresse dort direkt angegeben, wird der Tunnel umgangen und ist nicht erforderlich.

Wenn die StableNet-Datenbank auf demselben Server wie SKOOR eingerichtet ist, überspringen Sie diese Einrichtung einfach.

  1. Erstellen Sie einen SSH-Schlüssel für den Benutzer „skoor“ (legen Sie KEINE Passphrase fest):

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

  2. Drucken Sie den öffentlichen Schlüssel aus und kopieren Sie ihn:

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

  3. Melden Sie sich beim Ziel-Server (StableNet) an und fügen Sie den Schlüssel hinzu

    1. mkdir -p ~/.ssh

    2. chmod 700 ~/.ssh

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

    4. chmod 600 ~/.ssh/authorized_keys

    5. und melden Sie sich anschließend vom Ziel-Server ab

  4. Testen Sie die Anmeldung (vom SKOOR Server aus, keine Passwortabfrage)

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

  5. Installieren Sie autossh (auf dem SKOOR Server)

    1. sudo dnf install autossh

  6. Erstellen Sie eine systemd-Dienstdatei

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

    2. Hinweis: Überprüfen Sie zunächst den Pfad zu autossh mit dem Befehl „which autossh“ und fügen Sie das Ergebnis unter „ExecStart“ ein

[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. Dienst aktivieren und starten

    1. systemctl daemon-reload

    2. systemctl enable stablenet-mysql-tunnel

    3. systemctl start stablenet-mysql-tunnel

  2. Status prüfen

    1. systemctl status stablenet-mysql-tunnel

Ergebnis: Der lokale Port 3306 auf dem SKOOR Server wird über einen SSH-Tunnel an den MySQL-Port (3306) des StableNet-Servers weitergeleitet. Ersetzen Sie die Platzhalter <public-key> und <stablenet-ip> entsprechend.

Datenbankverbindung

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

Messung / Metrikfilterung

Um die Datenmenge zu begrenzen, die aus der StableNet-Datenbank synchronisiert werden muss, kann es sinnvoll sein, einige Filter zu konfigurieren oder bestimmte Messungstypen vollständig zu deaktivieren.

#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

Aufbewahrungsrichtlinien

Für jedes Aggregat kann festgelegt werden, wie lange die Daten gespeichert werden.

[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

Erweiterte Einstellungen

Es gibt noch zahlreiche weitere Optionen, mit denen sich das StableNet-FDW feinabstimmen lässt. Diese Einstellungen sind direkt in der Konfigurationsdatei beschrieben.

Verwendung von Umgebungsvariablen

Optionen können auch über Umgebungsvariablen mit dem Präfix „STABLENET_FDW_WEBSERVICE_“ und dem Optionsnamen in Großbuchstaben angegeben werden (z. B. „STABLENET_FDW_WEBSERVICE_URL“). Bei globalen Einstellungen muss „GLOBAL“ im ENV-Schlüssel weggelassen werden (z. B. „STABLENET_FDW_DEFAULT_USER“).

„url“ ist die Basis-URL des StableNet®-API-Webdienstes. Sie hat in der Regel die Form https://<host>:5443/api/1.

Mehrere StableNet-Server

Mehrere StableNet®-Instanzen können mithilfe mehrerer „webservice“-Abschnitte mit eindeutigen „server_id“-Suffixen definiert werden. Die „server_id“ dient als interne Kennung, um beispielsweise die passende Autorisierungszeichenfolge von SKOOR Auth abzurufen. Es sollte ein geeigneter „server_name“ festgelegt werden, der zur Identifizierung des Servers in den Fremd- und Aggregattabellen dient. Dies kann auch über Umgebungsvariablen konfiguriert werden (z. B. „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 = ...

Entsprechender Eintrag 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

Testen der Verbindung

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

Dies sollte die Anzahl der Geräte in der verbundenen StableNet®-Instanz zurückgeben.

Zurück
Einrichtung
Weiter
Update