Configure admission rules to prefilter searches

Admission rules let you filter out searches automatically before they start, based on a predicate (condition) that you define. If a search meets the specified condition, the search is not executed.

You can use admission rules to prevent the execution of rogue searches, such as poorly written and potentially harmful searches that might consume an excessive amount of 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 alltime 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, but allows the same role to run searches on weekends.

Admission rules have no explicit ordering. All admission rules are evaluated when a search is dispatched. If a search meets the conditions of a rule, the rule takes effect before the search is executed. If a search is already running, and you create a new admission rule that applies to that search, the running search is not affected by the new rule.

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, the configuration is stored under the [search_filter_rule:<rule_name>] stanza in workload_rules.conf. The default app context is search. Unless you specify a different app context, admission rules are stored along with workload rules in etc/apps/search/local/workload_rules.conf. 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 (condition) that must match to trigger this rule. The predicate syntax is <type>=<value> with optional AND, OR, NOT, (). For example, app=search AND role=power triggers all searches belonging 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 Specify predicate 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 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, "This search meets specified admission rule conditions. The search was not executed." 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 scheduler.log only.

4. Click Submit.

Specify predicate values

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

Predicate type	Valid values
app	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	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	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	Name of any valid user. For example, user=bob. The reserved internal user "nobody" is invalid; the reserved internal user "splunk-system-user" is valid.
search_type	adhoc, 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 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

Send a POST request to the following 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 endpoint details, 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 is executed. You can enable or disable admission rules using Splunk Web, the CLI or REST API.

When you enable the admission rules feature, the setting is stored under the [search_admission_control] stanza in workload_policy.conf. This file is located by default in etc/apps/search/local. For more information, see workload_policy.conf.

To enable admission rules, a user's role must hold 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 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 a 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.

Enable individual admission rules

You can enable or disable individual admission rules. This lets you create and save multiple different admission rules and apply them as needed. Individual admission rules are enabled by default when you create them. Disabled admission rules are not evaluated and have no effect on search execution.

When you enable or disable an admission rule, the is setting is stored under the [search_filter_rule:<rule_name>] stanza for the individual rule in workload_rules.conf. For more information, see workload_rules.conf.

You can enable or disable individual admission rules using Splunk Web, the CLI, or REST API.

Enable individual admission rules using Splunk Web

To enable or disable an individual admission rule using Splunk Web:

1. In Splunk Web, click Settings > Workload Management > Admission Rules.
2. In the Status column, toggle the switch to enable or disable the individual admission rule.

Enable individual admission rules using CLI

To enable or disable an individual admission rule, run the following CLI command, where the value of -workload_rule_type is search_filter:

./splunk <enable|disable> workload-rule <rule_name> -workload_rule_type search_filter

Enable individual admission rules using REST

Send a POST request to the workloads/rules endpoint, as shown:

curl -k -u <user:pass> -X POST https://localhost:8089/services/workloads/rules/<rule_name>/<enable|disable> -d workload_rule_type=search_filter

For endpoint details, see workloads/rules 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.

REST API searches default to the alltime time range, unless you explicitly define a different time range in the search query.

Example 3: Do not allow certain users to 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 case examples, see Scenario 3: Create admission rules to prefilter searches.