Return to
Portfolio

108.27. Remote Management (xm_soapadmin)

This module provides secure remote administration capabilities to the NXLog engine using SOAP over HTTP/HTTPS (also known as web services). SOAP is a widespread protocol 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_soapadmin module, NXLog can accept and initiate connections over TCP, SSL, and Unix domain sockets depending on its configuration. This module is superseded by xm_admin and will eventually be phased out. The xm_admin can be used as a direct replacement of this module for all intents and purposes.

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

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 (the compression is disabled).

Note
 Some Linux packages (for example, Debian) use the OpenSSL library provided by the OS 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.
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 525. 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 [Download file]

  
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.

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.27.2. Exported SOAP Methods

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

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.

108.27.3. Examples

Example 526. Configuration for Multiple Admin Ports

This configuration specifies two additional administration ports on localhost.

nxlog.conf [Download file]

  
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_soapadmin
    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_soapadmin
    Listen          localhost
    Port            8080
</Extension>

<Extension tcp_connect>
    Module          xm_soapadmin
    Connect         localhost
    Port            4040
</Extension>

← Previous: SNMP Traps (xm_snmp) | ↑ Up: Extension Modules | ⌂ Home: NXLog User Guide | Next: xm_stdinpw →