vrealize Log Insight- Entwicklerressourcen 11. September 2017 vrealize Log Insight 4.3

Transkript

1 vrealize Log Insight- Entwicklerressourcen 11. September 2017 vrealize Log Insight 4.3

2 vrealize Log Insight-Entwicklerressourcen Die neueste technische Dokumentation finden Sie auf der VMware-Website unter: Auf der VMware-Website finden Sie auch die aktuellen Produkt-Updates. Falls Sie Anmerkungen zu dieser Dokumentation haben, senden Sie Ihre Kommentare und Vorschläge an: Copyright 2017 VMware, Inc. Alle Rechte vorbehalten. Informationen zu Copyright und Marken. VMware, Inc Hillview Ave. Palo Alto, CA VMware Global, Inc. Zweigniederlassung Deutschland Freisinger Str Unterschleißheim/Lohhof Germany Tel.: +49 (0) Fax: +49 (0) VMware, Inc.

3 Inhalt 1 vrealize Log Insight Entwicklerressourcen 5 2 SSL-Verbindungen erzwingen 7 3 Verwenden der vrealize Log Insight Ingestion-API 9 Verwenden des events/ingest-dienstes 9 Verwenden des messages/ingest-dienstes (veraltet) 11 Die vrealize Log Insight -REST-API 13 Index 15 VMware, Inc. 3

4 vrealize Log Insight-Entwicklerressourcen 4 VMware, Inc.

5 vrealize Log Insight 1 Entwicklerressourcen Zielgruppe vrealize Log Insight-Entwicklerressourcen enthält Informationen zur vrealize Log Insight-API. Diese Informationen richten sich an jeden, der die vrealize Log Insight Ingestion-API verwenden möchte. Sie müssen mit REST-Konzepten sowie mit dem JSON-Serialisierungsformat vertraut sein. VMware, Inc. 5

6 vrealize Log Insight-Entwicklerressourcen 6 VMware, Inc.

7 SSL-Verbindungen erzwingen 2 Sie können die vrealize Log Insight-Web-Benutzeroberfläche verwenden, um die vrealize Log Insight Agents und die Ingestion-API so zu konfigurieren, dass nur SSL-Verbindungen mit dem Server zugelassen werden. Die vrealize Log Insight-API kann normalerweise über HTTP über den Port 9000 und über HTTPS über den Port 9543 erreicht werden. Beide Ports können vom vrealize Log Insight-Agent oder benutzerdefinierten API-Clients verwendet werden. Für alle authentifizierten Anforderungen ist SSL erforderlich. Nicht authentifizierte Anforderungen, einschließlich Erfassungsdatenverkehr über den vrealize Log Insight-Agent, können mit oder ohne SSL erfolgen. Sie können alle API-Anforderungen zwingen, SSL-Verbindungen zu verwenden. Dies führt zu keiner Einschränkung des Datenverkehrs über Syslog-Port 514 und hat keinen Einfluss auf die vrealize Log Insight-Benutzeroberfläche, für die Anforderungen an HTTP-Port 80 weiterhin an HTTPS-Port 443 weitergeleitet werden. Voraussetzungen Vergewissern Sie sich, dass Sie bei der Web-Benutzeroberfläche von vrealize Log Insight als Benutzer mit der Berechtigung Admin bearbeiten angemeldet sind. Das URL-Format lautet wobei log-insight-host die IP-Adresse oder der Hostname der virtuellen vrealize Log Insight-Appliance ist. Vorgehensweise 1 Klicken Sie auf das Dropdown-Menüsymbol für die Konfiguration und wählen Sie Verwaltung aus. 2 Klicken Sie unter Konfiguration auf SSL. 3 Wählen Sie unter API-Server-SSL die Einstellung SSL-Verbindung erforderlich. 4 Klicken Sie auf Speichern. Die vrealize Log Insight-API gestattet nur SSL-Verbindungen zu dem Server. Nicht-SSL-Verbindungen werden abgewiesen. VMware, Inc. 7

8 vrealize Log Insight-Entwicklerressourcen 8 VMware, Inc.

9 Verwenden der vrealize Log Insight 3 Ingestion-API Sie können mit der vrealize Log Insight Ingestion-API interagieren, um Ereignisse an den vrealize Log Insight-Server zu übermitteln. Bei sämtlichen API-Anforderungen und Antworten handelt es sich um UTF8-kodierte JSON-Zeichenfolgen mit dem Header-Feld Content-Type: application/json. Alle erfolgreichen Aufrufe geben den HTTP-Antwortcode 200 zurück. Dieses Kapitel behandelt die folgenden Themen: Verwenden des events/ingest-dienstes, auf Seite 9 Verwenden des messages/ingest-dienstes (veraltet), auf Seite 11 Die vrealize Log Insight-REST-API, auf Seite 13 Verwenden des events/ingest-dienstes Sie können den events/ingest-dienst verwenden, um unter Verwendung von HTTP POST-Anforderungen Ereignisse an einen vrealize Log Insight-Server zu senden. Der events/ingest-dienst verwendet die folgende Syntax. Protokoll HTTP HTTPS Wert HTTP-Methode POST Hinweis Die vrealize Log Insight Ingestion-API ist auf 4 MB pro HTTP POST-Anforderung beschränkt. Die maximale Größe für ein einzelnes Feld text beträgt 16 KB. VMware, Inc. 9

10 vrealize Log Insight-Entwicklerressourcen Parameter Parameter Typ Weiterleitungsziel Beschreibung agentid String In URL Die ID des sendenden Agent sollte dem UUID-Standard folgen. Der Agent kann ein offizieller vrealize Log Insight-Windows- oder Linux-Agent oder ein beliebiger Client sein, der die Ingestion-API nutzt. Content-Type: application/json String In POST- Textkörper Der Parameter Content-Type gibt die Art der Daten im POST-Textkörper an. Events array Array In POST- Textkörper Ein Array der Ereignisse. Jedes Ereignis muss das folgende Format aufweisen. {"events": [{ "text": optional, message text as a string, "timestamp": optional, timestamp encoded as number of milliseconds since Unix epoch in UTC, "fields": optional array of [{ "name": the name of the field, "content": optional, the content of the field, "startposition": optional, the start position in the "text", "length": optional, the length of the string in the "text", },...] },...] } Hinweis Der vrealize Log Insight-Server vergleicht den "timestamp", den Sie mit der lokalen Zeit auf dem vrealize Log Insight-Server angegeben haben. Wenn Sie einen "timestamp" angeben, der außerhalb der tolerierten 10-minütigen Abweichung liegt, ignoriert der vrealize Log Insight-Server Ihren "timestamp" und verwendet die lokale Zeit. Wenn "timestamp" nicht vorhanden ist, verwendet vrealize Log Insight die Ankunftszeit. Hinweis Wenn der "content" eines Felds nicht vorhanden ist, müssen die "startposition" und die "length" vorhanden sein und auf eine gültige Position in der "text"-feldzeichenfolge zeigen. HTTP-Rückgabewerte Name Typ Beschreibung 200 OK Integer Standard-HTTP-Antwortcodes 400 Bad Request 500 Internal Server Error 503 Service Unavailable Diese Antwort weist darauf hin, dass der Server überlastet ist. Der Retry- After-Antwortheader gibt den vorgeschlagenen Wiederholungszeitpunkt in Sekunden an. Beispielanforderung POST Host: loginsight:9000 Connection: keep-alive 10 VMware, Inc.

11 Kapitel 3 Verwenden der vrealize Log Insight Ingestion-API Content-Type: application/json charset: utf-8 Content-Length:?? {"events": [{ "fields": [ {"name": "Channel", "content": "Security"}, {"name": "EventID", "content": "4688"}, {"name": "EventRecordID", "content": " "}, {"name": "Keywords", "content": "Audit Success"}, {"name": "Level", "content": "Information"}, {"name": "OpCode","content": "Info"}, {"name": "ProcessID", "content": "4"}, {"name": "ProviderName", "content": "Microsoft-Windows-Security-Auditing"}, {"name": "Task", "content": "Process Creation"}, {"name": "ThreadID", "content": "64"} ], "text": "A new process has been created.", "timestamp": } ] } Beispielantwort HTTP/ OK {"status":"ok","message":"events ingested","ingested":18} Verwenden des messages/ingest-dienstes (veraltet) Sie können den messages/ingest-dienst verwenden, um unter Verwendung von HTTP POST-Anforderungen Ereignisse an einen vrealize Log Insight-Server zu senden. Der messages/ingest-dienst verwendet die folgende Syntax. Protokoll HTTP HTTPS Wert HTTP-Methode POST Hinweis Die vrealize Log Insight Ingestion-API ist auf 4 MB pro HTTP POST-Anforderung beschränkt. Die maximale Größe für ein einzelnes Feld text beträgt 16 KB. VMware, Inc. 11

12 vrealize Log Insight-Entwicklerressourcen Parameter Parameter Typ Weiterleitungsziel Beschreibung agentid String In URL Die ID des sendenden Agent sollte dem UUID-Standard folgen. Der Agent kann ein offizieller vrealize Log Insight-Windows- oder Linux-Agent oder ein beliebiger Client sein, der die Ingestion-API nutzt. Content-Type: application/json String In POST- Textkörper Der Parameter Content-Type gibt die Art der Daten im POST-Textkörper an. Events array Array In POST- Textkörper Ein Array der Ereignisse. Jedes Ereignis muss das folgende Format aufweisen. {"messages": [{ "text": optional, message text as a string, "timestamp": optional, timestamp encoded as number of milliseconds since Unix epoch in UTC, "fields": optional array of [{ "name": the name of the field, "content": optional, the content of the field, "startposition": optional, the start position in the "text", "length": optional, the length of the string in the "text", },...] },...] } Hinweis Der vrealize Log Insight-Server vergleicht den "timestamp", den Sie mit der lokalen Zeit auf dem vrealize Log Insight-Server angegeben haben. Wenn Sie einen "timestamp" angeben, der außerhalb der tolerierten 10-minütigen Abweichung liegt, ignoriert der vrealize Log Insight-Server Ihren "timestamp" und verwendet die lokale Zeit. Wenn "timestamp" nicht vorhanden ist, verwendet vrealize Log Insight die Ankunftszeit. Hinweis Wenn der "content" eines Felds nicht vorhanden ist, müssen die "startposition" und die "length" vorhanden sein und auf eine gültige Position in der "text"-feldzeichenfolge zeigen. HTTP-Rückgabewerte Name Typ Beschreibung 200 OK Integer Standard-HTTP-Antwortcodes 400 Bad Request 500 Internal Server Error 503 Service Unavailable Diese Antwort weist darauf hin, dass der Server überlastet ist. Der Retry- After-Antwortheader gibt den vorgeschlagenen Wiederholungszeitpunkt in Sekunden an. Beispielanforderung POST Host: loginsight:9000 Connection: keep-alive 12 VMware, Inc.

13 Kapitel 3 Verwenden der vrealize Log Insight Ingestion-API Content-Type: application/json charset: utf-8 Content-Length:?? {"messages": [{ "fields": [ {"name": "Channel", "content": "Security"}, {"name": "EventID", "content": "4688"}, {"name": "EventRecordID", "content": " "}, {"name": "Keywords", "content": "Audit Success"}, {"name": "Level", "content": "Information"}, {"name": "OpCode","content": "Info"}, {"name": "ProcessID", "content": "4"}, {"name": "ProviderName", "content": "Microsoft-Windows-Security-Auditing"}, {"name": "Task", "content": "Process Creation"}, {"name": "ThreadID", "content": "64"} ], "text": "A new process has been created.", "timestamp": } ] } Beispielantwort HTTP/ OK {"status":"ok","message":"messages ingested","ingested":18} Die vrealize Log Insight -REST-API Die REST-API bietet programmatischen Zugriff auf vrealize Log Insight und die damit erfassten Daten. Sie können die API verwenden, um Ereignisse in den vrealize Log Insight-Datenspeicher einzufügen, um Ereignisse abzufragen und um die Produktkonfiguration zu ändern. Sie können die API außerdem verwenden, um vrealize Log Insight zu installieren oder ein Upgrade durchzuführen. Weitere Informationen finden Sie in der vrealize Log Insight-API-Referenzdatei unter VMware, Inc. 13

14 vrealize Log Insight-Entwicklerressourcen 14 VMware, Inc.

15 Index A API messages/ingest-dienst 11 events/ingest-dienst 9 verwenden 9 E enforce SSL connection 7 R REST-API, Referenz 13 Z Zielgruppe 5 VMware, Inc. 15

16 vrealize Log Insight-Entwicklerressourcen 16 VMware, Inc.