NXLog Legacy Documentation

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, an 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 installer packages in the Available Modules chapter.

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 Manager uses this module to manage agents and requires the agent configuration to contain certain elements. For more information, see Agent configuration requirements in the NXLog Manager User Guide.

Configuration

The xm_admin module accepts the following directives in addition to the common module directives.

Connect: 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 TCP or SSL. Connect cannot be used together with any of the Host, ListenAddr or Listen directives. Multiple xm_admin instances may be configured if multiple administration ports are required.

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 at the end of the hostname or IP address using a colon as a separator (host:port). Port numbers defined here take precedence over any port number defined with the Port directive. If there is no Port directive, the default port is 8080.

When the Host directive is used with a hostname instead of an IP address, the 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 connection can be reestablished.

Listen: 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 TCP or SSL. Listen cannot be used together with any of the Host, ListenAddr or Connect directives. Multiple xm_admin instances may be configured if multiple administration ports are required. If neither Listen nor Host, ListenAddr, Connect are specified, the module will listen with SocketType TCP on 127.0.0.1.

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 at the end of the IP address using a colon as a separator (host:port). Port numbers defined here take precedence over any port number defined with the Port directive. If there is no Port directive, the default port is 8080.

When the ListenAddr (or similar) directive specifies a hostname, the module binds to the first IP address that is exposed by the system for that hostname. On most systems that support IPv6, this address will be an IPv6 address. This means that client applications and the systems they run on will also need to have IPv6 support enabled, and must be able to connect to the same IPv6 address. NXLog output modules achieve this requirement through failover. For third-party client applications, the configuration details are application-specific but they should have the ability to detect which IP address the server is listening on when using a hostname to connect.

For client applications that don’t support IPv6, to avoid the behavior described above the ListenAddr directive of the listening module may be set to an IPv4 address e.g. 0.0.0.0.

Alternatively, the server-side system may be configured to prioritize IPv4 addresses for the hostname specified by the ListenAddr directive, although this is a more complicated and potentially intrusive approach. On most Linux-based systems, this can be achieved through the /etc/gai.conf configuration file. On BSD-based systems, the ip6addrctl command can be used. Windows is more limited and can only be configured to prioritize IPv4 over IPv6 addresses for ALL hostnames resolved on the system, by setting the following registry value to 0x20:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters\DisabledComponents

For more information see the Microsoft documentation on Configuring IPv6 in Windows for advanced users.

This limitation will be addressed in a future release by making listening modules bind to all available IPv4/IPv6 addresses that a hostname resolves to.

Port: 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 8080.

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 may be used to specify a whitelist of IP addresses and/or networks that are allowed to connect. The directive can be specified more than once to add different IPs or networks to the whitelist. This directive is only active when the Listen or ListenAddr directives are present. In the absence of this directive, there is no restriction on the hosts which may connect to a listening module. The following formats may be used:

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)

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.

Unix-like operating systems use the /etc/ssl/certs path as their default for certificates. Windows uses the Windows Certificate Store as a default path for certificates.

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.

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. This directive is only supported on Windows and is mutually exclusive with the CADir and CAFile directives.

SearchAllCertStores: This optional boolean directive, when set to TRUE, enables the loading of all available Windows certificates into NXLog, for use during remote certificate verification. Any required certificates must be added to a Windows certificate store that NXLog can access. This directive is mutually exclusive with the CAThumbprint, CADir and CAFile 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.

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

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.

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 to use unusually high system resources or cause NXLog to become unresponsive.

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

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.

ReversionTimeout: This directive specifies how much time xm_admin should wait to acquire a connection, before it reverts the managed configuration file to the previous version. The default is 5 minutes. See PutFile for more information on configuration reversion.

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 timeoout detection.

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.

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 the NXLog agent. This requires an ACL to be specified in the NXLog agent configuration. GetFile requires the following parameters:

filetype: A value corresponding to the given-name of a defined ACL.
filename: The name of the file being requested.

GetLog

Download the log file from the NXLog agent. GetLog accepts the following parameters:

size: Defines the amount of data to get in bytes. The maximum size that can be specified is 1048576 bytes (1MB). If the log file is larger than the set size, the last n bytes are returned. When this parameter is not specified, the entire log file is returned if it’s smaller than 1MB.

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 the NXLog agent, such as a configuration file, certificate or certificate key, pattern database, correlation rule file, etc. Using this method NXLog 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. The NXLog Manager 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 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:

filetype

A value corresponding to the given-name of a defined ACL.

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.

ServerStart: Start all modules of the server, the opposite of ServerStop.

ServerStop: Stop all modules of the server. Note that the NXLog process will not exit, otherwise it would be impossible to start it again remotely. Extension modules are not stopped for the same reason.

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'>
      <started>1607103334282303</started>
      <load>0.2000</load>
      <pid>15519</pid>
      <mem>12709888</mem>
      <version>5.1.6133</version>
      <os>Linux</os>
      <systeminfo>OS: Linux, Hostname: voyager, Release: 4.4.0-96-generic, Version: #119-Ubuntu SMP Tue Sep 12 14:59:54 UTC 2017, Arch: x86_64, 4 CPU(s), 15.7Gb memory</systeminfo>
      <hostname>voyager</hostname>
      <servertime>1508405764586118</servertime>
      <modules></modules>
      <labels></labels>
    </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 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": {
      "started": 1607103334282303,
      "load": 0.05999999865889549,
      "pid": 15519,
      "mem": 12742656,
      "os": "Linux",
      "version": "5.1.6133",
      "systeminfo": "OS: Linux, Hostname: voyager, Release: 4.4.0-96-generic, Version: #119-Ubuntu SMP Tue Sep 12 14:59:54 UTC 2017, Arch: x86_64, 4 CPU(s), 15.7Gb memory",
      "hostname": "voyager",
      "servertime": 1508406647673758,
      "modules": {},
      "labels": {}
    }
  }
}

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'>
      <started>1607103334282303</started>
      <load>0.2000</load>
      <pid>15519</pid>
      <mem>12709888</mem>
      <version>5.1.6133</version>
      <os>Linux</os>
      <systeminfo>OS: Linux, Hostname: voyager, Release: 4.4.0-96-generic, Version: #119-Ubuntu SMP Tue Sep 12 14:59:54 UTC 2017, Arch: x86_64, 4 CPU(s), 15.7Gb memory</systeminfo>
      <hostname>voyager</hostname>
      <servertime>1508405764586118</servertime>
      <modules></modules>
      <labels></labels>
    </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>
              <queuesize>0</queuesize>
              <queuelimit>0</queuelimit>
              <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>
              <batchsize>0</batchsize>
              <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>120</evt-recvd>
            <evt-drop>0</evt-drop>
            <evt-fwd>120</evt-fwd>
            <queuesize>0</queuesize>
            <queuelimit>100</queuelimit>
            <batchsize>0</batchsize>
            <status>3</status>
            <module-type>3</module-type>
            <module>om_file</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 RouteInfoRequest request

{
  "response": "serverInfoReply",
  "status": "success",
  "data": {
    "server-info": {
      "started": 1607103334282303,
      "load": 0.05999999865889549,
      "pid": 15519,
      "mem": 12742656,
      "os": "Linux",
      "version": "5.1.6133",
      "systeminfo": "OS: Linux, Hostname: voyager, Release: 4.4.0-96-generic, Version: #119-Ubuntu SMP Tue Sep 12 14:59:54 UTC 2017, Arch: x86_64, 4 CPU(s), 15.7Gb memory",
      "hostname": "voyager",
      "servertime": 1508406647673758,
      "modules": {},
      "labels": {}
    }
  }
}

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,
          "queuesize": 0,
          "queuelimit": 0,
          "batchsize": 50,
          "status": 3,
          "module-type": 1,
          "module": "im_tcp",
          "variables": {}
        },
        "output_file": {
          "module-name": "output_file",
          "evt-recvd": 10,
          "evt-drop": 0,
          "evt-fwd": 10,
          "queuesize": 0,
          "queuelimit": 100,
          "batchsize": 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": {
        "outfile": {
            "module_name": "output_file",
            "evt-recvd": 120,
            "evt-drop": 0,
            "evt-fwd": 120,
            "queuesize": 0,
            "queuelimit": 100,
            "batchsize": 0,
            "status": 3,
            "module-type": 3,
            "module": "om_file",
            "variables": {}
        }
    }
}

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 service is running with a custom user account and NXLog is managed by NXLog Manager, 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 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. Refer to the documentation on Windows Event Log permission errors for instructions on how to resolve this error.