- Introduction
- Deployment
- Configuration
- OS Support
- Integration
- Troubleshooting
- Enterprise Edition Reference Manual
- 129. Man Pages
- 130. Configuration
- 131. Language
- 132. Extension Modules
- 132.1. Remote Management (xm_admin)
- 132.2. AIX Auditing (xm_aixaudit)
- 132.3. Apple System Logs (xm_asl)
- 132.4. Basic Security Module Auditing (xm_bsm)
- 132.5. Common Event Format (xm_cef)
- 132.6. Character Set Conversion (xm_charconv)
- 132.7. Delimiter-Separated Values (xm_csv)
- 132.8. Encryption (xm_crypto)
- 132.9. External Programs (xm_exec)
- 132.10. File Lists (xm_filelist)
- 132.11. File Operations (xm_fileop)
- 132.12. GELF (xm_gelf)
- 132.13. Go (xm_go)
- 132.14. Grok (xm_grok)
- 132.15. Java (xm_java)
- 132.16. JSON (xm_json)
- 132.17. Key-Value Pairs (xm_kvp)
- 132.18. LEEF (xm_leef)
- 132.19. Microsoft DNS Server (xm_msdns)
- 132.20. Multiline Parser (xm_multiline)
- 132.21. NetFlow (xm_netflow)
- 132.22. Microsoft Network Policy Server (xm_nps)
- 132.23. Pattern Matcher (xm_pattern)
- 132.24. Perl (xm_perl)
- 132.25. Python (xm_python)
- 132.26. Resolver (xm_resolver)
- 132.27. Rewrite (xm_rewrite)
- 132.28. Ruby (xm_ruby)
- 132.29. SNMP Traps (xm_snmp)
- 132.30. Remote Management (xm_soapadmin)
- 132.31. Syslog (xm_syslog)
- 132.32. W3C (xm_w3c)
- 132.33. WTMP (xm_wtmp)
- 132.34. XML (xm_xml)
- 132.35. Compression (xm_zlib)
- 133. Input Modules
- 134. Processor Modules
- 135. Output Modules
- NXLog Manager
- NXLog Add-Ons
132.1. 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.
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
orSSL
. 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.
Note
|
When the |
- 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
orSSL
. 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 SocketTypeTCP
on127.0.0.1
.
- ListenAddr
-
The module listens for connections on this IP address or DNS hostname. The default is
localhost
.
Note
|
When the For client applications that don’t support IPv6, to avoid the behavior
described above the Alternatively, the server-side system may be configured to prioritize IPv4
addresses for the hostname specified by the
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 isFALSE
: all connections must present a trusted certificate. This directive is only valid if SocketType is set toSSL
.
- 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 theinclude_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 isTRUE
: each connection must use a certificate. This directive is only valid if SocketType is set toSSL
.
- 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).NoteSome 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
, andTLSv1.3
. By default, theTLSv1.2
andTLSv1.3
protocols are allowed. Note that the OpenSSL library shipped by Linux distributions may not supportSSLv2
andSSLv3
, 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 namedconf
which allows reading and writing to its configuration directory, and the other namedcert
which allows reading and writing to its certificates directory. The NXLog Manager uses theconf
andcert
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
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>
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.
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>
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>
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
2020-12-02 15:54:03 INFO [xm_admin|tcp_listen] connection accepted from 10.0.0.100:51705
2020-12-02 15:54:03 INFO [xm_admin|tcp_listen] getLog called
</logfile>
</adm:getLogReply>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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": {}
}
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": {}
}
}
}
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
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.
This configuration specifies two additional administration ports on localhost.
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>