NXLog Agent Remote Management API definition
The following is a list of xm_admin API endpoints, how to structure requests, and the expected response. For SOAP, a WSDL file is available and can be used by different developer tools to easily hook into the exported WS API and reduce development time.
You can find further examples and scripts in the NXLog public Git repository.
GetFile
Download a file from NXLog Agent. This requires an ACL to be specified in the agent configuration.
- Parameters
-
- acl
-
string
- A value corresponding to the given name of a defined ACL. This parameter is equivalent to the filetype parameter. The acl and filetype parameters are mutually exclusive. - filetype
-
string
- A value corresponding to the given name of a defined ACL. This parameter is equivalent to the acl parameter. The acl and filetype parameters are mutually exclusive.The filetype parameter will become obsolete in NXLog Agent 7.0. Use acl instead.
- filename
-
string
- The name of the file being requested.
- Response object
-
- encoding
-
See the Encoding enumeration below.
- file
-
string
- The file content.
-
JSON
-
SOAP
The following is an example of a GetFile
JSON request for a file named test.txt
from the directory specified by the conf
ACL.
{
"msg": {
"command": "getFile",
"params": {
"filetype": "conf",
"filename": "test.txt"
}
}
}
{
"response": "getFileReply",
"status": "success",
"data": {
"file": "Log line 1.\nLog line 2.\n",
"encoding": "text"
}
}
The following is an example of a GetFile
SOAP request for a file named test.txt
from the directory specified by the conf
ACL.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:getFile xmlns:adm="http://log4ensics.com/2010/AdminInterface">
<filetype>conf</filetype>
<filename>test.txt</filename>
</adm:getFile>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:getFileReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
<file>Log line 1.
Log line 2.
</file>
<encoding>text</encoding>
</adm:getFileReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
GetLog
Download the NXLog Agent log file.
- Parameters
-
- size
-
integer
- Defines the amount of data to get in bytes. The allowed range is 1 to 1048576 bytes (1MB). If size is not specified, or is outside the allowed range, it defaults to 1048576 bytes. If the log file is larger than the set (or default) size, the last n bytes are returned, otherwise, the entire log file is returned.
- Response object
-
- logfile
-
string
- log contents.
-
JSON
-
SOAP
The following is an example of a GetLog
request using JSON.
The request specifies that the last 240 bytes of the log file should be returned.
{
"msg": {
"command": "getLog",
"params": {
"size": 200
}
}
}
{
"response": "getLogReply",
"status": "success",
"data": {
"logfile": "p_listen] connection closed from 10.0.0.100:51705\n2020-12-02 15:54:17 INFO [xm_admin|tcp_listen] connection accepted from 10.0.0.100:51706\n2020-12-02 15:54:17 INFO [xm_admin|tcp_listen] getLog called\n",
}
}
The following is an example of a GetLog
request using SOAP.
The request specifies that the last 240 bytes of the log file should be returned.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:getLog xmlns:adm="http://log4ensics.com/2010/AdminInterface">
<size>200</size>
</adm:getLog>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:getLogReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
<logfile>p_listen] connection closed from 10.0.0.100:51701
2020-12-02 15:54:03 INFO [xm_admin|tcp_listen] connection accepted from 10.0.0.100:51705
2020-12-02 15:54:03 INFO [xm_admin|tcp_listen] getLog called
</logfile>
</adm:getLogReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
GetUid
Return the unique identifier (UID) of the NXLog Agent installation.
- Parameters
-
- with-signature
-
boolean
(optional) - Boolean directive specifying if the response must include a signature. The default isFALSE
. If no signature is found, it returns an empty string.
- Response object
-
- uid
-
string
- signature
-
string
(optional)
ModuleInfo
Request information about a module instance. Note that the sum of dropped and forwarded events may not equal the events received, since events can be copied or generated within the module instance.
- Parameters
-
- name
-
string
- User-defined name of the module instance.
- Response object
-
- module-name
-
string
- The user-defined name of the module instance. - evt-recvd
-
long
- The number of events processed, including events from input or processor modules and rerouted events. Events can be rerouted with the reroute() and add_to_route() procedures. - evt-drop
-
long
- The number of dropped events. Events can be dropped with the drop() or duplicate_guard() procedures, pm_norepeat module, or due to FlowControl. - evt-fwd
-
long
- The number of events forwarded to the next module instance in the route or rerouted. This value may be greater than the sum ofevt-recvd
andqueuerecordcount
since some events may have been in the log queue when NXLog Agent started. - queuesize
-
long
- The current log queue size in bytes. - queuelimit
-
long
- The configured LogqueueSize for the module instance in bytes. The default is 2 MiB. - queuerecordcount
-
integer
- The number of records in the log queue. - batchsize
-
integer
- The configured BatchSize for the module instance in number of records. - status
-
See the Encoding enumeration below.
- module-type
-
See the ModuleType enumeration below.
- module
-
string
- The module type—for example, im_file. - tcp (optional)
-
-
current-listener-count
integer
-
listeners
array
- the list of local NXLog Agent connection points for incoming connections-
address
string
-
hostname
string
(optional) -
port
integer
-
-
current-connection-count
integer
-
cumulative-connection-count
integer
-
connections
array
- data structure see “listeners”; the list of external peers to which the connections are opened
-
- udp (optional)
-
-
current-listener-count
integer
-
listeners
array
- the list of local NXLog Agent connection points for incoming connections-
address
string
-
hostname
string
(optional) -
port
integer
-
-
- variables (optional)
-
-
name
string
-
type
string
-
value
string
-
- clients (optional)
-
-
client-count
integer
-
client (optional)
-
id
string
-
last-evt-time
long
-
evt-sent
long
-
-
- features (optional)
-
-
name
string
-
value
string
-
-
JSON
-
SOAP
The following is an example of a ModuleInfo
request using JSON.
The request is being made for an om_file module with the name output_file
.
{
"msg": {
"command": "moduleInfo",
"params": {
"name": "output_file"
}
}
}
{
"response":"moduleInfoReply",
"status":"success",
"data":{
"out3":{
"module_name":"out3",
"evt-recvd":63350,
"evt-drop":50,
"evt-fwd":63300,
"queuesize":188,
"queuelimit":200,
"queuerecordcount":25,
"status":3,
"module-type":3,
"module":"om_null",
"variables":{},
"features":{}
}
}
}
The following is an example of a ModuleInfo
request using SOAP.
The request is being made to an om_file module with the name output_file
.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:moduleInfo xmlns:adm="http://log4ensics.com/2010/AdminInterface">
<name>output_file</name>
</adm:moduleInfo>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:moduleInfoReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
<module-name>output_file</module-name>
<evt-recvd>152</evt-recvd>
<evt-drop>0</evt-drop>
<evt-fwd>152</evt-fwd>
<queuesize>175</queuesize>
<queuelimit>200</queuelimit>
<queuerecordcount>22</queuerecordcount>
<status>3</status>
<module-type>3</module-type>
<module>om_null</module>
</adm:moduleInfoReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
ModuleRestart
Restart a module instance.
- Parameters
-
- name
-
string
- The user-defined name of the module.
- Response object
-
none
ModuleStart
Start a module instance.
- Parameters
-
- name
-
string
- The user-defined name of the module.
- Response object
-
none
ModuleStop
Stop a module instance.
- Parameters
-
- name
-
string
- The user-defined name of the module.
- Response object
-
none
PutFile
Upload a file to NXLog Agent, such as a configuration file, certificate or certificate key, pattern database, correlation rule file, etc.
Using this method NXLog Agent can be reconfigured from a remote host.
PutFile requires an ACL to be specified in the NXLog Agent configuration.
By default, an NXLog Agent installation defines two ACLs in managed.conf
, one named conf
which allows reading and writing to its configuration directory, and the other named cert
which allows reading and writing to its certificates directory.
NXLog Platform uses the conf
and cert
ACLs to reconfigure an agent remotely.
When PutFile
is called to update the managed configuration file, it will first create a backup of the current file before replacing it.
The managed configuration file will be restored from backup if one of the following conditions is met:
-
The new NXLog Agent configuration is determined to be invalid.
-
When in connect mode, xm_admin fails to connect to the remote host within the reversion timeout.
-
When in listen mode, xm_admin does not receive a connection within the reversion timeout.
- Parameters
-
- acl
-
string
- A value corresponding to the given name of a defined ACL. This parameter is equivalent to the filetype parameter. The acl and filetype parameters are mutually exclusive. - filetype
-
string
- A value corresponding to the given name of a defined ACL. A synonym of acl. This parameter is equivalent to the acl parameter. The acl and filetype parameters are mutually exclusive.The filetype parameter will become obsolete in NXLog Agent 7.0. Use acl instead.
- filename
-
string
- The name of the file being requested. - file
-
string
- A string containing the content of the file. - executable
-
boolean
(optional) - Whentrue
, the file’s execute bit will be set. If this value is set tofalse
or is not specified, the file’s execute bit is not set or it is cleared in case of an existing file. This parameter is only supported on POSIX systems. - encoding
-
enumeration Encoding
(optional) - If not specified then NXLog Agent acts as if 'text' had been specified. Optional parameter to specify the file content type. Accepted values aretext
for text files orbase64
for binary files. If not specified, the default istext
. - append
-
boolean
(optional) - Optional parameter to specify whether to append existing files. Whentrue
, existing files will be appended. If this value is set tofalse
or is not specified, existing files will be overwritten.
- Response object
-
none
-
JSON
-
SOAP
The following is an example of a PutFile
request using JSON.
The request creates a file on the agent called test.txt
in the location specified in the ACL named temp
.
{
"msg": {
"command": "putFile",
"params": {
"filetype": "temp",
"filename": "test.txt",
"file": "File content\nA newline",
"executable": "false",
"encoding": "text",
"append": "false"
}
}
}
The file parameter needs to be a JSON escaped string, i.e., you must replace characters like newline, tab, double quotes, and backslash with their corresponding escaped sequence.
|
{
"response": "putFileReply",
"status": "success",
"data": {}
}
The following is an example of a PutFile
request using SOAP.
The request creates a file on the agent called test.txt
in the location specified in the ACL named temp
.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:putFile xmlns:adm="http://log4ensics.com/2010/AdminInterface">
<filetype>temp</filetype>
<filename>test.txt</filename>
<file>File Content
A newline
</file>
<!--Optional:-->
<executable>false</executable>
<!--Optional:-->
<encoding>text</encoding>
<!--Optional:-->
<append>false</append>
</adm:putFile>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:putFileReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
RouteInfoRequest
Request information about a route.
Returned data includes the status of the route, event processing statistics, the module instances in the route, and corresponding statistics for each module instance.
Note that input and output statistics may not be equal since the same events can be routed to multiple output instances.
For example, a route such as in1 ⇒ out1, out2
will output two events for every event it receives.
- Parameters
-
- name
-
string
- The user-defined name of the route.
- Response object
-
- route-name
-
string
- The user-defined name of the route. - evt-recvd
-
long
- The number of events processed by all input modules in the route. - evt-drop
-
long
- The number of dropped events. Events can be dropped with the drop() or duplicate_guard() procedures or the pm_norepeat module. This value does not include unsuccessfully rerouted events or events lost due to FlowControl. - evt-loss-flowcontrol
-
long
- The number of events dropped due to FlowControl. - evt-loss-reroute
-
long
- The number of events dropped because they could not be rerouted. Events fail to be rerouted if the queue of the next input module instance is full. - evt-fwd
-
long
- The number of events processed by all output modules in the route. - evt-fwd-reroute
-
long
- The number of events rerouted via the reroute() and add_to_route() procedures.- in-use
-
boolean
- route-modules (optional)
-
The same as ModuleInfo reply.
-
JSON
-
SOAP
The following is an example of a RouteInfoRequest
request using JSON.
The request is asking for information about a route named tcp_to_file.
{
"msg": {
"command": "routeInfoRequest",
"params": {
"name": "tcp_to_file"
}
}
}
{
"response": "routeInfoReply",
"status": "success",
"data": {
"tcp_to_file": {
"route-modules": {
"tcp_listen": {
"module-name": "tcp_listen",
"evt-recvd": 10,
"evt-drop": 0,
"evt-fwd": 10,
"batchsize": 50,
"status": 3,
"module-type": 1,
"module": "im_tcp",
"variables": {},
"features": {}
},
"output_file": {
"module-name": "output_file",
"evt-recvd": 10,
"evt-drop": 0,
"evt-fwd": 10,
"features" : {},
"queuesize": 0,
"queuelimit": 100,
"queuerecordcount" : 0,
"status": 3,
"module-type": 3,
"module": "om_file",
"variables": {}
},
"route-name": "tcp_to_file",
"evt-recvd": 20,
"evt-drop": 0,
"evt-fwd": 20,
"in-use": "true"
}
}
}
}
The following is an example of a RouteInfoRequest
request using SOAP.
It asks for information about a route named tcp_to_file.
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:routeInfoRequest xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
<name>tcp_to_file</name>
</adm:routeInfoRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:routeInfoReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
<route-name>tcp_to_file</route-name>
<evt-recvd>20</evt-recvd>
<evt-drop>0</evt-drop>
<evt-fwd>20</evt-fwd>
<in-use>true</in-use>
<route-modules>
<module-name>tcp_listen</module-name>
<evt-recvd>10</evt-recvd>
<evt-drop>0</evt-drop>
<evt-fwd>10</evt-fwd>
<batchsize>50</batchsize>
<status>3</status>
<module-type>1</module-type>
<module>im_tcp</module>
</route-modules>
<route-modules>
<module-name>output_file</module-name>
<evt-recvd>10</evt-recvd>
<evt-drop>0</evt-drop>
<evt-fwd>10</evt-fwd>
<queuesize>0</queuesize>
<queuelimit>100</queuelimit>
<queuerecordcount>16</queuerecordcount>
<status>3</status>
<module-type>3</module-type>
<module>om_file</module>
</route-modules>
</adm:routeInfoReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
ServerInfo
Request information about the server. This will also return info about all module instances.
- Parameters
-
none
- Response object
-
- uid
-
string
- started
-
long
- process start time in epoch time - load
-
float
- pid
-
integer
- cpu
-
long
- system+user cpu usage time from start in microseconds - thread_count
-
integer
- fd_count
-
integer
- mem
-
long
- version
-
string
- os
-
string
- systeminfo
-
string
- hostname
-
string
- servertime
-
long
- current server epoch time in microseconds - arch
-
string
- modules
-
equals to ModuleInfo reply
- labels (optional)
-
-
label
string
-
- extensions (optional)
-
-
module-name
string
-
module
string
-
- routes (optional)
-
JSON
-
SOAP
The following is an example of a ServerInfo
request using JSON.
The request specifies that information on extension instances should be included while route information should be omitted.
{
"msg": {
"command": "serverInfo",
"params": {
"with-extensioninfo": true,
"with-routeinfo": false
}
}
}
{
"response": "serverInfoReply",
"status": "success",
"data": {
"server-info": {
"uid": "d539f6ea-eecf-11ef-806a-49616b75002e",
"started": 1740480468564786,
"load": 0.05000000074505806,
"pid": 1,
"cpu" : 119471910,
"thread_count" : 7,
"fd_count" : 23,
"mem": 145707008,
"os": "Linux",
"osrelease" : "Rocky Linux",
"version": "5.99.8810",
"systeminfo": "OS: Linux, Hostname: nxlog-relay, Release: 5.18.2-1-default, Version: #1 SMP PREEMPT_DYNAMIC Tue Jun 7 06:08:54 UTC 2022 (695cfee), Arch: x86_64, 8 CPU(s), 15.6Gb memory",
"hostname": "nxlog-relay",
"servertime": 1740480612009126,
"arch": "x86_64",
"modules" : {
"in1" : {
"batchsize" : 50,
"evt-drop" : 0,
"evt-fwd" : 1009440,
"evt-recvd" : 1009440,
"features" : {},
"module" : "im_http",
"module-type" : 1,
"module_name" : "in1",
"status" : 3,
"tcp" : {
"connections" : [
{
"address" : "127.0.0.1",
"port" : 34322
}
],
"cumulative-connection-count" : 1,
"current-connection-count" : 1,
"max-connections" : 4294967295,
"current-listener-count" : 1,
"listeners" : [
{
"address" : "127.0.0.1",
"port" : 7000
}
]
},
"variables" : {}
},
"out1" : {
"evt-drop" : 0,
"evt-fwd" : 1009440,
"evt-recvd" : 1009440,
"features" : {},
"module" : "om_http",
"module-type" : 3,
"module_name" : "out1",
"queuelimit" : 10000000,
"queuerecordcount" : 0,
"queuesize" : 0,
"status" : 3,
"tcp" : {
"connections" : [
{
"address" : "127.0.0.1",
"port" : 7000
}
],
"cumulative-connection-count" : 1,
"current-connection-count" : 1,
"current-listener-count" : 0
},
"variables" : {}
}
},
"labels": {
"ou": "IT",
"location": "Germany"
},
"extensions": {
"admin": {
"module-name": "admin",
"module": "xm_admin"
},
"json": {
"module-name": "json",
"module": "xm_json"
},
"syslog": {
"module-name": "syslog",
"module": "xm_syslog"
},
"fileop": {
"module-name": "fileop",
"module": "xm_fileop"
}
}
}
}
}
The following is an example of a ServerInfo
request using SOAP.
The request specifies that information on extension instances should be included while route information should be omitted.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:serverInfo xmlns:adm="http://log4ensics.com/2010/AdminInterface">
<with-extensioninfo>true</with-extensioninfo>
<with-routeinfo>false</with-routeinfo>
</adm:serverInfo>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<adm:serverInfoReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
<uid>5f46514e-26db-11ee-80d1-736f636b7939</uid>
<started>1740482568294547</started>
<load>0.05000000074505806</load>
<pid>1</pid>
<cpu>122025135</cpu>
<thread_count>7</thread_count>
<fd_count>23</fd_count>
<mem>145707008</mem>
<version>6.6.9843</version>
<os>Linux</os>
<osrelease>Rocky Linux 9.0 (Blue Onyx)</osrelease>
<systeminfo>OS: Linux, Hostname: nxlog-relay, Release: 5.18.2-1-default, Version: #1 SMP PREEMPT_DYNAMIC Tue Jun 7 06:08:54 UTC 2022 (695cfee), Arch: x86_64, 8 CPU(s), 15.6Gb memory</systeminfo>
<hostname>nxlog-relay</hostname>
<servertime>1740482781171706</servertime>
<arch>x86_64</arch>
<modules>
<module-name>in1</module-name>
<evt-recvd>1000000</evt-recvd>
<evt-drop>1000000</evt-drop>
<evt-fwd>1000000</evt-fwd>
<batchsize>50</batchsize>
<status>3</status>
<module-type>1</module-type>
<module>im_testgen</module>
</modules>
<modules>
<module-name>out2</module-name>
<evt-recvd>0</evt-recvd>
<evt-drop>0</evt-drop>
<evt-fwd>0</evt-fwd>
<queuesize>0</queuesize>
<queuelimit>1048576</queuelimit>
<queuerecordcount>0</queuerecordcount>
<status>1</status>
<module-type>3</module-type>
<module>om_file</module>
</modules>
<labels>
<label name="ou">IT</label>
<label name="location">Germany</label>
</labels>
<extensions>
<module-name>admin</module-name>
<module>xm_admin</module>
</extensions>
<extensions>
<module-name>json</module-name>
<module>xm_json</module>
</extensions>
<extensions>
<module-name>_syslog</module-name>
<module>xm_syslog</module>
</extensions>
<extensions>
<module-name>_fileop</module-name>
<module>xm_fileop</module>
</extensions>
</adm:serverInfoReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
ServerStart
Start all module instances; the opposite of ServerStop.
- Parameters
-
none
- Returned object
-
none
ServerStop
Stop all module instances. The NXLog Agent process will not exit. Otherwise, it would be impossible to start it again remotely. Extension modules are not stopped for the same reason.
- Parameters
-
none
- Returned object
-
none
SetUid
Set a unique identifier and signature for the NXLog Agent installation.
- Parameters
-
- uid
-
Unique identifier to set.
- signature
-
Signature of the new unique identifier.
- Response object
-
none