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

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

modifyagent

Modifies the existing agent configuration.

Type of Request: PUT

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

Parameters are listed below.

Table 3. 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"
      }
    ]
  }