Set up agent filters

A key activity in defining a server class is specifying the set of agents that belong to the server class. You do this through agent filters.

Types of filters

There are three types of agent filters:

Include. Specifies agents to include, based on IP address, host name, DNS name, or agent name.
Exclude. Specifies agents to exclude, based on IP address, host name, DNS name, or agent name.
Machine type. Specifies agents to include, based on machine type, such as linux-i686, linux-x86_64, and so on.

Note: The "agent name" is a logical name that you can assign to an agent through the clientName attribute in deploymentclient.conf. For more information, see Set an agent name.

You can use one or all of these filters to define the set of agents for a server class. For example, you can combine an include filter for all agents for the North American region with a machine type filter that includes all Windows agents. That way, North American Windows agents will be in their own server class and handled separately from North American Linux agents or agents in other regions.

Define filters through the interface

In the interface, you always define filters for an entire server class. If you need to define filters at either the global or app level, you must edit serverclass.conf directly.

You define filters when you specify agents for a server class. The process of specifying agents is described in Use agent management UI to define server classes. The instructions in that topic take you to the Edit forwarders page. At the top of that page, there are separate fields for include, exclude, and machine type. Use those fields to define the filters.

Note:

You can enter values for as many of these filter fields as you need to. You can also enter multiple filters for each field.
To enter multiple include or exclude filters, separate each filter with a comma.
When specifying IP addresses or host names, you can use wildcards; for example, 10.1.1.* or fwdr-*.
For machine type filters, use the drop-down list. The list is populated with all machine types for the set of agents for agent management. For example, the drop-down list could include these values: linux-x86_64, linux-i686, and windows-x64. Depending on how you're grouping your agents, you might need a separate server class for each machine type, or you might be able to combine several machine types (for example, all Linux machine types) in a single server class.
The machine type filter in the interface corresponds to the machineTypesFilter attribute in serverclass.conf, not to the machineTypes attribute.

How filters combine

The various filters combine in the following ways:

Agents are not included in the server class by default.
Agents that match any include list entry, and do not match any exclude list entry, are included in the server class.
Agents that match any exclude list entry are not included in the server class, regardless of the include list.
The machine type filter operates on the output from the include or exclude filters. If you want to use the machine type as the sole qualifier, you must also put an asterisk in the include list filter.

The following examples describe various results and what you need to enter into the filter fields to obtain them. These are just examples and are dependent on specific conventions for agent host names and DNS names.

Example 1

This example includes all Windows 64-bit agents:

Include: *
Exclude:
Machine type: windows-x64

Note: The asterisk in the include filter is necessary. Otherwise, there will be no agents for the machine type filter to operate on.

Example 2

This example includes all Windows 64-bit forwarders:

Include: fwdr-*
Exclude:
Machine type: windows-x64

Example 3

This example includes Linux agents that are in the Ops area of the company and outside North America:

Include: *.ops.yourcompany.com
Exclude: northamerican-*
Machine type: linux-i686, linux-x86_64

The section in this topic that covers serverclass.conf includes additional information on filters that is also relevant to agent management UI filter configuration:

More details on filter behavior, see What you can configure for a server class
More examples, see Examples

Define filters through serverclass.conf

You can directly edit the serverclass.conf file if your filtering needs exceed the capabilities of the agent management interface; for example, if you need to layer filters across multiple levels or if you need to define different filters for different apps within a server class.

In serverclass.conf, you can define filters at any of three levels:

Global: These filters are used as template values for all server classes.
Server class: These filters apply to an entire server class.
App: These filters apply to just a single app within a server class.

These three levels have distinct roles in agent matching:

The global level is a template only and does not perform agent matching. It provides default values that serverClass stanzas inherit.
The server class level performs primary agent matching. If an agent does not match at this level, it receives no apps from this server class, regardless of app-level filters.
The app level performs secondary filtering within the server class scope. It can only further restrict which agents receive a specific app; it cannot add agents beyond those matched by the parent server class.

You can define multiple filters at different levels. Child levels inherit filters from parent levels unless they explicitly override them.

Important:

Atomic override behavior
When you override whitelist or blacklist at a child level, you must explicitly define both to avoid clearing inherited values. Overriding one filter type causes the other to be cleared as well. This applies to serverclass level and app level.
Filter-triggered atomic override (level-dependent)
Defining machineTypesFilter, packageTypesFilter, or updaterRunningFilter has different behavior depending on the level:
- At the app level: Defining any of these filters clears both inherited whitelist and blacklist from the parent server class. You must explicitly define filters at the app level.
- At the server class level: Defining any of these filters doesn't clear inherited whitelist and blacklist from the global level.
Filters not applicable at the global level
Defining machineTypesFilter, packageTypesFilter, or updaterRunningFilter at the global level has no effect. These filters are only operational at the serverClass or app level.

After you edit serverclass.conf, you must reload agent management so that the changes take effect. To reload agent management, invoke the CLI reload deploy-server command:

 splunk reload deploy-server

See Reload the agent management for details.

Note: Once you edit serverclass.conf directly, there's a strong possibility that you will no longer be able to use the interface for configuration purposes. For details, see the topic Compatibility and agent management.

Determine host names of agents

The filters can operate on the host names of agents. To determine the correct set of host names to filter on, you can run a CLI command on agent management:

 splunk list deploy-clients

List of filtering attributes

The following attributes in serverclass.conf determine filter behavior:

Filter attribute What it's for Default

filterType

Set to "whitelist" or "blacklist".

This determines the default matching behavior and how conflicts are resolved.

When filterType is whitelist (default-deny):

Items do not match by default.
Items must be in the whitelist AND not in the blacklist to match.
Formula: (in whitelist) AND (not in blacklist)

You can use this analogy: when filterType = whitelist , it's like a night club where you must have a ticket and cannot be on a banned guest list.

When filterType is blacklist (default-allow):

Items match by default.
Matches unless blacklisted.
Formula: (in whitelist) OR (not in blacklist)

You can use this analogy: when filterType = blacklist, it's like a public park where everyone can enter. Access is denied only if a user is on the banned list. (Note: Specific configurations might allow VIPs to bypass the ban.)

To summarize:

When filterType = whitelist (default-deny):

Blacklist match	Whitelist match	Agent matched
No	No	No
Yes	No	No
No	Yes	Yes
Yes	Yes	No

When filterType = blacklist (default-allow):

Blacklist match	Whitelist match	Agent matched
No	No	Yes
Yes	No	No
No	Yes	Yes
Yes	Yes	Yes

You can override this value at the serverClass and serverClass:app levels. If you specify filterType=whitelist at the global level, and then specify blacklist for an individual server class, the setting becomes blacklist for that server class.

Note:

The interface requires that filterType retain its default value of whitelist.

Important:

Version 9.4.3 change: Starting in Splunk Enterprise version 9.4.3, the app-level implicit filterType has been standardized: its default has changed from blacklist (default-allow) to whitelist (default-deny), aligning the app to the server class component for consistent filtering behavior. If you are upgrading from a pre-9.4.3 version and experience apps not deploying, you might need to add explicit whitelist or filterType settings at the app level. See the serverclass.conf specification file for migration guidance.

whitelist

whitelist.<n>

blacklist.<n>

<n> is an unsigned integer. The sequence can start at any value and can be non-consecutive.

Set the attribute to clientName, ipAddress, DNSname, hostname, or instanceId:

clientName is a logical or tag name that can be assigned to an agent in deploymentclient.conf.
ipAddress is the IP address of the agent. Can use wildcards, such as 10.1.1.*
DNSname is the DNS name of the agent. Can use wildcards, such as *.ops.yourcompany.com
hostname is the host name of agent. Can use wildcards, such as *.splunk.com
instanceId is the instanceId of the agent. This is a GUID string, for example: ffe9fe01-a4fb-425e-9f63-56cc274d7f8b.

The system attempt to match the value of the attribute to the agent details in this descending order of precedence: clientName, ipAddress, DNSname, hostname, instanceId

Here are some examples: When filterType is whitelist:

whitelist.0=*.fflanda.com
blacklist.0=printer.fflanda.com
blacklist.1=scanner.fflanda.com

This will cause all agents in fflanda.com except "printer" and "scanner" to match this server class.

When filterType is blacklist:

blacklist.0=*
whitelist.0=*.web.fflanda.com
whitelist.1=*.linux.fflanda.com

This will cause only the "web" and "linux" agents to match the server class. No other agents will match.

The agent management stops evaluating a filter at the first break in sequence of <n> values.

You can override filters at the serverClass and serverClass:app levels.

Important: Overriding one type of filter (whitelist/blacklist) causes the other to be overridden too (atomic override). If you override the whitelist, the blacklist will not be inherited from the parent; you must define both in the stanza.

Additionally, defining machineTypesFilter, packageTypesFilter, or updaterRunningFilter at app level triggers the same atomic override, clearing both whitelist and blacklist from the parent.

Example of incorrect override:

[global]
whitelist.0=*
blacklist.0=some-host.example.com

[serverClass:MyClass]
whitelist.0=*.ops.example.com
# Wrong: blacklist is cleared, some-host.example.com will now be included

Example of correct override:

[serverClass:MyClass]
whitelist.0=*.ops.example.com
blacklist.0=some-host.example.com
# Correct: Both filters explicitly defined

n/a

whitelist.from_pathname

blacklist.from_pathname

Set these attributes to a <pathname> that specifies either a plain text file or a comma-separated values (CSV) file that contains values for filtering.

These attributes instruct the agent management to import the <clientName>, <IP address>, or <hostname> list from the specified file.

If importing values from a CSV file, you must use these attributes in combination with the whitelist|blacklist.select_field, whitelist|blacklist.where_field, or whitelist|blacklist.where_equals attributes, which specify the fields in the CSV file that contain the desired values.

For detailed information on the use of all of these attributes, along with examples of how to import filter values from an external file, see serverclass.conf.

n/a

machineTypesFilter

Matches any of the machine types in a comma-separated list.

This setting lets you use the hardware type of the agent as a filter. This filter is used in boolean AND logic with whitelist and blacklist filters. An agent must match both the whitelist/blacklist filters AND the machineTypesFilter to be included.

The value for machineTypesFilter is a comma-separated list of machine types; for example, linux-i686, linux-x86_64, etc. Each machine type is a specific string designated by the hardware platform itself.

Note: A machineTypesFilter value can contain wildcards; for example: linux-*, windows-*, or aix-*

The method for finding this string on the agent varies by platform, but if the agent is already connected to the agent management , you can determine the string's value by using this CLI command on the agent management:

splunk list deploy-clients

This will return a value for utsname that you can use to specify machineTypesFilter.

This setting will match any of the machine types in a comma-delimited list. Commonly-used machine types are: linux-x86_64, windows-x64, linux-i686, freebsd-i386, darwin-i386, sunos-sun4u, linux-x86_64, sunos-i86pc, freebsd-amd64.

Important:

Defining machineTypesFilter at the app level triggers an atomic override that clears both whitelist and blacklist inherited from the parent server class. You must explicitly define whitelist or blacklist at the app level where you define machineTypesFilter, or agents will not match.

At the server class level, defining machineTypesFilter doesn't clear whitelist and blacklist inherited from the global level.

This filter has no effect when defined at the global level.

Not set

packageTypesFilter

Matches any of the package types in a comma-separated list. This filter is used in boolean AND logic with whitelist and blacklist filters. An agent must match both the whitelist/blacklist filters AND the packageTypesFilter to be included.

Important:

Defining packageTypesFilter at the app level triggers an atomic override that clears both whitelist and blacklist inherited from the parent server class. You must explicitly define whitelist or blacklist at the app level where you define packageTypesFilter, or agents will not match.

At the server class level, defining packageTypesFilter doesn't clear whitelist and blacklist inherited from the global level.

This filter has no effect when defined at the global level.

Commonly-used package types: tgz, msi

Not set

updaterRunningFilter

Boolean value that filters based on whether the self-updater is running on the agent. The self-updater must be installed separately to upgrade the agent. This filter is used in boolean AND logic with whitelist and blacklist filters.

Important:

Defining updaterRunningFilter at the app level triggers an atomic override that clears both whitelist and blacklist inherited from the parent server class. You must explicitly define whitelist or blacklist at the app level where you define updaterRunningFilter, or agents will not match.

At the server class level, defining updaterRunningFilter doesn't clear whitelist and blacklist inherited from the global level.

This filter has no effect when defined at the global level.

Not set

For more details on these attributes, see the serverclass.conf spec file in the Admin manual.

Examples

Here are several examples of serverclass.conf agent filtering. Note that these examples cannot be exactly duplicated in agent management UI for various reasons. The first example, for instance, defines one whitelist at the global level. In agent management UI, all filters are defined at the server class level. In the second example, one of the server classes sets the filterType attribute to blacklist. In agent management UI, the filterType is always set to whitelist.

For more examples, see the examples section in serverclass.conf.

# Example 1
# Match all clients and includ all apps in the server class

[global]
whitelist.0=*
# whitelist matches all clients.
[serverClass:AllApps]
[serverClass:AllApps:app:*]
# a server class that encapsulates all apps in the repositoryLocation 


# Example 2
# Assign server classes based on hostnames.

[global][serverClass:AppsForOps]
whitelist.0=*.ops.yourcompany.com
[serverClass:AppsForOps:app:unix]
[serverClass:AppsForOps:app:SplunkLightForwarder]

[serverClass:AppsForDesktops]
filterType=blacklist
# blacklist everybody except the Windows desktop machines.
blacklist.0=* 
whitelist.0=*.desktops.yourcompany.com
[serverClass:AppsForDesktops:app:SplunkDesktop]


# Example 3a
# Deploy server class based on machine types

[global]
# whitelist.0=* at the global level ensures all serverclasses get this rule
# and apply it as a primary filter.
whitelist.0=*

[serverClass:WindowsMachineTypes]
machineTypesFilter=windows-*
# At the serverClass level, machineTypesFilter doesn't trigger atomic override.
# The whitelist.0=* from global is inherited and applied first, then 
# machineTypesFilter is applied in AND logic.

[serverClass:WindowsMachineTypes:app:WindowsApp]

[serverClass:LinuxMachineTypes]
machineTypesFilter=linux-i686, linux-x86_64

[serverClass:LinuxMachineTypes:app:LinuxApp]

# Example 3b
# Deploy app based on machine types - app level filtering
# This shows the REQUIRED pattern for using machineTypesFilter at app level

[global]

[serverClass:AppsByMachineType]
# ServerClass matches all clients
whitelist.0=*

[serverClass:AppsByMachineType:app:WindowsApp]
# Required: Must explicitly set whitelist when using machineTypesFilter at
# app level. Without this, the app will not deploy to any agents.
whitelist.0=*
machineTypesFilter=windows-*

[serverClass:AppsByMachineType:app:LinuxApp]
# REQUIRED: Must explicitly set whitelist when using machineTypesFilter at
# app level
whitelist.0=*
machineTypesFilter=linux-i686, linux-x86_64

# Example 4a
# Blacklist a range of IP addresses, using a regular expression

[global]

[serverClass:ExcludeSomeIPAddresses]
filterType=whitelist
whitelist.0=*
blacklist.0=192.168.1.1[34][0-9]

# Example 4b
# Blacklist a range of IP addresses, using a regular expression

[global]

[serverClass:ExcludeSomeIPAddresses]
filterType=blacklist
blacklist.0=192.168.1.1[34][0-9]

# Example 5a
# Use (whitelist|blacklist) text file import.

[serverClass:MyApps]
whitelist.from_pathname = etc/system/local/clients.txt

# Example 5b
# Use (whitelist|blacklist) CSV file import to read all values from the Client
# field (ignoring all other fields).

[serverClass:MyApps]
whitelist.select_field = Client
whitelist.from_pathname = etc/system/local/clients.csv

# Example 5c
# Use (whitelist|blacklist) CSV file import to read some values from the Client
# field (ignoring all other fields) where ServerType is one of T1, T2, or
# starts with dc.

[serverClass:MyApps]
whitelist.select_field = Client
whitelist.from_pathname = etc/system/local/server_list.csv
whitelist.where_field = ServerType
whitelist.where_equals = T1, T2, dc*

# Example 5d
# Use (whitelist|blacklist) CSV file import to read some values from field 2
# (ignoring all other fields) where field 1 is one of T1, T2, or starts with
# dc.

[serverClass:MyApps]
whitelist.select_field = 2
whitelist.from_pathname = etc/system/local/server_list.csv
whitelist.where_field = 1
whitelist.where_equals = T1, T2, dc*