Enroll agents by rules

NXLog Platform supports creating enrollment rules that you can use to configure agents on enrollment automatically. For example, you can create rules for Windows workstations, Linux servers, and network devices. Whereas enrolling agents with the enroll command requires you to specify a configuration object or template UUID for each request, enrolling agents by rules configures them according to predefined enrollment policies.

Prerequisites

A machine with NXLog Agent installed and connected to NXLog Platform.
Your NXLog Platform organization ID.
An NXLog Platform API Personal Access Token (PAT).

About the enroll-by-rules command

Calling the agents endpoint with the enroll-by-rules command enrolls agents to NXLog Platform using predefined enrollment rules.

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

If matching agents exist and are enrolled successfully, the command returns 200 OK with the following JSON body.

[
  {
    "id": "{AGENT_UUID}",
    "status": "success"
  }
]

If matching agents exist but no enrollment rule matches the agents, the command returns 200 OK with the following JSON body.

[
  {
    "id": "{AGENT_UUID}",
    "status": "error",
    "error": "{\"message\":\"no applicable enroll rule found\",\"help\":\"None of the currently defined enroll rules matched this agent, therefore it cannot be enrolled automatically. Either enroll the agent manually, define a new, matching enroll rule, or update the filter in one of the existing rules, then retry this request.\"}"
  }
]

The command attempts to enroll all matching agents, even if already enrolled. Enrolling an agent that is already enrolled overwrites its configuration. To avoid re-enrolling agents, filter for agents that are not currently enrolled.

Enroll new agents

This example enrolls all new agents according to predefined enrollment rules.

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

POST /agents/*/enroll-by-rules/?filter=(enrolled=false)
Entity type	`agents`
Entity UUID	`*`
Command	`enroll-by-rules`
Filter	`(enrolled=false)`

Entity type

agents

Entity UUID

*

Command

enroll-by-rules

Filter

(enrolled=false)

Try it

Execute the following curl command or Python script to enroll all new agents using predefined enrollment rules.

curl

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/agents/*/enroll-by-rules/?filter=(enrolled=false)" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --data ""

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.

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)

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

query = '*/enroll-by-rules/?filter=(enrolled=false)'
r = requests.post('{}/{}'.format(url, query), headers=headers)

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.

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

This example enrolls an agent to NXLog Platform by its hostname using predefined enrollment rules. The agent will only be enrolled if it’s not already enrolled.

The hostname is case-sensitive.

POST /agents/*/enroll-by-rules/?filter=(hostname=PC1 AND enrolled=false)

POST /agents/*/enroll-by-rules/?filter=(hostname=PC1 AND enrolled=false)
Entity type	`agents`
Entity UUID	`*`
Command	`enroll-by-rules`
Filter	`(hostname=PC1 AND enrolled=false)`