NXLog Docs

Agent-Manager Connectivity

NXLog agent instances can be managed, monitored, and configured remotely over a secure channel. The management component in NXLog Manager is called the agent manager. There are two operation modes:

The NXLog agent initiates the connection and connects to the agent manager.
The agent manager initiates the connection and connects to the NXLog agent.

Each agent instance is provided with a special configuration file coming from the agent manager. The file name is managed.conf and it is located under the path /opt/nxlog/etc/nxlog.d on Linux and C:\Program Files\nxlog\conf\nxlog.d on Windows platforms.

Any agents created prior to the deployment of NXLog Manager will initially use the first mode of operation listed above. In this mode, managed.conf is essential to agent-manager connectivity since it contains the two constants needed for the agent to connect to its agent manager:

define NXLOG_MANAGER_ADDRESS X.X.X.X
define NXLOG_MANAGER_PORT 4041

These values are needed for the following assignments in the Remote Management (xm_admin) agent_management instance also defined in managed.conf:

<Extension agent_management>
    Module          xm_admin
    Connect         %NXLOG_MANAGER_ADDRESS%
    Port            %NXLOG_MANAGER_PORT%
</Extension>

In the second mode of operation listed above, managed.conf contains a BASE64-encoded blob in the header that stores the configuration of the agent. The agent manager can restore the configuration of the agent in case the agent configuration can no longer be retrieved from the NXLog Manager database. It is important that these 23 lines containing the BASE64-encoded blob should not be modified manually or deleted. If the agent manager cannot read the blob, an error message is generated:

Failed to unmarshal agent configuration

This message is logged in /opt/nxlog-manager/log/nxlog-manager.err.

Agent configuration requirements

To be able to configure and manage agents, NXLog Manager requires the agent configuration to contain certain elements. If any of these are missing, some functions may not work as expected, or connectivity with the agent may be lost completely.

An NXLog agent installation ships with default configuration files that include these elements. Care should be taken when editing the agent configuration to ensure that NXLog Manager can manage the instance.

The following is a list of constants that must be defined in the main agent configuration file (nxlog.conf):

CONFDIR: Specifies the path to the directory where the agent configuration file managed.conf is located.
CERTDIR: Specifies the path to the directory where the agent and agent manager certificates will be copied to. If this constant is not defined, connectivity with the agent will be affected.
LOGDIR: Specifies the path to the directory where the NXLog agent log file is located. If this constant is not defined, or is not set to a valid directory, the NXLog agent will not start.

Example:

define INSTALLDIR /opt/nxlog
define CONFDIR    %INSTALLDIR%/etc/nxlog.d
define CERTDIR    %INSTALLDIR%/var/lib/nxlog/cert
define LOGDIR     %INSTALLDIR%/var/log/nxlog

Additionally, nxlog.conf must also include the configuration file managed.conf. For example, the following includes all .conf files found in the defined configuration directory:

include %CONFDIR%/*.conf

The xm_admin instance in managed.conf must also define the following two ACLs:

An ACL named conf, which allows reading and writing to the directory where managed.conf is located. NXLog Manager requires this to be able to retrieve and push updates to the agent configuration.
An ACL named cert, which allows reading and writing to the directory where the agent and agent manager certificates are located. NXLog Manager requires this to be able to deploy and update the certificates.

The following diagram depicts the relationship between nxlog.conf and managed.conf, and shows the elements NXLog Manager needs in order to successfully communicate with an agent.

Agent configuration requirements

Mutual Authentication

Mutual X.509 certificate-based authentication is used over a trusted, secure TLS/SSL channel in order to guarantee that only an authorized NXLog agent can connect to the agent manager. The agent manager queries the status information of each NXLog agent every 60 seconds.

NXLog Manager and NXLog both have the ability to authenticate the other party. They use certificate-based authentication for this purpose. The agent is usually deployed with the following key/certificate files:

agent-ca.pem
agent-key.pem
agent-cert.pem

The file agent-ca.pem contains the issuing CA’s certificate. This can be used to authenticate the NXLog Manager communicating with the agent. The agent has settings controlling the authentication behavior (RequireCert, AllowUntrusted).

Similarly NXLog Manager uses the client certificate presented by NXLog to authenticate the agent. In addition to the SNA procedure outlined above it performs a certificate base authentication (client cert must be from a known CA, and must be valid).

If the agent has no certificate and key assigned through manager, the agent’s status will be UNTRUSTED. This is regardless of how SNA is set to operate.