Remote Management (xm_admin)
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.
| To examine the supported platforms, see the list of installation packages. |
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.
NXLog Platform uses this module to manage agents and requires the agent configuration to contain certain elements. For more information, see NXLog Agent connectivity in the NXLog Platform User Guide.
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.
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 to the hostname or IP address using a colon as a separator (
|
|||
The module listens for connections on this IP address or DNS hostname.
The default is The port number can be defined by appending it to the IP address using a colon as a separator ( |
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 NXLog Agent uses the operating system root certificate store 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, supported only on Windows, defines a pattern for locating a suitable CA (Certificate Authority) certificate and its thumbprint in the native Windows Certificate Storage.
The pattern must follow PCRE2 rules and use the format Configuration examples: or A normal log output example would look like as follows: |
|||
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, CAFile and CAPattern 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, supported only on Windows, defines a pattern for identifying a corresponding certificate and its thumbprint within the native Windows Certificate Storage.
The pattern must follow PCRE2 rules and use the format Configuration examples: or A normal log output example would look like as follows: |
|||
This optional directive specifies the thumbprint of the certificate that will be presented to the remote server during the HTTPS 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 When the global directive UseCNGCertificates is set to
On the contrary, when the global directive UseCNGCertificates is set to The usage of the directive is the same in all cases: 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:
|
|||||
With this optional directive it is possible to set the maximum number of allowed concurrent/active connections for a listening TCP socket.
If not specified, the default value is 2024-03-01 22:29:16 ERROR [im_tcp|in_tcp] Number of allowed active connections(10) reached: 10. Refusing connection from 127.0.0.1 |
|||||
This optional directive defines the maximum time in seconds before NXLog Agent closes TCP connections without traffic. The minimum timeout value is 15 seconds. If this directive is not specified, NXLog Agent does not close idle TCP connections. |
|||||
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 for including 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 double 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
This section provides details of the xm_admin SOAP methods and JSON objects, how to structure requests and the expected response.
Request-response format
When using SOAP, the HTTP POST request must include the Content-Type HTTP header with the value set to 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: nnnThe request details are added to the SOAP Body element and the XML must 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: nnnnThe 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 to 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: nnnThe 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 must 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: nnnnThe 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,
"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" : {}
}
}
}
}
}For more SOAP and JSON request examples, see the Request-response examples below.
Methods and 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 accepts the following parameters:
- 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.
- Returned object
-
- encoding
-
see enumeration encoding below.
- file
-
string- file contents.
- GetLog
-
Download the NXLog Agent log file.
GetLog accepts the following parameters:
- 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.
- Returned object
-
- logfile
-
string- log contents.
- GetUid
-
Return the unique identifier (UID) of the NXLog Agent installation.
GetUid accepts the following parameters:
- 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.
- Returned object
-
- uid
-
string - signature
-
string(optional)
- ModuleInfo
-
Request information about a module instance.
ModuleInfo requires the following parameters:
- Parameters
-
- name
-
string- The user-defined name of the module.
- Returned object
-
- module-name
-
string- The user-defined name of the module. - evt-recvd
-
long- The number of events taken from module input queue. - evt-drop
-
long- The number of events dropped while processing. - evt-fwd
-
long- The number of events exited the module. - queuesize
-
long- The current occupation of Logqueue in bytes. - queuelimit
-
long- The acting LogqueueSize in bytes, default is 2 MB. - batchsize
-
integer- The acting BatchSize for a specific module in records. - queuerecordcount
-
integer- The number of separate records in the queue. - status
-
see enumeration encoding below.
- module-type
-
see enumeration encoding below.
- module
-
string- instance of which type is that - 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
-
- ModuleRestart
-
Restart a module instance.
ModuleRestart requires the following parameters:
- Parameters
-
- name
-
string- The user-defined name of the module.
- Returned object
-
none
- ModuleStart
-
Start a module instance.
ModuleStart requires the following parameters:
- Parameters
-
- name
-
string- The user-defined name of the module.
- Returned object
-
none
- ModuleStop
-
Stop a module instance.
ModuleStop requires the following parameters:
- Parameters
-
- name
-
string- The user-defined name of the module.
- Returned 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 namedconfwhich allows reading and writing to its configuration directory, and the other namedcertwhich allows reading and writing to its certificates directory. NXLog Platform uses theconfandcertACLs 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:
- 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 tofalseor 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 aretextfor text files orbase64for 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 tofalseor is not specified, existing files will be overwritten.
- Returned object
-
none
-
- 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:
- Parameters
-
- name
-
string- The user-defined name of the route.
- Returned object
-
- route-name
-
string - evt-recvd
-
long - evt-drop
-
long - evt-fwd
-
long - in-use
-
boolean - route-modules (optional)
-
-
equals to ModuleInfo reply
-
- RouteStart
-
RouteStart requires the following parameters:
- Parameters
-
- name
-
string
- Returned object
-
none
- RouteRestart
-
RouteRestart requires the following parameters:
- Parameters
-
- name
-
string
- Returned object
-
none
- RouteStop
-
RouteStop requires the following parameters:
- Parameters
-
- name
-
string
- Returned object
-
none
- ServerInfo
-
Request information about the server. This will also return info about all module instances.
ServerInfo accepts the following optional parameters:
- Parameters
-
none
- Returned 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)
- ServerRestart
-
Restart all modules of the server.
ServerRestart requires the following parameters:
- Parameters
-
none
- Returned object
-
none
- ServerStart
-
Start all modules of the server, the opposite of ServerStop.
ServerStart requires the following parameters:
- Parameters
-
none
- Returned object
-
none
- 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. ServerStop requires the following parameters:
- Parameters
-
none
- Returned object
-
none
- SetUid
-
Set a unique identifier and signature for the NXLog Agent installation. SetUid requires the following parameters:
- Parameters
-
- uid
-
Unique identifier to set.
- signature
-
Signature of the new unique identifier.
- Returned object
-
none
- Enumeration types
- Encoding
-
Can be
textorbase64. - ModuleStatusType
-
0 = UNINITIALIZED
1 = STOPPED
2 = PAUSED
3 = RUNNING - ModuleType
-
1 = INPUT
2 = PROCESSOR
3 = OUTPUT
4 = EXTENSION
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 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>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,
"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" : {}
}
}
}
}
}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, 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. Refer to Access denied to a Windows Event Log channel in the Troubleshooting section for instructions on how to resolve this error. |