Agent Catalog¶
Contains the available agents to be installed in the Execution Environment.
Schema¶
Field |
Type |
Required |
Readonly |
Auto Managed |
Example |
---|---|---|---|---|---|
|
String |
True |
True |
False |
filebeat |
|
List(Action) |
False |
False |
False |
|
|
List(Parameter) |
False |
False |
False |
|
|
List(Resource) |
False |
False |
False |
|
|
String |
False |
False |
False |
Collect system metrics from execution environments. |
Action Schema¶
Field |
Type |
Required |
Readonly |
Auto Managed |
Example |
---|---|---|---|---|---|
|
String |
True |
True |
False |
start |
|
List(ActionConfig) |
True |
False |
False |
|
|
Enum(String)[started, stopped, unknown] |
False |
False |
False |
started |
|
String |
False |
False |
False |
Start the execution of the agent. |
Action Config Schema¶
Field |
Type |
Required |
Readonly |
Auto Managed |
Example |
---|---|---|---|---|---|
|
String |
True |
False |
False |
service filebeat start |
|
List(String) |
False |
False |
False |
-v |
|
Boolean |
False |
False |
False |
true |
Parameter Schema¶
Field |
Type |
Required |
Readonly |
Auto Managed |
Example |
---|---|---|---|---|---|
|
String |
True |
True |
False |
start |
|
Enum(String) 1 |
True |
False |
False |
integer |
|
ParameterConfig |
True |
False |
False |
|
|
Boolean |
False |
False |
False |
False |
|
Enum(String) |
False |
False |
False |
mysql |
|
String |
False |
False |
False |
Enable the agent. |
|
String |
False |
False |
False |
10s |
- 1
Possible values are “integer”, “number”, “time-duration”, “string”, “choice”, “boolean”, and “binary”.
Parameter Config Schema¶
x+————+——————————————-+———-+———-+————–+———————————-+
| Field | Type | Required | Readonly | Auto Managed | Example |
+============+===========================================+==========+==========+==============+==================================+
| schema
| Enum(String)[“yaml”, “json”, “propeties”] | True | False | False | yaml |
+————+——————————————-+———-+———-+————–+———————————-+
| source
| String | False | False | False | /usr/share/filebeat/filebeat.yml |
+————+——————————————-+———-+———-+————–+———————————-+
| path
| Lis(String) | False | False | False | enabled |
+————+——————————————-+———-+———-+————–+———————————-+
Resource Schema¶
Field |
Type |
Required |
Readonly |
Auto Managed |
Example |
---|---|---|---|---|---|
|
String |
True |
True |
False |
filebeat-config |
|
ResourceConfig |
True |
False |
False |
|
|
String |
False |
False |
False |
Filebeat configuration file. |
Resource Config Schema¶
Field |
Type |
Required |
Readonly |
Auto Managed |
Example |
---|---|---|---|---|---|
|
List(String) |
False |
False |
False |
/usr/share/filebeat/filebeat.yml |
Warning
It is not possible to update readonly fields.
it is not possible to set the Auto managed fields.
Note
id
is required but it is auto-generated if not provided. It is recommended to provide a friendly for simplify the retrieve of connected date in other indices.
Create¶
To create a new agent in the catalog use the following REST call:
-
POST
/catalog/agent/
(string: id)¶ with the request body in JSON format:
POST /catalog/agent HTTP/1.1 Host: cb-manager.example.com Content-Type: application/json { "id": "<agent-id>", "actions": [ { "id": "<action-id>", "status": "<action-status>", "config": { "cmd": "<action-cmd>" }, "description": "<action-human-readable-description>", "example": "<action-example>" } ], "parameters": [ { "id": "<parameter-id>", "type": "<parameter-type>", "config": { "schema": "<parameter-schema>", "source": "<parameter-source>", "path": [ "<parameter-path>" ] }, "description": "<parameter-human-readable-description>", "example": "<parameter-example>", } ], "resources": [ { "id": "<resource-id>", "config": { "path": "<resource-path>" }, "description": "<resource-human-readable-description>", "example": "<resource-example>", } ] }
- Parameters
id – optional agent id.
- Request Headers
Authorization – HTTP Basic Authentication with username and password.
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
201 Created – Agents correctly created.
204 No Content – No content to create agents for the catalog based on the request.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to create ore or more agents for the catalog based on the request.
500 Internal Server Error – Server not available to satisfy the request.
Replace the data with the correct values, for example <agent-id> with
nprobe
.If the creation is correctly executed the response is:
HTTP/1.1 201 Created Content-Type: application/json [ { "status": "Created", "code": 201, "error": false, "message": "Agent catalog with id=<agent-id> correctly created" } ]
Otherwise, if, for example, an agent with the given
id
is already found in the catalog, this is the response:HTTP/1.1 406 Not Acceptable Content-Type: application/json [ { "status": "Not Acceptable", "code": 406, "error": true, "message": "Id already found" } ]
If some required data is missing (for example
type
of oneparameter
), the response could be:HTTP/1.1 406 Not Acceptable Content-Type: application/json [ { "status": "Not Acceptable", "code": 406, "error": true, "message": { "parameter.type": "required" } } ]
Read¶
To get the list of the agents available in the catalog:
-
GET
/catalog/agent/(string: id)
¶ The response includes all the agents.
It is possible to filter the results using the following request body:
GET /catalog/agent HTTP/1.1 Host: cb-manager.example.com Content-Type: application/json { "select": [ "parameters" ], "where": { "equals": { "target:" "id", "expr": "<agent-id>" } } }
- Parameters
id – optional agent id from the catalog.
- Request Headers
Authorization – HTTP Basic Authentication with username and password.
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – List of agents from the catalog filtered by the query in the request body.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
404 Not Found – Data based on the request query not found.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to get agents from the catalog with the request query.
500 Internal Server Error – Server not available to satisfy the request.
In this way, it will be returned only the
parameters
of the agent in the catalog withid
= “<agent-id>”.
Update¶
To update an agent in the catalog, use:
-
PUT
/catalog/agent/
(string: id)¶ PUT /catalog/agent HTTP/1.1 Host: cb-manager.example.com Content-Type: application/json { "id": "<agent-id>", "parameters": [ { "id": "<parameter-id>", "type": "<new-parameter-type>" } ], "actions": [ { "id": "<new-action-id>", "config": { "cmd": "<new-action-cmd>" } } ] }
- Parameters
id – optional agent id.
- Request Headers
Authorization – HTTP Basic Authentication with username and password.
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
200 OK – All agents in the catalog correctly updated.
204 No Content – No content to update agents in the catalog based on the request.
304 Not Modified – Update for one or more agents in the catalog not necessary.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to update one or more agents in the catalog based on the request.
500 Internal Server Error – Server not available to satisfy the request.
This example
updates the new
type
of theparameter
withid
= “<parameter-id>”;adds a new action
of the agent with
id
= “<agent-id>”.A possible response is:
HTTP/1.1 200 OK Content-Type: application/json [ { "status": "OK", "code": 200, "error": false, "message": "Agent catalog with id=<agent-id> correctly updated" } ]
Instead, if the are not changes the response is:
HTTP/1.1 304 Not Modified Content-Type: application/json [ { "status": "Not Modified", "code": 304, "error": false, "message": "Update for agent catalog with id=<agent-id> not necessary" } ]
Delete¶
To delete agents from the catalog, use:
-
DELETE
/catalog/agent/
(string: id)¶ DELETE /catalog/agent HTTP/1.1 Host: cb-manager.example.com Content-Type: application/json { "where": { "equals": { "target:" "id", "expr": "<agent-id>" } } }
- Parameters
id – optional agent id from the catalog.
- Request Headers
Authorization – HTTP Basic Authentication with username and password.
Content-Type – application/json
- Response Headers
Content-Type – application/json
- Status Codes
205 Reset Content – All agents correctly deleted from the catalog.
400 Bad Request – Request not valid.
401 Unauthorized – Authentication failed.
404 Not Found – Agents based on the request query not found in the catalog.
406 Not Acceptable – Request validation failed.
415 Unsupported Media Type – Media type not supported.
422 Unprocessable Entity – Not possible to delete one or more agents from the catalog based on the request query.
500 Internal Server Error – Server not available to satisfy the request.
This request removes from the catalog the agent with
id
= “<agent-id>”.This is a possible response:
HTTP/1.1 205 Reset Content Content-Type: application/json [ { "status": "Reset Content", "code": 200, "error": false, "message": "Agent catalog the id=<agent-id> correctly deleted" } ]
Caution
Without request body, it removes all the agents from the catalog.
Loaded data¶
This data is already available:
-
GET
/catalog/agent
¶ HTTP/1.1 200 OK Content-Type: application/json [ { "id": "firewall", "actions": [ { "id": "start", "status": "started", "config": { "cmd": "polycubectl firewall add fw" } }, { "id": "stop", "status": "stopped", "config": { "cmd": "polycubectl fw del" } }, { "id": "attach", "config": { "cmd": "polycubectl attach fw {port}" } }, { "id": "insert", "config": { "cmd": "polycubectl firewall fw chain {chain} insert id={n} src={src} dst={dst} action={action}" } }, { "id": "append", "config": { "cmd": "polycubectl firewall fw chain {chain} append src={src} dst={dst} action={action}" } }, { "id": "prepend", "config": { "cmd": "polycubectl firewall fw chain {chain} insert src={src} dst={dst} action={action}" } }, { "id": "delete", "config": { "cmd": "polycubectl firewall fw chain {chain} rule del {n}" } }, { "id": "default", "config": { "cmd": "polycubectl firewall fw chain {chain} set default={action}" } }, { "id": "list", "config": { "cmd": "polycubectl firewall fw chain {chain} rule show" } }, { "id": "stats", "config": { "cmd": "polycubectl firewall fw chain {chain} stats show" } } ] }, [ { "id": "nprobe", "parameters": [ { "id": "network-interface", "type": "string", "example": "eth0", "description": "Set the network interface to probe", "config": { "schema": "properties", "source": "/etc/nprobe/nprobe.conf", "path": [ "-i" ] } }, { "id": "capture-direction", "type": "integer", "example": 1, "description": "Specify packet capture direction: 0=RX+TX (default), 1=RX only, 2=TX only", "config": { "schema": "properties", "source": "/etc/nprobe/nprobe.conf", "path": [ "-capture-direction" ] } }, { "id": "flow-template", "type": "string", "example": "%IPV4_SRC_ADDR %IPV4_DST_ADDR %IPV4_NEXT_HOP %INPUT_SNMP %OUTPUT_SNMP %IN_PKTS %IN_BYTES %FIRST_SWITCHED %LAST_SWITCHED %L4_SRC_PORT %L4_DST_PORT %TCP_FLAGS %PROTOCOL %SRC_TOS %SRC_AS %DST_AS %IPV4_SRC_MASK %IPV4_DST_MASK", "description": "Specifies the NFv9 template", "config": { "schema": "properties", "source": "/etc/nprobe/nprobe.conf", "path": [ "-T" ] } } ], "actions": [ { "id": "start", "status": "started", "config": { "cmd": "sudo systemctl start nprobe" } }, { "id": "stop", "status": "stopped", "config": { "cmd": "sudo systemctl stop nprobe" } }, { "id": "restart", "status": "started", "config": { "cmd": "sudo systemctl restart nprobe" } } ] } ] ]