NXLog Docs

Agent Names and Addresses

NXLog Manager has multiple options for naming agents:

  1. Use reverse DNS name, else IP address

  2. Use reverse DNS name, else certificate subject name

  3. Use certificate subject name

  4. Use agent’s host name

This information is used to name an agent when it is initially connected.

The IP address of the agent is retrieved from the socket that connects the agent to the manager. In case of plain TCP (L4) load balancers it is not possible to distinguish the agent from the load balancer, therefore many agents will apparently share the same IP address. This has consequences for Subject Name Authorization — see below.

In the most common deployment scenario, where agents connect to NXLog Manager, the following sequence takes place:

  1. The agent installs with a minimal configuration package: nxlog.conf, managed.conf, and a CA certificate, although no agent certificate or agent key is deployed.

  2. The agent opens an initial connection to NXLog Manager.

  3. NXLog Manager creates the agent object, adds a name using the sequence above, and starts monitoring the agent.

  4. The agent appears on the manager UI in an untrusted state, since it has yet to be issued a certificate and a key.

This has a potential side-effect. If the name used in NXLog Manager is impossible to associate with the agent reporting in at a later stage, a new object may be created.

One specific example is using Option 1 (Use reverse DNS name, else IP address). If DNS resolution is impossible, NXLog Manager will create a new agent object using the IP address.

In the case of Option 2 (Use reverse DNS name, else certificate subject name), the certificate subject (which defaults to the subject name) will likely match the existing agent name, so the agent can be associated with the object despite the missing RDNS result.

When Option 3 (Use certificate subject name) is used, the agent will be named using the certificate subject name no matter what.

With Option 4 (Use agent’s host name), the host name does not depend on name resolution, so if RDNS is unavailable, the agent’s name is not affected.

Subject Name Authorization

A returning agent may also be subject to Subject Name Authorization (SNA). This is a technique for ensuring the validity of an agent’s claimed identity. The SNA process is as follows:

  1. NXLog Manager takes the IP address of the incoming agent, then performs a reverse DNS lookup.

  2. The results of the lookup are compared to the certificate subject name.

  3. A warning is issued or the agent is rejected, depending on the SNA validation setting in NXLog Manager.

Step 1 is not performed if the agent naming is configured to Use agent’s host name. In this case, the agent name is simply compared to the name in the certificate subject.

The Subject Name Authorization configuration can be set to one of three possible options:

  1. Warn if untrusted: In case SNA fails, a warning is logged and the agent status will be FORGED as the agent is apparently using another agent’s certificate and key.

  2. Reject agent: Refuse the agent connection.

  3. Disable: Do not perform SNA.

With SNA Option 2 there is a potential side-effect: DNS outage may render agents unavailable in NXLog Manager. If the DNS server managing the agents' names is not 100% reliable, this might pose a risk worth considering.

When an L4 load balancer sits between the agents and NXLog Manager, or there is Network and Port Address Translation (NAT) device in the path of the traffic from the agents, multiple agents might have the same source address in their connection to NXLog Manager. This effectively breaks SNA, therefore it should be disabled—​unless the Agent name option is set to Use agent’s host name for agent naming.