NXLog search
Let's Talk Start free
Let's Talk

Create a configuration

Configurations allow you to create a library of NXLog Agent configurations that you can assign to multiple NXLog Agent instances, simplifying configuration management. A configuration can contain a complete NXLog Agent configuration or a partial configuration snippet you can combine with other configurations. For more information, see Configurations and Create a configuration in the NXLog Platform User Guide.

Prerequisites

About creating configurations

A POST request to the templates endpoint creates a new configuration. The command requires a configuration name and one of the following:

  • The static configuration.

    $ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "{CONFIG_NAME}", "content": "{AGENT_CONFIG}"}'

  • A list of existing configuration UUIDs in the order they should be included in the new configuration.

    $ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "{CONFIG_NAME}", "parts": ["{CONFIG_UUID}", "{CONFIG_UUID}"]}'
    You cannot delete a configuration that is a part of another configuration. You must remove it from all other configurations to delete it.

  • A file containing the static configuration. Use this method to avoid converting the configuration to an escaped JSON string. The request must use the multipart/form-data content type.

    $ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Accept: */*" \
       --form "name={CONFIG_NAME}" \
       --form "contents=@{CONFIG_FILE}"

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

Create a configuration

This example creates a configuration containing a snippet to collect Microsoft Windows events. It also applies the input and windows tags to the configuration for easy identification.

POST /templates

Entity type

templates

Request body

 
{
  "name": "Windows-evt",
  "content": "<Input windows_events>\nModule im_msvistalog\n</Input>\n",
  "tags": ["input", "windows"]
}

Try it

Execute the following curl command or Python script to create a new configuration.

  • curl

  • Python

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "Windows-evt", "content": "<Input windows_events>\nModule im_msvistalog\n</Input>\n", "tags": ["input", "windows"]}'
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. 
'''
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/templates'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {
    'Authorization': 'Bearer {}'.format(api_token),
    'Content-Type': 'application/json',
    'Accept': '*/*'
}

payload = {'name': 'Windows-evt', 'content': '<Input windows_events>\nModule im_msvistalog\n</Input>\n', 'tags': ['input', 'windows']}
r = requests.post(url, headers=headers, data=json.dumps(payload))

if r.status_code == 200:
    print('Status: {}'.format(r.status_code))
    print('Configuration 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.
Example response
Status: 200
Configuration UUID: 745908b9-99c7-11ef-8007-72731771e0df

Create a configuration from a file

You can create a configuration by uploading an NXLog Agent configuration file. This method saves you from converting the configuration to an escaped JSON string. The request must use the multipart/form-data content type and supports the following form fields.

Field Required Description

name

Yes

The configuration name.

contents

Yes

The configuration file to upload. The file must be UTF-8 encoded.

tags

No

A configuration tag. Repeat the field to apply multiple tags.

comment

No

A comment describing the configuration.

version_comment

No

A comment describing this configuration version.

This example creates a configuration from the windows-events.conf file containing a snippet to collect Microsoft Windows events. It also applies the input and windows tags to the configuration for easy identification.

windows-events.conf
<Input windows_events>
    Module    im_msvistalog
</Input>

<Output file>
    Module    om_file
    File      'C:\temp\windows_events.log'
</Output>

<Route r1>
    Path      windows_events => file
</Route>
POST /templates

Entity type

templates

Content type

multipart/form-data

Form fields

  • name: Windows-evt

  • contents: windows-events.conf

  • tags: input

  • tags: windows

Try it

Execute the following curl command or Python script to create a new configuration from a file.

  • curl

  • Python

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Accept: */*" \
       --form "name=Windows-evt" \
       --form "tags=input" \
       --form "tags=windows" \
       --form "contents=@windows-events.conf"(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 windows-events.conf with the path to your configuration file. The @ prefix instructs curl to upload the file contents.
The --form option automatically sets the Content-Type header to multipart/form-data. Do not set it to application/json. 
'''
Requires Python 3.x
'''

import requests

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

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

payload = {'name': 'Windows-evt', 'tags': ['input', 'windows']}
with open(config_file, 'rb') as f:
    r = requests.post(url, headers=headers, data=payload, files={'contents': f})

if r.status_code == 200:
    print('Status: {}'.format(r.status_code))
    print('Configuration 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 <CONFIG_FILE> with the path to your configuration file.
Example response
Status: 200
Configuration UUID: 745908b9-99c7-11ef-8007-72731771e0df

Build a configuration from multiple configurations

You can build a configuration by combining existing configurations. To do so, you need the UUIDs of the configurations you want to use. This example creates a configuration from existing configurations with their name starting with Windows-.

The API supports a maximum of one nesting level. Therefore, a configuration consisting of other configurations cannot be part of another configuration.
GET /templates/?fields=id&filter=(name LIKE 'Windows-%')

Entity type

templates

Field

id

Filter

(name LIKE 'Windows-%')
POST /templates

Entity type

templates

Request body

 
{
  "name": "All Windows events",
  "parts": ["4bddf35e-99f4-11ef-800e-eae9743d8daa", "34a11f77-99f4-11ef-800d-340c29e52f9c"]
}

Try it

Execute the following curl commands or Python script to create a configuration from existing ones.

  • curl

  • Python

Get the UUIDs of the existing configuration

$ curl --verbose --request GET \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates/?fields=id&filter=(name%20LIKE%20'Windows-%25')" \(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 configuration

$ curl --verbose --request POST \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "Windows log sources", "parts": ["4bddf35e-99f4-11ef-800e-eae9743d8daa", "34a11f77-99f4-11ef-800d-340c29e52f9c"]}'(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 configuration UUIDs with the ones you retrieved above. 
'''
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/templates'
url = '{}/{}/{}'.format(base_url, org, endpoint)
headers = {
    'Authorization': 'Bearer {}'.format(api_token),
}

query = '?fields=id&filter=(name LIKE "Windows-%")'
r = requests.get('{}/{}'.format(url, query), headers=headers)
if r.status_code == 200:
    configs = r.json()
    if (len(configs) > 0):
        headers['Content-Type'] = 'application/json'
        headers['Accept'] = '*/*'
        payload = {'name': 'Windows log sources', 'parts': configs}
        r = requests.post(url, headers=headers, data=json.dumps(payload))

        if r.status_code == 200:
            print('Status: {}'.format(r.status_code))
            print('Configuration UUID: {}'.format(r.text))
        else:
            print('Error: {} {}'.format(r.status_code, r.text))
    else:
        print("No matching configurations found")
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
Configuration UUID: 745908b9-99c7-11ef-8007-72731771e0df

© Copyright NXLog Ltd.

PRIVACY POLICY GENERAL TERMS OF BUSINESS