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. Specifies clients to include, based on IP address, host name, DNS name, or client name.
- Exclude. 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
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, exclude, and machine type. Use those fields to define the filters.
- 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,
- 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:
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
serverclass.conf, not to the
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.
This example includes all Windows 64-bit clients:
- Machine type:
Important: The asterisk in the include filter is necessary. Otherwise, there will be no clients for the machine type filter to operate on.
This example includes all Windows 64-bit forwarders:
- Machine type:
This example includes Linux clients that are in the Ops area of the company and outside North America:
- Machine type:
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.
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 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
You can override this value at the
Important: The forwarder management interface requires that
Set the attribute to
Here are some examples:
This will cause all deployment clients in fflanda.com except "printer" and "scanner" to match this server class.
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
You can override filters at the
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.
|Set these attributes to a
If importing values from a CSV file, you must use these attributes in combination with the
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.
|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
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:
This will return a value for
This setting will match any of the machine types in a comma-delimited list. Commonly-used machine types are:
For more details on these attributes, see the serverclass.conf spec file in the Admin manual.
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
# 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[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*
Use forwarder management to define server classes
Deploy apps to clients
This documentation applies to the following versions of Splunk® Enterprise: 8.2.0, 8.2.1