NXLog Docs

NXLog Agent Minder Agent management best practices

Agent enrollment life cycle

The recommended life cycle consists of the following stages:

Stage: new
Stage: enrolled
Stage: configured

Initially the agent starts up with its deployment configuration. That configuration should have the following content in /opt/minder/etc/nxlog/nxlog.d/managed.conf.

define NXLOG_MANAGER_ADDRESS 192.168.1.1
define NXLOG_MANAGER_PORT 4041

LogLevel    INFO
LogFile     %MYLOGFILE%

<Extension agent_managment>
    Module          xm_admin
    Connect         %NXLOG_MANAGER_ADDRESS%
    Port            %NXLOG_MANAGER_PORT%
    SocketType      SSL
    AllowUntrusted  TRUE
    RequireCert     FALSE
    <ACL conf>
        Directory   %CONFDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>
    <ACL cert>
        Directory   %CERTDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>
</Extension>

Agent labels

NXLog Agent Minder generates a simple connection configuration during enrollment. This can be later overridden by including a modified version of it in the configuration files being pushed. Labels may be defined in the configuration or on the agents based on the output of scripts.

Additional labels can be defined during enrollment with the extra-labels request parameter. See [NXLog Agent Minder Enrollment Request Format] for details.

Deploy custom labels script

In case a safer way is needed for adding labels the following procedure may be applied.

Create script /usr/local/bin/custom_labels.sh on the agent:

#!/bin/bash
LABELCONFIG=/opt/nxlog/etc/nxlog.d/local_labels
LOCAL_PREFIX=l_

[ -f $LABELCONFIG ] && awk -v LOCAL_PREFIX=${LOCAL_PREFIX} '{print LOCAL_PREFIX$1, $2}' $LABELCONFIG

exit 0

Add custom labels

The script above loads the contents of the local_labels file.

phone "+15555555"
location "DC-1"

The labels in local_labels will be prefixed by the string l_ to make it easier to distinguish and protect against name clashes. This behaviour can be changed in the script above.

Load local labels

The agent configuration should be amended as follows:

LogLevel    INFO
LogFile     %MYLOGFILE%

<Extension admin>
    Module      xm_admin
    Host        192.168.1.1:4041
    SocketType  SSL
    CAFile      %CERTDIR%/agent-ca.pem
    CertFile    %CERTDIR%/agent-cert.pem
    CertKeyFile %CERTDIR%/agent-key.pem

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

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

    <labels>
        include_stdout /usr/local/bin/custom_labels.sh
    </labels>
</Extension>

Container metadata as labels

This example script shows how labels can be leveraged to facilitate filtering on agent local information.

Dropping the following in /usr/local/bin/get_docker_id.sh

#!/bin/bash

awk -F / '/memory/{printf "container_id \"%s\"\n",$3}' /proc/self/cgroup
awk 'END{printf "container_ip \"%s\"\n", $1}' /etc/hosts

then adding include_stdout /usr/local/sbin/get_docker_id.sh in the Labels section will add container metadata as labels.