Construct a Search Filter for a Role
This page describes how to define an advanced search filter for a role. These instructions apply to the Advanced filter option in Step 6 of the Create a role procedure.
Understanding search filters
A search filter for a role defines what log data a user with that role can access. You can define a search filter using keywords, wildcards, metadata fields, and logical operators. Here is a simple role filter:
_sourceCategory=labs*
This filter grants access to logs whose _sourceCategory
begins with the string “labs”. (Logs whose _sourceCategory
don’t start with “labs” won’t be accessible.)
When a user with this filter enters a query like:
_sourceCategory=labs/apache | parse "* --" as src_ip | count by src_ip | sort _count
Sumo silently (it’s transparent to the user) adds the role filter to the beginning of the query with an AND:
_sourceCategory=labs* AND (_sourceCategory=labs/apache | parse "* --" as src_ip | count by src_ip | sort _count)
The example above positively grants access to log data. You can do the opposite: explicitly deny access to data, with an exclamation point (!). For example:
!_sourceCategory=JobX*
The role filter above denies access to log data whose _sourceCategory
begins with “JobX”. (Access to log data with other source category values is not restricted.)
The examples above are simple: they involve a single role, and hence a single role filter.
Typically however, a Sumo user will have multiple roles. If a user has multiple roles, Sumo OR
s the several role filters and prepends that expression to the user’s queries with an AND
, as discussed in Multiple role filters and filter precedence.
Search filter basics
The sections below list search filter limitations, and describe how you can use keywords, wildcards, metadata, and logical operators in filters.
The explanations of the behavior of each example filter assume that no other role filters apply. In practice, you will likely assign multiple roles to users. After you understand the basics of how role filters work, see Multiple role filters and filter precedence.
Search filter limitations
- Role filters should include only keyword expressions or built-in metadata field expressions using these fields:
_sourcecategory
,_collector
,_source
,_sourcename
,_sourcehost
. - Using
_index
or_view
in a role filter scope is not supported. - Role filters cannot include vertical pipes (
|
). - Role filters apply to log searches, not metric searches.
- The _dataTier search modifier is not supported in role filters.
- If one or more of your Field Extraction Rules (FERs) override the out-of-the-box metadata tags you use in your search filters for a role, Live Tail can still provide access to data outside of the scope intended in your search filter. You should either avoid overriding out-of-the-box metadata tags in your FERs or avoid overridden tags in your search filters.
- Using a field or FERs in a role filter is not supported. It will cause errors for any search run by a user in the role where the field is not valid. For example, if an FER created a field
foo
, adding thefoo=bar
scope to a role will break any search for a user where this field is not valid. This most often causes errors where users search a view where the field is not a valid schema field in that view.
For limitations related to the use of Scheduled Views or Partitions in a search filter, refer to Partitions and Scheduled Views.
Using metadata in a search filter
You can use metadata fields in a role search filter. The following search filter grants access to log data from a Collector named “HR_Tools”, and no other data:
_collector=HR_Tools
When a user with that role filter runs a query, Sumo prepends the filter to the query with an AND:
_collector=HR_Tools AND <user-query>