132.1. Remote Management (xm_admin)

Table of Contents

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.

Note	To examine the supported platforms, see the list of installer packages in the Available Modules chapter.

Note that 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 and it returns an HTTP(S) response.

132.1.1. Configuration

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

Connect: This directive has been deprecated (in favour 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.

Note

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, only the first IP address will be used. If a single output instance is configured with multiple Host directives, these hosts are accessed in failover mode. If a Host directive is configured with a hostname, it will send to that host as long a usable connection can be established with the IP address it resolves to. Should that connection fail, it will then resolve the IP address of the next hostname in the list and attempt to establish a connection with it. Each time a failure occurs, the next Host directive in the list is tried.

Listen: This directive has been deprecated (in favour 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.

Note

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 (infavour 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)

AllowUntrusted: This boolean directive specifies that the remote connection should be allowed without certificate verification. If set to TRUE the remote host will be able to connect with unknown and self-signed certificates. 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 specifies the path to a directory containing certificate authority (CA) certificates, which will be used to check the certificate of the remote socket. The certificate filenames in this directory must be in the OpenSSL hashed format. This directive is only valid if SocketType is set to SSL. A remote host’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.

CAFile: This specifies the path of the certificate authority (CA) certificate, which will be used to check the certificate of the remote socket. This directive is only valid if SocketType is set to SSL. To trust a self-signed certificate presented by the remote (which is not signed by a CA), provide that certificate instead.

CAThumbprint: This optional directive specifies the certificate thumbprint of the certificate authority (CA), which is used to look up the CA certificate from the Windows certificate store. The hexadecimal fingerprint string can be copied straight from Windows Certificate Manager (certmgr.msc), whitespaces are automatically removed. This directive is mutually exclusive with the CADir and CAFile directives.

CertFile: This specifies the path of the certificate file to be used for SSL connections. This directive is only valid if SocketType is set to SSL.

CertKeyFile: This specifies the path of the certificate key file to be used for SSL connections. This directive is only valid if SocketType is set to SSL.

CertThumbprint: This optional directive specifies the certificate thumbprint to be used for the SSL handshake. The hexadecimal fingerprint string can be copied straight from Windows Certificate Manager (certmgr.msc), whitespaces are automatically removed. This directive is only supported on Windows and is mutually exclusive with the CertFile and CertKeyFile.

CRLDir: This specifies the path to a directory containing certificate revocation lists (CRLs), which will be consulted when checking the certificate of the remote socket. The certificate filenames in this directory must be in the OpenSSL hashed format. 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 consulted when checking the certificate of the remote socket. This directive is only valid if SocketType is set to SSL.

KeyPass: With this directive, a password can be supplied for the certificate key file defined in CertKeyFile. This directive is only valid if SocketType is set to SSL. This directive is not needed for password-less private keys.

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 directive has been deprecated as of version 2.4. The module will try to reconnect automatically at increasing intervals on all errors.

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.

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 SSL cipher list, overriding the default. Use the format described in the ciphers(1ssl) man page.

SSLCiphersuites: This optional directive can be used to define the permitted SSL cipher list in case the SSLProtocol directive is set to TLSv1.3. Use the same format as in the SSLCipher directive.

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

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

132.1.2. 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: The amount of data to get in bytes. If the log file is bigger than the specified size, the last n bytes are returned. When this parameter is not specified the entire log file is returned.

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

ServerInfo: Request information about the server. This will also return info about all module instances.

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.

132.1.3. Request - response format

Example 629. 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 630. 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.

132.1.4. 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 631. 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>
    </adm:putFile>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Below is a successful response for 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 632. SOAP request for ModuleInfo

The following is an example of a ModuleInfo request using SOAP. The request is being made for 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>

The below example shows a successful response for 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 633. SOAP request for GetLog

The following is an example of a GetLog request using SOAP. The request specifies that the last 240 bytes of the log file should be returned.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <adm:getLog xmlns:adm="http://log4ensics.com/2010/AdminInterface">
        <size>200</size>
    </adm:getLog>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The below example shows a 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 634. 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"
    }
  }
}

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

Below is a successful response for a PutFile request.

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

Example 635. 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"
    }
  }
}

The below example shows a 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 636. 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
    }
  }
}

The below example shows a 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"
    }
}

132.1.5. Configuration examples

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


  1
2
3
4
5

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

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


  1
2
3
4
5
6
7
8
9
10
11
12
13
14

  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 639. Configuration for multiple admin ports

This configuration specifies two additional administration ports on localhost.

nxlog.conf


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

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

You are here

132.1. Remote Management (xm_admin) | Log Collection Solutions