Guide du développeur de VMware vrealize Log Insight

Transcription

1 Guide du développeur de VMware vrealize Log Insight vrealize Log Insight 3.0 Ce document prend en charge la version de chacun des produits répertoriés, ainsi que toutes les versions publiées par la suite jusqu'au remplacement dudit document par une nouvelle édition. Pour rechercher des éditions plus récentes de ce document, rendez-vous sur : FR

2 Guide du développeur de VMware vrealize Log Insight Vous trouverez la documentation technique la plus récente sur le site Web de VMware à l'adresse : Le site Web de VMware propose également les dernières mises à jour des produits. N hésitez pas à nous transmettre tous vos commentaires concernant cette documentation à l adresse suivante : docfeedback@vmware.com Copyright 2015 VMware, Inc. Tous droits réservés. Copyright et informations sur les marques. VMware, Inc Hillview Ave. Palo Alto, CA VMware, Inc Quartier Boieldieu Paris La Défense France 2 VMware, Inc.

3 Table des matières 1 À propos du Guide du développeur de vrealize Log Insight 5 Utilisation de l'api Ingestion de vrealize Log Insight 5 Utilisation de l'api Administration 8 Index 17 VMware, Inc. 3

4 Guide du développeur de VMware vrealize Log Insight 4 VMware, Inc.

5 À propos du Guide du développeur 1 de vrealize Log Insight Le Guide du développeur de VMware vrealize Log Insight fournit des informations sur l'api Ingestion de vrealize Log Insight. Public visé Ces informations s'adressent aux personnes qui veulent utiliser l'api Ingestion de vrealize Log Insight. Vous devez maîtriser les concepts REST et le format de sérialisation JSON. Ce chapitre aborde les rubriques suivantes : «Utilisation de l'api Ingestion de vrealize Log Insight», page 5 «Utilisation de l'api Administration», page 8 Utilisation de l'api Ingestion de vrealize Log Insight Vous pouvez interagir avec l'api Ingestion de vrealize Log Insight pour envoyer des événements au serveur vrealize Log Insight. Tous les corps de demande et de réponse de l'api sont des chaînes JSON codées en UTF8 avec un champ d'en-tête Content-Type: application/json. Tous les appels qui aboutissent renvoient le code de réponse HTTP 200. Appliquer les connexions SSL seulement Vous pouvez utiliser l'interface utilisateur Web de vrealize Log Insight pour configurer Log Insight Agents et l'api Ingestion pour autoriser uniquement les connexions SSL au serveur. REMARQUE La version actuelle de vrealize Log Insight ne prend pas en charge les connexions SSL syslog et fonctionne uniquement pour l'api Ingestion de vrealize Log Insight. Prérequis Vérifiez que vous êtes connecté à l'interface utilisateur Web de vrealize Log Insight en tant qu'utilisateur disposant de l'autorisation Modifier du contenu d'administration. Le format de l'url est où log-insight-host est l'adresse IP ou le nom d'hôte du dispositif virtuel vrealize Log Insight. Procédure 1 Cliquez sur l'icône du menu déroulant de configuration et sélectionnez Administration. 2 Dans Configuration, cliquez sur SSL. 3 Sous l'api Server SSL, cochez la case Exiger une connexion SSL. VMware, Inc. 5

6 Guide du développeur de VMware vrealize Log Insight 4 Cliquez sur Enregistrer. L'API vrealize Log Insight autorise uniquement les connexions SSL au serveur. Les connexions non-ssl sont refusées. Utilisation du service messages/ingestion Vous pouvez utiliser le service messages/ingestion pour envoyer des événements à un serveur vrealize Log Insight à l'aide de demandes HTTP POST. Le service messages/ingestion utilise la syntaxe suivante. Protocole HTTP HTTPS Valeur Si vous appliquez SSL à partir de l'interface utilisateur Web, vous ne pourrez utiliser que HTTPS. Reportezvous à «Appliquer les connexions SSL seulement», page 5. Méthode HTTP POST REMARQUE L'API vrealize Log Insight Ingestion a une limite de 100 Ko par demande HTTP POST. La taille maximale d'un seul champ text est de 16 Ko. 6 VMware, Inc.

7 Chapitre 1 À propos du Guide du développeur de vrealize Log Insight Paramètres Paramètre Type Où transférer Description agentid String Dans l'url L'ID de l'agent émetteur doit respecter la norme UUID. L'agent peut être un agent vrealize Log Insight Windows ou Linux officiel ou tout autre client tirant parti de l'api Ingestion. Content-Type: application/json String Dans le corps de publication Le paramètre Content-Type spécifie la nature des données dans le corps de publication. Events array Array Dans le corps de publication Un groupe d'événements. Chaque événement doit avoir le format suivant. "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",,...],...] REMARQUE Le serveur vrealize Log Insight compare le "timestamp" que vous fournissez à l'heure locale du serveur vrealize Log Insight. Si vous fournissez un "timestamp" se trouvant hors de la fenêtre de décalage de 10 minutes tolérée par défaut, le serveur vrealize Log Insight ne tient pas compte de votre "timestamp" et utilise son heure locale. En l'absence de "timestamp", vrealize Log Insight utilise l'heure d'arrivée. REMARQUE Si le "content" d'un champ est absent, "startposition" et "length" doivent être présents et doivent pointer vers une position valide dans la chaîne du champ "text". Valeurs HTTP de retour Nom Type Description 200 OK Entier Codes de réponse HTTP standard 400 Bad Request 500 Internal Server Error 503 Service Unavailable Cette réponse indique que le serveur est surchargé. L'en-tête de réponse Retry-After indique le laps de temps suggéré devant s'écouler avant une nouvelle tentative en secondes. Exemple de demande POST Host: loginsight:9000 Connection: keep-alive Content-Type: application/json charset: utf-8 Content-Length:?? VMware, Inc. 7

8 Guide du développeur de VMware vrealize Log Insight "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": ] Exemple de réponse HTTP/ OK "status":"ok","message":"messages ingested","ingested":18 Utilisation de l'api Administration Vous pouvez interagir avec l'api Administration de Log Insight pour configurer les demandes de connexion/d'authentification et de licence sur le serveur Log Insight. Services de l'api Administration Une liste de services que l'api Administration de Log Insight contient. API Authentification de la connexion L'authentification doit être fournie avec chaque demande pour utiliser l'api Restful de Log Insight HMAC (hash based message authentication, authentification de messages utilisant la fonction de hachage) est utilisé. Chaque en-tête de demande doit contenir les paramètres suivants des demandes authentifiées : X-li-session-id X-li-hmac X-li-timestamp L'en-tête X-li-hmac contient le paramètre SHA1HMAC de la signature de la demande avec le paramètre apikey fourni dans la réponse d'authentification. La signature de la demande est définie par : <METHOD> + <PATH> (+?<QUERY>) + <TIMESTAMP> (+ <REQUEST_BODY>) Exemple : GET/api/v1/users ou POST/api/v1/users "username": "newuser" Pour authentifier, utilisez l'action suivante. API POST (toutes les API sont disponibles sur pour les connexions SSL). 8 VMware, Inc.

9 Chapitre 1 À propos du Guide du développeur de vrealize Log Insight Demande "username": "admin", "password": "something" Le code d'état HTTP 200 est renvoyé en cas de réussite. Le code d'état HTTP 401 est renvoyé en cas de nom d'utilisateur ou mot de passe non valide. Réponse "userid": "USER_GUID", "sessionid": "HCvSSzt...some long session ID String", "apikey": "8NxL8...some long apikey String", "ttl": session timeout int value API Authentification L'exemple suivant illustre les méthodes de base pour authentifier et effectuer des demandes authentifiées. L'exemple de code source indique quelle réponse est renvoyée sur demande de connexion, quels paramètres sont utilisés pour effectuer la demande authentifiée, comment la clé HMAC peut être générée, et le type d'en-tête que les demandes authentifiées devraient avoir. private static final String HOST_ADDRESS = " private static final String USERNAME = "USERNAME "; private static final String PASSWORD = "PASSWORD"; private static String sessionid; private static String apikey; private static void authenticate() // authentication request String path = "/api/v1/sessions"; String body = String.format("\"username\":\"%s\",\"password\":\"%s\"", USERNAME, PASSWORD); HTTPResponse response = HTTPRequester.doHttpRequest(HOST_ADDRESS + path, RequestType.POST, body, null); try JSONObject jsonresponse = new JSONObject(response.responseString); // get sessionid, this will be used later for authenticated API calls sessionid = jsonresponse.getstring("sessionid"); // get apikey, this will be used later when generating hmac for authenticated API calls apikey = jsonresponse.getstring("apikey"); catch (JSONException e) // could not parse response; throw new RuntimeException(e); private static HTTPResponse makerequest(requesttype requesttype, String path, String body) VMware, Inc. 9

10 Guide du développeur de VMware vrealize Log Insight // create headers Map<String, String> headers = new HashMap<>(); headers.put("x-li-session-id", getsessionid()); String timestamp = String.valueOf(TimeUnit.MILLISECONDS.toSeconds(System.currentTimeMillis())); headers.put("x-li-timestamp", timestamp); try String hmac = calculatehmac(requesttype, path, timestamp, body, getapikey()); headers.put("x-li-hmac", hmac); catch (InvalidKeyException NoSuchAlgorithmException e) // could not calculate hmac throw new RuntimeException(e); return HTTPRequester.doHttpRequest(HOST_ADDRESS + path, requesttype, body, headers); private static String calculatehmac(requesttype requesttype, String path, String timestamp, String body, String apikey) throws InvalidKeyException, NoSuchAlgorithmException byte[] signature = (requesttype.tostring() + path + timestamp).getbytes(); if (body!= null) signature = ArrayUtils.addAll(signature, body.getbytes()); return calculatehmac(signature, apikey); private static String calculatehmac(byte[] signature, String apikey) throws NoSuchAlgorithmException, InvalidKeyException String hmacalgorithm = "HmacSHA1"; SecretKeySpec signingkey = new SecretKeySpec(apiKey.getBytes(), hmacalgorithm); Mac mac = Mac.getInstance(hmacAlgorithm); mac.init(signingkey); byte[] rawhmac = mac.dofinal(signature); return Base64.encodeBase64String(rawHmac); private static String getsessionid() if (sessionid == null) authenticate(); return sessionid; private static String getapikey() if (apikey == null) authenticate(); return apikey; API Gestion des licences Cette API décrit les fonctionnalités de gestion des licences du serveur Log Insight. API GET GET /api/v1/license Description : renvoie une liste de toutes les licences enregistrées sur le serveur Log Insight. 10 VMware, Inc.

11 Chapitre 1 À propos du Guide du développeur de vrealize Log Insight Demande : cette méthode n'utilise pas de paramètres de demandes. Réponse : représentation des données JSON de licences. Contrôle d'accès : cette API est disponible aux appelants avec les rôles VIEW_ADMIN et EDIT_ADMIN. L'objet Réponse peut contenir les champs suivants : "maxosis": Integer, // max supported OSes "maxcpus": Integer, // max supported CPUs "hascpu": Boolean, "hasosi": Boolean, "hastap": Boolean, "licenses": // array of licenseid:license pairs with all licenses available on the server "UUID_OF_LICENSE": "id": UUID //the id of license "status": String, //the status of license. Values should be from this array: "Error", "ACTIVE", "EXPIRED", "UNINITIALIZED", "DELETED" "error": String, //error text "configuration": String, //configuration description "expiration": Long, //expiration date "licensekey": String, //license key "infinite": Boolean, //is infinite cout or not "count": Integer, //count "typeenum": String //type of license Exemple Demande : GET Réponse HTTP 200 : "licenses": VMware, Inc. 11

12 Guide du développeur de VMware vrealize Log Insight "2cb6e13b-e880-46c2-9e2e-7ab92d706422": "id": "2cb6e13b-e880-46c2-9e2e-7ab92d706422", "status": "Active", "error": "", "configuration": "5 Operating System Instances (OSIs)", "expiration": , "licensekey": "SOME_KEY_GUID", "infinite": false, "count": 0, "typeenum": "OSI", "3fbcdf35-8be6-48f9-9ca5-cccf97243e01": "id": "3fbcdf35-8be6-48f9-9ca5-cccf97243e01", "status": "Active", "error": "", "configuration": "Unlimited Operating System Instances (OSIs)", "expiration": , "licensekey": "SOME_KEY_GUID", "infinite": true, "count": 0, "typeenum": "OSI" API : POST POST /api/v1/license 12 VMware, Inc.

13 Chapitre 1 À propos du Guide du développeur de vrealize Log Insight Description : ajoutez une nouvelle licence sur le serveur Log Insight. Demande : nouvelle clé de licence Réponse : représentation des données JSON d'une licence nouvellement enregistrée. Le résultat de réussite renvoie le code de réponse HTTP 200. Dans d'autres cas HTTP 400, les codes d'état 409 sont renvoyés. En cas de demande HTTP 400, le corps de demande peut contenir le champ «errorcode» avec les valeurs «FIELD_ERRORS» ou «LICENSE_ERROR». Le corps de la réponse devrait contenir le champ «errordetails» dans ces cas-ci. En cas de «errorcode»:«field_errors,» les paires «key»:«failure reason» sont renvoyées dans «errordetails». En cas de «errorcode»:«license_error», «key»:«value», les paires sont renvoyées dans «errordetails». Les valeurs peuvent être «ALREADY_EXISTS», «EXPIRED», «WRONG» en provenance du package «com.vmware.loginsight.api.errors.license». La valeur «ALREADY_EXISTS» est renvoyée dans l'état HTTP 409. Contrôle d'accès : cette API n'est disponible qu'aux appelants avec la capacité EDIT_ADMIN. Exemple : Demande : POST Corps : "key":"new_license_key" Response success HTTP 200: "id": "f2a53ddd-c88e e9c-913c63ccdee1", "status": "Active", "error": "", "configuration": "25 Operating System Instances (OSIs)", "expiration": , "licensekey": "NEW_LICENSE_KEY", "infinite": true, "count": 0, "typeenum": "OSI" VMware, Inc. 13

14 Guide du développeur de VMware vrealize Log Insight Échec de réponse HTTP 409 : "errormessage": "License already exists.", "errorcode": "LICENSE_ERROR", "errordetails": "key": "com.vmware.loginsight.api.errors.license.already_exists" Response failure HTTP 400: "errormessage": "License has expired.", "errorcode": "LICENSE_ERROR", "errordetails": "key": "com.vmware.loginsight.api.errors.license.expired" Échec de réponse HTTP 400 : "errormessage": "License has expired.", "errorcode": "LICENSE_ERROR", "errordetails": "key": "com.vmware.loginsight.api.errors.license.expired" API : DELETE Description : supprimez une licence du serveur Log Insight. Demande : id de clé de licence à supprimer Réponse : représentation des données JSON de la licence supprimée. 14 VMware, Inc.

15 Chapitre 1 À propos du Guide du développeur de vrealize Log Insight Si la clé de licence n'existe pas, le code de réponse est HTTP 404 introuvable. Le corps de la réponse devrait contenir la paire clé/valeur «errorcode»:«license_error» dans ce cas-ci. Contrôle d'accès : cette API n'est disponible qu'aux appelants avec la capacité EDIT_ADMIN. Exemple : Demande : DELETE Réponse : HTTP 200 : Corps : vide Réponse : HTTP 404 : Corps : "errorcode": "LICENSE_ERROR", "errormessage": "Could not remove nonexistent license key.", "errordetails": "key": "com.vmware.loginsight.api.errors.license.not_exists" Exemples d'api Licence Appels GET, POST et DELETE de l'api Gestion des licences. private static void getlicenses() String path = "/api/v1/licenses"; HTTPResponse response = makerequest(requesttype.get, path, null); System.out.println("GET Licenses:" + response.responsecode + " \nmessage: " + response.responsestring); private static void addlicense(string licensekey) String path = "/api/v1/licenses"; String body = String.format("\"key\":\"%s\"", licensekey); HTTPResponse response = makerequest(requesttype.post, path, body); System.out.println("POST license" + response.responsecode + " \nmessage: " + response.responsestring); private static void removelicense(string licenseid) String path = "/api/v1/licenses/" + licenseid; HTTPResponse response = makerequest(requesttype.delete, path, null); System.out.println("DELETE Licenses:" + response.responsecode + " \nmessage: " + response.responsestring); VMware, Inc. 15

16 Guide du développeur de VMware vrealize Log Insight 16 VMware, Inc.

17 Index A api, utilisation 5 API, service messages/ingestion 6 API d'authentification de connexion 8 API Gestion des licences 10 appliquer la connexion SSL 5 P Public ciblé 5 VMware, Inc. 17

18 Guide du développeur de VMware vrealize Log Insight 18 VMware, Inc.