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

Enroll agents

After installing and connecting an NXLog Agent instance to NXLog Platform, you must enroll it before you can monitor and configure it from NXLog Platform. For more information, see Enroll an agent and Agent deployment state in the NXLog Platform User Guide.

Prerequisites

About the enroll command

Calling the agents endpoint with the enroll command enrolls an agent to NXLog Platform. The command requires an Enrollment object specifying one of the following:

  • The connection mode (connect or listen) and NXLog Platform agent management URL and port.

    $ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/enroll/?filter=({QUERY})" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"connection": {"mode": "connect", "address": "{AGENTS_URL}"}}'

  • A configuration template UUID.

    $ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/enroll/?filter=({QUERY})" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"templateId": "{TEMPLATE_UUID}"}'

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"
  }
]
Enrolling an agent that is already enrolled overwrites its configuration.

Enroll new agents

When you install and connect an agent to NXLog Platform, it is registered as a new agent. You can only start and stop the agent and view its logs at this stage. This example enrolls all new agents so that NXLog Platform starts collecting metrics from them. It specifies an Enrollment object with the connection mode and the NXLog Platform agent management URL. Alternatively, see Enroll and configure agents below to enroll and configure agents simultaneously.

POST /agents/*/enroll/?filter=(enrolled=false)

Entity type

agents

Entity UUID

*

Command

enroll

Filter

(enrolled=false)

Request body

 
{
  "connection": {
     "mode": "connect",
     "address": "agents.example.com:5515"
  }
}

Try it

Execute the following curl command or Python script to enroll all new agents.

curl 
$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/enroll/?filter=(enrolled=false)" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"connection": {"mode": "connect", "address": "agents.example.com:5515"}}' (3)
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.
3 Replace the address with your agent management URL and port.
Python 
'''
Requires Python 3.x
'''

import requests
import json

api_token = '<API_TOKEN>' (1)
base_url = 'https://agents.<DOMAIN>/api' (2)
org = '<ORG_ID>' (3)
agents_url = '<AGENTS_URL>' (4)

endpoint = 'api/v1/agents'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {
    'Authorization': 'Bearer {}'.format(api_token),
    'Content-Type': 'application/json',
    'Accept': '*/*'
}

query = '*/enroll/?filter=(enrolled=false)'
payload = {'connection': {'mode': 'connect', 'address': agents_url}}
r = requests.post('{}/{}'.format(url, query), headers=headers, data=json.dumps(payload))

if r.status_code == 200:
    print('Status: {} {}'.format(r.status_code, r.reason))
    print(json.dumps(r.json(), indent=2))
else:
    print('Error: {} {}'.format(r.status_code, r.text))
1 Replace <API_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 <AGENTS_URL> with your agent management URL and port. It is typically agents.example.com:5515.
Example response 
Status: 200
[
  {
    "id": "1589a98a-66b3-11ee-80d5-4f584c6f672d",
    "status": "success"
  },
  {
    "id": "94fbcd8e-484c-11ef-8000-656536087e74",
    "status": "success"
  }
]

Enroll an agent by hostname

If you’ve just installed and connected an agent to NXLog Platform and want to enroll it, the easiest way is to filter by hostname. This example enrolls an agent to NXLog Platform by its hostname. It specifies an Enrollment object with the connection mode and the NXLog Platform agent management URL. Once enrolled, NXLog Platform starts collecting metrics from the agent. Alternatively, see Enroll and configure agents below to simultaneously enroll and configure an agent.

The hostname is case-sensitive.
POST /agents/*/enroll/?filter=(hostname=PC1 AND enrolled=false)

Entity type

agents

Entity UUID

*

Command

enroll

Filter

(hostname=PC1 AND enrolled=false)

Request body

 
{
  "connection": {
     "mode": "connect",
     "address": "agents.example.com:5515"
  }
}

Try it

Execute the following curl command or Python script to enroll an agent by its hostname.

curl 
$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/enroll/?filter=(hostname=PC1 AND enrolled=false)" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"connection": {"mode": "connect", "address": "agents.example.com:5515"}}' (3)
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.
3 Replace the address with your agent management URL and port.
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)
agents_url = '<AGENTS_URL>' (5)

endpoint = 'api/v1/agents'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {
    'Authorization': 'Bearer {}'.format(api_token),
    'Content-Type': 'application/json',
    'Accept': '*/*'
}

query = '*/enroll/?filter=(hostname={} AND enrolled=false)'.format(agent)
payload = {'connection': {'mode': 'connect', 'address': agents_url}}
r = requests.post('{}/{}'.format(url, query), headers=headers, data=json.dumps(payload))

if r.status_code == 200:
    print('Status: {} {}'.format(r.status_code, r.reason))
    print(json.dumps(r.json(), indent=2))
else:
    print('Error: {} {}'.format(r.status_code, r.text))
1 Replace <API_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 the hostname of the agent you want to enroll.
5 Replace <AGENTS_URL> with your agent management URL and port. It is typically agents.example.com:5515.
Example response 
Status: 200
[
  {
    "id": "94fbcd8e-484c-11ef-8000-656536087e74",
    "status": "success"
  }
]

Enroll and configure agents

You can simultaneously enroll and configure an agent by assigning it a configuration template. To do so, you need the template UUID. This example enrolls all new agents and assigns them a template called New agents. Alternatively, see Enroll an agent by hostname above to enroll a single agent.

GET /templates/*/id?filter=(name LIKE 'New agents')

Entity type

templates

Entity UUID

*

Field

id

Filter

(name LIKE 'New agents')
You can also get the template UUID from the NXLog Platform UI by opening the template from the Configurations Overview and copying the last part of the URL.
POST /agents/*/enroll/?filter=(enrolled=false)

Entity type

agents

Entity UUID

*

Data path

enroll

Filter

(enrolled=false)

Request body

 
{
  "templateId": "ef5b6794-4dbf-11ef-8000-aa8b17d1ce7b"
}

Try it

Execute the following curl commands or Python script to enroll and configure agents.

curl
Get the configuration template UUID

$ curl --verbose --request GET \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates/*/id?filter=(name%20LIKE%20'New%20agents')" \(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.
Enroll and configure the agents

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/enroll/?filter=(enrolled=false)" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"templateId": "ef5b6794-4dbf-11ef-8000-aa8b17d1ce7b"}' (3)
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.
3 Replace the template UUID with the one you retrieved above.
Python 
'''
Requires Python 3.x
'''

import requests
import json

api_token = '<API_TOKEN>' (1)
base_url = 'https://agents.<DOMAIN>/api' (2)
org = '<ORG_ID>' (3)
template_name = '<TEMPLATE_NAME>' (4)

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

query = '*/id?filter=(name LIKE "{}")'.format(template_name)
r = requests.get('{}/{}'.format(url, query), headers=headers)

if r.status_code == 200:
    template_uuid = r.json()[0]
    endpoint = 'api/v1/agents'
    url = '{}/{}/{}'.format(base_url, org, endpoint)
    headers['Content-Type'] = 'application/json'
    
    query = '*/enroll/?filter=(enrolled=false)'
    payload = {"templateId": template_uuid}
    r = requests.post('{}/{}'.format(url, query), headers=headers, data=json.dumps(payload))
    
    if r.status_code == 200:
        print('Status: {} {}'.format(r.status_code, r.reason))
        print(json.dumps(r.json(), indent=2))
else:
    print('Error: {} {}'.format(r.status_code, r.text))
1 Replace <API_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 <TEMPLATE_NAME> with your configuration template name.
Example response 
Status: 200
[
  {
    "id": "1589a98a-66b3-11ee-80d5-4f584c6f672d",
    "status": "success"
  },
  {
    "id": "94fbcd8e-484c-11ef-8000-656536087e74",
    "status": "success"
  }
]

© Copyright 2024 NXLog Ltd.

PRIVACY POLICY GENERAL TERMS OF BUSINESS