NXLog search
Let's talk Start free
Let's talk Start free

Sync agent configuration

An agent’s configuration can become out of sync with the configuration stored in NXLog Platform’s Agent Manager. An agent can get into this state if you update its configuration directly on the host or if the agent is offline when you deploy a configuration update from NXLog Platform. When this happens, you can instruct NXLog Platform to synchronize the agent’s configuration with the Agent Manager’s configuration or vice versa.

Prerequisites

About the files-sync command

Calling the agents endpoint with the files-sync command synchronizes files between the agent and Agent Manager. The command requires the following parameters:

  • The name of the ACL that applies to the file(s) you want to sync.

  • The file name or * to sync all files.

  • One of the following sync actions:

    • use-agent-file-version to send the agent’s files to Agent Manager.

    • use-manager-file-version to send the Agent Manager files to the agent.

    • use-last-synced-file-version to sync the newest files.

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/files-sync/{ACL}/{FILE_NAME}/{ACTION}/?filter=({QUERY})" \
       --header "Authorization: Bearer {TOKEN}" \
       --data ""

If matching agents exist, the command returns 200 OK with the following JSON body. Otherwise, it returns an empty JSON array.

[
  {
    "id": "{AGENT_UUID}",
    "status": "success"
  }
]
Offline agents will not have their configuration updated automatically. Once they come back online, the agents will have a warning status and you must synchronize the configuration again while they are online.

Sync configuration by agent hostname

If you need to synchronize the configuration for a single agent, the easiest way is to filter by hostname. This example syncs the configurations of an agent with the hostname PC1.

The hostname is case-sensitive.
POST /agents/*/files-sync/conf/*/use-manager-file-version?filter=(hostname=PC1)

Entity type

agents

Entity UUID

*

Command

files-sync

ACL

conf

File

*

Action

use-manager-file-version

Filter

(hostname=PC1)

Try it

Execute the following curl command or Python script to sync an agent’s configuration by its hostname.

curl 
$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/files-sync/conf/*/use-manager-file-version/?filter=(hostname=PC1)" \(1)
       --header "Authorization: Bearer {TOKEN}" (2)
       --data ""
1 Replace example.com with the NXLog Platform domain you specified when installing NXLog Platform, {ORG_ID} with your organization ID, and PC1 with your agent’s hostname.
2 Replace {TOKEN} with your API token. See Generating a token for instructions.
Python 
'''
Requires Python 3.x
'''

import requests
import json

# Set these variables for your environment
api_token = '<API_TOKEN>' (1)
base_url = 'https://agents.<DOMAIN>/api' (2)
org = '<ORG_ID>' (3)
agent = '<HOSTNAME>' (4)

endpoint = 'api/v1/agents'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {'Authorization': 'Bearer {}'.format(api_token)}

query = '*/files-sync/conf/*/use-manager-file-version?filter=(hostname={})'.format(agent)
r = requests.post('{}/{}'.format(url, query), headers=headers)
if r.status_code == 200:
    print('Status: {}'.format(r.status_code))
    print(json.dumps(r.json(), indent=2))
else:
    print('Error: {} {}'.format(r.status_code, r.text))
1 Replace {TOKEN} with your API token. See Generating a token for instructions.
2 Replace <DOMAIN> with the NXLog Platform domain you specified when installing NXLog Platform.
3 Replace <ORG_ID> with your organization ID.
4 Replace <HOSTNAME> with your agent’s hostname.
Example response 
Status: 200
[
  {
    "id": "94fbcd8e-484c-11ef-8000-656536087e74",
    "status": "success"
  }
]

Update out-of-sync configurations

NXLog Platform detects when an agent’s configuration is not in sync and sets it to a warning status. You can filter for agents with a warning state and sync their configuration if the warning pertains to the configuration. This example checks for agents that are not in sync because the configuration was updated from NXLog Platform and syncs them.

GET /agents/*/?fields=id,hostname,warnings&filter=(warnings/files-modified-on-manager IS NOT NULL)

Entity type

agents

Entity UUID

*

Fields

id,hostname,warnings

Filter

(warnings/files-modified-on-manager IS NOT NULL)

Agents with an out-of-sync configuration are shown in the NXLog Platform UI with a warning status.

NXLog Agent with out-of-sync configuration
POST /agents/94fbcd8e-484c-11ef-8000-656536087e74/files-sync/conf/*/use-manager-file-version

Entity type

agents

Entity UUID

94fbcd8e-484c-11ef-8000-656536087e74

Command

files-sync

ACL

conf

File

*

Action

use-manager-file-version

Try it

Execute the following curl commands or Python script to update the configuration of out-of-sync agents.

curl
List out-of-sync agents

$ curl --verbose --request GET \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/?fields=id,hostname,warnings&filter=(warnings%2Ffiles-modified-on-manager+IS+NOT+NULL)" \(1)
       --header "Authorization: Bearer {TOKEN}" (2)
1 Replace example.com with the NXLog Platform domain you specified when installing NXLog Platform and {ORG_ID} with your organization ID.
2 Replace {TOKEN} with your API token. See Generating a token for instructions.
Sync the configuration

$ curl --verbose --request POST \
        --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/{AGENT_UUID}/files-sync/conf/*/use-manager-file-version" \(1)
        --header "Authorization: Bearer {TOKEN}" (2)
        --data ""
1 Replace example.com with the NXLog Platform domain you specified when signing up, {ORG_ID} with your organization ID, and {AGENT_UUID} with the agent UUID you retrieved above.
2 Replace {TOKEN} with your API token. See Generating a token for instructions.
Python 
'''
Requires Python 3.x
'''

import requests
import json
import re

# Set these variables for your environment
api_token = '<API_TOKEN>' (1)
base_url = 'https://agents.<DOMAIN>/api' (2)
org = '<ORG_ID>' (3)
agent = '<HOSTNAME>' (4)

endpoint = 'api/v1/agents'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {'Authorization': 'Bearer {}'.format(api_token)}

query = '*/?fields=id,hostname,warnings&filter=(warnings/files-modified-on-manager IS NOT NULL)'
r = requests.get('{}/{}'.format(url, query), headers=headers)
if r.status_code == 200:
    acl = r'^conf.*$' (5)
    for agent in r.json():
        for file in agent['warnings']['filesModifiedOnManager']['files']:
            if (re.match(acl, file)):
                print('Syncing config for: {} - {}'.format(agent['hostname'], agent['id']))      
                query = '{}/files-sync/conf/*/use-manager-file-version'.format(agent['id'])
                r = requests.post('{}/{}'.format(url, query), headers=headers)
                if r.status_code == 200:
                    print('Status: {} {}'.format(r.status_code, r.reason))
                else:
                    print('Error: {} {}'.format(r.status_code, r.text))                    
else:
    print('Status: {} {}'.format(r.status_code, r.reason))
1 Replace {TOKEN} with your API token. See Generating a token for instructions.
2 Replace <DOMAIN> with the NXLog Platform domain you specified when installing NXLog Platform.
3 Replace <ORG_ID> with your organization ID.
4 Regular expression to search for files in the conf ACL.
Example response

Retrieving out-of-sync agents with the above requests results in the following JSON array.

[
  {
    "id": "94fbcd8e-484c-11ef-8000-656536087e74",
    "warnings": {
      "filesModifiedOnManager": {
        "message": "The Agent Manager changed some files, but they still need to be updated on the agent.",
        "help": "Start the agent if it's offline. Wait for automatic synchronization or use the Update Configuration option to force it.",
        "note": "The Agent Manager has changed some files but has not yet synchronized with the agent file contents.",
        "files": [
          "conf/managed.conf"
        ]
      }
    },
    "hostname": "PC1"
  }
]

The Python script outputs the following messages for each agent configuration it syncs.

Syncing config for: PC1 - 94fbcd8e-484c-11ef-8000-656536087e74
Status: 200 OK
Syncing config for: PC2 - 1589a98a-66b3-11ee-80d5-4f584c6f672d
Status: 200 OK

© Copyright 2024 NXLog Ltd.

PRIVACY POLICY GENERAL TERMS OF BUSINESS