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.

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.

Host

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 (host:port). The default port is 8080.

When the Host directive is used with a hostname instead of an IP address, the hostname will be resolved to an IP address for each new connection. If a resolver, e.g. DNS, returns multiple IP addresses, the module will connect to the first IP address. If a single output instance is configured with multiple Host directives or the resolver returns multiple addresses for a name, these hosts are accessed in failover mode. If a Host directive is configured with a hostname, the product performs a name lookup and establishes the connection to the first reachable address in the returned set of addresses. The module will remain connected to that address until it is stopped, or the connection is severed. DNS changes are therefore not picked up by the module without intervention. If the connection fails to the first address of the set, the module will attempt to connect to the next address, until it reaches the end of the set of addresses. Then it performs a lookup on the next Host directive, if so configured. Once all options are exhausted, the module will start over from the first Host directive, cycling through them again until the connection can be re-established.

ListenAddr

The module listens for connections on this IP address or DNS hostname. The default is localhost.

The port number can be defined by appending it to the IP address using a colon as a separator (host:port). The default port is 8080.

TLS/SSL directives

AllowExpired

This boolean directive specifies whether the connection should be allowed with an expired certificate. If set to TRUE, the remote host will be able to connect with an expired certificate. The default is FALSE: the certificate must not be expired. This directive is only valid if RequireCert is set to TRUE.

AllowUntrusted

This boolean directive specifies that the remote connection should be allowed regardless of the certificate verification results. If set to TRUE, the remote host will be able to connect with any unexpired certificate. The default value is FALSE: all connections must present a trusted certificate. This directive is only valid if SocketType is set to SSL.

CADir

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:

$ openssl x509 -hash -noout -in ca.crt

For example, if the certificate hash is e2f14e4a, then the certificate filename should be e2f14e4a.0. If there is another certificate with the same hash then it should be named e2f14e4a.1, and so on.

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 SSL.

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 /etc/ssl/certs. Windows operating systems use the Windows Certificate Store, while macOS uses the Keychain Access Application as the default certificate store.

CAFile

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 SSL.

CAPattern

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 "SUBJECT=, CN=, DN=, SAN=" where DN is "CN=, O=, OU=, L=, ST=, C=". During configuration, this directive resolves into the corresponding CAThumbprint value. If multiple matching certificates are found, the first encountered thumbprint is selected. We recommend ensuring that the used certificate storage is well-maintained for optimal performance. This feature is not dynamic; the agent must be restarted if the certificate changes. This directive is mutually exclusive with the CAThumbprint directive.

Configuration examples:

CAPattern    'Test' + ' ' + 'Root'

CAPattern    $domain

A normal log output example would look like as follows:

matching pattern [DN=CN=Client\.example\.com;.*?SAN=DNS:Client\.example\.com] to certificate [SUBJECT=US, ClientState, ClientCity, ClientCompany, ClientUnit, Client.example.com, CN=Client.example.com; DN=CN=Client.example.com, O=ClientCompany, OU=ClientUnit, L=ClientCity, ST=ClientState, C=US; SAN=DNS:Client.example.com; DNS:www.Client.example.com; IP:127.0.0.3; ]

CAThumbprint

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.

CertFile

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 SSL.

CertKeyFile

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 SSL.

CertPattern

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 "SUBJECT=, CN=, DN=, SAN=" where DN is "CN=, O=, OU=, L=, ST=, C=". The certificate must be imported in PFX format into the Local Computer\Personal certificate store for NXLog Agent to locate it. During configuration, this directive is resolved into the corresponding CertThumbprint value. The first found thumbprint will be chosen if multiple certificates match the pattern. We recommend ensuring that the used certificate storage is well-maintained for optimal performance. This feature is not dynamic; the agent must be restarted if the certificate changes. This directive is mutually exclusive with the CertThumbprint directive.

Configuration examples:

CertPattern    $hostname + 'Cert'

CertPattern    DN=CN=Client\.example\.com;.*?SAN=DNS:Client\.example\.com

A normal log output example would look like as follows:

matching pattern [DN=CN=Client\.example\.com;.*?SAN=DNS:Client\.example\.com] to certificate [SUBJECT=US, ClientState, ClientCity, ClientCompany, ClientUnit, Client.example.com, CN=Client.example.com; DN=CN=Client.example.com, O=ClientCompany, OU=ClientUnit, L=ClientCity, ST=ClientState, C=US; SAN=DNS:Client.example.com; DNS:www.Client.example.com; IP:127.0.0.3; ]

CertThumbprint

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 Local Computer\Personal certificate store in PFX format for NXLog Agent to find it. To create a PFX file from the certificate and private key using OpenSSL:

$ openssl pkcs12 -export -out server.pfx -inkey server.key -in server.pem

This directive is only supported on Windows and is mutually exclusive with the CertFile and CertKeyFile directives.

When the global directive UseCNGCertificates is set to FALSE, the private key associated with the certificate must be exportable.

If you generate the certificate request using Windows Certificate Manager, enable the Make private key exportable option from the certificate properties.
If you import the certificate with the Windows Certificate Import Wizard, make sure that the Mark this key as exportable option is enabled.
If you migrate the certificate and associated private key from one Windows machine to another, select Yes, export the private key when exporting from the source machine.

CRLDir

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:

$ openssl crl -hash -noout -in crl.pem

For example if the hash is e2f14e4a, then the filename should be e2f14e4a.r0. If there is another file with the same hash then it should be named e2f14e4a.r1, and so on.

This directive is only valid if SocketType is set to SSL.

CRLFile

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:

$ openssl ca -gencrl -out crl.pem

This directive is only valid if SocketType is set to SSL.

DHFile

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.

KeyPass

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:

$ openssl genrsa -des3 -out server.key 2048

This directive is not needed for passwordless, private keys and it is only valid if SocketType is set to SSL.

RequireCert

This boolean directive specifies that the remote host must present a certificate. If set to TRUE and a certificate is not presented during the connection handshake, the connection will be refused. The default value is TRUE: each connection must use a certificate. This directive is only valid if SocketType is set to SSL.

SearchAllCertStores

This optional boolean directive, when set to TRUE, enables the loading of all available Windows certificates into NXLog Agent, for use during remote certificate verification. Any required certificates must be added to a Windows certificate store that NXLog Agent can access. This directive is mutually exclusive with the CAThumbprint, CADir and CAFile directives.

SocketType

This directive sets the connection type. It can be one of the following:

SSL: TLS/SSL for secure network connections

TCP: TCP, the default if SocketType is not explicitly specified

SSLCipher

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 RSA:!COMPLEMENTOFALL to include all ciphers with RSA authentication but leave out ciphers without encryption.

If RSA or DSA ciphers with Diffie-Hellman key exchange are used, DHFile can be set for specifying custom dh-parameters.

SSLCiphersuites

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:

TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256

SSLCompression

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 FALSE: compression is disabled.

Some Linux packages (for example, Debian) use the OpenSSL library and may not support the zlib compression mechanism. The module will emit a warning on startup if the compression support is missing. The generic deb/RPM packages are bundled with a zlib-enabled libssl library.

SSLProtocol

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: SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3. By default, the TLSv1.2 and TLSv1.3 protocols are allowed. Note that the OpenSSL library shipped by Linux distributions may not support SSLv2 and SSLv3, and these will not work even if enabled with this directive.

Optional directives

ACL

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 [a-zA-Z0-9-._], so these file operations will only work within the specified directory. Example of usage is in the Examples section.

AllowRead: If set to TRUE, GetFile requests are allowed.

AllowWrite: If set to TRUE, PutFile requests are allowed.

Directory: The name of the directory where the files are saved to or loaded from.

AllowIP

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:

0.0.0.0 (IPv4 address)
0.0.0.0/32 (IPv4 network with subnet bits)
0.0.0.0/0.0.0.0 (IPv4 network with subnet address)
aa::1 (IPv6 address)
aa::12/64 (IPv6 network with subnet bits)

BlockIP

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:

0.0.0.0 (IPv4 address)
0.0.0.0/32 (IPv4 network with subnet bits)
0.0.0.0/0.0.0.0 (IPv4 network with subnet address)
aa::1 (IPv6 address)
aa::12/64 (IPv6 network with subnet bits)

ExclusiveAddrUse

This optional boolean directive specifies whether the module instance should exclusively bind to the specified port. The default value is FALSE; multiple module instances can bind to the same port.

This directive is only supported on Windows platforms.

ReuseAddr

This optional boolean directive determines whether the module instance should forcibly bind to a port already in use. The default value is TRUE; multiple instances can listen on the same port and process data simultaneously.

ReusePort

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 FALSE; multiple instances cannot bind to the same port.

This directive is not supported on Windows platforms.

DataTimeout

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 300 (5 minutes), accepts values between 5 and 3600. 0 is reserved for disabling management connection timeout detection.

Labels

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 <labels> block. They can also be set dynamically, for example at start-up with a script executed using the include_stdout directive, or at run-time before each response is sent. Setting labels is demonstrated in the Examples section.

Reconnect

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.

The Reconnect directive must be used with caution. If it is used on multiple systems, it can send reconnect requests simultaneously to the same destination, potentially overloading the destination system. It may also cause NXLog Agent to use unusually high system resources or cause NXLog Agent to become unresponsive.

The Reconnect directive only works when used in conjunction with the Host directive.

ReversionTimeout

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 300 (5 minutes), accepts values between 5 and 3600. 0 is reserved for disabling the reversion timeout. This should be set in the new (updated) configuration to disable the reversion mechanism. See PutFile for more information on configuration reversion.

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 identifier (UID) of the NXLog Agent installation. 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 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.

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 to false 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 or base64 for binary files. If not specified, the default is text.

append

Optional parameter to specify whether to append existing files. When true, existing files will be appended. If this value is set to false 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 to false 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 to false or is not specified, extension information is omitted from the response.

ServerRestart

Restart all modules of the server. Note that this call will not cause NXLog Agent process to restart but instead will result in a config reload.

terminate: This value is optional and set to false by default. When true, enables NXLog Agent process to terminate and let the service manager restart it again. Please note that if the service manager is not properly installed or the operating system does not support automatic restart features then this call will result in the termination of NXLog Agent process.

This flag has no effect on Windows platforms.

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

Example 1. SOAP Request 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>

Example 2. JSON request format

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.

Example 3. SOAP request for PutFile

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>

Successful response to a PutFile request

<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>

Example 4. SOAP request for ServerInfo

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>

Successful response to a ServerInfo request

<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>

Example 5. SOAP request for RouteInfoRequest

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>

Successful response to a RouteInfoRequest request

<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>

Example 6. SOAP request for ModuleInfo

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>

Successful response to a ModuleInfo request

<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>

Example 7. SOAP request for GetLog

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>

Successful response for a GetLog request

<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&#xA;2020-12-02 15:54:03 INFO [xm_admin|tcp_listen] connection accepted from 10.0.0.100:51705&#xA;2020-12-02 15:54:03 INFO [xm_admin|tcp_listen] getLog called&#xA;</logfile>
        </adm:getLogReply>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example 8. SOAP request for GetFile

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>

Successful response for a GetFile request

<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.&#xA;Log line 2.&#xA;</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.

Example 9. JSON request for PutFile

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.

Successful response to a PutFile request

{
  "response": "putFileReply",
  "status": "success",
  "data": {}
}

Example 10. JSON request for Server Info

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

Successful response for a ServerInfo request

{
  "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" : {}
            }
      }
    }
  }
}

Example 11. JSON request for RouteInfoRequest

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

Example 12. JSON request for ModuleInfo

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

Successful response for a ModuleInfo request

{
    "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":{}
	}
    }
}

Example 13. JSON request for GetLog

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

Successful response for a GetLog request.

{
    "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",
    }
}

Example 14. JSON request for GetFile

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

Successful response for a GetFile request.

{
  "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

Example 15. ACL block allowing read and write on files in a directory

This ACL is named "conf" and allows both GetFile and PutFile requests on the specified directory.

nxlog.conf

<ACL conf>
     Directory /var/run/nxlog/configs
     AllowRead TRUE
     AllowWrite TRUE
</ACL>

Example 16. Setting values for labels

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.

nxlog.conf

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>

Example 17. Configuration for multiple admin ports

This configuration specifies two additional administration ports on localhost.

nxlog.conf

<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:

ERROR PdhAddEnglishCounterA for '\Processor(_Total)\% Processor Time' failed with error 0x800007d0: Unable to connect to the specified computer or the computer is offline.;

Furthermore, an error may be logged when NXLog Agent is configured to collect events from Windows Event Log:

ERROR xm_admin error: FormatMessage() call failed: The storage control block address is invalid.

This happens when the user account does not have permission to access the specified Windows Event Log channels.