Set up client filters

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

Types of filters

There are three types of client filters:

• Include (whitelist). Specifies clients to include, based on IP address, host name, DNS name, or client name.
• Exclude (blacklist). Specifies clients to exclude, based on IP address, host name, DNS name, or client name.
• Machine type. Specifies clients to include, based on machine type, such as linux-i686, linux-x86_64, and so on.

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

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

Define filters through forwarder management

In forwarder management, 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 clients for a server class. The process of specifying clients is described in "Use forwarder management to define server classes". The instructions in that topic take you to the Edit Clients dashboard. At the top of that dashboard, there are separate fields for include (whitelist), exclude (blacklist), and machine type:

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/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 dropdown list. The list is populated with all machine types for the deployment server's set of clients. For example, the dropdown list could include these values: linux-x86_64, linux-i686, and windows-x64. Depending on how you're grouping your clients, 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 forwarder management corresponds to the machineTypesFilter attribute in serverclass.conf, not to the machineTypes attribute.

How filters combine

The various filters combine like this:

• Clients are not included in the server class by default.
• Clients that match any include list entry, and do not match any exclude list entry, are included in the server class.
• Clients 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/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 client host names and DNS names.

Example 1

This example includes all Windows 64-bit clients:

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

Important: The asterisk in the include filter is necessary. Otherwise, there will be no clients 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 clients 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 forwarder management filter configuration:

• More details on filter behavior
• More examples

Define filters through serverclass.conf

You can directly edit serverclass.conf if your filtering needs exceed the capabilities of the forwarder 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 a whitelist filter at the global level and then use different blacklist filters at each server class level to exclude some clients from each server class.

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

 splunk reload deploy-server

See "Reload the deployment server" for details.

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

Determine host names of deployment clients

The filters can operate on the host names of deployment clients. To determine the correct set of host names to filter on, you can run a CLI command on the deployment server:

 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. Important: The forwarder management 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 ipAddress, hostname, DNSname, or clientName: ipAddress is the IP address of the deployment client. Can use wildcards, such as 10.1.1.* hostname is the host name of deployment client. Can use wildcards, such as *.splunk.com DNSname is the DNS name of the deployment client. Can use wildcards, such as *.ops.yourcompany.com clientName is a logical or tag name that can be assigned to a deployment client in deploymentclient.conf. It takes precedence over ipAddress, hostname, or DNSname when matching a client to a filter. 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 deployment clients 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" clients to match the server class. No other clients will match. The deployment server 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 deployment server 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 deployment client as a filter. This filter will be used only if a client 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 client varies by platform, but if the deployment client is already connected to the deployment server, you can determine the string's value by using this CLI command on the deployment server: 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 client filtering. Note that these examples cannot be exactly duplicated in forwarder management for various reasons. The first example, for instance, defines one whitelist at the global level. In forwarder management, 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 forwarder management, 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*