NXLog Documentation

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"
      }
    ]
  }

json

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}"
      }
    ]
  }

json

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"
    }
  ]
}

json

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"
    }
  ]
}

json

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!"
        }
    ]
}

json

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"
      }
    ]
  }

json

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"
    }
  ]
}

json

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}"
    }
  ]
}

json

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"
    }
  ]
}

json

Did you like this article? Please leave review about it