NXLog User Guide

124. RESTful Web Services

NXLog manager provides a *RE*presentational *S*tate *T*ransfer (REST) interface, or RESTful web service API, that makes it possible to access agent information or configure the system without using the UI.

The base URL to access the REST API is http://hostname:port/nxlog-manager/mvc/restservice. Depending on the service, either GET, POST, PUT or DELETE requests should be used. The API responses are in XML or JSON. You will need to send REST_USER and REST_PASSWORD HTTP headers in order to authenticate the requests.

NXLog Manager is distributed with an embedded documentation of its REST API with detailed specification of all supported RESTful services. Once the NXLog Manager instance is up and running, the documentation is available at http://hostname:port/nxlog-manager/swagger-ui.html (for viewing in a web browser). If you want to get this documentation programmatically, use the http://hostname:port/nxlog-manager/v2/api-docs endpoint that returns information about NXLog Manager RESTful services as raw JSON.

Using GET to Pull appinfo Using wget

$ wget -q --header "REST_USER: $USER" --header "REST_PASSWORD: $PASS" -O - \
       "http://$HOST:$PORT/nxlog-manager/mvc/restservice/appinfo"

Note	Throughout this chapter the base URL is substituted with `[B_URL]`.

The following services are available:

agentmanager: Verify that NXLog Manager is up and running (GET).
appinfo: Get information about the NXLog Manager (GET).
agentinfo: Get information about the NXLog Agents (GET).
addagent: Add a new Agent (POST).
modifyagent: Modify an existing Agent (PUT).
deleteagent: Delete an existing Agent (DELETE).
certificateinfo: Retrieve certificate information (GET).
createfield: Create NXLog fields (POST).

124.1. agentmanager

This service is useful to verify the NXLog Manager is up and running. This is a GET request with URL [B_URL]/agentmanager and no additional parameters. This service can also be used if the Don’t encrypt agent manager’s private key setting is not enabled on the Settings tab and the NXLog Manager service has been restarted (or after a reboot). A REST call of a user who has ROLE_ADMINISTRATOR and/or ROLE_CERTIFICATE access rights can decrypt the master key, enabling the agent manager to establish the trusted control connection with the agents.

124.2. appinfo

This service provides information about a running NXLog Manager. This is a GET request with URL [B_URL]/appinfo and no additional parameters. This service provides the uptime, license state and expiration date, version, and revision.

Sample Output

<?xml version='1.0' encoding='UTF-8'?>
<result servicename="appinfo">
  <values>
    <applicationinfo>
      <nxmUptime>17143265</nxmUptime>
      <licenseState>LICENSED/Expired</licenseState>
      <licenseExpireDate>2011-12-30 22:00:00.0 UTC</licenseExpireDate>
      <appVersion>5.0</appVersion>
      <appRevisionNumber>4895</appRevisionNumber>
    </applicationinfo>
  </values>
</result>

124.3. agentinfo

This service provides information about NXLog Agents registered with the NXLog Manager. This is a GET request with URL [B_URL]/agentinfo that can take additional parameters. The response can be filtered by the name or the state of the agent with the options agentname and agentstate. Those two parameters cannot be combined, unlike the third parameter agentwithmodules which will also include module information with the agent information. For example, to get information for both the agents and the modules for all agents with state ONLINE the following REST call can be used: [B_URL]/agentinfo?agentstate=ONLINE&agentwithmodules=true. Refer to the Agents chapter for more information.

Sample Output

<?xml version='1.0' encoding='UTF-8'?>
<result servicename="agentinfo">
  <values>
    <agent>
      <name>192.168.122.1</name>
      <version>3.99.2866</version>
      <status>ONLINE</status>
      <load>0.16</load>
      <address>192.168.122.1</address>
      <started>2017-12-15 16:36:23.974 UTC</started>
      <memUsage>7442432.0</memUsage>
      <received>2</received>
      <processing>0</processing>
      <sent>2</sent>
      <sysinfo>OS: Linux, Hostname: voyager, Release: 4.4.0-103-generic, Version: #126-Ubuntu SMP Mon Dec 4 16:23:28 UTC 2017, Arch: x86_64, 4 CPU(s), 15.7Gb memory</sysinfo>
      <modules>
        <module>
          <name>in_int</name>
          <module>im_internal</module>
          <type>INPUT</type>
          <isRunning>true</isRunning>
          <received>2</received> <processing>0</processing>
          <sent>2</sent>
          <dropped>0</dropped>
          <status>RUNNING</status>
        </module>
        <module>
          <name>null_out</name>
          <module>om_null</module>
          <type>OUTPUT</type>
          <isRunning>true</isRunning>
          <received>2</received>
          <processing>0</processing>
          <sent>2</sent>
          <dropped>0</dropped>
          <status>RUNNING</status>
        </module>
      </modules>
    </agent>
  </values>
</result>

124.4. addagent

This service adds a new NXLog Agent to the list of existing Agents. This is a POST request with URL [B_URL]/addagent that can take several additional parameters. The only mandatory parameter is agentname, which is the name for the new agent. The optional parameter connectionmode can be used to change the connection type of the Agent, from the default CONNECT_TO, to either UNMANAGED or LISTEN_FROM. The connectionport parameter can be used to change the default port of the manager from 4041; this parameter can only be used for managed connection types. The connectionaddress parameter can be used to set the IP address the manager will either CONNECT_TO or LISTEN_FROM; the default value is localhost. The loglevel parameter can be used to set the log level; values can be DEBUG, INFO, WARNING, ERROR, or CRITICAL. The logtofiled parameter is used to enable the agent to use the local nxlog.log file. To create agent clones, the agentname parameter can be specified more than once with unique agent names. Refer to the Agents chapter for more information.

To create an Agent template instead of an Agent, include the agenttemplate parameter as agenttemplate=true. If multiple agent names are specified when creating a template, the first one will be the name of the template and the rest will be agents based on this template. Refer to the Templates chapter for more information.

Creating a new Agent, for example, can be done with this REST call: [B_URL]/addagent?agentname=Justatest&connectionmode=LISTEN_FROM. This will return the following XML message that includes the Agent configuration in base64 encoded format.

Sample Output

<?xml version='1.0' encoding='UTF-8'?>
<result servicename="addagent">
  <values>
    <addagent>
      <configuration># PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPGFnZW50PgogICAgPG5hbWU+
# SnVzdGF0ZXN0PC9uYW1lPgogICAgPG5zMTpnbG9iYWwtY29uZmlnIHhtbG5zOm5zMT0iaHR0cDov
# L2Nhc3Rvci5leG9sYWIub3JnLyI+CiAgICAgICAgPGNlcnQtaWQ+MTg8L2NlcnQtaWQ+CiAgICAg
# ICAgPGxvZy1sZXZlbCB4bWxuczp4c2k9Imh0dHA6Ly93d3cudzMub3JnLzIwMDEvWE1MU2NoZW1h
# LWluc3RhbmNlIgogICAgICAgICAgICB4bWxuczpqYXZhPSJodHRwOi8vamF2YS5zdW4uY29tIiB4
# c2k6dHlwZT0iamF2YTpqYXZhLmxhbmcuU3RyaW5nIj5JTkZPPC9sb2ctbGV2ZWw+CiAgICAgICAg
# PGlzLWxvZy10by1maWxlPnRydWU8L2lzLWxvZy10by1maWxlPgogICAgICAgIDxjb25uZWN0aW9u
# LW1vZGUKICAgICAgICAgICAgeG1sbnM6eHNpPSJodHRwOi8vd3d3LnczLm9yZy8yMDAxL1hNTFNj
# aGVtYS1pbnN0YW5jZSIKICAgICAgICAgICAgeG1sbnM6amF2YT0iaHR0cDovL2phdmEuc3VuLmNv
# bSIgeHNpOnR5cGU9ImphdmE6amF2YS5sYW5nLlN0cmluZyI+TElTVEVOX0ZST008L2Nvbm5lY3Rp
# b24tbW9kZT4KICAgICAgICA8Y29ubmVjdGlvbi1wb3J0PjA8L2Nvbm5lY3Rpb24tcG9ydD4KICAg
# IDwvbnMxOmdsb2JhbC1jb25maWc+CjwvYWdlbnQ+Cg==

</configuration>
    </addagent>
  </values>
<result>

124.5. modifyagent

This service modifies the configuration of an existing Agent. This is a PUT request with URL [B_URL]/modifyagent. This service has the same parameters as the addagent service, except for the agenttemplate parameter.

124.6. deleteagent

This service deletes an existing Agent. This is a DELETE request with URL [B_URL]/deleteagent. The only parameter required for this service is the agentname parameter.

124.7. certificateinfo

This safe service can retrieve certificate information from the NXLog Manager. This is a GET request with URL [B_URL]/certificateinfo. Without any parameters the service will list all certificate information. Parameter expirein can be used to list only certificates that will expire in the given number of days.

As an example, this call will list certificates expiring in one month: [B_URL]/certificateinfo?expirein=30. If no certificates are expiring in that time period, an empty result is returned.

Sample Output

<?xml version='1.0' encoding='UTF-8'?>
<result servicename="certificateinfo">
  <values>
    <ok>
      <message>The result is empty!</message>
    </ok>
  </values>
</result>

124.8. createfield

This service will create a field in NXLog Manager. This is a POST request with URL [B_URL]/createfield and there are several parameters. Parameter name is the name of the field and must be a unique identifier. Parameter type is the field type and must be one of the types: STRING, INTEGER, BINARY, IPADDR,IP4ADDR, IP6ADDR, BOOLEAN, and DATETIME. Parameter description is a short description of the field. Parameters persist and lookup can be true or false. Refer to the Fields chapter for more information.

The following REST call will create a TEST field of type STRING that is both persistent and lookup enabled: [B_URL]/createfield?name=TEST&type=STRING&description=Just a string&persist=true&lookup=true.

Sample Output

<?xml version='1.0' encoding='UTF-8'?>
<result servicename="createfield">
  <values>
    <ok>
      <message>OK</message>
    </ok>
  </values>
</result>