Agent services

addagent

This service creates a new agent. After creation, the new agent implements the basic configuration and can be managed via this API or the NXLog Manager user interface.

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/addagent

Parameters are listed below.

Table 1. List of Parameters
Parameter Description Format Type

agent

Object specifying the characteristics of the agent being created. It contains the name and the global-config nested data as per the description below.

XML or JSON object

Required

name

Unique name of the agent being created. If the request specifies the cert-fingerprint parameter containing the fingerprint of a valid certificate, the name parameter can be omitted. In this case, the certificate name as per the cert-fingerprint parameter will be used to name the agent.

String

Required/Optional

global-config

Object with several nested parameters which are listed below in this table. The first three parameters are required and define the minimum agent’s configuration, other are optional.

XML or JSON

Required

address

Communication address or DNS hostname of the agent in case of the Listen mode, or the manager address if the Connect mode should be configured. For more information, see the mode parameter of this service.

IPv4 and IPv6 addresses are supported.

String

Required

port

Port associated with the address parameter.

Integer

Required

ca-fingerprint

Fingerprint of the default certificate issuer which is used by the agent manager.

To obtain the fingerprint information, you can run the certificateinfo service.

String

Required

cert-fingerprint

Fingerprint of the existing certificate which can be assigned to the agent during creation. If this parameter is omitted, a new certificate will be created and assigned to the agent. Such certificate uses the agent name and the default subject parameters according to the values from the Certificates tab.

To obtain the certificate fingerprint of the existing certificate, you can run the certificateinfoservice.

String

Optional

is-log-to-file

Specifies the Log to file parameter configuration. The default value is TRUE to enable using a local nxlog.log file where NXLog agent internal events are written.

Boolean

Optional

log-level

Severity level set by the LogLevel directive. Accepts one of the following values: DEBUG, INFO, WARNING, ERROR, or CRITICAL. The default value is INFO.

String

Optional

mode

The connection mode the agent will use after creation. Accepts the Connect, Listen, or Unmanaged values. The default value is Connect.

For more details, see the Connection type parameter description of the Agent Configuration topic.

String

Optional

verbatim

Verbatim configuration of the agent. After the agent has been created, this configuration is available in the Verbatim config field of the NXLog Manager user interface.

String

Optional

Sample cURL Request
curl -k -v POST "https://hostname:9443/nxlog-manager/mvc/restservice/addagent" -H  "accept:application/json" -H  "REST_PASSWORD: nxlog123" -H  "REST_USER: admin" -H  "Content-Type: application/json" -d "{  \"global-config\": { \"ca-fingerprint\":\"82cb807dea47e8c31a448e7496afa45d1922aa8\", \"address\": \"192.168.31.86\", \"port\": 9442, \"mode\": \"Listen\" }, \"name\": \"Agent_192.168.31.86\"}"
Sample Response in JSON
{
    "servicename": "addagent",
    "values": [
      {
        "message": "Agent 'Agent_192.168.31.86' is created."
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate?name=Agent_192.168.31.86"
      }
    ]
  }

agentinfo

Retrieves information about NXLog agents registered with NXLog Manager.

Type of Request: GET

URL: https://hostname:9443/nxlog-manager/mvc/restservice/agentinfo

This service can accept the communication format specified via the .xml or .json extensions appended to the end of the URL which can be used instead of the accept and Content-Type headers.
For JSON format, the following URL should be used:
https://hostname:9443/nxlog-manager/mvc/restservice/agentinfo.json.
The following URL should be used for XML:
https://hostname:9443/nxlog-manager/mvc/restservice/agentinfo.xml.

Parameters are listed below. At least one parameter should be used to retrieve information.

Table 2. List of parameters
Parameter Description Format Type

agentname

A comma-delimited list of agent names for which information should be listed. This parameter is mutually exclusive with the agentstate parameter.

Can be combined with the agentwithmodules parameter to provide listing of modules of each specified agent.

Array[string]

Optional

agentstate

Listing of agent information based on the state. In case of several states, this parameter can be specified for each state separately.

The following states are available: ONLINE, OFFLINE, ERROR, UNMANAGED, UNTRUSTED, FORGED. For more information, see the Managing Agents section.

Mutually exclusive with the agentname parameter.

This can be combined with the agentwithmodules parameter to provide listing of modules in addition to the agent information.

Array[string]

Optional

agentwithmodules

Listing of modules. This parameter can be combined with the agentname and agentstate parameters to list modules of the specified agents. For example, to list modules of agents with the ONLINE state.

Boolean

Optional

Sample cURL request
curl -k -v -H  "REST_PASSWORD: nxlog123" -H  "REST_USER: admin"  "https://hostname:9443/nxlog-manager/mvc/restservice/agentinfo.json?agentstate=ONLINE&agentwithmodules=TRUE"
Sample response in JSON
{
  "servicename": "agentinfo",
  "values": [
    {
      "content": {
        "name": "192.168.31.86",
        "version": "5.0.5874",
        "status": "ONLINE",
        "os": "Linux",
        "address": "192.168.31.86",
        "hostname": "nxlog",
        "started": "2020-06-30 21:38",
        "load": "0.01",
        "memUsage": 1.0432512e7,
        "received": 0,
        "receivedToday": 0,
        "processing": 0,
        "sent": 0,
        "sentToday": 0,
        "lastOnline": "2020-07-03 23:43",
        "sysinfo": "OS: Linux, Hostname: nxlog, Release: 3.10.0-1127.8.2.el7.x86_64, Version: #1 SMP Tue May 12 16:57:42 UTC 2020, Arch: x86_64, 2 CPU(s), 3.7Gb memory",
        "modules": [
          {
            "module_name": "to_file",
            "module": "om_file",
            "module-type": 3,
            "type": "OUTPUT",
            "isRunning": true,
            "evt-recvd": 0,
            "queuesize": 0,
            "evt-fwd": 0,
            "evt-drop": 0,
            "status": 3,
            "module-status": "RUNNING",
            "id": 24,
            "serverInfo": {}
          },
          {
            "module_name": "from_file",
            "module": "im_file",
            "module-type": 1,
            "type": "INPUT",
            "isRunning": true,
            "evt-recvd": 0,
            "queuesize": 0,
            "evt-fwd": 0,
            "evt-drop": 0,
            "status": 3,
            "module-status": "RUNNING",
            "id": 23,
            "serverInfo": {}
          }
        ]
      },
      "links": [
        {
          "rel": "self",
          "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/agentinfo.json?agentname=192.168.31.86&agentwithmodules=true{&agentstate}"
        },
        {
          "rel": "online_agents_with_modules",
          "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/agentinfo.json?agentstate=ONLINE&agentwithmodules=true{&agentname}"
        },
        {
          "rel": "all_agents_with_modules",
          "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/agentinfo.json?agentwithmodules=true{&agentname,agentstate}"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "self",
      "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/agentinfo.json?agentstate=ONLINE&agentwithmodules=true{&agentname}"
    }
  ]
}

assigntemplatetoagent

Assigns the specified template to agents. Templates unify creation, configuration, tagging, and modification of agents. For more information, see the Templates section.

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/assigntemplatetoagent

Parameters are listed below.

Table 3. List of parameters
Parameter Description Format Type

agentUuids

A comma-delimited list of agent UUIDs that should be assigned a (master) template from the templateName parameter, and optionally any subtemplates from the values assigned to the subTemplateNames parameter.

Array[string]

Required

subTemplateNames

List of sub templates to be assigned in addition to the main template from the templateName parameter.

Array[string]

Optional

templateName

The name of a master template which has been created in NXLog Manager.

String

Optional

updateAgents

If set to TRUE, this parameter provides the immediate update and restart of agents after the template has been applied.

Boolean

Optional

Sample cURL request
curl -k -v -H "REST_PASSWORD: nxlog123" -H "REST_USER: admin" -H "accept: application/json" -H "Content-Type: application/json" -X POST "https://hostname:9443/nxlog-manager/mvc/restservice/assigntemplatetoagent?agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a,ae50ea00-5ce4-11ec-8000-b4c3747b9c2c&templateName=Linux&subTemplateNames=Central,Linux_Security&updateAgents=true"
Sample response in JSON
{
  "servicename" : "assigntemplatetoagent",
  "errors" : [
    {
      "status" : 0,
      "message" : "192.168.31.219: Agent reconnect failed in 10 seconds."
    },
    {
      "status" : 0,
      "message" : "192.168.31.223: Agent reconnect failed in 10 seconds."
    }
  ],
  "values" : [
    {
      "message" : "192.168.31.219: Agent was assigned to master template 'Linux'."
    },
    {
      "message" : "192.168.31.223: Agent was assigned to master template 'Linux'."
    },
    {
      "message" : "192.168.31.219: Agent was assigned to subtemplate 'Central, Linux_Security'."
    },
    {
      "message" : "192.168.31.223: Agent was assigned to subtemplate 'Central, Linux_Security'."
    },
    {
      "message" : "192.168.31.219: Agent configuration updated successfully."
    },
    {
      "message" : "192.168.31.223: Agent configuration updated successfully."
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate/192.168.31.219"
    },
    {
      "rel" : "self",
      "href" : "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate/192.168.31.223"
    }
  ]
}

updateandreloadagent

Sends updated configuration from NXLog Manager to the specified agent and reloads it after the update. This service can be applied after configuring the agent in the NXLog Manager UI.

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/updateandreloadagent

Parameters are listed below.

Table 4. List of parameters
Parameter Description Format Type

agentUuids

A comma-delimited list of agent UUIDs to be processed. If this parameter is omitted, all agents will be processed.

Array[string]

Optional

forceOverrideLocalChanges

If set to TRUE, the specified agents will be processed even if they contain local configuration differences which are not synchronized with the Manager configuration. The default value is FALSE.

Boolean

Optional

scheduledUpdate

In case of TRUE, scheduled update will be done. Otherwise it will be done immediately after call. The default value is FALSE.

Boolean

Optional

Sample cURL request
curl -k -v -H "REST_PASSWORD: nxlog123" -H "REST_USER: admin" -H "accept: application/json" -H "Content-Type: application/json" -X POST "https://hostname:9443/nxlog-manager/mvc/restservice/updateandreloadagent?agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a,ae50ea00-5ce4-11ec-8000-b4c3747b9c2c&forceOverrideLocalChanges=true"
Sample response in JSON
{
  "servicename" : "updateandreloadagent",
  "values" : [
    {
      "message" : "192.168.31.219: Agent configuration updated successfully."
    },
    {
      "message" : "192.168.31.219: Agent was reloaded successfully."
    },
    {
      "message" : "192.168.31.223: Agent configuration updated successfully."
    },
    {
      "message" : "192.168.31.223: Agent was reloaded successfully."
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate/192.168.31.219"
    },
    {
      "rel" : "self",
      "href" : "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate/192.168.31.223"
    }
  ]
}

deleteagent

Deletes the specified agent either with or without revocation of the assigned certificate. Depending on the certificate revocation, the deleted agent can reconnect at a later time.

It is recommended to disable agents before deleting them.

Type of Request: DELETE

URL: https://hostname:9443/nxlog-manager/mvc/restservice/deleteagent

Parameters are listed below.

Table 5. List of parameters
Parameter Description Format Type

agentUuids

A comma-delimited list containing the UUIDs of the agents to be deleted.

Array[string]

Required

revokeCert

If set to TRUE, this parameter revokes the agents' certificates and changes their status from VALID to REVOKED. Once revoked, the certificates cannot be used by the agents after reconnection.

If set to FALSE, the certificates retain the VALID status and can be used by the agents in future. If the deleted agent had been configured in the Connect mode, it can reconnect at a later time and use the same certificate.

The default value is TRUE.

Boolean

Required

Sample cURL request
curl -k -v -H "REST_PASSWORD: nxlog123" -H "REST_USER: admin" -H "accept: application/json" -H "Content-Type: application/json" -X DELETE "https://hostname:9443/nxlog-manager/mvc/restservice/deleteagent?agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a&revokeCert=true"

In case the operations of agent deletion and certificate revocation have been performed successfully, this service returns a 204 No Content response.

If the revokeCert parameter is set to FALSE, the response will contain a JSON structure according to the sample below.

Sample response in JSON
{
    "servicename": "deleteagent",
    "values": [
        {
            "message": "192.168.31.145: Warning: Agent certificate should be revoked."
        },
        {
            "message": "192.168.31.145: Agent was deleted!"
        }
    ]
}

modifyagent

Modifies the existing agent configuration.

Type of Request: PUT

URL: https://hostname:9443/nxlog-manager/mvc/restservice/modifyagent

Parameters are listed below.

Table 6. List of Parameters
Parameter Description Format Type

agentName

Specifies the name of the agent to be modified. Only one agent name per request can be used.

String

Required

agent

Object specifying the characteristics of the agent being created. It contains the name and the global-config nested data as per the description below.

XML or JSON object

Required

name

The new unique name which will be used to replace the existing agent’s name. In case the agent name needs to remain unaltered, this parameter should accept the same name as the agentName parameter does.

String

Required

global-config

Object containing several nested parameters which are listed below in this table. Three parameters are required, and other are optional. By providing new values to any of these parameters, the existing agent’s configuration can be altered.

XML or JSON

Required

address

Communication address or DNS hostname of the agent in case of the Listen mode, or the manager address if the Connect mode is used. For more information, see the mode parameter of this service.

IPv4 and IPv6 addresses are supported.

String

Required

port

Port associated with the address parameter.

Integer

Required

ca-fingerprint

Fingerprint of the default certificate issuer which is used by the agent manager.

To obtain the fingerprint information, you can run the certificateinfo service.

String

Required

cert-fingerprint

Fingerprint of the existing certificate which can be assigned to the agent after modification.

To obtain the certificate fingerprint, you can run the certificateinfo service.

String

Optional

is-log-to-file

Specifies the Log to file parameter configuration. The default value is TRUE to enable using a local nxlog.log file where NXLog agent internal events are written.

Boolean

Optional

log-level

Severity level set by the LogLevel directive. Accepts one of the following values: DEBUG, INFO, WARNING, ERROR, or CRITICAL. The default value is INFO.

String

Optional

mode

Connection mode the agent will use after modification. The parameter accepts the Connect, Listen, or Unmanaged values. The default value is Connect.

For more details, see the Connection type parameter description of the Agent configuration topic.

String

Optional

verbatim

Verbatim configuration which will be used by the agent after modification.

This configuration will be available in the Verbatim config field of the NXLog Manager user interface.

String

Optional

Sample cURL Request
curl -k -v -X PUT "https://hostname:9443/nxlog-manager/mvc/restservice/modifyagent?agentName=Agent_192.168.31.86" -H "accept: application/json" -H "REST_PASSWORD: nxlog123" -H "REST_USER: admin" -H "Content-Type: application/json" -d "{ \"global-config\": { \"ca-fingerprint\": \"82cb807dea47e8c31a448e7496afa45d1922aa8\", \"address\": \"192.168.31.218\", \"mode\": \"Listen\", \"port\": 9442 }, \"name\": \"Agent_192.168.31.218\"}"
Sample Response in JSON
{
    "servicename": "modifyagent",
    "values": [
      {
        "message": "Agent global configuration saved successfully."
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate?name=Agent_192.168.31.218"
      }
    ]
  }

startagent

Sends a restart request to the specified agents, causing each agent service to reload its configuration and restart its modules.

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/startagent

Parameters are listed below.

Table 7. List of parameters
Parameter Description Format Type

agentUuids

A comma-delimited list of agent UUIDs to be restarted.

Array[string]

Required

Sample cURL request
curl -k -v -H "REST_PASSWORD: nxlog123" -H "REST_USER: admin" -H "accept: application/json" -H "Content-Type: application/json" -X POST "https://hostname:9443/nxlog-manager/mvc/restservice/startagent?agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a,ae50ea00-5ce4-11ec-8000-b4c3747b9c2c"

stopagent

Sends a server_stop call to stop all running modules for each agent specified.

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/stopagent

Parameters are listed below.

Table 8. List of parameters
Parameter Description Format Type

agentUuids

A comma-delimited list of agent UUIDs to be stopped.

Array[string]

Required

Sample cURL request
curl -k -v -H "REST_PASSWORD: nxlog123" -H "REST_USER: admin" -H "accept: application/json" -H "Content-Type: application/json" -X POST "https://hostname:9443/nxlog-manager/mvc/restservice/stopagent?agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a,ae50ea00-5ce4-11ec-8000-b4c3747b9c2c"
Sample response in JSON
{
  "servicename" : "stopagent",
  "values" : [
    {
      "message" : "192.168.31.219: Agent was stopped successfully."
    },
    {
      "message" : "192.168.31.223: Agent was stopped successfully."
    }
  ],
  "links" : [
    {
      "rel" : "self",
      "href" : "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate/192.168.31.219"
    },
    {
      "rel" : "self",
      "href" : "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/viewagentortemplate/192.168.31.223"
    }
  ]
}

setcustomlabel

Depending on the parameters, this service either creates a new custom label or updates existing ones.

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/setcustomlabel

Parameters are listed below.

Table 9. List of parameters
Parameter Description Format Type

customLabel

Object which describes the label, and contains the name and value key-value pair. The label name must be unique, creating multiple labels under the same name is not permitted.

XML or JSON object

Required

agentUuids

A comma-delimited list of agents to assign the label to.

If this parameter is not specified for a new label, the label remains unassigned after creation.

When used for existing labels, this parameter updates the label value for the specified agents. If this parameter is not specified, the label value will be updated for all agents the label was previously assigned to.

Array[string]

Optional

oldName

The actual name of the label which will be renamed with the new name as per the customLabel parameter.

String

Optional

scheduledUpdate

If set to TRUE, this parameter denotes that the label should be pushed to the specified agents only during the next polling.

The default value is FALSE, which triggers an immediate update of the label on the agents` side.

Boolean

Optional

setForAgentsOnly

If set to TRUE, this parameter updates the values for the agents from the agentUuids parameter and keeps the previous version of the value for the agents which were not covered with the agentUuids parameter.

The default value is FALSE, which means updating the value for all agents consuming the label.

Boolean

Optional

Sample cURL request
curl -k -v -X POST "https://hostname:9443/nxlog-manager/mvc/restservice/setcustomlabel?agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a" -H  "accept:application/json" -H  "REST_PASSWORD: nxlog123" -H  "REST_USER: admin" -H  "Content-Type: application/json" -d "{\"name\": \"LabelOne\", \"value\": \"LabelValue\"}"
Sample response in JSON
{
  "servicename": "setcustomlabel",
  "links": [
    {
      "rel": "self",
      "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/setcustomlabel&agentUuids=9f60f380-fbab-11e7-8000-d85ff4257f2a?setForAgentsOnly=false&scheduledUpdate=false{&oldName,agentUuids}"
    }
  ]
}

removecustomlabel

Depending on the parameters, this service can perform the following actions:

  • Unassign the existing labels from agents

  • Completely remove the labels

Type of Request: POST

URL: https://hostname:9443/nxlog-manager/mvc/restservice/removecustomlabel

Parameters are listed below.

Table 10. List of parameters
Parameter Description Format Type

labelNames

A comma-delimited list of label names which should be unassigned from agents or removed.

The labels are removed from the system if they were not previously assigned to any agents, or the agentUuids parameter did not specify any agent names.

The labels are unassigned from the agents according to the values of the agentUuids parameter.

Array[string]

Required

agentUuids

A comma-delimited list of agents the labels should be unassigned from. The list of labels are specified as per the labelNames parameter.

In case the agentUuids parameter is not specified, the labels are unassigned from all agents they were previously assigned to.

Array[string]

Optional

Sample cURL request
curl -k -v -X POST "https://hostname:9443/nxlog-manager/mvc/restservice/removecustomlabel?labelNames=LabelOne,LabelTwo&agentUuids=ae50ea00-5ce4-11ec-8000-b4c3747b9c2c" -H  "accept:application/json" -H  "REST_PASSWORD: nxlog123" -H  "REST_USER: admin" -H  "Content-Type: application/json"
Sample response in JSON
{
  "servicename": "removecustomlabel",
  "links": [
    {
      "rel": "self",
      "href": "https://hostname:9443/nxlog-manager/mvc/mvc/restservice/removecustomlabel{pathExt:.*}?labelNames=LabelOne&labelNames=LabelTwo&agentUuids=ae50ea00-5ce4-11ec-8000-b4c3747b9c2c"
    }
  ]
}