Configure admission rules to prefilter searches

In addition to workload rules that let you control system resource allocation by placing running searches in dedicated workload pools, workload management provides admission rules that let you filter out searches entirely before they start, based on a predicate, or condition, that you define. If a search meets the specified condition, it does not run.

You can use admission rules to prevent running rogue searches, such as poorly written or potentially harmful searches that might consume an excessive amount of system resources and interfere with critical search workloads. For example, you can create a rule to filter out wildcard searches that target all indexes, or filter out searches in the all time time range.

You can also use admission rules to set up time-bound access to searches for roles, users, apps and so on. For example, you can create a rule that filters out all ad hoc searches from a certain role during peak business days, lets the same role run searches on weekends.

Unlike workload rules, admission rules have no explicit ordering. Workload management evaluates all admission rules when a search is dispatched. If a search meets the conditions of a rule, the rule takes effect before the search runs. If a search is already running, and you create a new admission rule that applies to that search, the new rule does not affect the search.

Create an admission rule

You can create and edit admission rules using Splunk Web, the CLI or REST API.

When you create an admission rule, workload management stores the configuration under the [search_filter_rule:<rule_name>] stanza in the workload_rules.conf configuration file, located in the etc/apps/search/local directory. For more information, see View workload_rules.conf.

Create an admission rule using Splunk Web

To create and edit admission rules, a user's role must have the list_workload_rules and edit_workload_rules capabilities.

To create an admission rule using Splunk Web:

1. In Splunk Web, click Settings > Workload Management > Admission Rules.
2. Click Add Admission Rule.
3. Define the following fields to configure a new admission rule:

   Field	Action
   Name	Specify the name of the admission rule.
   Predicate (Condition)	Specify a predicate, or condition, that must match to trigger this rule. The predicate syntax is <type>=<value> with optional AND, OR, NOT, and (). For example, app=search AND role=power triggers all searches that belong to both the Search app and the power role. Valid predicate types are app, role, index, user, search_type, search_mode, and search_time_range. For supported predicate values, see Predicate type values. In complex predicates, AND, OR, and NOT operators must be upper case. Lower case is not supported.
   Schedule	(Optional) Set a schedule for the admission rule. The schedule determines the time period during which the rule is valid. If set to Always On (the default), the rule remains valid indefinitely and does not expire. If set to Time Range, the rule is valid during the specified time range only and expires when the time range ends. If set to Every Day, Every Week, or Every Month, the rule becomes valid on a recurring basis during the specified time range every day, on the specified days of the week, or on the specified days of the month. The schedule time for an admission rule is based on the system timezone, regardless of the timezone set for an individual user in the Splunk Web UI.
   Action	Admission rules currently support the default Filter search action only.
   User Message	Enter a custom message that notifies the end user when a search triggers the admission rule action. For example, "The search meets specified admission rule conditions and did not run." If an ad hoc search triggers the rule action, the custom message appears beneath the search bar in the Search and Reporting app. If a scheduled search triggers the action, a default message appears in the scheduler.log file located in the $SPLUNK_HOME/var/log/splunk directory only.

4. Click Submit.

Predicate type values

The following table shows valid values for each admission rule predicate type:

Predicate type	Valid values
app	The name of the app. For example, app=search The correct name to specify for an app is the name of the app directory located in $SPLUNK_HOME/etc/apps. You can also find the correct name for an app in Splunk Web: Click Apps > Manage Apps. See app names listed under Folder name. App names are case insensitive.
role	the name of the role. For example, role=admin. For important details on role predicate values, see Searches run by single user can match multiple roles directly after this table on this page.
index	The name of the index. For example, index=_internal. Value can refer to internal or public index. You can optionally specify index=*" to classify searches containing either index=* or index=_*.
user	The name of any valid user on the instance. For example, user=bob. The reserved internal user "nobody" is invalid; the reserved internal user "splunk-system-user" is valid.
search_type	ad hoc, scheduled, datamodel_acceleration, report_acceleration, and summary_index
search_mode	realtime and historical
search_time_range	Supports alltime time range only.

Create an admission rule using the CLI

To create an admission rule using the CLI, run the splunk add workload-rule command as follows, where predicate has the syntax <type>=<value> with optional AND, NOT, OR, and (), and the value of action is filter:

./splunk add workload-rule <rule_name> -predicate <predicate_string> -action filter

To remove an admission rule, run the splunk remove workload-rule command where the value of workload_rule_type is search_filter:

./splunk remove workload-rule rule <rule_name> -workload_rule_type search_filter

To list admission rules:

./splunk list workload-rule -workload_rule_type search_filter

Create an admission rule using REST

Using a web data transfer tool such as 'cURL', send an HTTP POST request to the following REST endpoint:

workloads/rules 

For example:

curl  -k -u <user:passwd> -X POST <host:mgmt_port>/services/workloads/rules -d name=<rule_name> -d predicate=<predicate_string> -d action=filter

For details on the endpoint, see workloads/rules in the REST API Reference Manual.

Enable admission rules

You must globally enable the admission rules feature for any existing rules to apply when a search runs. You can enable or disable admission rules using Splunk Web, the CLI or the REST API.

When you enable the admission rules feature, workload management stores the setting under the [search_admission_control] stanza in workload_policy.conf, which is located by default in the Search app context, in the etc/apps/search/local directory. For more information, see workload_policy.conf.

To enable admission rules, a user must hold a role that has the list_workload_policy and edit_workload_policy capabilities.

Enable admission rules using Splunk Web

To enable or disable admission rules using Splunk Web:

1. In Splunk Web, click Settings > Workload Management > Admission Rules.
2. Toggle the Admission rules Enabled/Disabled switch to enable or disable Admission rules.

Enable admission rules using the CLI

To enable or disable admission rules, run the following CLI command:

./splunk edit search-admission-control -admission_rules_enabled <1|0>

Enable admission rules using REST

Send an HTTP POST request to the following endpoint:

workloads/policy/search_admission_control

For example:

curl -k -u <user:passwd> -X POST https://hostname:8089/services/workloads/policy/search_admission_control -d admission_rules_enabled=<1|0>

For endpoint details, see workloads/policy/search_admission_control in the REST API Reference Manual.

Example admission rules

The following examples show how you can define admission rules to filter out searches based on the objectives of your use case.

Example 1: Stop wildcard searches

The following rule excludes data model acceleration searches that use index=* from the filter:

index=* AND (NOT search_type=datamodel_acceleration)

Example 2: Stop all-time searches

Some monitoring searches use the alltime time range. The following rule excludes those searches from the filter:

search_time_range=alltime AND (NOT role=sc_admin) AND (NOT app=splunk_instance_monitoring)

The "View index inheritance for roles" feature also uses an alltime search. You can exclude users or roles that need to view indexes from the filter. The above rule excludes the sc_admin role.

Example 3: Do not let certain users run ad hoc searches at peak hours

search_type=adhoc AND role=new_users

After you define the admission rule predicate, set the schedule for the rule, specifying the time range that corresponds to your peak hours.

For more admission rule use cases and examples, see Scenario 3: Create admission rules to prefilter searches.