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
  • More 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 apply to 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.

You can define multiple filters at different levels. More specific filters always take precedence. For example, you can set up an include (whitelist) filter at the global level and then use different exclude (blacklist) filters at each server class level to exclude some agents from each server class.

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 order of execution of filters. If filterType is whitelist, all whitelist filters are applied first, followed by blacklist filters. If filterType is blacklist, all blacklist filters are applied first, followed by whitelist filters.

The whitelist setting indicates a filtering strategy that pulls in a subset:

  • Items are not considered to match the stanza by default.
  • Items that match any whitelist entry, and do not match any blacklist entry, are considered to match the stanza.
  • Items that match any blacklist entry are not considered to match the stanza, regardless of whitelist.

The blacklist setting indicates a filtering strategy that rules out a subset:

  • Items are considered to match the stanza by default.
  • Items that match any blacklist entry, and do not match any whitelist entry, are considered to not match the stanza.
  • Items that match any whitelist entry are considered to match the stanza.

To summarize:

  • whitelist: default no-match -> whitelists enable -> blacklists disable
  • blacklist: default match -> blacklists disable-> whitelists enable

You can override this value at the serverClass and serverClass:app levels. If you specify whitelist at the global level, and then specify blacklist for an individual server class, the setting becomes blacklist for that server class, and you have to provide another filter in that server class definition to replace the one you overrode.

Note:

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

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 client. 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. If, for example, you override the whitelist, the blacklist will not be inherited from the parent; you must provide one in the stanza.

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 will be used only if an agent matches the whitelist/blacklist filters.

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.

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. 

# Example 1
# Match all clients and includes 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 3
# Deploy server class based on machine types

[global]
# whitelist.0=* at the global level ensures that the machineTypesFilter attribute
# invoked later will apply.
whitelist.0=*

[serverClass:WindowsMachineTypes]
machineTypesFilter=windows-*

[serverClass:WindowsMachineTypes:app:WindowsApp]

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

[serverClass:LinuxMachineTypes:app:LinuxApp]

# Example 4
# 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 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*