NXLog Agent connectivity

You can configure, manage, and monitor NXLog Agent instances remotely from NXLog Platform. An NXLog Agent instance must initiate the first connection to NXLog Platform. Once the two establish a relationship, they communicate over a secure connection using certificate-based authentication.

See how to Enroll an agent manually and Bulk-deploy NXLog Agent for instructions.

NXLog Agent configuration

NXLog Agent ships with a default configuration that includes settings for remote connectivity. Be careful when editing the configuration files, as an incorrect configuration will cause the agent instance to lose connectivity with NXLog Platform. You can see the default configuration for your NXLog Platform instance as shown in Enroll an agent manually.

The main NXLog Agent configuration file is nxlog.conf. This file contains default configuration settings, such as the location of certificates and logs, and includes additional configuration files.

Each NXLog Agent installation includes another configuration file containing agent management settings called managed.conf. This file is typically located in /opt/nxlog/etc/nxlog.d on Linux and C:\Program Files\nxlog\conf\nxlog.d on Windows platforms.

The following diagram depicts the relationship between nxlog.conf and managed.conf and shows the elements NXLog Platform requires to communicate with an agent.

Figure 1. Managed NXLog Agent configuration

Configuration requirements

NXLog Platform requires that the agent configuration include certain elements to manage agents. If any of these elements are missing, some functions may not work as expected, or connectivity with the agent may be lost. These elements include:

Directory paths
NXLog Platform agent manager address
Access Control Lists (ACL)
TLS/SSL certificates

Directory paths

The main agent configuration file (nxlog.conf) must define the following constants:

CONFDIR: Specifies the directory where the managed.conf configuration file is located.
CERTDIR: Specifies the directory where the authentication certificates are located. If this constant is not defined, connectivity with the agent will be affected, as mutual authentication will fail.
LOGDIR: Specifies the directory where the agent log file is located. If this constant is not defined or is not set to a valid directory, NXLog Agent will not start.

The default settings on Windows are as follows:

define INSTALLDIR  C:\Program Files\nxlog
define CONFDIR     %INSTALLDIR%\conf\nxlog.d
define CERTDIR     %INSTALLDIR%\cert
define LOGDIR      %INSTALLDIR%\data

As previously mentioned, nxlog.conf must include the configuration file managed.conf. For example, the following includes all .conf files in the defined configuration directory:

include       %CONFDIR%/*.conf

The default managed.conf file uses the certificates directory to set the certificate file settings as follows:

CAFile       %CERTDIR%\agent-ca.pem
CertFile     %CERTDIR%\agent-cert.pem
CertKeyFile  %CERTDIR%\agent-key.pem

NXLog Platform agent manager address

The default managed.conf file contains a HOST constant defining the address of the NXLog Platform agent manager.

define HOST 192.168.1.23:5541

The Remote Management module instance in the same configuration file uses the address to connect to NXLog Platform.

<Extension admin>
    Module       xm_admin
    Host         %HOST%
    ...
</Extension>

ACLs

The Remote Management module instance in managed.conf must also define the following ACLs:

conf: An ACL allowing read/write permissions to the directory where managed.conf resides. NXLog Platform requires this access to update the NXLog Agent configuration.
cert: An ACL allowing read/write permissions to the directory where the NXLog Agent TLS/SSL certificate and private key reside. NXLog Platform requires this access to deploy and renew the certificates.

The following example demonstrates the required ACLs:

<ACL conf>
   Directory    %CONFDIR%
   AllowRead    TRUE
   AllowWrite   TRUE
</ACL>

<ACL cert>
   Directory    %CERTDIR%
   AllowRead    TRUE
   AllowWrite   TRUE
</ACL>

TLS/SSL certificates

NXLog Platform communicates with agents over a secure TLS/SSL channel using mutual X.509 certificate-based authentication. This ensures that only authorized agents can connect to your NXLog Platform instance and vice versa.

NXLog Agent must have the following files:

CAFile: The NXLog Platform Certificate Authority (CA) certificate. NXLog Agent uses it to verify the identity of the NXLog Platform instance. It is typically named agent-ca.pem.
CertFile: The certificate NXLog Agent will present to NXLog Platform during the SSL handshake to prove its identity. It is typically named agent-cert.pem.
CertKeyFile: The private key file that was used to generate the agent certificate. It is typically named agent-key.pem.

The following example shows the default configuration:

CAFile       %CERTDIR%/agent-ca.pem
CertFile     %CERTDIR%/agent-cert.pem
CertKeyFile  %CERTDIR%/agent-key.pem