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.*
orfwdr-*
.
- 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
, andwindows-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 inserverclass.conf
, not to themachineTypes
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 The
The
To summarize:
You can override this value at the Important: The forwarder management interface requires that |
whitelist |
whitelist.<n> blacklist. |
<n> is an unsigned integer. The sequence can start at any value and can be non-consecutive.
Set the attribute to
Here are some examples:
When
This will cause all deployment clients in fflanda.com except "printer" and "scanner" to match this server class. When
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. |
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.
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. |
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 Note: A 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.
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*
Use forwarder management to define server classes | Deploy apps to clients |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14
Feedback submitted, thanks!