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. 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, NXLog Agent can accept or initiate connections over TCP, SSL, and Unix domain sockets depending on its Configuration.
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, which returns an HTTP(S) response.
NXLog Platform uses this module to manage agents and requires the agent configuration to 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 two 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.
Host is the preferred directive, while ListenAddr is mostly useful for manual debugging.
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 to the hostname or IP address using a colon as a separator (
|
|||
The module listens for connections on this IP address or DNS hostname.
The default is The port number can be defined by appending it to the IP address 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 |
|||
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 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
|
|||
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 xm_admin waits for an incoming request from the agent management system.
If no valid request arrives before the timer expires xm_admin will reset the management connection. The timer resets on every incoming request
Defaults to |
|||
Lets you 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 xm_admin 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 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. If the duration of the successful connection is greater than the current reconnect interval, then the reconnect interval will be 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 in seconds how much time xm_admin should wait to acquire a connection before it reverts the managed configuration file to the previous version.
Defaults to |
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
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_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_fqdn hostname_fqdn()
</labels>
</Extension>This configuration specifies two additional administration ports on localhost.
<Extension ssl_connect>
Module xm_admin
Host 192.168.1.1: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
ListenAddr localhost:8080
</Extension>
<Extension tcp_connect>
Module xm_admin
Host localhost:4040
</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. |