Remote Management (xm_admin)
This module provides secure remote administration capabilities for NXLog Agent installations via JSON or SOAP over HTTP(S), making it easy to implement administrative scripts or create plugins for system monitoring tools such as Nagios, Munin, or Zabbix. With this module, NXLog Agent can accept or initiate connections over TCP, SSL, and Unix domain sockets.
Although the module can both initiate and accept connections, the direction of HTTP(S) requests is always the same: the module receives requests and returns an HTTP(S) response.
NXLog Platform uses this module to manage agents and requires that agent configurations contain certain elements. For more information, see NXLog Agent connectivity in the NXLog Platform User Guide.
| To examine the supported platforms, see the list of installation packages. |
Configuration
The xm_admin module accepts the following directives in addition to the common module directives.
Required directives
One of the following directives is required for the module to start.
The xm_admin module either initiates a connection (using Host) or listens for connections (using ListenAddr), but not both simultaneously.
The module connects to this IP address or hostname. If using a hostname, the module resolves the hostname to an IP address on each new connection. You can define the port number by appending it to the IP address or hostname using a colon as a separator ( IPv6 addresses must be enclosed in square brackets ( |
|
The module listens for connections on this IP address or DNS hostname.
The default is You can define the port number by appending it to the IP address or hostname using a colon as a separator ( |
TLS/SSL directives
The following directives configure secure data transfer via TLS/SSL.
Specifies if the connection should be allowed with an expired certificate.
If set to |
||||||||||||||||
Specifies if the certificate FQDN should be validated against the server hostname or not.
If set to |
||||||||||||||||
Specifies if the connection should be allowed regardless of the certificate verification results.
If set to |
||||||||||||||||
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: For example, if the certificate hash is 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. |
||||||||||||||||
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 the case of certificates signed by an intermediate CA, the certificate specified must contain the complete certificate chain (certificate bundle). |
||||||||||||||||
You can use this directive on Windows to specify a PCRE2-compliant regular expression for locating a suitable Certificate Authority (CA) certificate from the Windows Certificate Store. The pattern must be in the format The above configuration will result in the following logging in the NXLog Agent log file: If the pattern matches multiple certificates, NXLog Agent will use the first one. If the certificate changes, you must restart NXLog Agent for it to start using the new certificate. This directive is mutually exclusive with the CAThumbprint, CADir, and CAFile directives. |
||||||||||||||||
This optional directive, supported only on Windows, specifies the thumbprint of the certificate authority (CA) certificate that will be used to verify the certificate presented by the remote host. The hexadecimal fingerprint string can be copied from Windows Certificate Manager (certmgr.msc). Whitespaces are automatically removed. The certificate must be added to a Windows certificate store that is accessible by NXLog Agent. This directive is mutually exclusive with the CADir, CAFile and CAPattern directives. |
||||||||||||||||
Path of the certificate file that will be presented to the remote host during the SSL handshake. |
||||||||||||||||
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 optional directive, supported only on Windows, defines a pattern for identifying a corresponding certificate and its thumbprint within the native Windows Certificate Storage.
The pattern must follow PCRE2 rules and use the format
Configuration examples: or A normal log output example would look like as follows: |
||||||||||||||||
This optional directive, supported only on Windows, specifies the thumbprint of the certificate that will be presented to the remote server during the HTTPS 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 When the global directive UseCNGCertificates is set to
On the contrary, when the global directive UseCNGCertificates is set to The usage of the directive is the same in all cases: This directive is only supported on Windows and is mutually exclusive with the CertFile and CertKeyFile directives. |
||||||||||||||||
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: For example if the hash is |
||||||||||||||||
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: |
||||||||||||||||
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. |
||||||||||||||||
Passphrase of the private key specified by the CertKeyFile directive. A passphrase is required when the private key is encrypted. The following example generates a private key with Triple DES encryption using OpenSSL: This directive is not required for passwordless private keys. |
||||||||||||||||
If set to This directive is only supported on Windows. |
||||||||||||||||
Specifies if the remote host must present a certificate.
If set to |
||||||||||||||||
This optional directive, supported only on Windows, if set to |
||||||||||||||||
The signature algorithm parameter that is being sent to the Windows SSL library. Allowed values depend on the available encryption providers. This directive is only supported on Windows. |
||||||||||||||||
This optional directive specifies the hostname used for Server Name Indication (SNI). |
||||||||||||||||
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
|
||||||||||||||||
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:
|
||||||||||||||||
Specifies if data compression is enabled when sending data over the network.
The compression mechanism is based on the zlib compression library.
The default value is
|
||||||||||||||||
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: |
||||||||||||||||
This optional directive enables the logging of the TLS protocol version and cipher suite upon a successful SSL/TLS handshake.
Setting this directive to |
||||||||||||||||
Use this directive to log the remote host’s certificate details when a TLS/SSL handshake fails, to help with debugging.
Setting this directive to This directive depends on the values of the AllowUntrusted and RequireCert directives:
|
||||||||||||||||
If set to TRUE, the module uses the Windows Cryptography API: Next Generation (CNG) to access the private keys associated with certificates identified by a thumbprint. This directive is only supported on Windows. |
Optional directives
This block directive makes a directory accessible via the GetFile and PutFile requests. These requests use the ACL name along with the filename. You can specify this directive multiple times for different directories.
|
|||
This optional directive can be used to allow IP addresses and/or networks to connect. The directive can be set multiple times to add different IPs or networks to allow. This directive is only active when the ListenAddr directive is present. In the absence of this directive, the BlockIP directive is considered. If both AllowIP and BlockIP are absent, then hosts are not restricted from connecting to a listening module. The following formats may be used for the AllowIP directive:
|
|||
This optional directive can be used to deny IP addresses and/or networks to connect. The directive can be set multiple times to add different IPs or networks to deny. This directive is only active when the ListenAddr directive is present. In the absence of this directive, the AllowIP directive is considered. If both AllowIP and BlockIP are absent, then hosts are not restricted from connecting to a listening module. The following formats may be used for the BlockIP directive:
|
|||
With this optional directive it is possible to set the maximum number of allowed concurrent/active connections for a listening TCP socket.
If not specified, the default value is 2024-03-01 22:29:16 ERROR [im_tcp|in_tcp] Number of allowed active connections(10) reached: 10. Refusing connection from 127.0.0.1 |
|||
This optional directive defines the maximum time in seconds before NXLog Agent closes TCP connections without traffic. The minimum timeout value is 15 seconds. If this directive is not specified, NXLog Agent does not close idle TCP connections. |
|||
This optional boolean directive specifies whether the module instance should exclusively bind to the specified port.
The default value is
|
|||
This optional boolean directive determines whether the module instance should forcibly bind to a port already in use.
The default value is |
|||
This optional boolean directive specifies whether multiple xm_admin module instances can listen on the same port.
When you enable this directive, multiple instances run in a separate thread, allowing NXLog Agent to process incoming logs simultaneously.
See the examples below.
The default value is
|
|||
This directive sets the number of seconds that the module waits for an incoming request.
If a valid request does not arrive before the timer expires, the module resets the connection.
It accepts values between |
|||
Block directive to define custom key-value pairs to add metadata to an agent, such as the FQDN, geo-location, department, admin contact information, and so on. The module returns labels as part of the response to a ServerInfo API request. You can set label values statically by specifying a string, a constant, or an environment variable. You can also set values by calling functions or using the include_stdout directive to execute a script. Label values are resolved only once during agent startup. Event fields and module variables result in an Undef value since these are not available when processing labels during agent startup. Labels should adhere to the POSIX.1-2017 standard for environment variables. Label names can only contain underscores and alphanumeric characters. The first character of a label name cannot be a digit. Symbols in label values should belong to the portable character set. See Setting agent labels below for an example. |
|||
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 double with every attempt. In the latter case, when the system decides that the reconnection is successful, the reconnect interval is immediately reset to 1 sec.
|
|||
This optional directive defines the behavior when the connection with the remote host is lost.
When set to NOTE: The Reconnect directive only works when used in conjunction with the Host directive. |
|||
This directive specifies how much time, in seconds, the module should wait to acquire a connection before it reverts the managed configuration file to the previous version.
It accepts values between See PutFile for more information on configuration reversion. |
|||
This directive sets the connection type. It can be one of the following:
|
Remote Management API
The way you request information from the API depends on whether you’re using JSON or SOAP.
-
JSON
-
SOAP
When using JSON, the HTTP POST request must include the Content-Type HTTP header with the value set to 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: nnnInclude the request details in a JSON object with the key name msg.
This object should contain the following key/values:
-
command - A string value specifying the name of the method you’re requesting. This value is required.
-
params - A JSON object containing the required parameters. May be omitted for methods that do not require additional parameters.
You must send the JSON object in the body of the POST request as raw data. The following is a JSON request for ServerInfo.
{
"msg": {
"command": "serverInfo",
"params": {
"with-extensioninfo": true,
"with-routeinfo": false
}
}
}Below is an example response header to the above request.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: nnnnWhen using SOAP, the HTTP POST request must include the Content-Type HTTP header with the value set to 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: nnnAdd the request details to the Body element.
You must send the XML data 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">
<with-extensioninfo>true</with-extensioninfo>
<with-routeinfo>false</with-routeinfo>
</adm:serverInfo>
</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: nnnnAPI endpoints
The following table lists the available xm_admin API endpoints. Click on each endpoint for details.
| Endpoint | Description |
|---|---|
Download a file from the NXLog Agent host. |
|
Download the NXLog Agent log file. |
|
Retrieve the unique identifier (UID) of the NXLog Agent installation. |
|
Request information about a module instance. |
|
Restart a module instance. |
|
Start a module instance. |
|
Stop a module instance. |
|
Upload a file to the NXLog Agent host. |
|
Request information about a route. |
|
Restart a route. |
|
Start a route. |
|
Stop a route. |
|
Request information about NXLog Agent and its host. |
|
Restart all module instances. |
|
Start all module instances. |
|
Stops all input, processor, and output module instances. |
|
Set the NXLog Agent’s unique identifier (UID) and signature. |
Examples
The following is a basic configuration that listens for connections on all available network interfaces on port 8080. This configuration is more suitable for testing and troubleshooting.
%CERTDIR% and %CONFDIR% are constants defined in the default NXLog Agent configuration.
<Extension admin>
Module xm_admin
ListenAddr 0.0.0.0:8080
SocketType TCP
<ACL conf>
Directory %CONFDIR%
AllowRead TRUE
AllowWrite TRUE
</ACL>
<ACL cert>
Directory %CERTDIR%
AllowRead TRUE
AllowWrite TRUE
</ACL>
</Extension>This configuration uses TLS/SSL certificates for secure communication with the remote host.
%CERTDIR% and %CONFDIR% are constants defined in the default NXLog Agent configuration.
<Extension admin>
Module xm_admin
Host agents.nxlog.example.com:5515
SocketType SSL
CAFile %CERTDIR%/agent-ca.pem (1)
CertFile %CERTDIR%/agent-cert.pem (2)
CertKeyFile %CERTDIR%/agent-key.pem (3)
<ACL conf>
Directory %CONFDIR%
AllowRead TRUE
AllowWrite TRUE
</ACL>
<ACL cert>
Directory %CERTDIR%
AllowRead TRUE
AllowWrite TRUE
</ACL>
<ACL logs> (4)
Directory /tmp/logs
AllowRead TRUE
AllowWrite TRUE
</ACL>
</Extension>| 1 | The CAFile directive specifies the path of the Certificate Authority (CA) certificate. |
| 2 | The CertFile directive specifies the path of the local server’s certificate. |
| 3 | The CertKeyFile directive specifies the path of the server’s certificate private key. |
| 4 | A custom ACL named logs that allows GetFile and PutFile requests for the specified directory. |
This configuration sets three static labels:
When using define or envvar, the values must be enclosed in quotes as shown below.
It also sets labels using two other methods:
-
The include_stdout general directive to set labels via a script.
-
The hostname_fqdn() function to set the host_fqdn label. This is a good practice if you need to view the host’s FQDN in NXLog Platform, since xm_admin only sends the short hostname by default.
include_stdout executes scripts during agent startup with elevated privileges.
Use this feature cautiously, as it poses a security risk if the script is modified maliciously.
|
define BASE /opt/nxlog
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_fqdn hostname_fqdn()
</labels>
</Extension>|
On Microsoft Windows, if the NXLog Agent service is running with a custom user account and NXLog Agent is managed from NXLog Platform, 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: Furthermore, an error may be logged when NXLog Agent is configured to collect events from Windows Event Log: This happens when the user account does not have permission to access the specified Windows Event Log channels. Refer to Access denied to a Windows Event Log channel in the Troubleshooting section for instructions on how to resolve this error. |