NXLog User Guide

108.1. Remote Management (xm_admin)

This module provides secure remote administration capabilities for the NXLog engine using either SOAP over HTTP/HTTPS (also known as web services) or JSON. Both the SOAP protocol and the JSON format are widespread and can be used from many different programming languages, consequently 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 can accept and initiate connections over TCP, SSL, and Unix domain sockets depending on its configuration. It is advisable to prefer this module over the xm_soapadmin module since this module is intended as a replacement and xm_soapadmin will eventually be phased out.

Note that though the module can both initiate and accept connections, the direction of the HTTP requests is always the same: requests are sent to the module and it returns HTTP responses.

108.1.1. Configuration

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

Connect: This directive instructs the module to connect to a remote socket. The argument must be an IP address when SocketType is set to TCP or SSL. Otherwise it must be a name of a socket for UDS. Connect cannot be used together with the Listen directive. Multiple xm_soapadmin instances may be configured if multiple administration ports are required.

Listen: This directive instructs the module to accept connections. The argument must be an IP address when SocketType is TCP or SSL. Otherwise it must be the name of a socket for UDS. Listen cannot be used together with the Connect directive. Multiple xm_admin instances may be configured if multiple administration ports are required. If neither Listen nor Connect are specified, the module will listen with SocketType TCP on 127.0.0.1.

Port: This specifies the port number used with the 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 directory.

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.

Example 481. ACL Block Allowing Read and Write on Files in the 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>

AllowIP

This optional directive can be used to specify an IP address or a network that is allowed to connect. The directive can be specified more than once to add different IPs or networks to the whitelist. The following formats can 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 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’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.

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.

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.

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 must present a certificate. If set to TRUE and there is no certificate 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

UDS: Unix domain socket

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.

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

108.1.2. Exported SOAP Methods and JSON Objects

The xm_admin module exports the following SOAP methods (web services) which can be called remotely. There is a WSDL file which can be used by different developer tools to easily hook into the exported WS API to reduce development time.

GetFile: Download a file from the NXLog agent. This will only work if the specified ACL exists.

GetLog: Download the log file from the NXLog agent.

ModuleInfo: Request information about a module instance.

ModuleRestart: Restart a module instance.

ModuleStart: Start a module instance.

ModuleStop: Stop a module instance.

PutFile: Upload a file to the NXLog agent. This will only work if the specified ACL exists. A file can be a configuration file, certificate or certificate key, pattern database, correlation rule file, etc. Using this method enables NXLog to be reconfigured from a remote host.

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

ServerRestart: Restart 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 make it come back online remotely. Extension modules are not stopped for the same reason.

The same SOAP methods where used to create an equivalent JSON Schema, so JSON Objects can be used instead of SOAP methods. This is illustrated better in the following examples.

108.1.3. Request - Response Examples

This is a typical SOAP ServerInfo request and its response.

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

<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <adm:serverInfoReply xmlns:adm='http://log4ensics.com/2010/AdminInterface'>
      <started>1508401312424622</started>
      <load>0.2000</load>
      <pid>15519</pid>
      <mem>12709888</mem>
      <version>3.99.2802</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>
    </adm:serverInfoReply>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The equivalent request and response using JSON.

{
  "msg": {
    "command": "serverInfo"
  }
}

{
  "response": "serverInfoReply",
  "status": "success",
  "data": {
    "server-info": {
      "started": 1508401312424622,
      "load": 0.05999999865889549,
      "pid": 15519,
      "mem": 12742656,
      "os": "Linux",
      "version": "3.99.2802",
      "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": {}
    }
  }
}

An example of a SOAP PutFile request and its response.

<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>tmp</filetype>
      <filename>test.tmp</filename>
      <file>File Content
A newline
      </file>
    </adm:putFile>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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

The equivalent request and response using JSON.

{
  "msg": {
    "command": "putFile",
    "params": {
      "filetype": "tmp",
      "filename": "test.tmp",
      "file": "File content\nA newline\n"
    }
  }
}

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

108.1.4. Examples

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