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

Create an enrollment rule

Enrollment rules are policies that determine how to enroll and configure NXLog Agent instances. Enrollment rules can be applied automatically or manually and allow you to enroll and optionally configure agents. For more information, see Auto enroll and Set up automatic agent enrollment in the NXLog Platform User Guide.

Prerequisites

About creating enrollment rules

A POST request to the enroll-rules endpoint creates a new enrollment rule. The command requires an EnrollRule object specifying a name, selector, and 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/enroll-rules" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "{RULE_NAME}", "options": {"connection": {"mode": "connect", "address": "{AGENTS_URL}"}}, "selector": "{QUERY}"}'

  • A configuration template UUID.

    $ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/enroll-rules" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "{RULE_NAME}", "options": {"templateId": "{TEMPLATE_UUID}"}, "selector": "{QUERY}"}'

If successful, the command returns 200 OK and the new enrollment rule UUID.

Create a rule to auto-enroll new agents

This example creates a rule to automatically enroll new agents when they connect to NXLog Platform and sets the rule priority to 1. The lowest priority is 0, which is also the default.

POST /enroll-rules

Entity type

enroll-rules

Request body

 
{
  "name": "New agents",
  "options": {
    "connection": {
      "mode": "connect",
      "address": "agents.example.com:5515"
    }
  },
  "selector": "enrolled == false",
  "priority": 1,
  "automatic": true
}

Try it

Execute the following curl command or Python script to create an automatic enrollment rule.

curl 
$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/enroll-rules" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "New agents", "options": {"connection": {"mode": "connect", "address": "agents.example.com:5515"}}, "selector": "enrolled == false", "priority": 1, "automatic": true}' (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. It is typically agents.example.com:5515.
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)
agents_url = '<AGENTS_URL>' (4)

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

payload = {'name': 'New agents', 'options': {'connection': {'mode': 'connect', 'address': agents_url}}, 'selector': 'enrolled == false', 'priority': 1, 'automatic': True}
r = requests.post(url, headers=headers, data=json.dumps(payload))

if r.status_code == 200:
    print('Status: {}'.format(r.status_code))
    print('Rule UUID: {}'.format(r.text))
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
Rule UUID: 3cae6955-abeb-11ef-8004-3c2d91911792

Create a rule to auto-enroll and configure agents

You can configure enrollment rules to assign matching agents a configuration template. To do so, you need the template UUID. This example creates a rule to automatically enroll Windows 10 and 11 clients and assign them a configuration template called Windows clients. It sets the rule priority to 10, so it is higher than any catch-all enrollment rule like the example above that auto-enrolls all new agents.

GET /templates/*/id?filter=(name LIKE 'Windows clients')

Entity type

templates

Entity UUID

*

Field

id

Filter

(name LIKE 'Windows clients')
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 /enroll-rules

Entity type

enroll-rules

Request body

 
{
  "name": "Windows clients",
  "options": {
    "templateId": "ef5b6794-4dbf-11ef-8000-aa8b17d1ce7b"
  },
  "selector": "os-release REGEX \"Windows (10|11).*\" AND enrolled == false",
  "priority": 10,
  "automatic": true
}

Try it

Execute the following curl commands or Python script to create a rule that enrolls agents and assigns them a configuration template.

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'Windows%20clients')" \(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.
Create the enrollment rule

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/enroll-rules" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "New agents", "options": {"templateId": "8d02ec19-a35c-11ef-8000-82a780fc14a7"}, "selector": "os-release REGEX \"Windows (10|11).*\" AND enrolled == false", "priority": 10, "automatic": true}'(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

# Set these variables for your environment
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/enroll-rules'
    url = '{}/{}/{}'.format(base_url, org, endpoint)
    headers['Content-Type'] = 'application/json'
    headers['Accept'] = '*/*'
    
    payload = {'name': 'Windows clients', 'options': {'templateId': template_uuid}, 'selector': 'os-release REGEX "Windows (10|11).*" AND enrolled == false', 'priority': 10, 'automatic': True}
    r = requests.post(url, headers=headers, data=json.dumps(payload))
    if r.status_code == 200:
        print('Status: {}'.format(r.status_code))
        print('Rule UUID: {}'.format(r.text))

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
Rule UUID: 3cae6955-abeb-11ef-8004-3c2d91911792

© Copyright 2024 NXLog Ltd.

PRIVACY POLICY GENERAL TERMS OF BUSINESS