Checkmk
to checkmk.com

1. Einleitung

Checkmk bietet Ihnen umfangreiche Möglichkeiten Oracle-Datenbanken zu überwachen. So können Sie mit dem Plugin nicht nur Tablespaces oder die aktiven Sitzungen einer Datenbank abrufen, sondern zusätzlich noch viele andere Metriken. Eine vollständige Liste der Überwachungsmöglichkeiten können Sie in unserem Katalog der Check-Plugins nachlesen. Wir erweitern diese Plugins regelmäßig, so dass sich ein Blick in den Katalog immer wieder lohnt. Unter anderem kann Checkmk die folgenden Werte überwachen:

Um die Datenbanken überwachen zu können, brauchen Sie lediglich das Agentenplugin zusätzlich zu dem Agenten auf dem Datenbankserver. Unterstützt werden dafür zur Zeit die Betriebssysteme Linux, AIX, Solaris, HP-UX und Windows. Zusätzliche Software wird weder auf der Checkmk-Instanz noch auf dem Datenbankserver für eine Überwachung benötigt.

Viele Schritte, um die Überwachung einzurichten, sind zwischen Linux und Windows gleich. Aus diesem Grund werden zunächst die allgemeinen Schritte beschrieben und danach die spezifischen für die jeweilige Betriebssystemgruppe. Bitte beachten Sie, dass die Einrichtung mittels der Agentenbäckerei derzeit nur für Linux, Solaris und AIX zur Verfügung steht.

2. Allgemeine Schritte zur ersten Einrichtung

2.1. Benutzer anlegen

Prinzipiell ist die erste Einrichtung schnell und in nur drei Schritten erledigt. Der erste Schritt ist natürlich sicherzustellen, dass es einen Benutzer gibt, welcher die Datenbanken auch abfragen darf. Sofern Sie keine RAC nutzen, legen Sie dafür auf jeder zu überwachenden Datenbank einen Benutzer an. Wie Sie sich auf einer Instanz einloggen, unterscheidet sich je nachdem, welches Betriebssystem Sie einsetzen. Für Linux können Sie das zum Beispiel erledigen, indem Sie zuerst immer die jeweilige Instanz als Umgebungsvariable setzen, für die ein Benutzer angelegt werden soll. Normalerweise wechselt man dafür zuvor auf den oracle-Benutzer. Das kann sich aber je nach Setup unterscheiden:

root@linux# su - oracle
oracle@myhost$ export ORACLE_SID=MYINST1

Danach loggen Sie sich auf der Instanz ein und legen einen Benutzer für das Monitoring an. Um an alle Daten zu kommen, werden auch die nachfolgenden Berechtigungen benötigt. In dem folgendem Beispiel heißt der neu angelegte Benutzer checkmk. Sie können auch jeden anderen Namen wählen:

sqlplus> create user checkmk identified by myPassword;
sqlplus> grant select_catalog_role to checkmk;
sqlplus> grant create session to checkmk;
sqlplus> connect checkmk/myPassword
sqlplus> exit

Wie die Anmeldung an einer bestimmten Instanz genau funktioniert, können Sie in der Oracle-Dokumentation nachlesen.

Multi-Tenant-Datenbanken

Man kann auch den Login für Multi-Tenant-Datenbanken konfigurieren. Das wird normalerweise mit einem speziellen Benutzer und in der Konfiguration mit dem Präfix C## durchgeführt. Die Berechtigungsvergabe unterscheidet sich jedoch leicht von der Anleitung für normale Nutzer, da Sie diese für alle jetzigen und zukünftigen Container festlegen:

sqlplus> create user c##checkmk identified by myPassword;
sqlplus> alter user c##checkmk set container_data=all container=current;
sqlplus> grant select_catalog_role to c##checkmk container=all;
sqlplus> grant create session to c##checkmk container=all;
sqlplus> exit

2.2. Konfiguration und Benutzer anlegen

Nachdem Sie einen Benutzer angelegt haben, sorgen Sie als Zweites dafür, dass das Agentenplugin später diese Informationen auch bekommt. Die einfachste Möglichkeit ist es dann, wenn Sie für alle Instanzen die gleichen Login-Daten gesetzt haben und einen Standard in der Konfiguration setzen können. Legen Sie also nun auf dem Oracle-Host eine Konfigurationsdatei für Linux, AIX, Solaris oder für Windows an. In dem folgenden Beispiel sehen Sie die Datei für die unixoiden Systeme:

/etc/check_mk/mk_oracle.cfg
# Syntax:
# DBUSER='USERNAME:PASSWORD'
DBUSER='checkmk:myPassword'

Für Windows sieht das sehr ähnlich aus. Hier setzen Sie die Variable in einem PowerShell-Skript:

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1
# Syntax:
# $DBUSER = @("USERNAME","PASSWORD")
$DBUSER = @("checkmk","myPassword")

Der Standardbenutzer ist das Einzige, was das Plugin zwingend benötigt. Alle anderen Einstellungen, die Sie unter unixoiden Systemen oder unter Windows verwenden können, sind optional.

2.3. Konfiguration auf den Host bringen

Nachdem Sie nun also einen Benutzer angelegt und diesen in der Konfigurationsdatei hinterlegt haben, bringen Sie noch das Plugin in das richtige Verzeichnis des Agenten. Wie der Pfad für Agentenplugins korrekt lautet, wird in den Artikeln zu Linux und Windows beschrieben. Für Solaris und AIX können Sie in der Regel den gleichen Pfad nutzen wie unter Linux.

Achtung: Das Oracle-Plugin verträgt sich nicht gut mit systemd (siehe Werk #13732). Auf Systemen mit systemd müssen Sie das Plugin daher asynchron ausführen lassen. Das heißt, Sie installieren das Plugin nicht unter /usr/lib/check_mk_agent/plugins direkt, sondern in einem Unterordner /usr/lib/check_mk_agent/plugins/ZAHL. ZAHL meint dabei das Ausführungsintervall in Sekunden, wir empfehlen die minütliche Ausführung, also /usr/lib/check_mk_agent/plugins/60. Bei der Einrichtung über die Agentenbäckerei erledigen Sie das freilich über die Option Host uses xinetd or systemd in der Oracle-Regel; standardmäßig ist hier xinetd vorgegeben.

Achten Sie unter Linux (und auch unter AIX oder Solaris) darauf, dass das Plugin ausführbar ist und korrigieren Sie das gegebenenfalls:

root@linux# cd /usr/lib/check_mk_agent/plugins/
root@linux# ls -lA
-rw-r--r-- 1 root root 120808 Jan 25 11:29 mk_oracle
root@linux# chmod +x mk_oracle
root@linux# ls -lA
-rwxr-xr-x 1 root root 120808 Jan 25 11:29 mk_oracle

2.4. Oracle-Wallet nutzen

Alternativ dazu, den Benutzer direkt und mit Passwort in einer Konfigurationsdatei anzugeben, können Sie auch das Oracle-Wallet nutzen. Das hat den Vorteil, dass Sie nicht mehr die Zugangsdaten unverschlüsselt sowohl auf dem Checkmk-Server als auch auf dem Oracle-Host ablegen müssen. Denn selbst wenn Sie die Rechte der Konfigurationsdatei auf dem Oracle-Host entsprechend angepasst haben, haben die Zugangsdaten dennoch den Server verlassen und befinden sich auf dem Checkmk-Server, sofern Sie die Agentenbäckerei nutzen.

Das Oracle-Wallet wiederum legt die Zugangsdaten verschlüsselt auf dem zu überwachenden Host ab, so dass sie benutzt werden können, aber keine Logindaten explizit bekannt gemacht werden müssen. Checkmk kann dieses Wallet nutzen, so dass die Zugangsdaten prinzipiell nur dem Datenbankadministrator (DBA) bekannt sein müssen. Dazu legen Sie — oder der DBA — ein Wallet auf dem entsprechenden Server an:

root@linux# mkstore -wrl /etc/check_mk/oracle_wallet -create

Auf diese Datei wird das Plugin später immer dann zugreifen, wenn eine Verbindung zu einer Instanz hergestellt werden soll. Damit die nötigen Benutzerdaten auch gefunden werden, müssen Sie diese einmalig in das Wallet eintragen. In dem folgenden Beispiel fügen Sie also den Benutzer checkmk für die Instanz MYINST1 hinzu:

root@linux# mkstore -wrl /etc/check_mk/oracle_wallet -createCredential MYINST1 check_mk myPassword

Damit das Plugin weiß, wo es nach dem Wallet suchen muss, muss es zwei Dateien finden. Die erste Datei ist die sqlnet.ora in welcher hinterlegt wird, wo das Wallet zu finden ist. Die zweite Datei — tnsnames.ora bestimmt die Adresse der Instanz, so dass diese auch über ihren Alias angesprochen werden kann. Damit das Agentenplugin diese Dateien findet, können Sie den Pfad unter Linux, Solaris und AIX über die erweiterte Variable TNSALIAS setzen. Das ist vor allem dann von Vorteil, wenn die Dateien bereits existieren. Alternativ können Sie sie auch explizit anlegen. Unter Windows ist es sogar erforderlich, dass Sie diese manuell bestimmen.

Legen Sie zunächst die Datei sqlnet.ora an. In dieser Datei sucht das Plugin alternativ nach den Zugangsdaten, so dass hier also der korrekte Pfad zu der eben erstellten Wallet-Datei angegeben werden muss. Achten Sie dabei darauf, dass Sie den Parameter SQLNET.WALLET_OVERRIDE auf TRUE setzen:

/etc/check_mk/sqlnet.ora
LOG_DIRECTORY_CLIENT = /var/log/check_mk/oracle_client
DIAG_ADR_ENABLED = OFF

SQLNET.WALLET_OVERRIDE = TRUE
WALLET_LOCATION =
 (SOURCE=
   (METHOD = FILE)
   (METHOD_DATA = (DIRECTORY=/etc/check_mk/oracle_wallet))
 )

Jetzt weiß das Plugin, welche Zugangsdaten benutzt werden sollen. Damit es auch die korrekte Adresse ansteuert, legen Sie als zweite Datei die tnsnames.ora an. Beispiele zu einer Konfiguration finden Sie auf dem Checkmk-Server und auch auf dem Oracle-Host. Die genaue Syntax können Sie der Oracle-Dokumentation entnehmen, aber als Beispiel könnte die Datei so aussehen:

/etc/check_mk/tnsnames.ora
MYINST1
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = 127.0.0.1)(PORT = 1521))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = MYINST1_ALIAS)
    )
  )

Mit diesem letzten Schritt haben Sie die Voraussetzungen geschaffen, um die Zugangsdaten aus der Konfigurationsdatei des Agentenplugins herauszunehmen. Stattdessen tragen Sie lediglich ein / (Schrägstrich) ein:

/etc/check_mk/mk_oracle.cfg
DBUSER='/:'

Sie können dem Wallet natürlich zu einem späteren Zeitpunkt weitere Zugangsdaten hinzufügen. Lediglich die Datei tnsnames.ora muss dann gegebenenfalls erweitert werden.

3. Linux, AIX, Solaris

3.1. Plugin- und Konfigurationspfade

Unter unixoiden Systemen verwendet Checkmk ein einheitliches Plugin. Das reduziert zum einen den Aufwand der Pflege, da SQL-Abfragen nicht dupliziert werden müssen, und sorgt zum anderen dafür, dass Sie nur ein einziges Plugin zu beachten haben. Auf allen unterstützten Systemen sind die Pfade für die Agenten gleich oder sehr ähnlich. Konkret benötigen Sie die folgenden Verzeichnisse, wenn Sie diese nicht verändert haben:

OS Plugin-Pfad Konfigurationspfad

Linux, Solaris, UNIX

/usr/lib/check_mk_agent/plugins/

/etc/check_mk/

Linux mit systemd

/usr/lib/check_mk_agent/plugins/<Zahl>

/etc/check_mk/

AIX

/usr/check_mk/lib/plugins/

/usr/check_mk/conf/

3.2. Erweiterte Optionen

In der allgemeinen Einrichtung haben Sie bereits erste Variablen kennengelernt, um Überwachungsdaten von Ihren Oracle-Instanzen zu bekommen. Je nach Anwendungsszenario werden Sie aber schnell weitere Möglichkeiten benötigen, um die Überwachung besser und individuell pro Instanz steuern zu können.

Erweiterte Benutzerkonfiguration

Mit dem Standardlogin können Sie reguläre oder vielleicht sogar alle Instanzen einer Datenbank abfragen. Es gibt jedoch Sonderfälle, in denen Sie für einzelne Instanzen individuelle Zugangsdaten benötigen. Bei der Konfigurationsdatei haben Sie daher die folgenden drei Möglichkeiten, Benutzer anzugeben:

Parameter Beschreibung

DBUSER

Der Standard, wenn keine individuellen Zugangsdaten für die Datenbankinstanz definiert sind.

DBUSER_MYINST1

Zugangsdaten für eine ganz bestimmte Datenbankinstanz. In diesem Fall für die Instanz MYINST1. Die Logindaten werden nur für diese SID benutzt.

ASMUSER

Spezielle Zugangsdaten für das Automatic Storage Management (ASM).

Wichtig: Für ein ASM kann immer nur ein Login angegeben werden.

Zusätzlich erlauben diese Variablen noch mehr Optionen außer Benutzername und Passwort. Sie können auch bestimmen, ob es sich bei dem Benutzer um einen SYSDBA oder SYSASM handelt, auf welcher Kombination von Adresse und Port die Instanz lauscht und sogar, welcher TNSALIAS benutzt werden soll. Diese Angaben sind aber immer — im Gegensatz zu Benutzer und Passwort — optional. Zusätzlich zu dem obigen Beispiel kann eine Konfiguration dann so aussehen:

/etc/check_mk/mk_oracle.cfg
# Syntax
# DBUSER='USERNAME:PASSWORD:ROLE:HOST:PORT:TNSALIAS'
DBUSER='checkmk:myPassword'

DBUSER_MYINST1='cmk_specific1:myPassword1:SYSDBA:localhost:1521'
DBUSER_MYINST2='cmk_specific2:myPassword2::localhost::INST2'

ASMUSER='cmk_asm:myASMPassword:SYSASM'

Ein paar Erläuterungen zu dem Beispiel:

  • Sie können beliebig viele individuelle Zugangsdaten definieren. Diese werden immer gegenüber dem Standard bevorzugt.

  • Jede Option wird von den anderen durch ein : (Doppelpunkt) voneinander getrennt.

  • Wird ein optionales Feld mittendrin ausgelassen, muss der Doppelpunkt geschrieben werden. Siehe DBUSER_MYINST2, bei dem keine spezielle Rolle angegeben wurde.

  • Werden ab einem bestimmten Punkt keine optionalen Felder mehr gebraucht, können Sie die Doppelpunkte weglassen. Siehe ASMUSER, bei dem weder der Host, noch der Port angegeben wurde.

Instanzen ein- oder ausschließen

In manchen Fällen wollen Sie bestimmte Instanzen nicht in die Überwachung mit einbeziehen. Das kann zum Beispiel sein, weil es nur eine Spielwiese für Entwickler ist. Um die Konfiguration im Einzelfall möglichst einfach zu machen, haben Sie verschiedene Möglichkeiten, um eine oder mehrere Instanzen ganz oder teilweise auszuschließen:

Parameter Beschreibung

ONLY_SIDS

Hier kann bestimmt werden, welche Instanzen überwacht werden sollen. Es handelt sich hierbei um eine positive Liste, bei der alle Instanzen ignoriert werden, die nicht explizit gelistet sind. Die Option eignet sich also sehr gut, wenn die Menge der zu überwachenden Instanzen kleiner ist, als die Anzahl derer, die ignoriert werden sollen.

SKIP_SIDS

Im Gegensatz zu ONLY_SIDS, handelt es sich hier um eine negative Liste, bei der alle Instanzen außer die hier explizit gelisteten überwacht werden. Diese Option eignet sich daher sehr gut, wenn die Anzahl der zu ignorierenden Instanzen kleiner ist, als diejenige, die überwacht werden soll.

EXCLUDE__{SID}_

Mit dieser Option können Sie Instanzen teilweise ausschließen. Zwar können Sie auch hier mit dem Wert ALL alle Sektionen ausschließen und daher dasselbe erreichen, als würden Sie sie zu SKIP_SIDS hinzufügen. Allerdings können Sie auch nur bestimmte Sektionen für die angegebene Instanz abschalten und auf diese Weise ebenfalls eine Negativliste für einzelne Sektionen der Instanz definieren. Wichtig: Eine ASM (+ASM) kann mit dieser Option nicht komplett abgeschaltet werden.

Sie werden es schon ahnen: Die Reihenfolge der Verarbeitung dieser Optionen bestimmt das Ergebnis. Tatsächlich werden die Angaben auch genau in der Reihenfolge pro Instanz verarbeitet, wie sie oben angegeben sind. Wenn also die Variable ONLY_SIDS gesetzt ist, wird SKIP_SIDS gar nicht mehr ausgewertet und auch nicht mehr, ob es eine Angabe der Variable EXCLUDE_ auf ALL für diese Instanz gibt. Ist ONLY_SIDS nicht gesetzt, geht es dann entsprechend der Reihenfolge weiter. Im Zweifel — also als Standardverhalten — wird die Instanz entsprechend überwacht.

Am nachfolgenden Beispiel erläutern wir das Verhalten, falls alle Variablen gesetzt sind:

/etc/check_mk/mk_oracle.cfg
ONLY_SIDS='INST1 INST2 INST5'
SKIP_SIDS='INST7 INST3 INST2'
EXCLUDE_INST1='ALL'
EXCLUDE_INST2='tablespaces rman'

Da die positive Liste aus der ersten Zeile immer bevorzugt wird, werden entsprechend auch die zweite und dritte Zeile nicht mehr ausgewertet. Lediglich die vierte (letzte) Zeile wird zu einem späteren Zeitpunkt berücksichtigt, da hier die Instanz nur teilweise ausgewertet werden soll.

In der Praxis ist es also sinnvoll nur eine der Variablen zu nutzen, um die Menge der zu überwachenden Instanzen zu bestimmen.

Zu holende Daten bestimmen

Wie Sie bereits im vorherigen Abschnitt gelernt haben, können Sie Instanzen nicht nur komplett abschalten, sondern auch lediglich teilweise überwachen. Die Einsatzzwecke sind vielfältig und vor allem dann sinnvoll, wenn Sie bestimmte, lang laufende Sektionen nicht überall berücksichtigen wollen oder auf Testinstanzen nur grundlegende Informationen benötigen. Um Sektionen global einzuschränken, setzen Sie die entsprechenden Variablen direkt. Um nur bestimmte Instanzen einzuschränken, können Sie die Variable EXCLUDE__{SID}_ nutzen, die Sie im vorherigen Abschnitt bereits kennengelernt haben. Die globalen Variablen sind:

Parameter Beschreibung

SYNC_SECTIONS

Sektionen, die synchron — das heißt bei jedem Lauf des Agenten — abgefragt werden sollen. Da das Abfrageintervall im Standard bei 60 Sekunden liegt, müssen die benutzten SQL-Abfragen entsprechend schnell durchlaufen. Wird die Variable nicht angegeben, werden alle Sektionen abgefragt.

ASYNC_SECTIONS

Sektionen, die asynchron — das heißt nur alle x Minuten — abgefragt werden sollen. Wie lange die Daten gültig sind, bestimmt die Variable CACHE_MAXAGE weiter unten in der Tabelle.

SYNC_ASM_SECTIONS

Hier greift der gleiche Mechanismus für Sektionen der ASM, wie das bei der anderen Variable SYNC_SECTIONS der Fall ist.

ASYNC_ASM_SECTIONS

Hier greift der gleiche Mechanismus für Sektionen der ASM, wie das bei der anderen Variable ASYNC_SECTIONS der Fall ist.

CACHE_MAXAGE

Mit dieser Variable bestimmen Sie, wie lange asynchron abgerufene Daten valide sind. Wird die Variable nicht angegeben, wird ein Standard von 600 Sekunden (10 Minuten) benutzt.

Der Mechanismus erlaubt es demnach, in der Konfigurationsdatei einen Standard zu setzen und diesen bei Bedarf je Instanz noch einmal zu überschreiben. Eine Konfiguration könnte dann zum Beispiel so aussehen:

/etc/check_mk/mk_oracle.cfg
# DEFAULTS:
# SYNC_SECTIONS="instance sessions logswitches undostat recovery_area processes recovery_status longactivesessions dataguard_stats performance locks"
# ASYNC_SECTIONS="tablespaces rman jobs ts_quotas resumable"
# SYNC_ASM_SECTIONS="instance processes"
# ASYNC_ASM_SECTIONS="asm_diskgroup"
# CACHE_MAXAGE=600

SYNC_ASM_SECTIONS='instance'
ASYNC_SECTIONS='tablespaces jobs rman resumable'

CACHE_MAXAGE=300

EXCLUDE_INST1='undostat locks'
EXCLUDE_INST2='jobs'

Wie Sie in dem Beispiel sehen, wird für die ASM-Instanzen lediglich die Sektion instance abgefragt und auf allen regulären Instanzen ein Minimalset für die asynchronen Sektionen angegeben. Zusätzlich wird auf der Instanz INST1 auf die synchronen Sektionen undostat und locks verzichtet. Da die synchronen Sektionen nicht explizit angegeben wurden, werden auf allen anderen Instanzen alle synchronen Sektionen abgerufen. INST2 wiederum fragt nur drei der vier asynchronen Sektionen ab, da jobs zusätzlich ausgeschlossen wurde. Und zuletzt wird der Cache von 10 Minuten auf 5 Minuten (300 Sekunden) heruntergesetzt, da es möglich ist, alle Daten in diesem Zeitraum zu holen.

Wichtig: Wenn Sie in der Konfigurationsdatei bestimmen, welche Sektionen auf welche Weise abgeholt werden sollen, Sie können ja auch eine asynchrone Sektion zu einer synchronen machen, müssen Sie alle Sektionen angeben, welche in dem jeweiligen Bereich ausgeführt werden sollen. Wollen Sie zum Beispiel nur locks aus der synchronen Abfrage herausnehmen, geben Sie die gesamte synchrone Liste an und lassen Sie lediglich locks weg:

/etc/check_mk/mk_oracle.cfg
# Just exclude 'locks' from sync sections:
SYNC_SECTIONS='instance sessions logswitches undostat recovery_area processes recovery_status longactivesessions dataguard_stats performance'

Gleiches gilt auch für die anderen drei Variablen, in denen die Sektionen bestimmt werden.

TNS Alias und TNS_ADMIN konfigurieren

Wird nachgeliefert

3.3. Entfernte Datenbanken überwachen

Unter unixoiden Systemen können Sie nicht nur lokal laufende Instanzen abrufen, sondern sich auch auf entfernten einloggen und die dort laufenden Datenbanken abrufen. Dies ist zum Beispiel dann von Vorteil, wenn Sie keinen Zugriff auf das darunter liegende System haben, aber die Datenbank dennoch überwachen wollen. Um entfernte Datenbanken zu überwachen, gibt es die folgenden Voraussetzungen:

  • Die Linux AIO access library ist installiert. Unter RHEL/CentOS heißt das Paket libaio.

  • Der Oracle Instant Client ist installiert.

  • Das Programm sqlplus ist in der Installation schon vorhanden oder muss ggf. als Erweiterungspaket zu dem Client installiert werden.

In der Regel sind die Voraussetzungen schon erfüllt, wenn sich auf dem Host, auf dem das Plugin ausgeführt werden soll, eine Oracle-Installation befindet. Andernfalls holen Sie dies über die entsprechenden Pakete nach.

Damit sich das Plugin mit der entfernten Datenbank verbinden kann, hinterlegen Sie zunächst in der Konfigurationsdatei die Zugangsdaten. Diese sind ähnlich zu den Angaben, die Sie bereits vom DBUSER kennen. Allerdings gibt es zusätzlich noch eine Reihe mehr an verpflichtenden Angaben:

/etc/check_mk/mk_oracle.cfg
# Syntax:
# REMOTE_INSTANCE_[ID]='USER:PASSWORD:ROLE:HOST:PORT:PIGGYBACKHOST:SID:VERSION:TNSALIAS'

REMOTE_INSTANCE_1='check_mk:mypassword::myRemoteHost:1521:myOracleHost:MYINST3:11.2'
REMOTE_INSTANCE_myinst1='/:::myRemoteHost:1521::MYINST1:11.2:INST1'

REMOTE_ORACLE_HOME='/usr/lib/oracle/11.2/client64'

In dem Beispiel sind zwei entfernte Instanzen konfiguriert. Damit jede Zeile eindeutig ist, wird jeder Variablen eine ID übergeben. Diese können Sie frei wählen --, sie muss lediglich pro Konfigurationsdatei eindeutig sein. Wie Sie wahrscheinlich schon bemerkt haben, folgen auf die Angabe des Ports nun weitere Werte. Diese sind teilweise optional und teilweise notwendig, um eine Verbindung aufbauen zu können:

Der erste zusätzlich verwendete Wert (PIGGYBACKHOST) bei der Instanz MYINST3 ist myOracleHost. Durch diese Angabe werden die Ergebnisse für die Abfrage dem angegebenen Host zugeordnet. Ist dieser in Checkmk als Host vorhanden, werden die neuen Services entsprechend dort erscheinen, anstatt auf dem Host, auf dem das Plugin läuft, bzw. von dem aus die Daten geholt wurden. Auf der zweiten Instanz MYINST1 sehen Sie diese Angabe nicht; die Zuordnung zu einem anderen Host ist optional.

Der zweite neue Wert (SID) ist die Angabe des Instanznamens. Da das Plugin auf dem entfernten Host nicht schauen kann, welche Instanzen dort laufen, muss für jede entfernte Instanz eine Konfigurationszeile angegeben werden — der Wert ist also notwendig und damit nicht optional.

Der dritte Wert (VERSION) ist notwendig und ebenfalls dem Umstand geschuldet, dass viele Metadaten nur zur Verfügung stehen, wenn man sich direkt auf dem Host befindet. Die Versionsangabe kann daher auch nicht weggelassen werden und bestimmt, welche SQL-Abfragen an die Instanz übergeben werden können. In dem Beispiel verwenden beide Instanzen die Version 11.2.

Der vierte und letzte Wert (TNSALIAS) ist wieder optional und kann verwendet werden, wenn Sie auf die entfernte Instanz per Wallet oder LDAP/Active Directory zugreifen möchten. Für den Fall, dass die Instanz dann nur auf einen bestimmten TNS-Alias antwortet, können Sie diesen hier angeben.

Um auch das Programm sqlplus zu finden, geben Sie über die Variable REMOTE_ORACLE_HOME an, wo sich der Oracle-Client auf dem Host befindet, der das Plugin ausführt. Nur dann sind alle Ressourcen verfügbar, die für die Abfragen benötigt werden.

Wichtig: Bei der Abfrage von entfernten Instanzen gelten ein paar Einschränkungen und Besonderheiten:

  • Sie können — logischerweise — entfernte Instanzen nicht per SKIP_SIDS ausschließen und brauchen sie im Gegenzug auch nicht bei ONLY_SIDS zu berücksichtigen.

  • Instanzen mit gleichem Namen (SID) dürfen nicht demselben Host zugewiesen werden. Das ist vor allem dann relevant, wenn Sie Instanzen von mehreren entfernten Hosts und/oder dem lokalen Host abrufen und dort identische Namen verwendet werden.

3.4. Einrichtung über die Agentenbäckerei

CEE Die Einrichtung kann unter Linux, AIX, Solaris und HP-UX mit der Agentenbäckerei stark vereinfacht werden, da Syntaxfehler in den Konfigurationsdateien vermieden und Anpassungen an sich verändernde Umgebungen einfacher umgesetzt werden können. Der wesentliche Unterschied zu einer manuellen Konfiguration ist, dass Sie nur noch dann auf dem Oracle-Host auf der Kommandozeile arbeiten müssen, wenn Sie spezielle Oracle-spezifische Konfigurationen vornehmen wollen.

Nichtsdestoweniger können Sie nicht alle Funktionen des Plugins über die Agentenbäckerei konfigurieren. Zum einen dann, wenn es sich um veraltete Konfigurationsoptionen handelt, die nur noch aus Kompatibilitätsgründen vorhanden sind. Diese lassen sich dann entsprechend durch die aktuellen Optionen ersetzen. Zum anderen, wenn es Funktionen sind, welche einen größeren Eingriff benötigen und eine deutliche Expertise voraussetzen. Entsprechend sind die Custom SQLs nicht direkt in der Agentenbäckerei konfigurierbar.

Über Setup > Agents > Windows, Linux, Solaris, AIX und das Menü Agents > Agent rules > ORACLE Databases (Linux, Solaris, AIX, Windows) legen Sie eine Regel an. Hier finden Sie alle Optionen, die Ihnen für die Konfiguration des Plugins zur Verfügung stehen:

monitoring oracle bakery ruleset

Benutzer konfigurieren

Auch in der Agentenbäckerei haben Sie die Möglichkeit, Standardbenutzer und Ausnahmen für spezielle Instanzen anzulegen. Die Optionen, die Sie in der Konfigurationsdatei mit Doppelpunkt separiert finden, finden Sie hier als einzelne Optionen, die Sie dann entsprechend ausfüllen. In der einfachsten Konfiguration sieht das dann etwa so aus:

monitoring oracle bakery login1

Natürlich können Sie auch hier das Wallet nutzen, indem Sie in dem Drop-down-Menü Authentication method einfach auf Use manually created ORACLE password wallet wechseln.

Die Konfiguration für eine ASM erledigen Sie analog über die Option Login for ASM und die Ausnahmen für spezifische Instanzen finden Sie bei Login for selected databases.

Erweiterte Optionen

In der folgenden Tabelle finden Sie die restlichen Optionen des Regelsatzes ORACLE Databases (Linux, Solaris, AIX, Windows) zusammen mit einem Verweis darauf, wo Sie eine Beschreibung zu der Option finden:

Option Beschreibung

Host uses xinetd or systemd (Linux/AIX/Solaris only)

Muss für Systeme mit xinetd/systemd aktiviert werden. Dass Plugin wird dann asynchron im festgelegten Intervall ausgeführt.

Instances to monitor

Diese Option fasst mehrere Optionen der Konfigurationsdatei zusammen, mit denen Sie Instanzen aus- oder einschließen können.

Add pre or postfix to TNSALIASes

Mit dieser Option können Sie den TNSALIAS entweder global oder für eine spezifische Instanz erweitern.

Sections - data to collect

Alle verfügbaren Sektionen sind unter dieser Option gelistet und können individuell auf globaler Ebene konfiguriert werden. Sie entsprechen daher den beiden Variablen SYNC_SECTIONS und ASYNC_SECTIONS sowie deren Gegenstück bei einer ASM aus dem Abschnitt, wo es um die zu holenden Daten geht.

Exclude some sections on certain instances

Wenn Sie mit EXCLUDE_{SID} nicht die gesamte Instanz, sondern nur ein paar Sektionen ausschließen wollen, können Sie das über diese Option machen. Eine genauere Beschreibung finden Sie bei den Optionen zu den Instanzen und Sektionen.

Cache age for background checks

Legen Sie hier fest, wie lange asynchrone Sektionen gültig sein sollen. Der Standardwert liegt bei 600 Sekunden (10 Minuten).

Sqlnet Send timeout

Diese Option wird der sqlnet.ora hinzugefügt und setzt ein Timeout für die Instanz selbst.

Remote instances

Entfernte Instanzen konfigurieren Sie mit dieser Option. Sie enthält alle Elemente der Konfiguration, die Sie bereits kennen. Für die Bestimmung der ID der Variable haben Sie über die Unique ID die Wahl aus verschiedenen Möglichkeiten. Diese wirken sich lediglich auf die erwähnte ID aus und müssen lediglich einzigartig sein.

ORACLE_HOME to use for remote access

Hier können Sie bestimmen, wo das Agentenplugin das Programm sqlplus findet. Sie müssen es dann angeben, wenn Sie eine entfernte Instanz überwachen wollen, aber sqlplus nicht über die Umgebungsvariablen gefunden werden kann.

TNS_ADMIN to use for sqlnet.ora and tnsnames.ora

Haben Sie bereits die entsprechenden Dateien an einem anderen Ort angelegt, können Sie mit dieser Option — wie weiter oben beschrieben — auf die den Pfad zu den Dateien verweisen. Andernfalls wird unter /etc/check_mk/ danach gesucht.

4. Windows

4.1. Plugin- und Konfigurationspfade

Unter Windows wird PowerShell als Skriptsprache benutzt, um Oracle-Datenbanken zu überwachen. Die Funktionalität ist an das Plugin unter unixoiden Systemen angelehnt, enthält aber nur einen Teil davon. Um das Plugin unter Windows nutzen zu können, benötigen Sie die folgenden Pfade, wenn Sie diese nicht verändert haben:

OS Plugin-Pfad Konfigurationspfad

Windows

C:\ProgramData\checkmk\agent\plugins

C:\ProgramData\checkmk\agent\plugins

Windows (Legacy-Agent)

C:\Program Files (x86)\check_mk\plugins\

C:\Program Files (x86)\check_mk\config\

Hinweis: Da der Legacy-Agent nur noch in sehr seltenen Ausnahmefällen benötigt wird, wird er bei der folgenden Beschreibung nicht beachtet. Es wird sich daher immer auf die aktuelle Architektur des Agenten bezogen.

Um das Plugin mk_oracle.ps1 zu aktivieren, kopieren Sie das Plugin von C:\Program Files (x86)\checkmk\service\plugins\ in das oben beschriebene Plugin-Verzeichnis. Alternativ können Sie in der Konfigurationsdatei des Agenten auf die Datei im Installationspfad verweisen.

4.2. Besonderheiten unter Windows

Windows verhindert normalerweise die Ausführung von PowerShell-Skripten, wenn diese nicht signiert sind. Sie können dieses Problem nun sehr einfach umgehen, indem Sie die Richtlinien zur Ausführung von PowerShell-Skripten für den Benutzer anpassen, welcher den Checkmk-Agenten ausführt:

PS C:\ProgramData\checkmk\agent\> Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope LocalMachine
PS C:\ProgramData\checkmk\agent\> Get-ExecutionPolicy -Scope LocalMachine
Bypass

Diese Option ist praktisch, wenn man kurz ein Skript oder die generelle Funktionalität des Checkmk-Agenten testen möchte. Um die Sicherheit Ihres Systems nicht zu gefährden, setzen Sie nach dem Test die Einstellung auf produktiven Servern wieder zurück:

PS C:\Program\checkmk\agent\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
PS C:\Program\checkmk\agent\> Get-ExecutionPolicy -Scope LocalMachine
RemoteSigned

Verständlicherweise haben Sie wahrscheinlich keine Lust, alle 60 Sekunden die Richtlinien umzustellen. Setzen Sie daher eine permanente Ausnahme nur für die relevanten Skripte. Dabei muss auch das Konfigurationsskript zu den Ausnahmen hinzugefügt werden. Die Ausgabe aus dem Beispiel wurde zu Gunsten der Lesbarkeit komplett weggelassen:

PS C:\ProgramData\checkmk\agent\> Unblock-File -Path .\plugins\mk_oracle.ps1
PS C:\ProgramData\checkmk\agent\> Unblock-File -Path .\config\mk_oracle_cfg.ps1

4.3. Erweiterte Optionen

In der allgemeinen Einrichtung haben Sie bereits erste Variablen kennengelernt, um Überwachungsdaten von Ihren Oracle-Instanzen zu bekommen. Weitere Optionen, die Ihnen auch unter Windows zur Verfügung stehen, finden Sie in den nachfolgenden Abschnitten.

Erweiterte Benutzerkonfiguration

Wie unter Linux können Sie auch bei dem Windows-Plugin nicht nur einen Standardlogin definieren, sondern auch individuelle Logins für einzelne Instanzen. Sie haben also die gleichen drei Möglichkeiten, Benutzer anzugeben:

Parameter Beschreibung

DBUSER

Der Standard, wenn keine individuellen Zugangsdaten für die Datenbankinstanz definiert sind.

DBUSER_MYINST1

Zugangsdaten für eine ganz bestimmte Datenbankinstanz. In diesem Fall für die Instanz MYINST1. Die Logindaten werden nur für diese SID benutzt.

ASMUSER

Spezielle Zugangsdaten für das Automatic Storage Management (ASM).

Wichtig: Auch hier kann für eine ASM immer nur ein Login angegeben werden.

Zusätzlich können auch hier noch mehr Optionen außer Benutzername oder Passwort angegeben werden. Diese zusätzlichen Angaben sind ebenfalls optional. Allerdings muss jede Angabe ausgefüllt werden, wenn sie benutzt wird. Eine Konfiguration kann dann zum Beispiel so aussehen:

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1
# Syntax
# DBUSER = @("USERNAME", "PASSWORD", "ROLE", "HOST", "PORT")
# Default
# DBUSER = @("", "", "", "localhost", "1521")
$DBUSER = @("checkmk", "myPassword", "SYSDBA", "localhost", "1521")

@DBUSER_MYINST1 = @("cmk_specific1", "myPassword1", "", "10.0.0.73")
@DBUSER_MYINST2 = @("cmk_specific2", "myPassword2", "SYSDBA", "localhost", "1531")

@ASMUSER = @("cmk_asm", "myASMPassword", "SYSASM")

Ein paar Erläuterungen zu dem Beispiel:

  • Sie können beliebig viele individuelle Zugangsdaten definieren. Diese werden immer dem Standard gegenüber bevorzugt.

  • Jede Option wird in einer Liste definiert. Die Reihenfolge der Einträge ist nicht beliebig und darf daher nicht vertauscht werden.

  • Soll ein optionales Feld nicht verändert werden, aber ein danach folgendes, so müssen beide korrekt angegeben werden. Siehe DBUSER_MYINST2, bei dem der HOST weiterhin auf localhost gesetzt wird, obwohl nur der PORT verändert werden soll.

  • Werden ab einem bestimmten Punkt keine optionalen Felder mehr gebraucht, können sie weggelassen werden. Siehe ASMUSER, bei dem nur die Rolle des Benutzers angegeben wurde.

  • Soll dem Benutzer keine spezielle Rolle zugewiesen, aber HOST oder PORT angepasst werden, tragen Sie an der Stelle lediglich zwei Anführungszeichen ("") ein.

Instanzen ein- oder ausschließen

Auch unter Windows möchte man bestimmte Instanzen nicht immer einbeziehen. Gründe dafür wurden ja in dem Abschnitt für Linux bereits beschrieben. Zwei der drei Möglichkeiten, die sie von Linux kennen, können Sie auch hier verwenden:

Parameter Beschreibung

ONLY_SIDS

Hier kann bestimmt werden, welche Instanzen überwacht werden sollen. Es handelt sich hierbei um eine positive Liste, bei der alle Instanzen ignoriert werden, die nicht explizit gelistet sind. Die Option eignet sich also sehr gut, wenn die Menge der zu überwachenden Instanzen kleiner ist, als die Anzahl derer, die ignoriert werden sollen.

EXCLUDE__{SID}_

Da Ihnen die Option SKIP_SIDS nicht zur Verfügung steht, können Sie nur über diese Option Instanzen ausschließen und dadurch eine negative Liste definieren. Sie machen das, in dem der Wert der Variable auf ALL gesetzt wird. Zusätzlich können Sie aber auch hier nur bestimmte Sektionen für die angegebene Instanz abschalten und auf diese Weise eine Negativliste für einzelne Sektionen der Instanz definieren. Wichtig: Eine ASM (+ASM) kann mit dieser Option nicht komplett abgeschaltet werden.

Die Verarbeitung erfolgt in der oben angegebenen Reihenfolge pro Instanz. Es wird also zuerst geprüft, ob sich die Instanz in ONLY_SIDS befindet und erst danach, ob bestimmte Sektionen ausgeschlossen werden sollen. Ist weiter die Variable EXCLUDE_ auf ALL gesetzt, so wird auch keine Sektion ausgeführt.

Nachfolgend ein Beispiel, bei dem beide Variablen einmal gezeigt werden:

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1
$ONLY_SIDS = @("MYINST1", "MYINST3")
$EXCLUDE_INST1 = "tablespaces rman"
$EXCLUDE_INST3 = "ALL"

Beachten Sie, dass es sich bei ONLY_SIDS um eine Liste handelt, bei EXCLUDE_INST1 hingegen um einen String, der durch Leerzeichen separierte Sektionen enthält.

Zu holende Daten bestimmen

Die Angabe, welche Sektionen überhaupt zu holen sind, erfolgt äquivalent zu Linux. Daher hier nur ein Beispiel der Konfiguration:

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1
# DEFAULTS:
# $SYNC_SECTIONS = @("instance", "sessions", "logswitches", "undostat", "recovery_area", "processes", "recovery_status", "longactivesessions", "dataguard_stats", "performance", "locks")
# $ASYNC_SECTIONS = @("tablespaces", "rman", "jobs", "ts_quotas", "resumable")
# $SYNC_ASM_SECTIONS = @("instance", "processes")
# $ASYNC_ASM_SECTIONS = @("asm_diskgroup")
# $CACHE_MAXAGE = 600

$SYNC_ASM_SECTIONS = @("instance")
$ASYNC_SECTIONS = @("tablespaces", "jobs", "rman", "resumable")

$CACHE_MAXAGE = 300

$EXCLUDE_INST1 = "undostat locks"
$EXCLUDE_INST2 = "jobs'

Wichtig: Wenn Sie in der Konfigurationsdatei bestimmen, welche Sektionen auf welche Weise abgeholt werden sollen — Sie können ja auch eine asynchrone Sektion zu einer synchronen machen — , müssen Sie alle Sektionen angeben, welche in dem jeweiligen Bereich ausgeführt werden sollen. Wollen Sie zum Beispiel nur locks aus der synchronen Abfrage herausnehmen, geben Sie die gesamte synchrone Liste an und lassen lediglich locks weg:

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1
# Just exclude 'locks' from sync sections:
$SYNC_SECTIONS = @("instance", "sessions", "logswitches", "undostat", "recovery_area", "processes", "recovery_status", "longactivesessions", "dataguard_stats", "performance")

Gleiches gilt auch für die anderen drei Variablen, in denen die Sektionen bestimmt werden.

4.4. Entfernte Datenbanken überwachen

Die Überwachung entfernter Datenbanken ist derzeit nicht über das Windows-Plugin möglich. Wenn Sie entfernte Datenbanken überwachen wollen, benötigen Sie daher einen Host mit einem kompatiblen unixoiden Betriebssystem.

4.5. Einrichtung über die Agentenbäckerei

CEE Zur Zeit steht die Einrichtung über die Agentenbäckerei nur für unixoide Systeme zur Verfügung.

5. Cluster-Instanzen

5.1. Standby-Datenbanken

Oracle unterstützt sogenannte Standby-Datenbanken, welche bestimmte Aufgaben erfüllen können und in der Regel schlicht Kopien von produktiven bzw. primären Datenbanken sind. Diese Datenbankkonzepte benötigen auch spezielle Mechanismen in der Überwachung. Welche das sind, erfahren Sie in den folgenden Abschnitten.

Mit Active Data Guard (ADG)

Haben Sie ADG lizenziert und aktiviert, müssen Sie keinerlei Veränderungen in der Konfiguration des Agentenplugins vornehmen, da Sie jederzeit von einer Standby-Instanz lesen können, ohne die Synchronisation mit der primären Instanz unterbrechen zu müssen.

Ohne Active Data Guard (DG)

Wenn die Instanzen nicht über ADG verfügen, benötigt der Benutzer, mit dem die Überwachungsdaten der Standby-Instanzen geholt werden sollen, die Rolle sysdba. Durch diese Berechtigung ist der Benutzer auch dann in der Lage zumindest einen Teil der Daten zu holen, wenn die primäre Instanz ausfällt und auf dem Standby-Server die Instanz noch nicht von MOUNTED auf OPEN umgestellt wurde.

Weisen Sie die Berechtigung dem Benutzer zu, welcher die Daten von der oder den Instanzen abholen darf. Wichtig: Wie das funktioniert, kann von dem folgenden Beispiel abweichen. Die Rolle wird hier dem Benutzer zugewiesen, wie er in dem früheren Beispiel weiter oben angelegt wurde:

sqlplus> grant sysdba to checkmk;

Damit die Daten im Fehlerfall von dem Agentenplugin auf dem Standby-Server abgefragt werden können, legen Sie den Benutzer auf der primären Instanz an und kopieren Sie die Passwortdatei danach auf den Standby-Server. In der Konfigurationsdatei des Plugins setzen Sie abschließend die Rolle des Benutzers auf sysdba:

/etc/check_mk/mk_oracle.cfg
# Syntax:
# DBUSER='USER:PASSWORD:ROLE:HOST:PORT:TNSALIAS'
DBUSER='checkmk:myPassword:sysdba'

Beachten Sie, dass die Angabe eines Hosts, Ports oder des TNS-Alias optional ist und wie immer weggelassen werden kann. Zusätzlich muss natürlich das Agentenplugin sowohl auf dem primären Oracle-Host als auch auf den Standby-Hosts installiert sein.

Cluster-Services einrichten

Auf der Seite von Checkmk ist es notwendig, dass Sie — egal, ob Sie ADG oder DG nutzen — die Services anpassen und einem Cluster-Host zuweisen. Die entsprechenden Check-Plugins wurden bereits soweit vorbereitet, dass Sie auch als Cluster-Services konfiguriert werden können. Legen Sie also einen Cluster-Host in Checkmk an und ordnen Sie diesem Host die einzelnen Oracle-Hosts zu, denen die primäre und die Standby-Instanzen zugeordnet sind. Danach weisen Sie die folgenden Services diesem Cluster-Host zu:

  • ORA .* RMAN Backup

  • ORA .* Job

  • ORA .* Tablespaces

Sie brauchen sich sich nun nicht mehr darum zu kümmern, von welcher Instanz die Daten kommen und haben auch im Falle eines Schwenks der primären Instanz eine nahtlose Überwachung der oben erwähnten Services sichergestellt.

5.2. Real Application Cluster (RAC)

Da es in einem RAC einen zentralen Speicher für die Daten gibt, reicht es hier, den Benutzer für das Agentenplugin nur einmal anzulegen. Lediglich das Agentenplugin muss auf jedem Knoten des Oracle-Clusters installiert und konfiguriert werden.

Wichtig: Richten Sie immer die Knoten des Clusters selbst ein und verzichten Sie auf die Abfrage des SCAN-Listeners. Nur dadurch ist gewährleistet, dass der Zugriff über das Plugin funktioniert.

Cluster-Services einrichten

Auch bei einem RAC ist es sinnvoll, bestimmte Services in einem Cluster-Host zusammenzufassen. Zusätzlich zu den Services, die Sie bei einem (Active) Data Guard dem Cluster-Host zuordnen, weisen Sie auch die folgenden Services zu, um im Falle eines Schwenks eine nahtlose Überwachung sicherzustellen:

  • ASM .* Diskgroup

  • ORA .* Recovery Area

6. Mit eigenen SQL-Abfragen überwachen (Custom SQLs)

6.1. Warum eigene SQL-Abfragen nutzen?

Checkmk bietet mit dem offiziellen Plugin bereits eine große Menge an SQL-Abfragen, mit denen Sie Ihre Datenbankinstanzen überwachen können. Damit diese für eine möglichst große Menge an technischen und inhaltlichen Anforderungen passend sind, sind diese natürlich sehr allgemein gehalten.

Um die individuellen Anforderungen eines jeden Unternehmens an die Überwachung einer konkreten Datenbank erfüllen zu können, bietet Checkmk die Möglichkeit, eigene SQL-Abfragen zu definieren und mit dem Plugin mk_oracle abfragen zu lassen. Diese werden dann automatisch in der Weboberfläche als eigene Services erkannt und überwacht.

Wichtig: Es gibt nur unter Linux, AIX und Solaris die Möglichkeit, eigene SQL-Abfragen abzufragen. Unter Windows steht diese Option nicht zur Verfügung.

6.2. Einfache eigene SQL-Abfragen einbinden

Abzufragende SQL-Abfragen schreiben

Die einfachste Weise so ein SQL anzubinden, ist die Nutzung des Check-Plugins Oracle Database: Custom SQLs. Erstellen Sie dafür zunächst die Datei mySQL.sql in dem Agenten-Konfigurationsverzeichnis des Hosts, auf dem das SQL ausgeführt werden soll. Nachfolgend ein Dummy, welcher die Syntax veranschaulicht:

/etc/check_mk/MySQL.sql
/*Syntax help in comments. The first word is alwyas the key word and ends with a ":"*/

/*details:Text to display in the service detail output*/
prompt details: Some details for the service output;

/*perfdata:METRIKNAME=CURRENTVALUE;WARN;CRIT;MAX METRIKNAME=CURRENTVALUE2;WARN;CRIT;MAX*/
prompt perfdata:MyMetricName1=10;15;20;30 MyMetricName2=16;15;20;30;
prompt perfdata:MyMetricName3=21;15;20;30 MyMetricName4=15;15;20;30;

/*long:Text to display in the long output of the service*/
prompt long: Here comes some long output for the service;
prompt long: Here comes some more long output for the service;

/*exit:Status of the service as a number*/
prompt exit:2;

Das Beispiel zeigt zum einen, dass Sie in einer solchen Datei beliebig viele Anweisungen definieren können. Zum anderen ist die Syntax dem eines lokalen Checks vor allem mit Blick auf die Performance-Werte sehr ähnlich. Im Detail ist diese Syntax hier wesentlich mächtiger, da Sie mehrzeilige Ausgaben erzeugen können und diese dann auf dem Checkmk-Server als ein Service verarbeitet werden. Prinzipiell sind alle Zeilen optional und müssen nicht befüllt werden. Die möglichen Schlüsselwörter sind im Einzelnen:

  • details: Hier können Sie bestimmen, was im Status Detail des erzeugten Service ausgegeben werden soll. Die Zeile wird mit dem Schlüsselwort und einem Doppelpunkt eingeleitet. Der Rest der Zeile ergibt die Ausgabe.

  • perfdata: Performance-Daten werden mit diesem Schlüsselwort übergeben. Innerhalb einer Zeile können Sie beliebig viele Metriken — getrennt durch ein Leerzeichen — erzeugen. Sie können die Ausgabe der Metriken auch über mehrere Zeilen verteilen. Beginnen Sie dabei einfach immer mit dem Schlüsselwort perfdata:.

  • long: Wenn der Service einen Long Output haben soll, können Sie diesen hier angeben. Auch dieses Schlüsselwort können Sie mehrmals verwenden, um mehrere Zeilen im Long Output zu erzeugen.

  • exit: Soll die Ausgabe einen bestimmten Status haben, können Sie diesen hier bestimmen. Es stehen Ihnen dabei die bekannten Zuordnungen 0,1,2,3 für die Status OK, WARN, CRIT, UNKNOWN zur Verfügung.

Hinweis: Das Schlüsselwort elapsed müssen Sie nicht manuell definieren. Es wird während der Laufzeit automatisch erzeugt, um zu prüfen, wie lange die von Ihnen definierten Anweisungen gebraucht haben.

mk_oracle-Plugin konfigurieren

Nachdem Sie nun Ihr erstes, sehr einfaches SQL definiert haben, machen Sie es dem Plugin bekannt. Das erfolgt über die bekannte Konfigurationsdatei, die Sie entsprechend erweitern:

/etc/check_mk/mk_oracle.cfg
SQLS_SECTIONS="mycustomsection1"

mycustomsection1 () {
    SQLS_SIDS="INST1"
    SQLS_DIR="/etc/check_mk"
    SQLS_SQL="MyCustomSQL.sql"
}

Mit der ersten Option (SQLS_SECTIONS) bestimmen Sie, welche individuellen Sektionen Sie ausführen lassen möchten. In dem Beispiel haben wir nur eine angegeben und diese dann direkt danach näher beschrieben. Jede Sektion ist also eigentlich eine kleine Funktion, die vom mk_oracle-Plugin aufgerufen wird.

In dieser Funktion können Sie dann weitere Details bestimmen und festlegen, für welche Instanzen (SQLS_SIDS) diese Sektion gilt. Außerdem bestimmen Sie zusätzlich, wo sich die Datei mit den SQL-Anweisungen befindet (SQLS_DIR) und wie diese Datei heißt (SQLS_SQL). Diese einfache Konfiguration reicht bereits aus, um das Ergebnis in Checkmk sehen zu können. Führen Sie dafür eine Serviceerkennung durch und aktivieren Sie den neuen Service. Danach sehen Sie ihn bei den anderen Services in der Übersicht des Hosts:

monitoring oracle custom sqls list

6.3. Erweiterte Optionen

Die Möglichkeiten, mit eigenen SQL-Abfragen zu überwachen, gehen natürlich über den einfachen — oben gezeigten — Fall hinaus. Im nachfolgenden finden Sie eine kleine Übersicht der verfügbaren Variablen. Für eine ausführliche Beschreibung können Sie auch das Plugin mit der Option --help aufrufen. Wichtig: Variablen, die nur außerhalb oder nur innerhalb einer Sektions-Funktion gesetzt werden können, sind entsprechend markiert. Alle anderen können in beiden Bereichen definiert werden. Werden sie außerhalb einer Sektion gesetzt, gelten sie global für alle Sektionen.

Variable Kurzbeschreibung optional

SQLS_SECTIONS

Die selbst definierten Sektions-Funktionen, die von dem Plugin ausgeführt werden sollen. Wichtig: Diese Variable kann nur außerhalb einer Sektions-Funktion (global) gesetzt werden.

nein

SQLS_SIDS

Die Instanzen, welche die Sektion(en) ausführen sollen. Kann global oder pro Sektion gesetzt werden.

nein

SQLS_DIR

Der Pfad, in dem die eigenen SQL-Abfragen abgelegt wurden. Kann global oder pro Sektion gesetzt werden.

nein

SQLS_SQL

Die Datei, welche die Anweisungen für eine Sektion enthält.

nein

SQLS_SECTION_NAME

Der Sektions-Name, wenn Sie ein eigenes Check-Plugin für die individuellen SQL-Abfragen geschrieben haben.

ja

SQLS_SECTION_SEP

Der Separator der einzelnen Elemente in einer Zeile als ASCII-ID. Diese Variable kann nur in Verbindung mit der Variable SQLS_SECTION_NAME benutzt werden.

ja

SQLS_ITEM_NAME

Bestimmt einen individuellen Identifikator für den Servicenamen. Normalerweise werden die SID und der Dateiname der SQL-Abfragen genommen. Wichtig: Diese Variable kann nicht zusammen mit der Variable SQLS_SECTION_NAME benutzt werden und kann auch nur innerhalb einer Sektions-Funktion gesetzt werden.

ja

SQLS_MAX_CACHE_AGE

Erfüllt dieselbe Aufgabe, wie CACHE_MAXAGE — allerdings für die eigenen SQL-Abfragen.

ja

SQLS_DBUSER

Bestimmt einen individuellen Benutzer für die Sektionen.

ja

SQLS_DBPASSWORD

Bestimmt ein individuelles Passwort für die Sektionen.

ja

SQLS_DBSYSCONNECT

Erweitert die Verbindung über eine SYS-Rolle für die Sektionen.

ja

SQLS_TNSALIAS

Setzt einen individuellen TNSALIAS für die Sektionen.

ja

6.4. Eigene Check-Plugins nutzen

Sollten Ihnen die Möglichkeiten der oben beschriebenen Syntax nicht ausreichen, können Sie über die Variable SQLS_SECTION_NAME auch eigene Sektionsnamen für ein oder mehrere SQL-Abfragen ausgeben lassen. Das setzt allerdings voraus, dass Sie auch ein entsprechendes Check-Plugin geschrieben und in Ihre Checkmk-Instanz eingebunden haben.

Haben Sie ein solches Check-Plugin geschrieben, sind Sie komplett frei in der Syntax der Plugin-Ausgabe und können ganz eigene Wege gehen. Da dieser Weg der umfangreichste und auch schwierigste ist, ist er hier nur der Vollständigkeit halber erwähnt. Er setzt voraus, dass Sie wissen, wie man ein agentenbasiertes Check-Plugin schreibt und in die Monitoring-Instanz einbindet. Danach ordnen Sie lediglich die individuellen SQL-Abfragen mit den Variablen diesem Check-Plugin zu.

7. Diagnosemöglichkeiten

7.1. Verbindung testen

Linux, AIX, Solaris

Sollten Sie Problem mit der Verbindung zu einer oder mehreren Instanzen auf einem Oracle-Server haben, können Sie als Erstes grundlegende Parameter prüfen lassen. Mit der Option -t geben Sie die Details zu einer Verbindung aus. In der Ausgabe wurden die Dummy-Sektionen zugunsten der Lesbarkeit weggelassen. Beachten Sie außerdem, dass dem Plugin zuvor der Pfad zu seiner Konfigurationsdatei bekannt gemacht werden muss, da er sich darauf verlässt. Im Folgenden also das Beispiel auf einem Linux-Server:

root@linux# export MK_CONFDIR="/etc/check_mk/"
root@linux# /usr/lib/check_mk_agent/plugins/mk_oracle -t
---login----------------------------------------------------------------
    Operating System:       Linux
    ORACLE_HOME (oratab):   /u01/app/oracle/product/11.2.0/xe
    Logincheck to Instance: XE
    Version:                11.2
    Login ok User:          checkmk on ORA-SRV01 Instance XE
    SYNC_SECTIONS:          instance dataguard_stats processes longactivesessions sessions recovery_status undostat logswitches recovery_area performance
    ASYNC_SECTIONS:         tablespaces rman jobs ts_quotas resumable
------------------------------------------------------------------------

Da man diesen Aufruf eher im Fehlerfall machen wird, werden Sie dann natürlich auch weitere Informationen erhalten: Sowohl den Connection String, welcher für die Verbindung benutzt wurde, als auch die ersten 100 Zeichen der Fehlermeldung, die bei dem Verbindungsversuch zurückgegeben wurde. Mit Hilfe dieser Informationen können Sie bereits schnell einfache Konfigurationsprobleme identifizieren und dann auch entsprechend beheben.

Windows

Das Plugin akzeptiert unter Windows keine Parameter. Um hier also die Verbindung zu testen, limitieren Sie temporär die abzurufenden Sektionen auf instance und aktivieren Sie die Option DEBUG:

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1
# Syntax:
# $DBUSER = @("USERNAME", "PASSWORD")
$DBUSER = @("checkmk", "myPassword")

SYNC_SECTIONS = @("instance")
ASYNC_SECTIONS = @("")
DEBUG = 1

Führen Sie danach das Plugin manuell aus. Auch hier werden Sie Informationen darüber bekommen, wie das Plugin versucht, auf die Instanzen zuzugreifen. Eine Ausgabe kann dann z.B. so aussehen:

C:\ProgramData\checkmk\agent\plugins\> .\mk_oracle.ps1
2020-08-23T12:48:20.3930944+02:00 DEBUG:value of DBVERSION software = xxx112020xxx
<<<oracle_instances>>>
2020-08-23T12:48:20.3930944+02:00 DEBUG:value of inst_name = xxxXExxx
2020-08-23T12:48:20.3930944+02:00 DEBUG:value of DBVERSION database = xxx112020xxx
2020-08-23T12:48:20.3930944+02:00 DEBUG:value of the_section = sql_instance
2020-08-23T12:48:20.3930944+02:00 DEBUG:now calling multiple SQL
2020-08-23T12:48:20.3930944+02:00 DEBUG:value of sql_connect in dbuser = checkmk/myPassword@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SID=XE))) as sysdba
<<<oracle_instance>>>
XE|FAILURE|...

7.2. Ein Log erstellen lassen

Linux, AIX, Solaris

Falls der Fehler nicht durch die Prüfung einer einfachen Verbindung gefunden werden kann, können Sie als nächsten Schritt ein komplettes Log anlegen lassen, welches sämtliche Schritte des Plugins protokolliert. Auch hier benötigen Sie den Pfad zu der Konfigurationsdatei und zusätzlich auch den Pfad zu den zwischengespeicherten Daten des Plugins. Die Ausgabe der Sektionen wurde hier ebenfalls übersprungen, um die Lesbarkeit zu erhöhen:

root@linux# export MK_CONFDIR="/etc/check_mk/"
root@linux# export MK_VARDIR="/var/lib/check_mk_agent/"
root@linux# /usr/lib/check_mk_agent/plugins/mk_oracle -l
Start logging to file: /var/lib/check_mk_agent/log/mk_oracle.log

Mit Hilfe dieses Logs können Sie im Zweifel sehr genau identifizieren, an welcher Zeile des Skripts das Problem auftritt.

Windows

Das Logging unter Windows funktioniert ähnlich wie der Verbindungstest an sich. Ist die Verbindung selbst stabil, können Sie in der Konfigurationsdatei die echten Sektionen wieder hinzufügen und bekommen dann entsprechend eine komplette Logging-Ausgabe.

7.3. Debugging des Plugins

Linux, AIX, Solaris

Wenn Sie auch mit Hilfe des Logs nicht an das Problem kommen, bietet das Plugin die komplette Ausgabe aller Schritte als letzte Möglichkeit der Fehleranalyse. Diese Ausgabe ist entsprechend auch die umfangreichste und sicherlich auch die am schwersten zu lesende Möglichkeit, an die Ursache eines Problems zu kommen und sollte daher auch nur als letztes Mittel eingesetzt werden. Sie können das Debugging mit der Option -d aufrufen. Vergessen Sie nicht die notwendige Umgebungsvariable:

root@linux# export MK_CONFDIR="/etc/check_mk/"
root@linux# /usr/lib/check_mk_agent/plugins/mk_oracle -d

Wichtig: In dieser Ausgabe werden keine sensiblen Daten wie Passwörter maskiert. Es ist also alles in Klartext lesbar.

Windows

Unter Windows steht Ihnen eine ähnliche Funktionalität zur Verfügung. Da Sie dem Plugin keine Argumente übergeben können, müssen Sie das Tracing allerdings manuell anschalten:

C:\ProgramData\checkmk\agent\plugins\> Set-PSDebug -Trace 1
C:\ProgramData\checkmk\agent\plugins\> .\mk_oracle.ps1

8. Dateien und Verzeichnisse

8.1. Linux, AIX und Solaris

Pfad Bedeutung

/usr/bin/check_mk_agent

Der Agent, welcher alle Daten zu dem Host sammelt.

/usr/lib/check_mk/plugins/mk_oracle/

Das übliche Verzeichnis, wo das Plugin liegt. Beachten Sie, dass der Pfad unter AIX etwas anders ist: /usr/check_mk/lib/plugins/mk_oracle/

/etc/check_mk/oracle.cfg

Die Konfigurationsdatei für das Plugin. Auch hier unterscheidet sich AIX: /usr/check_mk/conf/mk_oracle.cfg

/etc/check_mk/sqlnet.ora

Die Konfigurationsdatei, welche für das Oracle-Wallet benötigt wird.

/etc/check_mk/tnsnames.ora

Die Konfigurationsdatei, welche einen Alias für ein Schema bestimmt, wenn Sie sie manuell angeben. Beispieldateien liegen auch in der Oracle-Installation, aber da sich der Pfad je nach Installation unterscheidet, kann er nicht pauschal angegeben werden.

8.2. Windows

Pfad Bedeutung

C:\Program Files (x86)\checkmk\service\check_mk_agent.exe

Der Agent, welcher alle Daten zu dem Host sammelt.

C:\ProgramData\checkmk\agent\plugins\mk_oracle.ps1

Das übliche Verzeichnis, wo die Plugins abgelegt werden.

C:\ProgramData\checkmk\agent\config\mk_oracle_cfg.ps1

Die Konfigurationsdatei für das Plugin.

C:\ProgramData\checkmk\agent\config\sqlnet.ora

Die Konfigurationsdatei, welche für das Oracle-Wallet benötigt wird.

C:\ProgramData\checkmk\agent\config\tnsnames.ora

Die Konfigurationsdatei, welche einen Alias für ein Schema bestimmt, wenn Sie sie manuell angeben. Beispieldateien liegen auch in der Oracle-Installation, aber da sich der Pfad je nach Installation unterscheidet, kann er nicht pauschal angegeben werden.

8.3. Auf dem Checkmk-Server

Pfad Bedeutung

~/share/check_mk/agents/cfg_examples/mk_oracle.cfg

Hier befinden sich Beispiele zu der Konfiguration unter Linux, AIX oder Solaris. Eine solche Konfiguration benötigt das Plugin, um Daten abholen zu dürfen, da dort u.a. auch Zugangsdaten definiert werden können.

~/share/check_mk/agents/windows/cfg_examples/mk_oracle_cfg.ps1

Beispiele zu der Konfiguration unter Windows befinden sich hier.

~/share/check_mk/agents/windows/plugins/mk_oracle.ps1

Das Plugin für Windows, welches auf dem Oracle-Host die Daten holt.

~/share/check_mk/agents/plugins/mk_oracle

Das Plugin für unixoide Systeme, welches auf dem Oracle-Host die Daten holt.

~/share/check_mk/agents/plugins/mk_oracle_crs

Dieses Plugin liefert Daten zu einem Oracle Cluster Manager.

Auf dieser Seite