KNW-1345 - ready for review

Author: thomaskoslowski

images/ds_program_netapp.png

@@ -1,8 +1,8 @@
 // -*- coding: utf-8 -*-
-// IGNORE WebAPI
+// IGNORE
 include::global_attr.adoc[]
 = Datenquellenprogramme
-:revdate: 2023-01-30
+:revdate: draft
 :title: Datenquellenprogramme - Geräte ohne direkten Agentenzugriff überwachen
 :description: Mit Datenquellenprogrammen werden Hosts überwacht, welche nicht direkt oder nur über eine API erreichbar sind. Grundlegende Informationen zur Funktion werden hier beschrieben.
 
@@ -14,6 +14,7 @@ xref:piggyback#[Der Piggyback-Mechanismus]
 {related-end}
 
 
+[#intro]
 == Einleitung
 
 Der {CMK}-Server erreicht Hosts im xref:glossar#pull_mode[Pull-Modus] üblicherweise über eine TCP-Verbindung auf Port 6556.
@@ -32,7 +33,7 @@ Die Idee ist sehr einfach:
 Sie geben {CMK} die Kommandozeile eines Befehls.
 Anstelle der Verbindung auf Port 6556 führt {CMK} diesen Befehl aus.
 Dieser produziert die Agentendaten auf der _Standardausgabe_, welche dann von {CMK} genauso verarbeitet werden, als kämen sie von einem „normalen“ Agenten.
-Da Änderungen der Datenquellen meist Transportwege betreffen, ist es wichtig, dass Sie den Host in der Setup-GUI auf der Einstellung [.guihint]#API integrations if configured, else {CMK} agent# belassen.
+Da Änderungen der Datenquellen meist Transportwege betreffen, ist es wichtig, dass Sie den Host in der xref:hosts_setup#monitoring_agents[Setup-GUI] auf der Einstellung [.guihint]#API integrations if configured, else {CMK} agent# belassen.
 
 Die Modularität von {CMK} hilft, diese Anforderungen zu erfüllen.
 Letztlich kann die Klartextausgabe des Agentenskripts über beliebige Wege transportiert werden -- direkt oder indirekt, per Pull oder Push.
@@ -48,13 +49,14 @@ Ein weiterer Anwendungsbereich für Datenquellenprogramme sind Systeme, die kein
 In solchen Fällen können Sie ein Datenquellenprogramm schreiben, das die vorhandene Schnittstelle abfragt und aus den gewonnenen Daten Agenten-Output generiert.
 
 
+[#writing]
 == Schreiben von Datenquellenprogrammen
 
 === Das einfachst mögliche Programm
 
 Das Schreiben und Einbinden eines eigenen Datenquellenprogramms ist nicht schwer.
 Sie können jede von Linux unterstützte Skript- und Programmiersprache verwenden.
-Legen Sie das Programm am besten im Verzeichnis `~/local/bin` an, dann wird es immer automatisch ohne Pfadangabe gefunden.
+Legen Sie das Programm am besten im Verzeichnis `~/local/bin/` an, dann wird es immer automatisch ohne Pfadangabe gefunden.
 
 Folgendes erstes minimale Beispiel heißt `myds` und erzeugt einfache fiktive Monitoring-Daten.
 Anstatt einen neuen Transportweg zu integrieren, erzeugt es Monitoring-Daten selbst. 
@@ -236,37 +238,41 @@ Einige häufig benötigte Datenquellenprogramme werden von {CMK} mitgeliefert.
 Diese erzeugen Agentenausgaben nicht durch den Abruf eines normalen {CMK}-Agenten auf irgendwelchen krummen Wegen, sondern sind für die Abfrage von bestimmter Hardware oder Software konzipiert.
 
 Weil diese Programme teilweise recht komplexe Parameter benötigen, haben wir dafür spezielle Regelsätze in der Setup-GUI definiert, mit denen Sie diese direkt konfigurieren können.
-Diese Regelsätze finden Sie gruppiert nach Anwendungsfällen unter [.guihint]#Setup > Agents > Other integrations# und [.guihint]#Setup > Agents > VM, Cloud, Container#.
+Diese Regelsätze finden Sie gruppiert nach Anwendungsfällen unter [.guihint]#Setup > Agents > VM, cloud, container# und [.guihint]#Setup > Agents > Other integrations:#
 
+.Regelsätze unter [.guihint]#Setup > Agents > Other integrations#
+image::ds_program_rules.png[alt="Regelsätze für die Überwachung von Anwendungen per Datenquelle und Piggyback."]
+
+[TIP]
+====
 Wer von älteren {CMK} Versionen umgestiegen ist, wird sich möglicherweise über die neue Gruppierung wundern:
 Seit {v20} gruppiert {CMK} nicht mehr nach Zugriffstechnik, sondern nach Art des überwachten Objektes.
 Dies ist insbesondere deshalb sinnvoll, weil es in vielen Fällen den Anwender nicht interessiert, mit welcher Technik Daten eingeholt werden und zudem oft Datenquellen und xref:piggyback#[Piggyback] miteinander kombiniert werden, hier also keine klare Abgrenzung möglich ist.
+====
 
-image::ds_program_rules.png[alt="Regelsätze für die Überwachung von Anwendungen per Datenquelle und Piggyback."]
-
-Diese Programme heißen auch „Spezialagenten“, weil sie eben ein _spezieller_ Ersatz für den normalen {CMK}-Agenten sind.
-Nehmen Sie als Beispiel die Überwachung von NetApp Filers.
+Diese Programme heißen auch _Spezialagenten,_ weil sie eben ein _spezieller_ Ersatz für den normalen {CMK}-Agenten sind.
+Nehmen Sie als Beispiel die Überwachung von _NetApp Filers._
 Diese lassen die Installation eines {CMK}-Agenten nicht zu.
 Die SNMP-Schnittstelle ist langsam, fehlerhaft und unvollständig.
-Aber es gibt eine spezielle HTTP-Schnittstelle, welche Zugriff auf alle Überwachungsdaten liefert.
-
-Der Spezialagent `agent_netapp` greift über diese Schnittstelle zu und wird über den Regelsatz [.guihint]#NetApp via WebAPI# als Datenquellenprogramm eingerichtet.
-Wichtig ist, dass Sie den Host in der Setup-GUI auf der Einstellung [.guihint]#API integrations if configured, else {CMK} agent# belassen.
+Aber es gibt eine spezielle HTTP-Schnittstelle, welche Zugriff auf das NetApp-Betriebssystem _Ontap_ und alle Überwachungsdaten liefert.
 
+Der Spezialagent `agent_netapp_ontap` greift über eine REST-API auf diese Schnittstelle zu und wird über den Regelsatz [.guihint]#NetApp via Ontap REST API# als Datenquellenprogramm eingerichtet.
 Im Inhalt der Regel können Sie dann die Daten eingeben, die der Spezialagent braucht.
 Fast immer sind das irgendwelche Zugangsdaten.
-Beim NetApp-Agenten gibt es noch eine zusätzliche Checkbox für das Erfassen von Metriken (die hier recht umfangreich werden können):
+Beim NetApp-Spezialagenten gibt es unter anderen auch noch eine zusätzliche Checkbox für das Erfassen von Metriken (die hier recht umfangreich werden können):
+
+image::ds_program_netapp.png[alt="Regel zur Konfiguration des Netapp-Spezialagenten."]
 
-image::ds_program_netapp.png[alt="Eingabemaske der Zugangsdaten für die Netapp-Überwachung."]
+Wichtig ist, dass Sie den Host in der xref:hosts_setup#monitoring_agents[Setup-GUI] auf der Einstellung [.guihint]#API integrations if configured, else {CMK} agent# belassen.
 
 Es gibt seltene Situationen, in denen Sie sowohl einen Spezialagenten als auch den normalen Agenten abfragen möchten.
 Ein Beispiel dafür ist die Überwachung von xref:monitoring_vmware#[VMware ESXi] über das vCenter.
 Letzteres ist auf einer (meist virtuellen) Windows-Maschine installiert, auf welcher sinnvollerweise auch ein {CMK}-Agent läuft.
 
-image::ds_program_vcenter.png[alt="Auswahlmöglichkeiten 'host system' vs. 'vCenter' in der VMware ESXi Konfiguration."]
+image::ds_program_vcenter.png[alt="Auswahlmöglichkeiten beim Abfragetyp in der VMware ESXi Konfiguration."]
 
-Die Spezialagenten sind unter `~/share/check_mk/agents/special` installiert.
-Wenn Sie eine Modifikation an einem solchen Agenten machen möchten, dann kopieren Sie die Datei mit dem gleichen Namen nach `~/local/share/check_mk/agents/special` und ändern Sie sie dort.
+Die Spezialagenten sind unter `~/share/check_mk/agents/special/` installiert.
+Wenn Sie eine Modifikation an einem solchen Agenten machen möchten, dann kopieren Sie die Datei mit dem gleichen Namen nach `~/local/share/check_mk/agents/special/` und ändern Sie sie dort.
 
 
 [#files]
@@ -277,7 +283,6 @@ Wenn Sie eine Modifikation an einem solchen Agenten machen möchten, dann kopier
 |Pfad |Bedeutung
 
 |`~/local/bin/` |Ablage von eigenen Programmen oder Skripten, die im Suchpfad sein sollen und ohne Pfadangabe direkt ausgeführt werden können. Ist ein Programm sowohl in `~/bin/` als auch in `~/local/bin/`, hat letzteres Vorrang.
-|`~/share/check_mk/agents/special` |Hier sind die mitgelieferten Spezialagenten installiert.
-|`~/local/share/check_mk/agents/special` |Ablage der von Ihnen modifizierten Spezialagenten.
+|`~/share/check_mk/agents/special/` |Hier sind die mitgelieferten Spezialagenten installiert.
+|`~/local/share/check_mk/agents/special/` |Ablage der von Ihnen modifizierten Spezialagenten.
 |===
-

images/ds_program_rules.png

@@ -1,8 +1,8 @@
 // -*- coding: utf-8 -*-
-// IGNORE WebAPI
+// IGNORE
 include::global_attr.adoc[]
 = Datasource programs
-:revdate: 2023-03-06
+:revdate: draft
 :title: Datasource programs - Monitoring devices without access to an operating system
 :description: Datasource programs monitor hosts that are reachable only through an API. Basic information about this function is provided here.
 
@@ -14,6 +14,7 @@ xref:piggyback#[The piggyback mechanism]
 {related-end}
 
 
+[#intro]
 == Introduction
 
 {CMK} usually accesses monitored hosts in the xref:glossar#pull_mode[pull mode] via a TCP connection to port 6556.
@@ -32,7 +33,7 @@ The idea is very simple:
 one passes a command as text to {CMK}.
 Instead of connecting to port 6556, {CMK} executes this command.
 This produces the agent data on the _standard output_, which is then processed by {CMK} in exactly the same way as if it had come from a ‘normal’ agent.
-Since changes to data sources usually only affect transports, it is important that you leave the host to [.guihint]#API integrations if configured, else {CMK} agent# in the Setup GUI.
+Since changes to data sources usually only affect transports, it is important that you leave the host to [.guihint]#API integrations if configured, else {CMK} agent# in the xref:hosts_setup#monitoring_agents[Setup GUI].
 
 The modularity of {CMK} helps you to fulfill these requirements by transmitting the plain text agent output over arbitrary means of transport.
 Ultimately, the plain text output of the agent script can be transported by any means -- direct or indirect, pull or push.
@@ -48,13 +49,14 @@ Another area of application for datasource programs are systems that do not allo
 In such cases, you can write a datasource program that queries the existing interface and generates agent output from the data obtained.
 
 
-== Writing from datasource programs
+[#writing]
+== Writing datasource programs
 
 === The simplest possible program
 
 The writing and installation of a datasource program is not difficult.
 Any Linux-supported script and program language can be used.
-The program is best stored in the `~/local/bin` directory, where it will always be found automatically without the need to specify a data path.
+The program is best stored in the `~/local/bin/` directory, where it will always be found automatically without the need to specify a data path.
 
 The following first very basic example is called `myds` and it generates simple, fictional monitoring data.
 Instead of integrating a new transport path, it generates the monitoring data itself. 
@@ -235,37 +237,41 @@ A number of often-required datasource programs are delivered with {CMK}.
 These generate agent outputs not just by calling a normal {CMK} agent in a roundabout way, rather they have been specially conceived for the querying of particular hardware or software.
 
 Because these programs sometimes require quite complex parameters, we have defined special rule sets in the Setup GUI that allow you to configure them directly.
-You can find these rule sets grouped by use cases under [.guihint]#Setup > Agents > Other integrations# and [.guihint]#Setup > Agents > VM, Cloud, Container#.
+You can find these rule sets grouped by use cases under [.guihint]#Setup > Agents > VM, cloud, container# and [.guihint]#Setup > Agents > Other integrations#.
 
+.Rule sets under [.guihint]#Setup > Agents > Other integrations#
+image::ds_program_rules.png[alt="Rule sets for monitoring applications by datasource and piggyback."]
+
+[TIP]
+====
 Those who have switched from older {CMK} versions may be surprised by the new grouping:
 {CMK} {v20} no longer groups according to access technique, but by type of monitored object.
 This is particularly useful because in many cases the user is not interested in which technique is used to retrieve data and, moreover, data sources and xref:piggyback#[piggyback] are often combined, so no clear delimitation is possible here.
+====
 
-image::ds_program_rules.png[alt="Rule sets for monitoring applications by datasource and piggyback."]
-
-These programs are also known as ‘special agents’, because they are a _special_ alternative to the normal {CMK} agents.
-As an example, let us take the monitoring of NetApp Filers.
+These programs are also known as _special agents_, because they are a _special_ alternative to the normal {CMK} agents.
+As an example, let us take the monitoring of _NetApp Filers_.
 These do not allow the installation of {CMK} agents.
 The SNMP interface is slow, flawed and incomplete.
-There is however a special HTTP interface which provides access to all of the monitoring data.
-
-The `agent_netapp` special agent accesses via this interface and is set up as a datasource program via the [.guihint]#NetApp via WebAPI# rule set.
-It is important that you leave the host set to [.guihint]#API integrations if configured, else {CMK} agent# in the Setup GUI.
+There is however a special HTTP interface which provides access to the NetApp _Ontap_ operating system and all of the monitoring data.
 
+The `agent_netapp_ontap` special agent accesses this interface via a REST API and is set up as a data source program using the [.guihint]#NetApp via Ontap REST API# rule set.
 The data required by the special agent can then be entered into the rule's content.
 This is almost always some sort of access data.
-With the NetApp agent there is also an additional check box for the recording of metrics (which here can be quite comprehensive):
+With the NetApp special agent there is also an additional check box for the recording of metrics (which here can be quite comprehensive):
+
+image::ds_program_netapp.png[alt="Rule for configuring the NetApp special agent."]
 
-image::ds_program_netapp.png[alt="Input mask of the access data for Netapp monitoring."]
+It is important that you leave the host set to [.guihint]#API integrations if configured, else {CMK} agent# in the xref:hosts_setup#monitoring_agents[Setup GUI].
 
 There are rare occasions in which it is desired that both a special agent, as well as the normal agent are to be queried.
 An example for this is the monitoring of xref:monitoring_vmware#[VMware ESXi] over the vCenter.
 This latter is installed on a (usually virtual) Windows machine, on which reasonably enough a {CMK} agent is also running.
 
-image::ds_program_vcenter.png[alt="Choices 'host system' vs. 'vCenter' in VMware ESXi configuration."]
+image::ds_program_vcenter.png[alt="Query type options in the VMware ESXi configuration."]
 
-The special agents are installed under `~/share/check_mk/agents/special`.
-If you wish to modify such an agent, first copy the file with the same name to `~/local/share/check_mk/agents/special` and make your changes in that new version.
+The special agents are installed under `~/share/check_mk/agents/special/`.
+If you wish to modify such an agent, first copy the file with the same name to `~/local/share/check_mk/agents/special/` and make your changes in that new version.
 
 
 [#files]
@@ -275,6 +281,6 @@ If you wish to modify such an agent, first copy the file with the same name to `
 |===
 |Path |Function 
 |`~/local/bin/` |The repository for own programs and scripts that should be in a search path, and which can be directly executed without specifying the path. If a program is in `~/bin/` as well as in `~/local/bin/`, the latter has priority.
-|`~/share/check_mk/agents/special` |The special agents provided with {CMK} are installed here.
-|`~/local/share/check_mk/agents/special` |The repository for your own modified special agents.
+|`~/share/check_mk/agents/special/` |The special agents provided with {CMK} are installed here.
+|`~/local/share/check_mk/agents/special/` |The repository for your own modified special agents.
 |===