From 4d06a8ddc1ead483934ff08b28cbaf3f52fe884b Mon Sep 17 00:00:00 2001 From: Evan Adam Date: Wed, 14 Aug 2024 12:42:08 +0200 Subject: [PATCH] doc(Gorgone): Fix documentation of action module Refs:MON-139728 --- gorgone/docs/api.md | 64 +++++++++++++++-------------- gorgone/docs/modules/core/action.md | 18 +++++--- 2 files changed, 46 insertions(+), 36 deletions(-) diff --git a/gorgone/docs/api.md b/gorgone/docs/api.md index 4ee643f273d..d98a8ea86a8 100644 --- a/gorgone/docs/api.md +++ b/gorgone/docs/api.md @@ -6,14 +6,14 @@ Centreon Gorgone provides a RestAPI through its HTTP server module. ### Get Nodes Connection Status -| Endpoint | Method | -| :- | :- | -| /internal/constatus | `GET` | +| Endpoint | Method | +|:--------------------|:-------| +| /internal/constatus | `GET` | #### Headers -| Header | Value | -| :- | :- | +| Header | Value | +|:-------|:-----------------| | Accept | application/json | #### Example @@ -42,14 +42,14 @@ curl --request GET "https://hostname:8443/api/internal/constatus" \ ### Get Public Key Thumbprint -| Endpoint | Method | -| :- | :- | -| /internal/thumbprint | `GET` | +| Endpoint | Method | +|:---------------------|:-------| +| /internal/thumbprint | `GET` | #### Headers -| Header | Value | -| :- | :- | +| Header | Value | +|:-------|:-----------------| | Accept | application/json | #### Example @@ -73,14 +73,14 @@ curl --request GET "https://hostname:8443/api/internal/thumbprint" \ ### Get Runtime Informations And Statistics -| Endpoint | Method | -| :- | :- | -| /internal/information | `GET` | +| Endpoint | Method | +|:----------------------|:-------| +| /internal/information | `GET` | #### Headers -| Header | Value | -| :- | :- | +| Header | Value | +|:-------|:-----------------| | Accept | application/json | #### Example @@ -158,6 +158,7 @@ The available endpoints depend on which modules are loaded. Endpoints are basically built from: * API root, +* optional target node, local if not present ( `/nodes/:nodeid/` ) * Module's namespace, * Module's name, * Action @@ -175,7 +176,7 @@ curl --request POST "https://hostname:8443/api/core/action/command" \ ]" ``` -Find more informations directly from modules documentations [here](../docs/modules.md). +Find more informations directly from modules documentations [here](./modules.md). As Centreon Gorgone is asynchronous, those endpoints will return a token corresponding to the action. @@ -187,7 +188,7 @@ As Centreon Gorgone is asynchronous, those endpoints will return a token corresp } ``` -That being said, its possible to make Gorgone work synchronously by providing two parameters. +That being said, it is possible to make Gorgone work synchronously by providing two parameters. First one is `log_wait` with a numeric value in microseconds: this value defines the amount of time the API will wait before trying to retrieve log results. @@ -202,7 +203,7 @@ Note: the `sync_wait` parameter is induced if you ask for a log directly specify Using the `/core/action/command` endpoint with `log_wait` parameter set to 100000: ```bash -curl --request POST "https://hostname:8443/api/core/action/command&log_wait=100000" \ +curl --request POST "https://hostname:8443/api/core/action/command?log_wait=100000" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data "[ @@ -219,12 +220,12 @@ This call will ask for the API to execute an action and will give a result after Note: there is no need for logs synchronisation when dealing with local actions. -##### Launch a command remotly and wait for the result +##### Launch a command remotely and wait for the result Using the `/nodes/:id/core/action/command` endpoint with `log_wait` parameter set to 100000: ```bash -curl --request POST "https://hostname:8443/api/nodes/2/core/action/command&log_wait=100000&sync_wait=200000" \ +curl --request POST "https://hostname:8443/api/nodes/2/core/action/command?log_wait=100000&sync_wait=200000" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data "[ @@ -241,23 +242,24 @@ This call will ask for the API to execute an action on the node with ID 2, will ## Log endpoint -To retrieve the logs, a specific endpoint can be called as follow. +To retrieve the logs, a specific endpoint can be called as follows. -| Endpoint | Method | -| :- | :- | -| /log/:token | `GET` | +| Endpoint | Method | +|:------------------------------|:-------| +| /api/nodes/:nodeid/log/:token | `GET` | #### Headers -| Header | Value | -| :- | :- | -| Accept | application/json | +| Header | Value | +|:-------|:------------------| +| Accept | application/json | #### Path variables -| Variable | Description | -| :- | :- | -| token | Token of the action | +| Variable | Description | +|:---------|:---------------------------| +| token | Token of the action | +| nodeid | node id to search log into | #### Examples @@ -271,7 +273,7 @@ curl --request GET "https://hostname:8443/api/nodes/2/log/3f25bc3a797fe989d1fb05 --header "Accept: application/json" ``` -This second example will force logs synchonisation before looking for results to retrieve. Default temporisation is 10ms and can be changed by providing `sync_wait` parameter. +This second example will force logs synchronisation before looking for results to retrieve. Default wait time is 10ms and can be changed by providing `sync_wait` parameter. #### Response example diff --git a/gorgone/docs/modules/core/action.md b/gorgone/docs/modules/core/action.md index c885dcd0cac..db21bbe971c 100644 --- a/gorgone/docs/modules/core/action.md +++ b/gorgone/docs/modules/core/action.md @@ -7,7 +7,7 @@ This module aims to execute actions on the server running the Gorgone daemon or ## Configuration | Directive | Description | Default value | -| :--------------- | :------------------------------------------------------------- | :------------ | +|:-----------------|:---------------------------------------------------------------|:--------------| | command_timeout | Time in seconds before a command is considered timed out | `30` | | whitelist_cmds | Boolean to enable commands whitelist | `false` | | allowed_cmds | Regexp list of allowed commands | | @@ -38,7 +38,7 @@ allowed_cmds: ## Events | Event | Description | -| :---------- | :-------------------------------------------------------------------------------------- | +|:------------|:----------------------------------------------------------------------------------------| | ACTIONREADY | Internal event to notify the core | | PROCESSCOPY | Process file or archive received from another daemon | | COMMAND | Execute a shell command on the server running the daemon or on another server using SSH | @@ -48,20 +48,20 @@ allowed_cmds: ### Execute a command line | Endpoint | Method | -| :------------------- | :----- | +|:---------------------|:-------| | /core/action/command | `POST` | #### Headers | Header | Value | -| :----------- | :--------------- | +|:-------------|:-----------------| | Accept | application/json | | Content-Type | application/json | #### Body | Key | Value | -| :---------------- | :------------------------------------------------------- | +|:------------------|:---------------------------------------------------------| | command | Command to execute | | timeout | Time in seconds before a command is considered timed out | | continue_on_error | Behaviour in case of execution issue | @@ -76,8 +76,11 @@ allowed_cmds: ] ``` + #### Example +See a complete exemple of this endpoint in the [api documentation](../../api.md) + ```bash curl --request POST "https://hostname:8443/api/core/action/command" \ --header "Accept: application/json" \ @@ -88,3 +91,8 @@ curl --request POST "https://hostname:8443/api/core/action/command" \ } ]" ``` +Output : +```bash +{"token":"b3f825f87d64764316d872c59e4bae69299b0003f6e5d27bbc7de4e27c50eb65fc17440baf218578343eff7f4d67f7e98ab6da40b050a2635bb735c7cec276bd"} +``` +