API custom configuration channels allow you to manually supply agent configuration file settings to multiple hosts included in one or more host sets. Using the API, you can create, modify, and delete custom configuration channels. You can also use the API to review the channel definitions and to obtain a list of the agent settings for a specific host.
Configuration file settings applied using an API custom configuration channel replace all existing agent configuration settings. If any configuration file settings are not specified in a custom configuration channel, the default values for the Trellix Endpoint Security (HX) xAgent settings are used. See the Agent Configuration File Reference for all default values.
The agent default values are not necessarily the same as the Web UI default values for the same configuration options. Any changes you make to these values in the Web UI are ignored by the values applied after you use an API custom configuration channel to change the agent settings.
The only exceptions to this are the values for the credentials and serverlist sections of the configuration file and the following individual configuration settings: channel, id, name, ts, type, and version. The values for these configuration file settings cannot be specified using custom configuration channels and any attempts to do so will be overridden by the Endpoint Security (HX) API with values established during initial Endpoint Security (HX) server and agent deployment.
Important
Trellix recommends that you provide settings for every configuration file setting when you create an API custom configuration channel. If you do not provide a value for an agent configuration file setting, the agent default values are used.
api_admin authorization for the API
Custom configuration channels can only be specified for hosts running Endpoint Security (HX) xAgent software version 20 or greater.
Any hosts running versions earlier than version 20 that are included in the host sets of a custom configuration channel are ignored.
You must have one or more host sets defined in the Web UI that identify the host endpoints to which you want the new configuration settings applied. For information about managing host sets, see the Endpoint Security (HX) Server User Guide.
In addition, you must know the IDs for the host sets before you create a custom configuration channel that will include them. Host set IDs can be identified using the API. See Identifying Host Set IDs Using the API .
The following sections describe custom configuration channel behavior and how to create and delete a custom configuration channel request. For information on API custom configuration channel endpoints, see the Endpoint Security (HX) REST API Guide.
xAgent Configuration Setting Hierarchy
Agent configuration settings are normally specified for a host using the Web UI. However, if a custom configuration channel is created for a host set, any agent configuration settings established using the Web UI are ignored for the hosts included in that host set.
To return to using the Web UI agent settings instead of the custom configuration channel settings for a host, you must first remove the host sets that include that host from any custom configuration channels.
As long as a host is included in a host set used by a custom configuration channel, its agent settings are established by the custom configuration channel. When a host is no longer included in a host set used by a custom configuration channel, its agent settings are established by the Web UI settings.
In addition, if a host is included in multiple host sets with different custom configuration channels, channel priority numbers are used to determine which agent settings apply to the host. See Understanding Configuration Channel Priorities.
Understanding Configuration Channel Priorities
A single host can be included in multiple host sets, which may have different custom configuration channels. To determine which configuration settings should be used for a host included in multiple configuration channels, a priority number is assigned when you create the custom configuration channel. Channels with the lowest priority numbers are given the highest priority.
You can list the defined custom configuration channels to see their priorities. See Listing Custom Configuration Channels.
Priority Number Behavior for New Channels
Priority numbers for custom configuration channels are set when you create the channels. However, priority numbers cannot be skipped. If you skip a priority number when you create a channel or if you leave the priority blank, the API will automatically assign it the next highest priority number in the channel sequence.
For example, the first custom configuration channel you create will be given a priority of 1, regardless of what you specify as its priority. The second custom configuration channel you create will be given a priority number of 2, regardless of what you specify. This is portrayed in the following table.
Channel Creation Order | Name | Requested Priority | Assigned Priority |
|---|---|---|---|
1 | Channel1 | 6000 | 1 |
2 | Channel2 | 5 | 2 |
If you create a custom configuration channel with the same priority number as an existing channel, the newer channel is given its requested priority number and the priority numbers of the other channels are adjusted upward. This is shown in the following table.
Channel Creation Order | Name | Requested Priority | Assigned Priority |
|---|---|---|---|
1 | Channel1 | 1 | 2 |
2 | Channel2 | 2 | 3 |
3 | Channel3 | 1 | 1 |
Priority Number Behavior for Changed Channel Priorities
If you change the priority number of a custom configuration channel, the priority numbers of the other channels may or may not be adjusted, depending on how the priority number is modified.
If you change the priority of a custom configuration channel to a lower number (giving it higher priority), all the priority numbers of the configuration channels between the two priority numbers are increased by one. For example, suppose you have five channels with priorities 1 through 5 and you change the channel with priority 4 to priority 2. The following table shows what happens to the channel priority numbers.
Name
Original Priority
Priority After Change
Channel1
1
1
Channel2
2
3
Channel3
3
4
Channel4
4
2
Channel5
5
5
If you change the priority of a custom configuration channel to a higher number (giving it lower priority), all the priority numbers of the configuration channels between the two priority numbers are decreased by one. For example, suppose you change the channel with priority 2 to priority 4. The following table shows what happens to the channel priority numbers.
Name
Original Priority
Priority After Change
Channel1
1
1
Channel2
2
4
Channel3
3
2
Channel4
4
3
Channel5
5
5
Priority Number Behavior for Deleted Channels
When you delete a custom configuration channel, the priority numbers are adjusted so that the channels with higher priority numbers are all reduced by one. For example, suppose you delete the channel with priority 3 from a series of channels. The following table shows what happens to the channel priority numbers.
Channel Name | Original Priority | Priority After Delete |
|---|---|---|
Channel1 | 1 | 1 |
Channel2 | 2 | 2 |
Channel3 | 3 | deleted |
Channel4 | 4 | 3 |
Channel5 | 5 | 4 |
Identifying Host Set IDs Using the API
Before you create or update custom configuration channels in the API, you should identify the host set IDs of the host sets you will be using in those channel definitions.
To identify host set IDs using the API:
Use an API to request a list of the host sets defined for the Endpoint Security server. Here is a sample cURL request. The host sets must already be defined in the Web UI.
curl 'https://<HX IP address>:<port number>/hx/api/v3/host_sets' -X 'GET' -H 'X-FeApi-Token: <API token>' -H 'Accept: application/json'The response body to the request provides the following information about each host set.
"_id": <host-set-ID>, "name": "<host-set-name>", "type": "<host-set-type>", "_revision": "yyyymmddnnnnnnnnnnnnnnn", "url": "<host-set-path>/<host-set-ID>" },For complete information on API custom configuration channel endpoints, see the Endpoint Security (HX) REST API Guide.
Locate the host sets you want to use in a custom configuration channel in the response body of the API request. Make note of their host set IDs.
Creating a custom configuration channel
Trellix recommends that you specify every configuration file setting (for which you do not want the agent default values) when you create a custom configuration channel. See Agent Configuration File Reference.
The only exceptions to this are the values for the credentials and serverlist sections of the configuration file and the following individual configuration settings: channel, id, name, ts, type, and version. The values for these configuration file settings cannot be specified using custom configuration channels and any attempts to do so will be overridden by the Endpoint Security (HX) API with values established during Endpoint Security (HX) server and agent deployment.
To create a custom configuration channel:
Use the API to request the custom configuration channel be added. Here is a sample cURL request.
curl 'http://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels' -X 'POST' --data-binary '{"name”:”<name>","host_sets":[ {"_id":<host_set_ID1>}, {"_id":<host_set_ID2>},...], "description":"<description>","priority":<priority> configuration: {"<key1>":"<value1>", "<key2>":"<value2>",...}' -H 'X-FeApi-Token: <API_token>' -H 'Accept: application/json' -H 'Content-Type: application/json'To identify host set IDs, see Identifying Host Set IDs Using the API. For information about priority settings, see Understanding Configuration Channel Priorities. For information about the configuration settings (the key/value pairs in the cURL request above), see Agent Configuration File Reference.
For complete information on API custom configuration channel endpoints, see the Endpoint Security (HX) REST API Guide.
Listing Custom Configuration Channels
You can list the defined custom configuration channel using the GET https://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels API endpoint. Channel priorities and channel IDs are shown in the response to this request.
See the Endpoint Security (HX) REST API Guide for more information about API endpoints for custom configuration channels.
Deleting a Custom Configuration Channel
To delete a custom configuration channel:
Use the API to request the custom configuration channel be deleted. Here is a sample cURL request.
curl 'http://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channels/<channel ID>' -X 'DELETE' -H 'X-FeApi-Token: <API_token>'The channel ID is shown in the response body to the original creation request and can be obtained using the
GET https://<HX_IP_address>:<port_number>/hx/api/v3/host_policies/channelsAPI endpoint.For complete information on API custom configuration channel endpoints, see the Endpoint Security (HX) REST API Guide.
Obtaining a list of xAgent configuration settings
At any time, you can obtain a list of the agent configuration settings for a host using the GET hosts/<:agent_id>/configuration/actual.json API endpoint. See the Endpoint Security (HX) REST API Guide for more information about API endpoints for custom configuration channels.