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

Update configurations

You can update a configuration or change its type. Updating a configuration does not automatically deploy the changes to NXLog Agent instances. See Sync agent configuration for instructions on syncing an agent’s configuration.

Prerequisites

About updating configurations

A PATCH request to the templates endpoint updates an existing configuration. The command requires the configuration UUID. The following configuration properties can be updated: name, parts, content, tags, and comment. If parts or content are updated, the command creates a new version of the configuration.

$ curl --verbose --request PATCH \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates/{CONFIG_ID}" \
       --header "Authorization: Bearer {TOKEN}" \
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{OBJECT}'

Alternatively, you can upload the static configuration as a file instead of embedding it in the request body as an escaped JSON string. To do so, send the request as multipart/form-data and specify the file in the contents field.

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

If a matching configuration exists and it is updated successfully, the command returns 204 No content.

Rename a configuration

This example renames a configuration by its ID.

PATCH /templates/ea217bc8-3823-11f1-8000-c6dc36d72137

Entity type

templates

Entity UUID

ea217bc8-3823-11f1-8000-c6dc36d72137

Request body

 
{
  "name": "New configuration name"
}

Try it

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

  • curl

  • Python

$ curl --verbose --request PATCH \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates/{CONFIG_ID}" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"name": "New configuration name"}'
1 Replace example.com with the NXLog Platform domain you specified when installing NXLog Platform, {ORG_ID} with your organization ID, and {CONFIG_ID} with your configuration UUID.
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)
config_id = '<CONFIG_ID>' (4)

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

payload = {'name': 'New configuration name'}
r = requests.patch(url, headers=headers, data=json.dumps(payload))

if r.status_code == 204:
    print('Status: 204')
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_ID> with your configuration UUID.
Example response
Status: 204

Change the configuration type

You can update a configuration to either include other configurations as parts or use a static configuration by specifying the corresponding field. The content and parts fields are mutually exclusive. Therefore, specifying one field in an update request overwrites the other field.

Specifying both the content and parts properties returns 400 Bad Request - Trying to set parts and contents at the same time.

This example changes a configuration consisting of other configurations to static configuration.

PATCH /templates/ea217bc8-3823-11f1-8000-c6dc36d72137

Entity type

templates

Entity UUID

ea217bc8-3823-11f1-8000-c6dc36d72137

Request body

 
{
  "content": "<Input windows_events>\nModule im_msvistalog\n</Input>\n"
}

Try it

Execute the following curl command or Python script to change a configuration consisting of other configurations to static configuration.

  • curl

  • Python

$ curl --verbose --request PATCH \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates/{CONFIG_ID}" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Content-Type: application/json" \
       --header "Accept: */*" \
       --data '{"content": "<Input windows_events>\nModule im_msvistalog\n</Input>\n"}'
1 Replace example.com with the NXLog Platform domain you specified when installing NXLog Platform, {ORG_ID} with your organization ID, and {CONFIG_ID} with your configuration UUID.
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)
config_id = '<CONFIG_ID>' (4)

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

payload = {'content': '<Input windows_events>\nModule im_msvistalog\n</Input>\n'}
r = requests.patch(url, headers=headers, data=json.dumps(payload))

if r.status_code == 204:
    print('Status: 204')
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_ID> with your configuration UUID.
Example response
Status: 204

Update a configuration from a file

You can update 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

contents

No

The configuration file to upload. The file must be UTF-8 encoded. Uploading a file creates a new version of the configuration.

name

No

The configuration name.

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 the new configuration version.

If you only specify fields other than contents, the command updates the configuration details without creating a new version.

Uploading a file does not support specifying the parts field. If you need to update a configuration to consist of other configurations, use a JSON request body instead, as described in Change the configuration type.

This example updates a configuration with the contents of the windows-security.conf file, which collects events from the Windows Security channel only. It also adds a comment to describe the new configuration version.

windows-security.conf
<Input windows_events>
    Module  im_msvistalog
    <QueryXML>
        <QueryList>
            <Query Id="0">
                <Select Path="Security">*</Select>
            </Query>
        </QueryList>
    </QueryXML>
</Input>

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

<Route r1>
    Path      windows_events => file
</Route>
PATCH /templates/ea217bc8-3823-11f1-8000-c6dc36d72137

Entity type

templates

Entity UUID

ea217bc8-3823-11f1-8000-c6dc36d72137

Content type

multipart/form-data

Form fields

  • version_comment: Collect Security events only

  • contents: windows-security.conf

Try it

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

  • curl

  • Python

$ curl --verbose --request PATCH \
       --url "https://agents.example.com/api/{ORG_ID}/api/v1/templates/{CONFIG_ID}" \(1)
       --header "Authorization: Bearer {TOKEN}" \(2)
       --header "Accept: */*" \
       --form "version_comment=Collect Security events only" \
       --form "contents=@windows-security.conf"(3)
1 Replace example.com with the NXLog Platform domain you specified when installing NXLog Platform, {ORG_ID} with your organization ID, and {CONFIG_ID} with your configuration UUID.
2 Replace {TOKEN} with your API token. See Generating a token for instructions.
3 Replace windows-security.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_id = '<CONFIG_ID>' (4)
config_file = '<CONFIG_FILE>' (5)

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

payload = {'version_comment': 'Collect Security events only'}
with open(config_file, 'rb') as f:
    r = requests.patch(url, headers=headers, data=payload, files={'contents': f})

if r.status_code == 204:
    print('Status: 204')
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_ID> with your configuration UUID.
5 Replace <CONFIG_FILE> with the path to your configuration file.
Example response
Status: 204

© Copyright NXLog Ltd.

PRIVACY POLICY GENERAL TERMS OF BUSINESS