Remote Management (xm_admin)
Previously known as xm_soapadmin, this module provides secure remote administration capabilities for NXLog Agent installations using either JSON or SOAP over HTTP(S), also known as a web service. Both SOAP and JSON are widely supported in many different programming languages. This makes it easy to implement administration scripts or create plugins for system monitoring tools such as Nagios, Munin, or Cacti. Using the xm_admin module, NXLog Agent can accept and initiate connections over TCP, SSL, and Unix domain sockets depending on its Configuration.
Although the module can both initiate and accept connections, the direction of the HTTP(S) requests is always the same, i.e., requests are sent to the module, which returns an HTTP(S) response.
Configuration
The xm_admin module accepts the following directives in addition to the common module directives.
Required directives
The following directives are required for the module to start.
This directive has been deprecated (in favor of the Host directive) as of version 5.3.
The module initiates a connection to a remote socket.
The argument must be an IP address when SocketType is set to |
|||
The module initiates a connection to the IP address or hostname (and port) defined by this directive. If additional hosts are specified on new lines, the module works in a failover configuration. If a destination becomes unavailable, the module automatically fails over to the next one. If the last destination becomes unavailable, the module fails over to the first destination. The port number can be defined by appending it at the end of the hostname or IP address using a colon as a separator (
|
|||
This directive has been deprecated (in favor of the ListenAddr directive) as of version 5.3.
This directive instructs the module to accept connections.
The argument must be an IP address when SocketType is |
|||
The module listens for connections on this IP address or DNS hostname.
The default is The port number can be defined by appending it at the end of the IP address using a colon as a separator ( |
|||
This directive has been deprecated (in favor of the Host and ListenAddr directives) as of version 5.3.
This specifies the port number used with the Host, ListenAddr, Listen or Connect modes.
The default port is |
TLS/SSL directives
This boolean directive specifies whether the connection should be allowed with an expired certificate.
If set to |
|||
This boolean directive specifies that the remote connection should be allowed regardless of the certificate verification results.
If set to |
|||
This directive specifies a path to a directory containing certificate authority (CA) certificates. These certificates will be used to verify the certificate presented by the remote host. The certificate files must be named using the OpenSSL hashed format, i.e. the hash of the certificate followed by .0, .1, etc. To find the hash of a certificate using OpenSSL:
For example, if the certificate hash is A remote server’s self-signed certificate (which is not signed by a CA) can also be trusted by including a copy of the certificate in this directory. This directive is only valid if SocketType is set to The default operating system root certificate store will be used if this directive is not specified.
Unix-like operating systems commonly store root certificates in |
|||
This specifies the path of the certificate authority (CA) certificate that will be used to verify the certificate presented by the remote host.
A remote host’s self-signed certificate (which is not signed by a CA) can be trusted by specifying the remote host certificate itself.
In case of certificates signed by an intermediate CA, the certificate specified must contain the complete certificate chain (certificate bundle).
This directive is only valid if SocketType is set to |
|||
This optional directive specifies the thumbprint of the certificate authority (CA) certificate that will be used to verify the certificate presented by the remote server. The hexadecimal fingerprint string can be copied from Windows Certificate Manager (certmgr.msc). Any whitespace is automatically removed. The certificate must be added to a Windows certificate store that is accessible by NXLog Agent. This directive is only supported on Windows and is mutually exclusive with the CADir and CAFile directives. |
|||
This specifies the path of the certificate file that will be presented to the remote host during the SSL handshake.
This directive is only valid if SocketType is set to |
|||
This specifies the path of the private key file that was used to generate the certificate specified by the CertFile directive.
This is used for the SSL handshake.
This directive is only valid if SocketType is set to |
|||
This optional directive specifies the thumbprint of the certificate that will be presented to the remote host during the SSL handshake.
The hexadecimal fingerprint string can be copied from Windows Certificate Manager (certmgr.msc).
Whitespaces are automatically removed.
The certificate must be imported to the
This directive is only supported on Windows and is mutually exclusive with the CertFile and CertKeyFile directives.
|
|||
This directive specifies a path to a directory containing certificate revocation list (CRL) files. These CRL files will be used to check for certificates that were revoked and should no longer be accepted. The files must be named using the OpenSSL hashed format, i.e., the hash of the issuer followed by .r0, .r1, etc. To find the hash of the issuer of a CRL file using OpenSSL:
For example if the hash is This directive is only valid if SocketType is set to |
|||
This specifies the path of the certificate revocation list (CRL) which will be used to check for certificates that have been revoked and should no longer be accepted. Example to generate a CRL file using OpenSSL:
This directive is only valid if SocketType is set to |
|||
This optional directive specifies a file with dh-parameters for Diffie-Hellman key exchange. These parameters can be generated with dhparam(1ssl). If this directive is not specified, default parameters will be used. See the OpenSSL Wiki for further details. |
|||
This directive specifies the passphrase of the private key specified by the CertKeyFile directive. A passphrase is required when the private key is encrypted. Example to generate a private key with Triple DES encryption using OpenSSL:
This directive is not needed for passwordless, private keys and it is
only valid if SocketType is set to |
|||
This boolean directive specifies that the remote host must present a certificate.
If set to |
|||
This optional boolean directive, when set to |
|||
This directive sets the connection type. It can be one of the following:
|
|||
This optional directive can be used to set the permitted cipher list for TLSv1.2 and below, overriding the default.
Use the format described in the ciphers(1ssl) man page.
For example specify
|
|||
This optional directive can be used to set the permitted cipher list for TLSv1.3. Use the same format as in the SSLCipher directive. Refer to the OpenSSL documentation for a list of valid TLS v1.3 cipher suites. The default value is:
|
|||
This boolean directive allows you to enable data compression when sending data over the network.
The compression mechanism is based on the zlib compression library.
If the directive is not specified, it defaults to
|
|||
This directive can be used to set the allowed SSL/TLS protocol(s). It takes a comma-separated list of values which can be any of the following: |
Optional directives
This block defines directories which can be used with the GetFile and PutFile web service requests.
The name of the ACL is used in these requests together with the filename.
The filename can contain only characters
|
|||||
This optional directive can be used to allow IP addresses and/or networks to connect. The directive can be set multiple times to add different IPs or networks to allow. This directive is only active when the ListenAddr directive is present. In the absence of this directive, the BlockIP directive is considered. If both AllowIP and BlockIP are absent, then hosts are not restricted from connecting to a listening module. The following formats may be used for the AllowIP directive:
|
|||||
This optional directive can be used to deny IP addresses and/or networks to connect. The directive can be set multiple times to add different IPs or networks to deny. This directive is only active when the ListenAddr directive is present. In the absence of this directive, the AllowIP directive is considered. If both AllowIP and BlockIP are absent, then hosts are not restricted from connecting to a listening module. The following formats may be used for the BlockIP directive:
|
|||||
This optional boolean directive specifies whether the module instance should exclusively bind to the specified port.
The default value is
|
|||||
This optional boolean directive determines whether the module instance should forcibly bind to a port already in use.
The default value is |
|||||
This optional boolean directive specifies whether multiple xm_admin module instances can listen on the same port.
When you enable this directive, multiple instances run in a separate thread, allowing NXLog Agent to process incoming logs simultaneously.
See the examples below.
The default value is
|
|||||
This directive sets the number of seconds xm_admin waits for an incoming request from the agent management system.
If no valid request arrives before the timer expires xm_admin will reset the management connection. The timer resets on every incoming request
Defaults to |
|||||
This directive allows custom key-value pairs to be defined with static or dynamic values. Labels are very useful to provide supplementary details about agents, such as the display name, operating system, local contact information and so on. Labels are returned as part of the response to a ServerInfo request. Label values can be set statically by specifying a string, a defined constant, or an environment variable in the |
|||||
This optional directive sets the reconnect interval in seconds. If it is set, the module attempts to reconnect in every defined second. If it is not set, the reconnect interval will start at 1 second and doubles with every attempt. If the duration of the successful connection is greater than the current reconnect interval, then the reconnect interval will be reset to 1 sec.
|
|||||
This directive specifies in seconds how much time xm_admin should wait to acquire a connection before it reverts the managed configuration file to the previous version.
Defaults to |
Exported SOAP methods and JSON objects
The xm_admin module exports the following methods which can be called remotely. 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.
- GetFile
-
Download a file from NXLog Agent. This requires an ACL to be specified in the agent configuration. GetFile requires the following parameters:
- acl
-
A value corresponding to the given name of a defined ACL.
This parameter is the equivalent of the filetype parameter. The acl and filetype parameters are mutually exclusive. - filetype
-
A value corresponding to the given name of a defined ACL.
This parameter is the equivalent of the acl parameter. The acl and filetype parameters are mutually exclusive. This parameter is planned to be obsolete with NXLog Agent v7. - filename
-
The name of the file being requested.
- GetLog
-
Download the NXLog Agent log file. GetLog accepts the following parameters:
- size
-
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.
- GetUid
-
Return the unique signature of the NXLog Agent installation. identifier (UID). GetUid accepts the following parameters:
- with-signature
-
Boolean directive specifying if the response must include a signature. The default is
FALSE
. If no signature is found, it returns an empty string
- ModuleInfo
-
Request information about a module instance. ModuleInfo requires the following parameters:
- name
-
The user-defined name of the module.
- ModuleRestart
-
Restart a module instance. ModuleInfo requires the following parameters:
- name
-
The user-defined name of the module.
- ModuleStart
-
Start a module instance. ModuleStart requires the following parameters:
- name
-
The user-defined name of the module.
- ModuleStop
-
Stop a module instance. ModuleStop requires the following parameters:
- name
-
The user-defined name of the module.
- 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 namedconf
which allows reading and writing to its configuration directory, and the other namedcert
which allows reading and writing to its certificates directory. NXLog Platform uses theconf
andcert
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.
PutFile requires the following parameters:
- acl
-
A value corresponding to the given name of a defined ACL.
This parameter is the equivalent of the filetype parameter. The acl and filetype parameters are mutually exclusive. - filetype
-
A value corresponding to the given name of a defined ACL.
This parameter is the equivalent of the acl parameter. The acl and filetype parameters are mutually exclusive. This parameter is planned to be obsolete with NXLog Agent v7. - filename
-
The name of the file.
- file
-
A string containing the content of the file.
- executable
-
Optional parameter to specify whether the file is an executable. When
true
, 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
-
Optional parameter to specify the file content type. Accepted values are
text
for text files orbase64
for binary files. If not specified, the default istext
. - append
-
Optional parameter to specify whether to append existing files. When
true
, existing files will be appended. If this value is set tofalse
or is not specified, existing files will be overwritten.
-
- 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. RouteInfoRequest requires the following parameters:
- name
-
The user-defined name of the route.
- ServerInfo
-
Request information about the server. This will also return info about all module instances. ServerInfo accepts the following optional parameters:
- with-routeinfo
-
When
true
, the response will include information about the configured routes. This includes the route name, status, event processing statistics, the module instances in the route and corresponding statistics for each. If this value is set tofalse
or is not specified, route information is omitted from the response. - with-extensioninfo
-
When
true
, the response will include a list of the available extension instances. If this value is set tofalse
or is not specified, extension information is omitted from the response.
- ServerRestart
-
Restart all modules of the server.
- ServerStart
-
Start all modules of the server, the opposite of ServerStop.
- ServerStop
-
Stop all modules of the server. Note that 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.
- SetUid
-
Set a unique identifier and signature for the NXLog Agent installation. SetUid requires the following parameters:
- uid
-
Unique identifier to set.
- signature
-
Signature of the unique identifier to set.
SetUid The new UID will become active only after restarting NXLog Agent. |
Refer to the Request - response format and Request - response examples sections below for examples of how to use these methods.
Request - response format
When using SOAP, the HTTP POST request must include the Content-Type
HTTP header with the value set as text/xml
.
The following is an example header:
POST / HTTP/1.1
Host: 192.168.1.123:8080
Content-Type: text/xml; charset=utf-8
Content-Length: nnn
The request details are added to the SOAP Body
element and the XML needs to be sent in the body of the POST request as raw data.
The following is a SOAP request for ServerInfo.
<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"/>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Below is an example response header to the above request.
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: nnnn
The response body will include the requested data in XML format as follows:
<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>1655360183350993</started>
<load>0.05000000074505806</load>
<pid>1</pid>
<mem>145707008</mem>
<version>5.5.7535</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>1655796519122516</servertime>
<arch>x86_64</arch>
<cpu>122025135</cpu>
<thread_count>7</thread_count>
<fd_count>23</fd_count>
<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>
</adm:serverInfoReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
When using JSON, the HTTP POST request must include the Content-Type
HTTP header with the value set as application/json
.
The following is an example header:
POST / HTTP/1.1
Host: 192.168.1.123:8080
Content-Type: application/json; charset=utf-8
Content-Length: nnn
The request details need to be included in a JSON object with the key name msg
.
This object should contain the following key/values:
- command
-
String value containing the name of the method being requested. This value is required.
- params
-
JSON object containing the required parameters for the method being requested. May be omitted for methods that do not require additional parameters.
The JSON object needs to be sent in the body of the POST request as raw data. The following is a JSON request for ServerInfo.
{
"msg": {
"command": "serverInfo"
}
}
Below is an example response header to the above request.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
The response body will include the requested data in JSON format as follows:
{
"response": "serverInfoReply",
"status": "success",
"data": {
"server-info": {
"servertime" : 1649926291358427,
"started": 1655360183350993,
"load": 0.05000000074505806,
"pid": 1,
"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",
"arch": "x86_64",
"cpu" : 119471910,
"fd_count" : 23,
"thread_count" : 7,
"uid" : "5f46514e-26db-11ee-80d1-736f636b7939",
"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,
"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" : {}
}
}
}
}
}
For more SOAP and JSON request examples, see the Request - response examples below.
Request - response examples
This section contains examples of typical SOAP and JSON requests. Further examples and scripts can be found in the NXLog public repository on GitLab.
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>
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"/>
</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>1655360183350993</started>
<load>0.05000000074505806</load>
<pid>1</pid>
<mem>145707008</mem>
<version>5.5.7535</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>1655796519122516</servertime>
<arch>x86_64</arch>
<cpu>122025135</cpu>
<thread_count>7</thread_count>
<fd_count>23</fd_count>
<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>
</adm:serverInfoReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The following is an example of a RouteInfoRequest using SOAP. The request is asking 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>
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>
The following is an example of a GetLog request using SOAP. The requestspecifies 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>
The following is an example of a GetFile request for a file named test.txt
from the directory specified by the conf
ACL using SOAP.
<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>
The encoding in the response specifies the automatically detected content type.
The possible values are text for text files and base64 for binary files.
|
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.
characters like newline, tab, double quotes and backslash should be
replaced with their corresponding escaped sequence.
|
{
"response": "putFileReply",
"status": "success",
"data": {}
}
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"
}
}
{
"response": "serverInfoReply",
"status": "success",
"data": {
"server-info": {
"servertime" : 1649926291358427,
"started": 1655360183350993,
"load": 0.05000000074505806,
"pid": 1,
"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",
"arch": "x86_64",
"cpu" : 119471910,
"fd_count" : 23,
"thread_count" : 7,
"uid" : "5f46514e-26db-11ee-80d1-736f636b7939",
"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,
"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" : {}
}
}
}
}
}
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"
}
}
}
The below example shows a successful response for a RouteInfoRequest request.
{
"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 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 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 GetFile request for a file named test.txt
from the directory specified by the conf
ACL using JSON.
{
"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 encoding in the response specifies the automatically detected content type.
The possible values are text for text files and base64 for binary files.
|
Configuration examples
This example provides static and dynamic configuration of labels.
Static configuration is set with the define
string, environment variable envvar
, and describing key value pairs inside the <labels>
block.
Dynamic configuration is achieved via the start-up script of the include_stdout
directive and run-time function set with the host
label.
define BASE /opt/nxlog_new
envvar NXLOG_OS
<Extension admin>
Module xm_admin
...
<labels>
os_name "Debian"
agent_base %BASE%
os %NXLOG_OS%
include_stdout /path/to/labels.sh
host hostname_fqdn()
</labels>
</Extension>
This configuration specifies two additional administration ports on localhost.
<Extension ssl_connect>
Module xm_admin
Connect 192.168.1.1
Port 4041
SocketType SSL
CAFile %CERTDIR%/ca.pem
CertFile %CERTDIR%/client-cert.pem
CertKeyFile %CERTDIR%/client-key.pem
KeyPass secret
AllowUntrusted FALSE
RequireCert TRUE
Reconnect 60
<ACL conf>
Directory %CONFDIR%
AllowRead TRUE
AllowWrite TRUE
</ACL>
<ACL cert>
Directory %CERTDIR%
AllowRead TRUE
AllowWrite TRUE
</ACL>
</Extension>
<Extension tcp_listen>
Module xm_admin
Listen localhost
Port 8080
</Extension>
<Extension tcp_connect>
Module xm_admin
Connect localhost
Port 4040
</Extension>
On Microsoft Windows platforms, if the NXLog Agent service is running with a custom user account and NXLog Agent is managed from NXLog Platform, the account needs to be added to the built-in Performance Monitor Users Windows group to be able to access performance counter data. If not, the following error will be logged in the log file:
Furthermore, an error may be logged when NXLog Agent is configured to collect events from Windows Event Log:
This happens when the user account does not have permission to access the specified Windows Event Log channels. |